This release makes some major changes to the API, the required version of python and a couple of other changes.
At a high level:
- Py-FSRS now requires python 3.10+
- The scheduler can now randomly "fuzz" calculated review intervals
- The scheduler can now set explicit learning and relearning steps
- Card objects no longer have a New state (new cards now start off in the Learning state)
- Card objects now have different attributes
- The scheduler has been renamed from `FSRS` to `Scheduler`
- The `repeat` method has been replaced in favor of the `review_card` method
Upgrade from v3 -> v4
To upgrade, first make sure you're using python 3.10 or later.
Next, you'll want to review the updated [README](https://github.com/open-spaced-repetition/py-fsrs/blob/main/README.md) to get familiar with the new API, which should hopefully be mostly straightforward.
The tricky part will be in updating previous v3 cards to v4.
This was the old class schema for v3 Cards:
python
class Card:
"""
Represents a flashcard in the FSRS system.
Attributes:
due (datetime): The date and time when the card is due next.
stability (float): Core FSRS parameter used for scheduling.
difficulty (float): Core FSRS parameter used for scheduling.
elapsed_days (int): The number of days since the card was last reviewed.
scheduled_days (int): The number of days until the card is due next.
reps (int): The number of times the card has been reviewed in its history.
lapses (int): The number of times the card has been lapsed in its history.
state (State): The card's current learning state.
last_review (datetime): The date and time of the card's last review.
"""
due: datetime
stability: float
difficulty: float
elapsed_days: int
scheduled_days: int
reps: int
lapses: int
state: State
last_review: datetime
and here's the new class schema for v4 Cards:
python
class Card:
"""
Represents a flashcard in the FSRS system.
Attributes:
card_id (int): The id of the card. Defaults to the epoch miliseconds of when the card was created.
state (State): The card's current learning state.
step (int | None): The card's current learning or relearning step or None if the card is in the Review state.
stability (float | None): Core mathematical parameter used for future scheduling.
difficulty (float | None): Core mathematical parameter used for future scheduling.
due (datetime): The date and time when the card is due next.
last_review (datetime | None): The date and time of the card's last review.
"""
card_id: int
state: State
step: int | None
stability: float | None
difficulty: float | None
due: datetime
last_review: datetime | None
To upgrade your v3 cards to v4 cards, do the following:
- Set `card_id` to a unique integer value. Unless otherwise specified, new v4 cards will be set to the epoch miliseconds of when the card was created, but you are free to set it to anything else.
- If your card's `state` was set to New, convert it to Learning and set its `stability` and `difficulty` values to `None`
- If your card was in the New, Learning or Relearning state, set its `step` to 0, otherwise, if the v3 card was in the Review state, set its `step` to `None`
- Remove the following attributes from your v3 cards (these were removed since they don't affect scheduling)
- `elapsed_days`
- `scheduled_days`
- `reps`
- `lapses`
- If your v3 card previously didn't have a `last_review` attribute, create one and set it to `None`
Now as for upgrading your v3`ReviewLog` objects to v4 objects, this will likely require some custom migration on your part. Apologies for any inconvenience.
In either case, this was the old v3 `ReviewLog` class schema:
python
class ReviewLog:
"""
Represents the log entry of Card that has been reviewed.
Attributes:
rating (Rating): The rating given to the card during the review.
scheduled_days (int): The number of days until the card is due next.
elapsed_days (int): The number of days since the card was last reviewed.
review (datetime): The date and time of the review.
state (State): The learning state of the card before the review.
"""
rating: Rating
scheduled_days: int
elapsed_days: int
review: datetime
state: State
and here's the new v4 `ReviewLog` schema:
python
class ReviewLog:
"""
Represents the log entry of a Card object that has been reviewed.
Attributes:
card (Card): Copy of the card object that was reviewed.
rating (Rating): The rating given to the card during the review.
review_datetime (datetime): The date and time of the review.
review_duration (int | None): The number of miliseconds it took to review the card or None if unspecified.
"""
card: Card
rating: Rating
review_datetime: datetime
review_duration: int | None
Upgrading to the new scheduler should be simple enough, just review the new README and compare it to how you were previously using the scheduler.
What's Changed
* Major update and refactor by joshdavham in https://github.com/open-spaced-repetition/py-fsrs/pull/64
**Full Changelog**: https://github.com/open-spaced-repetition/py-fsrs/compare/v3.1.0...v4.0.0