Free Spaced Repetition Scheduler
Project description
Py-FSRS
Py-FSRS is a python package that allows developers to easily create their own spaced repetition system using the Free Spaced Repetition Scheduler algorithm.
Installation
You can install the fsrs
python package from PyPI using pip:
pip install fsrs
Quickstart
Import and initialize the FSRS scheduler
from fsrs import FSRS, Card, Rating
f = FSRS()
Create a new Card object
# all new cards are 'due' immediately upon creation
card = Card()
Choose a rating and review the card
# you can choose one of the four possible ratings
"""
Rating.Again # forget; incorrect response
Rating.Hard # recall; correct response recalled with serious difficulty
Rating.Good # recall; correct response after a hesitation
Rating.Easy # recall; perfect response
"""
rating = Rating.Good
card, review_log = f.review_card(card, rating)
See when the card is due next
from datetime import datetime, timezone
due = card.due
# how much time between when the card is due and now
time_delta = due - datetime.now(timezone.utc)
print(f"Card due: at {repr(due)}")
print(f"Card due in {time_delta.seconds} seconds")
"""
> Card due: at datetime.datetime(2024, 7, 12, 18, 16, 4, 429428, tzinfo=datetime.timezone.utc)
> Card due in: 599 seconds
"""
Usage
Custom scheduler
You can initialize the FSRS scheduler with your own custom weights as well as desired retention rate and maximum interval.
f = FSRS(
w=(
0.4197,
1.1869,
3.0412,
15.2441,
7.1434,
0.6477,
1.0007,
0.0674,
1.6597,
0.1712,
1.1178,
2.0225,
0.0904,
0.3025,
2.1214,
0.2498,
2.9466,
0.4891,
0.6468,
),
request_retention=0.85,
maximum_interval=3650,
)
Advanced reviewing of cards
Aside from using the convenience method review_card
, there is also the repeat
method:
from datetime import datetime, timezone
# custom review time (must be UTC)
review_time = datetime(2024, 7, 13, 20, 7, 56, 150101, tzinfo=timezone.utc)
scheduling_cards = f.repeat(card, review_time)
# can get updated cards for each possible rating
card_Again = scheduling_cards[Rating.Again].card
card_Hard = scheduling_cards[Rating.Hard].card
card_Good = scheduling_cards[Rating.Good].card
card_Easy = scheduling_cards[Rating.Easy].card
# get next review interval for each rating
scheduled_days_Again = card_Again.scheduled_days
scheduled_days_Hard = card_Hard.scheduled_days
scheduled_days_Good = card_Good.scheduled_days
scheduled_days_Easy = card_Easy.scheduled_days
# choose a rating and update the card
rating = Rating.Good
card = scheduling_cards[rating].card
# get the corresponding review log for the review
review_log = scheduling_cards[rating].review_log
Serialization
Card
and ReviewLog
objects are JSON-serializable via their to_dict
and from_dict
methods for easy database storage:
# serialize before storage
card_dict = card.to_dict()
review_log_dict = review_log.to_dict()
# deserialize from dict
new_card = Card.from_dict(card_dict)
new_review_log = ReviewLog.from_dict(review_log_dict)
Reference
Card objects have one of four possible states
State.New # Never been studied
State.Learning # Been studied for the first time recently
State.Review # Graduate from learning state
State.Relearning # Forgotten in review state
There are four possible ratings when reviewing a card object:
Rating.Again # forget; incorrect response
Rating.Hard # recall; correct response recalled with serious difficulty
Rating.Good # recall; correct response after a hesitation
Rating.Easy # recall; perfect response
Algorithm
For a brief overview of the FSRS algorithm, please see ALGORITHM.md.
Contribute
Checkout CONTRIBUTING to help improve Py-FSRS!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file fsrs-3.1.0.tar.gz
.
File metadata
- Download URL: fsrs-3.1.0.tar.gz
- Upload date:
- Size: 13.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.9.20
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3106a03f9abf4c76ad9482d237d0539ff701010d18e2cafd8dbb8d49e7fd1044 |
|
MD5 | 4dd962c03bd22debdf342279f8c9acd2 |
|
BLAKE2b-256 | b5a578ecd534772be03e805371b5de1ca58e423f29c778088ee08c9d493a2d41 |
File details
Details for the file fsrs-3.1.0-py3-none-any.whl
.
File metadata
- Download URL: fsrs-3.1.0-py3-none-any.whl
- Upload date:
- Size: 10.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.9.20
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 88c0043f79356b6267bb7f6b80eaa86137aae86ab4f370d963453c638957ddad |
|
MD5 | edb3903ea25dcb147c15a8ad541c0b84 |
|
BLAKE2b-256 | dc6983f7a0b9084e37b2714851907253a40309e1433424d2112cc6ff2892798c |