Merge pull request #36 from smekcio/fix/optional-cli-bootstrap

fix(cli): bootstrap optional CLI dependencies

Author: smekcio

.github/workflows/publish-pypi.yml

@@ -60,6 +60,10 @@ jobs:
         run: |
           python -m pytest --cov=ksef_client --cov-report=term-missing --cov-fail-under=100
 
+      - name: Check CLI packaging
+        run: |
+          python tools/check_cli_packaging.py
+
       - name: Build
         run: |
           python -m build

.github/workflows/python-application.yml

@@ -60,11 +60,16 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install -r requirements-dev.txt
+          python -m pip install build
 
       - name: Run tests
         run: |
           python -m pytest --cov=ksef_client --cov-fail-under=100 --cov-report=term-missing --cov-report=xml --cov-report=html
 
+      - name: Check CLI packaging
+        run: |
+          python tools/check_cli_packaging.py
+
       - name: Upload coverage artifact
         uses: actions/upload-artifact@v4
         with:

README.md

@@ -39,7 +39,7 @@ Aktualna kompatybilność: **KSeF API `v2.3.0`** ([api-changelog.md](https://git
 
 Wymagania: Python `>= 3.10`.
 
-Podstawowe SDK:
+Podstawowe SDK (bez zależności CLI):
 
 ```bash
 pip install ksef-client
@@ -61,10 +61,19 @@ pip install "ksef-client[xml,qr,cli]"
 - `qr` - generowanie PNG z kodami QR przez `qrcode` i `pillow`
 - `cli` - interfejs wiersza poleceń oparty o `typer`, `rich`, `keyring`
 
+Po podstawowej instalacji `pip install ksef-client` pakiet SDK jest gotowy do użycia, ale komenda `ksef`
+zwróci kontrolowany komunikat o brakujących zależnościach CLI. Aby uruchamiać CLI, doinstaluj extra `cli`.
+
 ## 🚀 Szybki start: CLI
 
 CLI `ksef` zostało zaprojektowane tak, aby skrócić wejście w SDK do minimum.
 
+Najpierw zainstaluj zależności CLI:
+
+```bash
+pip install "ksef-client[cli]"
+```
+
 1. Utwórz i aktywuj profil:
 
 ```bash
@@ -104,6 +113,17 @@ Najważniejsze grupy komend:
 
 Pełna specyfikacja CLI: [`docs/cli/README.md`](docs/cli/README.md)
 
+## 🛠️ Troubleshooting CLI
+
+Jeśli po `pip install ksef-client` uruchomisz `ksef`, komenda nie zakończy się tracebackiem, tylko czytelną
+instrukcją doinstalowania CLI:
+
+```text
+Install CLI dependencies with: pip install "ksef-client[cli]"
+```
+
+To zachowanie jest celowe: bazowa instalacja obejmuje SDK, a CLI pozostaje opcjonalne.
+
 ## 🧩 Szybki start: SDK
 
 Minimalny przebieg integracji:

docs/README.md

@@ -22,12 +22,16 @@ pip install -e .
 Opcjonalne dodatki (extras):
 
 ```bash
-pip install -e .[xml,qr]
+pip install -e .[cli,xml,qr]
 ```
 
+- `cli` – komenda `ksef` i zależności CLI (`typer`, `rich`, `keyring`)
 - `xml` – podpis XAdES (`lxml`, `xmlsec`)
 - `qr` – generowanie PNG z kodami QR (`qrcode`, `pillow`)
 
+Jeżeli pracujesz tylko z API Pythona, `pip install -e .` wystarcza. Do pracy z CLI użyj `pip install -e .[cli]`
+albo pełnego zestawu extras.
+
 ## Struktura SDK
 
 Biblioteka udostępnia dwa poziomy użycia:

docs/cli/README.md

@@ -38,7 +38,7 @@ CLI ma skracac droge od instalacji do pierwszej realnej operacji KSeF:
 1. Instalacja:
 
 ```bash
-pip install -e .
+pip install -e .[cli]
 ```
 
 2. Inicjalizacja profilu:
@@ -63,6 +63,17 @@ ksef send online --invoice ./fa.xml --wait-upo --save-upo ./out/upo-online.xml
 ksef invoice download --ksef-number <KSEF_NUMBER> --out ./out/
 ```
 
+## Troubleshooting
+
+Bazowa instalacja `pip install -e .` albo `pip install ksef-client` nie instaluje zależności CLI.
+W takim przypadku uruchomienie `ksef` kończy się kontrolowanym komunikatem:
+
+```text
+Install CLI dependencies with: pip install "ksef-client[cli]"
+```
+
+To zachowanie jest poprawne. Aby korzystać z CLI, doinstaluj extra `cli`.
+
 ## Drzewo komend
 
 ```text

pyproject.toml

@@ -43,7 +43,7 @@ Documentation = "https://github.com/smekcio/ksef-client-python/blob/main/docs/RE
 Issues = "https://github.com/smekcio/ksef-client-python/issues"
 
 [project.scripts]
-ksef = "ksef_client.cli.app:app_entrypoint"
+ksef = "ksef_client.cli.bootstrap:app_entrypoint"
 
 [tool.setuptools]
 package-dir = {"" = "src"}

requirements-dev.txt

@@ -1,4 +1,7 @@
 -r requirements.txt
+typer>=0.12.0
+rich>=13.7.0
+keyring>=25.0.0
 pytest>=8.0.0
 pytest-cov>=5.0.0
 ruff>=0.6.0

requirements.txt

@@ -1,5 +1,2 @@
 httpx>=0.27.0
 cryptography>=42.0.0
-typer>=0.12.0
-rich>=13.7.0
-keyring>=25.0.0

src/ksef_client/cli/__init__.py

@@ -1,5 +1,15 @@
 """CLI package for ksef-client."""
 
-from .app import app, app_entrypoint
-
 __all__ = ["app", "app_entrypoint"]
+
+
+def __getattr__(name: str):
+    if name == "app":
+        from .bootstrap import get_app
+
+        return get_app()
+    if name == "app_entrypoint":
+        from .bootstrap import app_entrypoint
+
+        return app_entrypoint
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/ksef_client/cli/__main__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from .app import app_entrypoint
+from .bootstrap import app_entrypoint
 
 if __name__ == "__main__":
     app_entrypoint()