Finalize major update

README.md

@@ -11,12 +11,12 @@ pinned: True
 
 # Welcome to Chessli2 🏰
 
-[Chessli2](https://github.com/pwenker/chessli2) is your **always free** and **open-source** chess trainer 🛡️, designed to elevate your game by allowing you to analyze games, identify mistakes, and sharpen your tactics, all sourced directly from [lichess.org](https://lichess.org/).
+[chessli2](https://github.com/pwenker/chessli2) is your **always free** and **open-source** chess trainer 🛡️, designed to elevate your game by allowing you to analyze games, identify mistakes, and sharpen your tactics, all sourced directly from [lichess.org](https://lichess.org/).
 
 ## Why a second version?
 
-Incredibly, despite my prolonged absence, I continue to receive heartfelt 💌 thank you notes and eager requests for `chessli`. 
-This overwhelming support has inspired me to develop a sleek new version of Chessli that not only squashes all those pesky bugs 🐛 but also introduces a user-friendly graphical interface. This means no programming experience is required to dive in!
+Incredibly, despite my prolonged absence, I continue to receive heartfelt 💌 thank you notes and eager requests for [chessli](https://github.com/pwenker/chessli). 
+This overwhelming support has inspired me to develop a sleek new version of `chessli` that not only squashes all those pesky bugs 🐛 but also introduces a user-friendly graphical interface. This means no programming experience is required to dive in!
 
 ## Features 🌟
 
@@ -29,7 +29,7 @@ Chessli2 is here to support your journey to becoming a chess master. Dive in and
 
 ## Quickstart 🚀
 
-### 👉 Click here to try out the app directly:
+### 👉 Click here to try out the app directly without any setup:
 [**Chessli2**](https://pwenker-chessli2.hf.space/)
 
 ### 🔍 Inspect code at:
@@ -65,6 +65,9 @@ For more details, visit: [Basics - Rye](https://rye-up.com/guide/basics/)
 
 ### Start the App 🌟
 
+> [!NOTE]  
+> If you choose to install `chessli2` without `rye`, or in case you activate the rye shell with `rye shell`, just omit `rye run` for the following commands.
+
 Launch the app using:
 ```
 rye run python src/chessli2/app.py
@@ -72,6 +75,21 @@ rye run python src/chessli2/app.py
 
 Finally, open your browser and visit [http://localhost:7860](http://localhost:7860/) to start practicing!
 
+
+## Programmatic Access
+
+### API endpoints
+Thanks to [Gradio](https://www.gradio.app/), you can find an API documentation for `chessli2` at [Chessli2 API](https://pwenker-chessli2.hf.space/?view=api).
+
+### CLI
+
+There is also a CLI, for usage information type:
+```
+rye run chessli2 --help
+```
+
+For complete usage information of all commands and options, take a look at the CLI documentation at [docs/cli.md](docs/cli.md).
+
 ## FAQ
 
 ### 🗝️ How to Obtain Your Lichess API Token

docs/cli.md

@@ -0,0 +1,77 @@
+# `chessli2`
+
+**Usage**:
+
+```console
+$ chessli2 [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `mistakes`: Fetches mistakes from the API based on the...
+* `puzzles`: Fetches puzzles from the API based on the...
+* `serve`: Starts the app and serves it given...
+
+## `chessli2 mistakes`
+
+Fetches mistakes from the API based on the specified parameters.
+
+**Usage**:
+
+```console
+$ chessli2 mistakes [OPTIONS]
+```
+
+**Options**:
+
+* `--src TEXT`: Select either the name of the Hugging Face Space to load, (e.g. "pwenker/chessli2") or the full URL (including "http" or "https") of the hosted Gradio app to load (e.g. "http://localhost:7860/" or "https://bec81a83-5b5c-471e.gradio.live/  [default: pwenker/chessli2]
+* `--lichess-api-token TEXT`: Select lichess API token  [default: lip_5tGPs3qUPcYoWpSnEZfH]
+* `--user-name TEXT`: Select user name  [default: pwenker]
+* `--start-date TEXT`: Select start date (YYYY-MM-DD)  [default: 2017-05-14]
+* `--end-date TEXT`: Select end date (YYYY-MM-DD)  [default: 2024-05-14]
+* `--nags INTEGER`: Filter by mistake nag type (blunder=4, mistake=2, speculative=5, dubious=6)  [default: 4, 2]
+* `--time-control [Bullet|Blitz|Rapid|Classical|UltraBullet|All Time Controls]`: Filter by time control  [default: All Time Controls]
+* `--output [file|info|pgn]`: Select whether to output mistakes as markdown table, as PGN string, or file path of CSV file containing PGNS  [default: file]
+* `--help`: Show this message and exit.
+
+## `chessli2 puzzles`
+
+Fetches puzzles from the API based on the specified parameters.
+
+**Usage**:
+
+```console
+$ chessli2 puzzles [OPTIONS]
+```
+
+**Options**:
+
+* `--src TEXT`: Select either the name of the Hugging Face Space to load, (e.g. 'pwenker/chessli2') or the full URL (including 'http' or 'https') of the hosted Gradio app to load (e.g. 'http://localhost:7860/' or 'https://bec81a83-5b5c-471e.gradio.live/')  [default: http://pwenker.github.io/chessli2/]
+* `--lichess-api-token TEXT`: Select lichess API token  [default: lip_5tGPs3qUPcYoWpSnEZfH]
+* `--before TEXT`: Only get puzzle activity before this date (format YYYY-MM-DD)  [default: 2024-05-15]
+* `--max INTEGER`: Select maxmimum number of puzzles  [default: 100]
+* `--themes [Advanced pawn|Advantage|Anastasia's mate|Arabian mate|Attacking f2 or f7|Attraction|Back rank mate|Bishop endgame|Boden's mate|Castling|Capture the defender|Crushing|Double bishop mate|Dovetail mate|Equality|Kingside attack|Clearance|Defensive move|Deflection|Discovered attack|Double check|Endgame|Exposed king|Fork|Hanging piece|Hook mate|Interference|Intermezzo|Knight endgame|Long puzzle|Master games|Master vs Master games|Checkmate|Mate in 1|Mate in 2|Mate in 3|Mate in 4|Mate in 5 or more|Middlegame|One-move puzzle|Opening|Pawn endgame|Pin|Promotion|Queen endgame|Queen and Rook|Queenside attack|Quiet move|Rook endgame|Sacrifice|Short puzzle|Skewer|Smothered mate|Super GM games|Trapped piece|Underpromotion|Very long puzzle|X-Ray attack|Zugzwang|Healthy mix|Player games]`: Filter by puzzle themes  [default: Advanced pawn, Advantage, Anastasia's mate, Arabian mate, Attacking f2 or f7, Attraction, Back rank mate, Bishop endgame, Boden's mate, Castling, Capture the defender, Crushing, Double bishop mate, Dovetail mate, Equality, Kingside attack, Clearance, Defensive move, Deflection, Discovered attack, Double check, Endgame, Exposed king, Fork, Hanging piece, Hook mate, Interference, Intermezzo, Knight endgame, Long puzzle, Master games, Master vs Master games, Checkmate, Mate in 1, Mate in 2, Mate in 3, Mate in 4, Mate in 5 or more, Middlegame, One-move puzzle, Opening, Pawn endgame, Pin, Promotion, Queen endgame, Queen and Rook, Queenside attack, Quiet move, Rook endgame, Sacrifice, Short puzzle, Skewer, Smothered mate, Super GM games, Trapped piece, Underpromotion, Very long puzzle, X-Ray attack, Zugzwang, Healthy mix, Player games]
+* `--output [file|info|pgn]`: Select whether to output info about mistakes, mistakes as PGN string, or a file path of CSV file containing PGNs  [default: file]
+* `--help`: Show this message and exit.
+
+## `chessli2 serve`
+
+Starts the app and serves it given specified `server_name` and `server_port`.
+
+**Usage**:
+
+```console
+$ chessli2 serve [OPTIONS]
+```
+
+**Options**:
+
+* `--server-name TEXT`: To make app accessible on local network, set this to '0.0.0.0'. Can be set by environment variable GRADIO_SERVER_NAME. If None, will use '127.0.0.1  [default: 127.0.0.1]
+* `--server-port INTEGER`: Will start gradio app on this port (if available). Can be set by environment variable GRADIO_SERVER_PORT. If None, will search for an available port starting at 7860.  [default: 7860]
+* `--help`: Show this message and exit.

src/chessli2/cli.py

@@ -72,7 +72,7 @@ def mistakes(
     elif output == Output.pgn:
         print(mistake_pgns)
     elif output == Output.file:
-        print(mistake_csv["value"])
+        print(mistake_csv.get("value", "No mistakes found"))
 
 
 @app.command()
@@ -107,6 +107,7 @@ def puzzles(
         before=before,
         max=max,
         themes_selection=themes,
+        lichess_api_token=lichess_api_token,
         api_name="/get_puzzles",
     )
 
@@ -115,7 +116,7 @@ def puzzles(
     elif output == Output.pgn:
         print(puzzle_pgns)
     elif output == Output.file:
-        print(puzzle_csv["value"])
+        print(puzzle_csv.get("value", "No puzzles found"))
 
 
 if __name__ == "__main__":

tests/test_cli.py

@@ -6,10 +6,10 @@ from chessli2.settings import settings
 
 runner = CliRunner()
 
-sources = ["pwenker/chessli2", "http://localhost:7860"]
+sources = ["pwenker/chessli2"]  # , "http://localhost:7860"]
 
 
-@pytest.mark.parametrize("src", ["http://localhost:7860"])
+@pytest.mark.parametrize("src", sources)
 def test_mistakes_with_options(src):
     result = runner.invoke(
         app,
@@ -38,7 +38,7 @@ def test_mistakes_with_options(src):
     assert result.exit_code == 0
 
 
-@pytest.mark.parametrize("src", ["http://localhost:7860"])
+@pytest.mark.parametrize("src", sources)
 def test_puzzles_with_options(src):
     """
     chessli puzzles --src http://localhost:7860  --user-name pwenker --before 2024-05-14 --max 100 --output file
@@ -54,10 +54,9 @@ def test_puzzles_with_options(src):
             "--before",
             "2024-05-14",
             "--max",
-            '10',
+            10,
             "--output",
             "file",
         ],
     )
-    __import__('pdb').set_trace()
     assert result.exit_code == 0