Skip to main content

Free Spaced Repetition Scheduler

Project description

Open Spaced Repetition logo

Py-FSRS

🧠🔄 Build your own Spaced Repetition System in Python 🧠🔄


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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fsrs-3.1.0.tar.gz (13.0 kB view details)

Uploaded Source

Built Distribution

fsrs-3.1.0-py3-none-any.whl (10.3 kB view details)

Uploaded Python 3

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

Hashes for fsrs-3.1.0.tar.gz
Algorithm Hash digest
SHA256 3106a03f9abf4c76ad9482d237d0539ff701010d18e2cafd8dbb8d49e7fd1044
MD5 4dd962c03bd22debdf342279f8c9acd2
BLAKE2b-256 b5a578ecd534772be03e805371b5de1ca58e423f29c778088ee08c9d493a2d41

See more details on using hashes here.

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

Hashes for fsrs-3.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 88c0043f79356b6267bb7f6b80eaa86137aae86ab4f370d963453c638957ddad
MD5 edb3903ea25dcb147c15a8ad541c0b84
BLAKE2b-256 dc6983f7a0b9084e37b2714851907253a40309e1433424d2112cc6ff2892798c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page