reformat code, add linting CI, bump to 0.3.2, fix README.md

Author: icedevml

.github/workflows/lint.yml

@@ -0,0 +1,30 @@
+name: Python application
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8
+        pip install ./
+    - name: Check CLI commands
+      run: |
+        ksef_auth_file --help
+        ksef_auth_pkcs11 --help
+        p11_list_objects --help
+        p11_list_tokens --help
+    - name: Lint with flake8
+      run: |
+        flake8 src/pyksef --max-line-length=120

README.md

@@ -1,9 +1,12 @@
 # Python KSeF Authentication Library (for PKCS#11 and local private keys)
 
-> [!NOTE]  
-> PL: Biblioteka do języka Python obsługująca logowanie do KSeF z użyciem dowolnego klucza prywatnego obsługującego interfejs PKCS#11 – kwalifikowane podpisy i pieczęci elektroniczne (na karcie, tokenie USB lub w formie HSM), a także certyfikaty wydane przez KSeF, do których klucze prywatne przechowywane są na HSMie (np. YubiHSM, YubiKey, Google Cloud KMS). Obsługuje również klasyczne uwierzytelnianie kluczem przechowywanym lokalnie na dysku twardym w pliku `.key` (format PEM).
+## (PL) Opis
 
-Supported features:
+Biblioteka do Pythona implementująca logowanie do Krajowego Systemu e-Faktur (KSeF) z użyciem dowolnego klucza prywatnego obsługującego interfejs PKCS#11.
+Obsługuje kwalifikowane podpisy i pieczęci elektroniczne w dowolnej postaci (na karcie, tokenie USB lub w formie HSM), a także certyfikaty wydane przez KSeF, do których klucze prywatne przechowywane są na HSMie (np. YubiHSM, YubiKey, Google Cloud KMS). Biblioteka wspiera  również klasyczne uwierzytelnianie kluczem przechowywanym lokalnie na dysku twardym w pliku `.key` (format PEM).
+
+
+## Supported features
 
 * Authentication using private keys available through PKCS#11 interface:
   * Qualified signature or qualified seal issued on a physical device,
@@ -293,10 +296,12 @@ ksef_auth_file \
 
 ## Troubleshooting
 
-If you see the following exception even though the DLL physically exists at the path indicated:
+In case if you see the following exception even though the DLL physically exists at the path indicated:
 
 ```
 pkcs11.exceptions.PKCS11Error: OS exception while loading <file path>.dll: The specified module could not be found.
 ```
 
-please check if your `PATH` environment variable is set correctly. Your PKCS#11 DLL might depend on some auxiliary DLLs that are unavailable.
+Please check if your `PATH` environment variable is set correctly. The error is actually due to the fact that your PKCS#11 DLL tries to load other DLLs that couldn't be located within the `PATH`.
+
+If your PKCS#11 library comes with other required DLL files that are all hosted within the same directory, it is going to help when you add the directory of your PKCS#11 library to `PATH` environment variable.

pyproject.toml

@@ -4,24 +4,24 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyksef"
-version = "0.3.1"
+version = "0.3.2"
 description = "KSeF Authentication library"
 readme = "README.md"
 authors = [
     {name = "Michał Leszczyński", email = "ml@icedev.pl"}
 ]
 license = {text = "MIT"}
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
     "requests>=2.32.5",

src/pyksef/__init__.py

@@ -1,6 +1,6 @@
-"""KSeF XAdES Authentication Library"""
+"""Python KSeF Authentication Library (for PKCS#11 and local private keys)"""
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 
 from pyksef.auth import ksef_auth_xades
 

src/pyksef/auth/__init__.py

@@ -1 +1 @@
-from pyksef.auth.xades_auth import ksef_auth_xades
+from pyksef.auth.xades_auth import ksef_auth_xades  # noqa: F401

src/pyksef/auth/state.py

@@ -14,7 +14,8 @@ class KSEFAuthFailError(RuntimeError):
     def __init__(self, auth_state):
         status_code = auth_state["status"]["code"]
         auth_state_str = json.dumps(auth_state)
-        super(KSEFAuthFailError, self).__init__(f"Authentication failed with status code: {status_code}: {auth_state_str}")
+        super(KSEFAuthFailError, self).__init__(
+            f"Authentication failed with status code: {status_code}: {auth_state_str}")
         self.auth_state = auth_state
 
 
