# cligame
Lightweight python library to easily create CLI interactive games to learn or practice new concepts,
without having to worry about the game related aspects such as score or timers.
## Why?
When attempting to learn something quickly, it is often useful to quiz oneself repeatedly.
This library makes life easier by abstracting away the elements surrounding the game itself,
such as score, mistakes, streaks, time, etc.
With this library, it is easy and frictionless to quickly create a CLI game and start training as soon as possible,
knowing that the user experinence will be consitent and adequate from the get-go.
### Modes
The currently supported game modes are as follows:
- Timed mode. Game ends when timer runs out.
- Number of questions mode. Game ends after certain number of questions, regardless of right or wrong answer.
- Score mode. Game ends when a certain score is reached.
- Mistake mode. Game ends after a certain number of errors are made.
- Consecutive mode. Game ends after correctly answering a determined number of questions in a row.
## Usage
- install the library:
`pip install cligame`
- create a script that asks questions based on your logic
```python
### myscript.py ###
from cligame import Game
from random import randint
# create a function with the following signature: (bool) => (bool, str)
# in this example we ignore the bool that is passed in
def ask_question(_):
x, y = randint(1, 10), randint(1, 10)
ans = input(f"What is {x} + {y}? ")
correct_ans = str(x + y)
return ans == correct_ans, correct_ans
# initizlize a Game object with that function, and start the game
mygame = Game(ask_question)
mygame.start()
```
- run the script:
`python myscript.py`
That's it! Upon running the program, you will be prompted to choose a game mode and will be quizzed accordingly.
## Explanation
The user must provide a function that:
- takes in a boolean `repeat`
- this indicates if the same question as last time should be asked again
- for now, this functionallity must be implemented by the user
- returns a boolean and a string
- the boolean indicates whether the correct answer was given
- the string represents either the correct answer or an explanation on how to get the correct answer.
- this will be shown to the user upon a wrong answer unless `noexplain` is enabled.
Let's see a more complete example of the above function
```python
x, y = randint(1, 10), randint(1, 10)
def ask_question(repeat):
global x, y
if not repeat:
x, y = randint(1, 10), randint(1, 10)
ans = input(f"What is {x} + {y}? ")
correct_ans = str(x + y)
return ans == correct_ans, f"the correct answer was '{correct_ans}', but '{ans}' was given"
```
## Command-line arguments
(run `python myscript.py --help` to see all options)
Once you've become familiar with the different game modes, you can quick-start a game by passing command-line arguments:
- `python myscript.py t 5` will start a 5 minute game.
- `python myscript.py c 10` will start a game that ends after correctly answering 10 questions in a row.
### Further configuration
You can customize different aspects of the game using the following flags:
- `-E` or `--noexplain` to disable explanations. Upon answering a question incorrectly, the correct answer won't be shown.
- `-q` or `--quiet` to disable feedback. After answering a question, there will be no indication whether the answer was correct or not (implies `noexplain`)
- `-r` or `--repeat` to enable repetition. Upon answering a question incorrectly, the same question will be asked until the correct answer is given. Currently, this must be handled by the function created by the user, as indicated by the `repeated` argument (implies `noexplian`)
## Stats logging
If you want to keep track of your performance to track your progress over time, call the `save_raw` function after the game is done:
```python
mygame = Game(ask_question)
mygame.start()
mygame.save_raw("my_stats.json")
```
- If no filename is provided, "stats.json" will be used by default
- if using this package with multiple games, be careful to store the stats in different files!
In the future, this package will implement modules to analize the resulting output
# TODO
- move `repeat` to game logic
- configuration without command-line arguments
- add submodes
- add more stats logging options
- add stats analizer
- add spaced repetition
Raw data
{
"_id": null,
"home_page": "https://github.com/Alex23rodriguez/cligame",
"name": "cligame",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python,cli,game,interactive,cligame,terminal,learn",
"author": "Alex Rodriguez",
"author_email": "alex.rodriguez.oro@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/28/d7/67b41fd949eab484d4d0ab083d2fe11214b4014262b818019ab7fdc87b53/cligame-0.2.2.tar.gz",
"platform": null,
"description": "# cligame\n\nLightweight python library to easily create CLI interactive games to learn or practice new concepts,\nwithout having to worry about the game related aspects such as score or timers.\n\n## Why?\n\nWhen attempting to learn something quickly, it is often useful to quiz oneself repeatedly.\nThis library makes life easier by abstracting away the elements surrounding the game itself,\nsuch as score, mistakes, streaks, time, etc.\n\nWith this library, it is easy and frictionless to quickly create a CLI game and start training as soon as possible,\nknowing that the user experinence will be consitent and adequate from the get-go.\n\n### Modes\n\nThe currently supported game modes are as follows:\n\n- Timed mode. Game ends when timer runs out.\n- Number of questions mode. Game ends after certain number of questions, regardless of right or wrong answer.\n- Score mode. Game ends when a certain score is reached.\n- Mistake mode. Game ends after a certain number of errors are made.\n- Consecutive mode. Game ends after correctly answering a determined number of questions in a row.\n\n## Usage\n\n- install the library:\n\n`pip install cligame`\n\n- create a script that asks questions based on your logic\n\n```python\n### myscript.py ###\n\nfrom cligame import Game\nfrom random import randint\n\n# create a function with the following signature: (bool) => (bool, str)\n# in this example we ignore the bool that is passed in\ndef ask_question(_):\n x, y = randint(1, 10), randint(1, 10)\n ans = input(f\"What is {x} + {y}? \")\n correct_ans = str(x + y)\n return ans == correct_ans, correct_ans\n\n# initizlize a Game object with that function, and start the game\nmygame = Game(ask_question)\nmygame.start()\n```\n\n- run the script:\n `python myscript.py`\n\nThat's it! Upon running the program, you will be prompted to choose a game mode and will be quizzed accordingly.\n\n## Explanation\n\nThe user must provide a function that:\n\n- takes in a boolean `repeat`\n - this indicates if the same question as last time should be asked again\n - for now, this functionallity must be implemented by the user\n- returns a boolean and a string\n - the boolean indicates whether the correct answer was given\n - the string represents either the correct answer or an explanation on how to get the correct answer.\n - this will be shown to the user upon a wrong answer unless `noexplain` is enabled.\n\nLet's see a more complete example of the above function\n\n```python\nx, y = randint(1, 10), randint(1, 10)\ndef ask_question(repeat):\n global x, y\n if not repeat:\n x, y = randint(1, 10), randint(1, 10)\n\n ans = input(f\"What is {x} + {y}? \")\n correct_ans = str(x + y)\n return ans == correct_ans, f\"the correct answer was '{correct_ans}', but '{ans}' was given\"\n```\n\n## Command-line arguments\n\n(run `python myscript.py --help` to see all options)\n\nOnce you've become familiar with the different game modes, you can quick-start a game by passing command-line arguments:\n\n- `python myscript.py t 5` will start a 5 minute game.\n- `python myscript.py c 10` will start a game that ends after correctly answering 10 questions in a row.\n\n### Further configuration\n\nYou can customize different aspects of the game using the following flags:\n\n- `-E` or `--noexplain` to disable explanations. Upon answering a question incorrectly, the correct answer won't be shown.\n- `-q` or `--quiet` to disable feedback. After answering a question, there will be no indication whether the answer was correct or not (implies `noexplain`)\n- `-r` or `--repeat` to enable repetition. Upon answering a question incorrectly, the same question will be asked until the correct answer is given. Currently, this must be handled by the function created by the user, as indicated by the `repeated` argument (implies `noexplian`)\n\n## Stats logging\n\nIf you want to keep track of your performance to track your progress over time, call the `save_raw` function after the game is done:\n\n```python\nmygame = Game(ask_question)\nmygame.start()\nmygame.save_raw(\"my_stats.json\")\n```\n\n- If no filename is provided, \"stats.json\" will be used by default\n - if using this package with multiple games, be careful to store the stats in different files!\n\nIn the future, this package will implement modules to analize the resulting output\n\n# TODO\n\n- move `repeat` to game logic\n- configuration without command-line arguments\n- add submodes\n- add more stats logging options\n- add stats analizer\n- add spaced repetition\n",
"bugtrack_url": null,
"license": "",
"summary": "Python library to easily create CLI interactive games to learn or practice new concepts, without having to worry about the game related aspects such as score or timers",
"version": "0.2.2",
"split_keywords": [
"python",
"cli",
"game",
"interactive",
"cligame",
"terminal",
"learn"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "57e69621aa2261ca0177e1ee4a31ce35456b8e0c1ae918d467c1d688591eb835",
"md5": "1dee4b80bc14a801b4cbd219f43f3e98",
"sha256": "2a3737ed6d6e9c9d5c82dd8a63a0372ff85016835f6ac477c0e9f63e647a0241"
},
"downloads": -1,
"filename": "cligame-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1dee4b80bc14a801b4cbd219f43f3e98",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17425,
"upload_time": "2023-04-01T17:53:17",
"upload_time_iso_8601": "2023-04-01T17:53:17.511797Z",
"url": "https://files.pythonhosted.org/packages/57/e6/9621aa2261ca0177e1ee4a31ce35456b8e0c1ae918d467c1d688591eb835/cligame-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "28d767b41fd949eab484d4d0ab083d2fe11214b4014262b818019ab7fdc87b53",
"md5": "59ef3e8f7284fcb572fe744d0a0a9b11",
"sha256": "91cabf54f8bdf2f83aa14692682a444a62662e04421908575eba51d68b946115"
},
"downloads": -1,
"filename": "cligame-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "59ef3e8f7284fcb572fe744d0a0a9b11",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17167,
"upload_time": "2023-04-01T17:53:19",
"upload_time_iso_8601": "2023-04-01T17:53:19.644413Z",
"url": "https://files.pythonhosted.org/packages/28/d7/67b41fd949eab484d4d0ab083d2fe11214b4014262b818019ab7fdc87b53/cligame-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-01 17:53:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Alex23rodriguez",
"github_project": "cligame",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cligame"
}
JSON
