Proposed little modification to the library's API (to make it more understandable)

[cjauvin]

Hi! I'm absolutely new to spaced repetition and FSRS, and I'm looking to use this code in the prototype of a Django-based language learning app I'm currently building for myself. So first of all thank you very much for your good work!

I had some trouble trying to understand how I could use your library in a very simple way (as a total newcomer to this field), and it actually took me the example in this thread https://github.com/open-spaced-repetition/py-fsrs/issues/15 to get a starting idea of what would a very basic usage loop looks like.

Furthermore, I have some more questions like: if I want to record the state of a card in a database, is storing the state of the Card object at a moment in time sufficient, or do I need to store some other stuff as well?

But for now, I would like to propose a little possible change to the API (i.e. the interface) of your library, based on my very initial understanding of how it works. Suppose that FSRS.repeat was modified to have the following signature:

def repeat(self, card: Card, now: datetime, rating: int) -> SchedulingInfo

which could be accomplished by simply changing its last line to: return s.record_log(card, now)[rating]

The advantage of that is that the update loop of the example code in https://github.com/open-spaced-repetition/py-fsrs/issues/15 could simply become:

for rating in ratings:
    sched_info = fsrs.repeat(card, now, rating)
    card = sched_info.card
    log = sched_info.review_log
    logs.append(log)
    now = card.due

which would provide, IMO, a much more intuitive and understandable API for beginners and external users of your library.

[L-M-Sherlock]

The current API could provide 4 intervals in one call. It allows developers to display 4 intervals for 4 ratings before users press rating buttons:

[cjauvin]

It makes a lot of sense, my bad then!

[L-M-Sherlock]

if I want to record the state of a card in a database, is storing the state of the Card object at a moment in time sufficient, or do I need to store some other stuff as well?

What do you mean the state of a card?

[cjauvin]

Sorry it wasn't super clear indeed. I'm using your library in the context of a Django application, so I need to store whatever state is needed to interrupt a FSRS session (and resume it later) in a database. I was wondering if storing the values of all Card variables (i.e. which is what I mean by its "state") was enough:

https://github.com/open-spaced-repetition/py-fsrs/blob/9980d8522c9bf097c744e5b92ba300dfc7863ad0/src/fsrs/models.py#L36-L45

It's probably a good idea to store the parameters as well, although I don't intend to modify them:

https://github.com/open-spaced-repetition/py-fsrs/blob/9980d8522c9bf097c744e5b92ba300dfc7863ad0/src/fsrs/models.py#L135-L143

I'm less clear about the ReviewLog, it's probably necessary to store them as well in the context of a full-feature app like Anki, but in the case of my own app, which is very simple for the moment, I don't think it's necessary.

[L-M-Sherlock]

If you don't want to provide stats with users or allow them to optimize the parameters, it's OK to not store ReviewLog.