@@ -38,8 +39,8 @@ def ksef_poll_auth_finalized(
         api_base_url: str,
         reference_number: str,
         authentication_token: str,
-        poll_interval: float=1.0,
-        timeout: float=120.0) -> dict:
+        poll_interval: float = 1.0,
+        timeout: float = 120.0) -> dict:
     if poll_interval < 0.1:
         raise ValueError("Poll interval is smaller than 0.1s")
 

src/pyksef/auth/xades_auth.py

@@ -13,8 +13,11 @@
 
 def _build_xml(challenge: str, context_id: ContextIdentifier,
                subject_id_type: SubjectIdentifierType) -> etree.ElementTree:
+    root_ns = ('xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" '
+               'xmlns:xsd="http://www.w3.org/2001/XMLSchema" '
+               'xmlns="http://ksef.mf.gov.pl/auth/token/2.0"')
     data = f"""<?xml version="1.0" encoding="utf-8"?>
-    <AuthTokenRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://ksef.mf.gov.pl/auth/token/2.0">
+    <AuthTokenRequest {root_ns}>
         <Challenge>{challenge}</Challenge>
         <ContextIdentifier>
             {context_id.serialize()}

src/pyksef/cli/ksef_auth_file.py

@@ -42,7 +42,8 @@ def cli():
                         help="Optional: 'nip' (default), 'nipVatUe', or 'internalId'.")
     parser.add_argument("--context-id", required=True, help="Context identifier to authenticate against.")
     parser.add_argument("--subject-id-type", default="certificateSubject",
-                        help="Optional: Subject identifier type: 'certificateSubject' (default) or 'certificateFingerprint'.")
+                        help="Optional: Subject identifier type: 'certificateSubject' (default) "
+                             "or 'certificateFingerprint'.")
     args = parser.parse_args()
 
     context_id = ContextIdentifier(

src/pyksef/cli/ksef_auth_pkcs11.py

@@ -48,16 +48,19 @@ def cli():
     parser.add_argument("--key-id", help="Private key ID (hex).")
     parser.add_argument("--key-label", help="Private key label.")
     parser.add_argument("--user-pin",
-                        help="Optional: User PIN to login to the token. You will be interactively prompted for PIN if this argument is not provided.")
+                        help="Optional: User PIN to login to the token. You will be interactively prompted for "
+                             "PIN if this argument is not provided.")
     parser.add_argument("--cert-file",
-                        help="Optional: File path for X.509 PEM Certificate file. If not provided, we will try to load it from the token (device) itself.")
+                        help="Optional: File path for X.509 PEM Certificate file. If not provided, we will try "
+                             "to load it from the token (device) itself.")
     parser.add_argument("--api-base-url", default="https://api.ksef.mf.gov.pl/v2",
                         help="Optional: KSeF API base url. Default: https://api.ksef.mf.gov.pl/v2")
     parser.add_argument("--context-id-type", default="nip",
                         help="Optional: 'nip' (default), 'nipVatUe', or 'internalId'.")
     parser.add_argument("--context-id", required=True, help="Context identifier to authenticate against.")
     parser.add_argument("--subject-id-type", default="certificateSubject",
-                        help="Optional: Subject identifier type: 'certificateSubject' (default) or 'certificateFingerprint'.")
+                        help="Optional: Subject identifier type: 'certificateSubject' (default) "
+                             "or 'certificateFingerprint'.")
     args = parser.parse_args()
 
     context_id = ContextIdentifier(

src/pyksef/cli/p11_list_objects.py

@@ -36,9 +36,12 @@ def cli():
     parser.add_argument("--token-label", help="Token's label.")
     parser.add_argument("--token-serial", help="Token's serial number (hex).")
     parser.add_argument("--user-pin",
-                        help="Optional: User PIN to login to the token. You will be interactively prompted for PIN if this argument is not provided.")
+                        help="Optional: User PIN to login to the token. You will be interactively prompted "
+                             "for PIN if this argument is not provided.")
     parser.add_argument("--output", choices=["list", "certificates"], default="list",
-                        help="Output type. For 'list' will output a list of certificates and private keys available with certain PKCS#11 token. For 'certificates' it will dump all available certificates in the PEM format.")
+                        help="Output type. For 'list' will output a list of certificates and private keys available "
+                             "with certain PKCS#11 token. For 'certificates' it will dump all available certificates "
+                             "in the PEM format.")
     args = parser.parse_args()
 
     token_serial = None