# SuperMemo2
[](https://pypi.org/project/supermemo2/)
[](https://github.com/alankan886/SuperMemo2/actions?query=workflow%3ACI)
[](https://codecov.io/gh/alankan886/SuperMemo2)
[](https://pepy.tech/project/supermemo2)
A package that implemented the spaced repetition algorithm SM-2 for you to quickly calculate your next review date for whatever you are learning.
📌 **Note:** The algorithm SM-2 doesn't equal to the computer implementation SuperMemo2. In fact, the 3 earliest implementations (SuperMemo1, SuperMemo2 and SuperMemo3) all used algorithm SM-2. I didn't notice that when I first published the package on PyPI, and I can't change the package name.
📦 [PyPI page](https://pypi.org/project/supermemo2/)
## Table of Contents
- [Motivation](#motivation)
- [Installing and Supported Versions](#install-versions)
- [A Simple Example](#example)
- [Features](#features)
- [What is SM-2?](#sm2)
- [Code Reference](#code)
- [Testing](#testing)
- [Changelog](#changelog)
- [Credits](#credits)
<a name="motivation">
## Motivation
The goal was to have an efficient way to calculate the next review date for studying/learning. Removes the burden of remembering the algorithm, equations, and math from the users.
<a name="install-versions">
## Installation and Supported Versions
### Package Install
Install and upate the package using [pip](https://pip.pypa.io/en/stable/quickstart/):
```bash
pip install -U supermemo2
```
<a name="download">
### To Play Around with the Code
Download the code:
```bash
git clone https://github.com/alankan886/SuperMemo2.git
```
Install dependencies to run the code:
```bash
pip install -r requirements.txt
```
supermemo2 supports Python 3.8+
<a name="example">
## A Simple Example
```python
from supermemo2 import first_review, review
# first review
# using quality=4 as an example, read below for what each value from 0 to 5 represents
# review date would default to datetime.utcnow() (UTC timezone) if not provided
first_review = first_review(4, "2024-06-22")
# first_review prints { "easiness": 2.36, "interval": 1, "repetitions": 1, "review_datetime": "2024-06-23 01:06:02"))
# second review
second_review = review(4, first_review["easiness"], first_review["interval"], first_review["repetitions"], first_review["review_datetime"])
# or just unpack the first review dictionary
second_review = review(4, **first_review)
# second_review prints similar to example above.
```
<a name="features">
## Features
📣 Calculates the review date of the task following the SM-2 algorithm.
<br/> 📣 The first_review method to calculate the review date at ease without having to know the initial values.
<a name="sm2">
## What is SM-2?
🎥 If you are curious of what spaced repetition is, check this [short video](https://youtu.be/-uMMRjrzPmE?t=94) out.
📌 A longer but interactive [article](https://ncase.me/remember/) on spaced repetition learning.
📎 [The SM-2 Algorithm](https://www.supermemo.com/en/archives1990-2015/english/ol/sm2)
### What are the "values"?
The values are the:
- Quality: The quality of recalling the answer from a scale of 0 to 5.
- 5: perfect response.
- 4: correct response after a hesitation.
- 3: correct response recalled with serious difficulty.
- 2: incorrect response; where the correct one seemed easy to recall.
- 1: incorrect response; the correct one remembered.
- 0: complete blackout.
- Easiness: The easiness factor, a multipler that affects the size of the interval, determine by the quality of the recall.
- Interval: The gap/space between your next review.
- Repetitions: The count of correct response (quality >= 3) you have in a row.
<a name="code">
## Code Reference
**first_review(** quality, review_datetime=None**)**
function that calcualtes the next review datetime for the your first review without having to know the initial values, and returns a dictionary containing the new values.
**Parameters:**
- quality (int) - the recall quality of the review.
- review_datetime (str or datetime.datetime) - optional parameter, the datetime in ISO format up to seconds in UTC timezone of the review.
**Returns:** dictionary containing values like quality, easiness, interval, repetitions and review_datetime.
**Return Type:** Dict
**Usage:**
```python
from supermemo2 import first_review
# using default datetime.utcnow() if you just reviewed it
first_review(3)
# providing string date in Year-Month-Day format
first_review(3, "2024-06-22")
# providing date object date
from datetime import datetime
d = datetime(2024, 1, 1)
first_review(3, d)
```
**review(** quality, easiness, interval, repetitions, review_datetime=None **)**
Calcualtes the next review date based on previous values, and returns a dictionary containing the new values.
**Parameters:**
- quality (int) - the recall quality of the review.
- easiness (float) - the easiness determines the interval.
- interval (int) - the interval between the latest review date and the next review date.
- repetitions (int) - the count of consecutive reviews with quality larger than 2.
- review_datetime (str or datetime.datetime) - optional parameter, the datetime in ISO format up to seconds in UTC timezone of the review.
**Returns:** dictionary containing values like quality, easiness, interval, repetitions and review_datetime.
**Return Type:** Dict
**Usage:**
```python
from supermemo2 import first_review, review
# using previous values from first_review call
r = first_review(3)
# using default datetime.utcnow() if you just reviewed it
review(3, r["easiness"], r["interval"], r["repetitions"])
# providing review_datetime from previous review
review(3, r["easiness"], r["interval"], r["repetitions"], r["review_datetime"])
# providing string review_datetime
review(3, r["easiness"], r["interval"], r["repetitions"], "2024-01-01")
# providing datetime object review_datetime
from datetime import datetime
d = datetime(2024, 1, 1)
review(3, r["easiness"], r["interval"], r["repetitions"], d)
```
<a name="testing">
## Testing
Assuming you [dowloaded the code and installed requirements](#download).
### Run the tests
```bash
pytest tests/
```
### Check test coverages
```bash
pytest --cov
```
Check coverage on [Codecov](https://codecov.io/gh/alankan886/SuperMemo2).
<a name="changelog">
## Changelog
3.0.1 (2024-06-22): Minor changes, Update recommended
- Forgot to update some code and tests from review_date to review_datetime, the returned dictionary was review_date instead review_datetime.
3.0.0 (2024-06-22): Major changes/rebuild, Update recommended
- Rewrote the code to remove the class structure, simplfying the code and usability.
- Update to provide datetime instead of just date, more specific with when to review.
2.0.0 (2021-03-28): Major changes/rebuild, Update recommended
- Rebuilt and simplfied the package.
1.0.3 (2021-01-30): Minor bug fix, Update recommended
- Re-evaluate the default date argument to first_review() on each call.
1.0.2 (2021-01-18): Major and Minor bug fix, Update recommended
- Add required attrs package version to setup.py.
- Allow users to access SMTwo model.
- Fix E-Factor calculation when q < 3.
1.0.1 (2021-01-02): Fix tests, update README and add Github actions, Update not required
- Add missing assertions to test_api.py.
- Update README badges and fix format.
- Add Github actions to run tests against Python versions 3.6 to 3.9 in different OS, and upload coverage to Codecov.
1.0.0 (2021-01-01): Complete rebuild, Update recommended
- Build a new SMTwo class using the attrs package.
- Provide API methods to quickly access the SMTwo class.
- Develop 100% coverage integration and unit tests in a TDD manner.
- Write new documentation.
0.1.0 (2020-07-14): Add tests, Update not required
- Add passing unit tests with a coverage of 100%.
0.0.4 (2020-07-10): Minor bug fix, Update recommended
- Fix interval calculation error when q < 3.
0.0.3 (2020-07-06): Documentation Update, Update not required
- Add new section about SM-2 in documentation, and fix some formats in README.
0.0.2 (2020-07-05): Refactor feature, Update recommended
- Refactor the supermemo2 algorithm code into a simpler structure, and remove unnecessary methods in the class.
0.0.1 (2020-07-02): Feature release
- Initial Release
<a name="credits">
## Credits
1. [pytest](https://docs.pytest.org/en/stable/)
2. [The SM-2 Algorithm](https://www.supermemo.com/en/archives1990-2015/english/ol/sm2)
Raw data
{
"_id": null,
"home_page": "https://github.com/alankan886/SuperMemo2",
"name": "supermemo2",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "spaced-repetition SM-2 SuperMemo Python",
"author": "Alan Kan",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a6/a3/6256c93b74ff78b590f819ace15068053a90ac7c5590e9d8d0ad44ca58bf/supermemo2-3.0.1.tar.gz",
"platform": null,
"description": "# SuperMemo2\n\n[](https://pypi.org/project/supermemo2/)\n[](https://github.com/alankan886/SuperMemo2/actions?query=workflow%3ACI)\n[](https://codecov.io/gh/alankan886/SuperMemo2)\n[](https://pepy.tech/project/supermemo2)\n\nA package that implemented the spaced repetition algorithm SM-2 for you to quickly calculate your next review date for whatever you are learning.\n\n\ud83d\udccc **Note:** The algorithm SM-2 doesn't equal to the computer implementation SuperMemo2. In fact, the 3 earliest implementations (SuperMemo1, SuperMemo2 and SuperMemo3) all used algorithm SM-2. I didn't notice that when I first published the package on PyPI, and I can't change the package name.\n\n\ud83d\udce6 [PyPI page](https://pypi.org/project/supermemo2/)\n\n## Table of Contents\n- [Motivation](#motivation)\n- [Installing and Supported Versions](#install-versions)\n- [A Simple Example](#example)\n- [Features](#features)\n- [What is SM-2?](#sm2)\n- [Code Reference](#code)\n- [Testing](#testing)\n- [Changelog](#changelog)\n- [Credits](#credits)\n\n<a name=\"motivation\">\n\n## Motivation\nThe goal was to have an efficient way to calculate the next review date for studying/learning. Removes the burden of remembering the algorithm, equations, and math from the users.\n\n<a name=\"install-versions\">\n\n## Installation and Supported Versions\n\n### Package Install\nInstall and upate the package using [pip](https://pip.pypa.io/en/stable/quickstart/):\n\n```bash\npip install -U supermemo2\n```\n\n<a name=\"download\">\n\n### To Play Around with the Code\nDownload the code:\n\n```bash\ngit clone https://github.com/alankan886/SuperMemo2.git\n```\n\nInstall dependencies to run the code:\n```bash\npip install -r requirements.txt\n```\n\nsupermemo2 supports Python 3.8+\n\n<a name=\"example\">\n\n## A Simple Example\n\n```python\nfrom supermemo2 import first_review, review\n\n# first review\n# using quality=4 as an example, read below for what each value from 0 to 5 represents\n# review date would default to datetime.utcnow() (UTC timezone) if not provided\nfirst_review = first_review(4, \"2024-06-22\")\n# first_review prints { \"easiness\": 2.36, \"interval\": 1, \"repetitions\": 1, \"review_datetime\": \"2024-06-23 01:06:02\"))\n\n# second review\nsecond_review = review(4, first_review[\"easiness\"], first_review[\"interval\"], first_review[\"repetitions\"], first_review[\"review_datetime\"])\n# or just unpack the first review dictionary\nsecond_review = review(4, **first_review)\n# second_review prints similar to example above.\n```\n\n<a name=\"features\">\n\n## Features\n\ud83d\udce3 Calculates the review date of the task following the SM-2 algorithm.\n<br/> \ud83d\udce3 The first_review method to calculate the review date at ease without having to know the initial values.\n\n<a name=\"sm2\">\n\n## What is SM-2?\n\ud83c\udfa5 If you are curious of what spaced repetition is, check this [short video](https://youtu.be/-uMMRjrzPmE?t=94) out.\n\n\ud83d\udccc A longer but interactive [article](https://ncase.me/remember/) on spaced repetition learning.\n\n\ud83d\udcce [The SM-2 Algorithm](https://www.supermemo.com/en/archives1990-2015/english/ol/sm2)\n\n### What are the \"values\"?\nThe values are the:\n\n- Quality: The quality of recalling the answer from a scale of 0 to 5.\n\t- 5: perfect response.\n\t- 4: correct response after a hesitation.\n\t- 3: correct response recalled with serious difficulty.\n\t- 2: incorrect response; where the correct one seemed easy to recall.\n\t- 1: incorrect response; the correct one remembered.\n\t- 0: complete blackout.\n- Easiness: The easiness factor, a multipler that affects the size of the interval, determine by the quality of the recall.\n- Interval: The gap/space between your next review.\n- Repetitions: The count of correct response (quality >= 3) you have in a row.\n\n<a name=\"code\">\n\n## Code Reference\n**first_review(** quality, review_datetime=None**)**\n\n function that calcualtes the next review datetime for the your first review without having to know the initial values, and returns a dictionary containing the new values.\n\n**Parameters:**\n- quality (int) - the recall quality of the review.\n- review_datetime (str or datetime.datetime) - optional parameter, the datetime in ISO format up to seconds in UTC timezone of the review.\n\n**Returns:** dictionary containing values like quality, easiness, interval, repetitions and review_datetime.\n\n**Return Type:** Dict\n\n**Usage:**\n```python\nfrom supermemo2 import first_review\n# using default datetime.utcnow() if you just reviewed it\nfirst_review(3)\n\n# providing string date in Year-Month-Day format\nfirst_review(3, \"2024-06-22\")\n\n# providing date object date\nfrom datetime import datetime\nd = datetime(2024, 1, 1)\nfirst_review(3, d)\n```\n\n**review(** quality, easiness, interval, repetitions, review_datetime=None **)**\n\n Calcualtes the next review date based on previous values, and returns a dictionary containing the new values.\n\n**Parameters:**\n- quality (int) - the recall quality of the review.\n- easiness (float) - the easiness determines the interval.\n- interval (int) - the interval between the latest review date and the next review date.\n- repetitions (int) - the count of consecutive reviews with quality larger than 2.\n- review_datetime (str or datetime.datetime) - optional parameter, the datetime in ISO format up to seconds in UTC timezone of the review.\n\n**Returns:** dictionary containing values like quality, easiness, interval, repetitions and review_datetime.\n\n**Return Type:** Dict\n\n**Usage:**\n```python\nfrom supermemo2 import first_review, review\n# using previous values from first_review call\nr = first_review(3)\n\n# using default datetime.utcnow() if you just reviewed it\nreview(3, r[\"easiness\"], r[\"interval\"], r[\"repetitions\"])\n\n# providing review_datetime from previous review\nreview(3, r[\"easiness\"], r[\"interval\"], r[\"repetitions\"], r[\"review_datetime\"])\n\n# providing string review_datetime\nreview(3, r[\"easiness\"], r[\"interval\"], r[\"repetitions\"], \"2024-01-01\")\n\n# providing datetime object review_datetime\nfrom datetime import datetime\nd = datetime(2024, 1, 1)\nreview(3, r[\"easiness\"], r[\"interval\"], r[\"repetitions\"], d)\n```\n\n<a name=\"testing\">\n\n## Testing\n\nAssuming you [dowloaded the code and installed requirements](#download).\n\n### Run the tests\n```bash\npytest tests/\n```\n\n### Check test coverages\n```bash\npytest --cov\n```\nCheck coverage on [Codecov](https://codecov.io/gh/alankan886/SuperMemo2).\n\n<a name=\"changelog\">\n\n## Changelog\n3.0.1 (2024-06-22): Minor changes, Update recommended\n- Forgot to update some code and tests from review_date to review_datetime, the returned dictionary was review_date instead review_datetime.\n\n3.0.0 (2024-06-22): Major changes/rebuild, Update recommended\n- Rewrote the code to remove the class structure, simplfying the code and usability.\n- Update to provide datetime instead of just date, more specific with when to review.\n\n2.0.0 (2021-03-28): Major changes/rebuild, Update recommended\n- Rebuilt and simplfied the package.\n\n1.0.3 (2021-01-30): Minor bug fix, Update recommended\n- Re-evaluate the default date argument to first_review() on each call.\n\n1.0.2 (2021-01-18): Major and Minor bug fix, Update recommended\n- Add required attrs package version to setup.py.\n- Allow users to access SMTwo model.\n- Fix E-Factor calculation when q < 3.\n\n1.0.1 (2021-01-02): Fix tests, update README and add Github actions, Update not required\n- Add missing assertions to test_api.py.\n- Update README badges and fix format.\n- Add Github actions to run tests against Python versions 3.6 to 3.9 in different OS, and upload coverage to Codecov.\n\n1.0.0 (2021-01-01): Complete rebuild, Update recommended\n- Build a new SMTwo class using the attrs package.\n- Provide API methods to quickly access the SMTwo class.\n- Develop 100% coverage integration and unit tests in a TDD manner.\n- Write new documentation.\n\n0.1.0 (2020-07-14): Add tests, Update not required\n- Add passing unit tests with a coverage of 100%.\n\n0.0.4 (2020-07-10): Minor bug fix, Update recommended\n- Fix interval calculation error when q < 3.\n\n0.0.3 (2020-07-06): Documentation Update, Update not required\n- Add new section about SM-2 in documentation, and fix some formats in README.\n\n0.0.2 (2020-07-05): Refactor feature, Update recommended\n- Refactor the supermemo2 algorithm code into a simpler structure, and remove unnecessary methods in the class.\n\n0.0.1 (2020-07-02): Feature release\n- Initial Release\n\n<a name=\"credits\">\n\n## Credits\n\n1. [pytest](https://docs.pytest.org/en/stable/)\n2. [The SM-2 Algorithm](https://www.supermemo.com/en/archives1990-2015/english/ol/sm2)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Implemented the SM-2 algorithm for spaced repetition learning.",
"version": "3.0.1",
"project_urls": {
"Homepage": "https://github.com/alankan886/SuperMemo2"
},
"split_keywords": [
"spaced-repetition",
"sm-2",
"supermemo",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48d391644269b83c2dd5fc71d2de11629c1253379af8cd1d1a690b21a3e29dcb",
"md5": "c3706b0aaeacdda55f9380ffe4f505f1",
"sha256": "123424550e416a23297dc3d0819a2448e3151698455e0d6e79f752f999f8c3c7"
},
"downloads": -1,
"filename": "supermemo2-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3706b0aaeacdda55f9380ffe4f505f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7156,
"upload_time": "2024-06-23T03:23:01",
"upload_time_iso_8601": "2024-06-23T03:23:01.236021Z",
"url": "https://files.pythonhosted.org/packages/48/d3/91644269b83c2dd5fc71d2de11629c1253379af8cd1d1a690b21a3e29dcb/supermemo2-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a6a36256c93b74ff78b590f819ace15068053a90ac7c5590e9d8d0ad44ca58bf",
"md5": "e4dd59c9fa7485c7d0f32b2087cb4efc",
"sha256": "928b1cf504033dba05ee6cd8db9e99b40a91f1db3e4aeb4e6eb59c01e58e7e61"
},
"downloads": -1,
"filename": "supermemo2-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "e4dd59c9fa7485c7d0f32b2087cb4efc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6742,
"upload_time": "2024-06-23T03:23:02",
"upload_time_iso_8601": "2024-06-23T03:23:02.695149Z",
"url": "https://files.pythonhosted.org/packages/a6/a3/6256c93b74ff78b590f819ace15068053a90ac7c5590e9d8d0ad44ca58bf/supermemo2-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-23 03:23:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alankan886",
"github_project": "SuperMemo2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest-cov",
"specs": [
[
"==",
"2.10.1"
]
]
},
{
"name": "freezegun",
"specs": [
[
"==",
"1.5.1"
]
]
}
],
"lcname": "supermemo2"
}
JSON
