Add type hints and py.typed marker (PEP 561)

Annotate the whole codebase (client, main GrobidClient, the TEI2LossyJSON and
TEI2Markdown converters, the CLIs and the validator) and ship a py.typed marker
so type checkers pick up the inline hints. Each module uses
'from __future__ import annotations' so annotations stay lazy and cannot affect
runtime behavior (and remain valid on Python 3.8).

Packaging:
- add grobid_client/py.typed and expose it via package-data and MANIFEST.in
- include the grobid_client.format subpackage in the distribution
- add a [tool.mypy] section (ignore missing third-party stubs; relax the
  BeautifulSoup-heavy converter modules whose dynamic API yields false positives)

CI:
- install mypy and run 'mypy grobid_client' in the build workflow (on 3.11)

mypy runs clean on the package and the existing test-suite still passes.

Closes #71

Author: lfoppiano

.github/workflows/ci-build.yml

@@ -30,14 +30,18 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install --upgrade flake8 pytest pycodestyle pytest-cov pytest-mock
+          pip install --upgrade flake8 pytest pycodestyle pytest-cov pytest-mock "mypy==2.3.*"
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
       - name: Lint with flake8
         run: |
           # stop the build if there are Python syntax errors or undefined names
           flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
           # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
           flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+      - name: Type check with mypy
+        if: matrix.python-version == '3.11'
+        run: |
+          mypy grobid_client
       - name: Test with pytest
         run: |
           pytest tests/ -v --cov=grobid_client --cov-report=xml --cov-report=term-missing

MANIFEST.in

@@ -1 +1,2 @@
-include Readme.md
+include Readme.md
+include grobid_client/py.typed

Readme.md

@@ -33,6 +33,7 @@ concurrent processing capabilities for PDF documents, reference strings, and pat
 - **Sentence Segmentation**: Layout-aware sentence segmentation capabilities
 - **JSON Output**: Convert TEI XML output to structured JSON format with CORD-19-like structure
 - **Markdown Output**: Convert TEI XML output to clean Markdown format with structured sections
+- **Type Hints**: Ships inline type annotations and a `py.typed` marker (PEP 561) for static type checking
 
 ## 📋 Prerequisites
 

grobid_client/client.py

@@ -1,6 +1,10 @@
 """ Generic API Client """
+from __future__ import annotations
+
 from copy import deepcopy
 import json
+from typing import Any, Optional, Tuple
+
 import requests
 
 try:
@@ -16,12 +20,17 @@ class ApiClient(object):
     service methods, i.e. ``get``, ``post``, ``put`` and ``delete``.
     """
 
-    accept_type = "application/xml"
-    api_base = None
+    accept_type: str = "application/xml"
+    api_base: Optional[str] = None
 
     def __init__(
-        self, base_url, username=None, api_key=None, status_endpoint=None, timeout=60
-    ):
+        self,
+        base_url: str,
+        username: Optional[str] = None,
+        api_key: Optional[str] = None,
+        status_endpoint: Optional[str] = None,
+        timeout: int = 60,
+    ) -> None:
         """Initialise client.
 
         Args:
@@ -37,7 +46,7 @@ def __init__(
         self.timeout = timeout
 
     @staticmethod
-    def encode(request, data):
+    def encode(request: Any, data: Optional[dict]) -> Any:
         """Add request content data to request body, set Content-type header.
 
         Should be overridden by subclasses if not using JSON encoding.
@@ -58,7 +67,7 @@ def encode(request, data):
         return request
 
     @staticmethod
-    def decode(response):
+    def decode(response: Any) -> Any:
         """Decode the returned data in the response.
 
         Should be overridden by subclasses if something else than JSON is
@@ -73,9 +82,9 @@ def decode(response):
         try:
             return response.json()
         except ValueError as e:
-            return e.message
+            return e.message  # type: ignore[attr-defined]  # pre-existing (Python 2 style)
 
-    def get_credentials(self):
+    def get_credentials(self) -> dict:
         """Returns parameters to be added to authenticate the request.
 
         This lives on its own to make it easier to re-implement it if needed.
@@ -87,14 +96,14 @@ def get_credentials(self):
 
     def call_api(
         self,
-        method,
-        url,
-        headers=None,
-        params=None,
-        data=None,
-        files=None,
-        timeout=None,
-    ):
+        method: str,
+        url: str,
+        headers: Optional[dict] = None,
+        params: Optional[dict] = None,
+        data: Optional[dict] = None,
+        files: Optional[dict] = None,
+        timeout: Optional[int] = None,
+    ) -> Tuple[requests.Response, int]:
         """Call API.
 
         This returns object containing data, with error details if applicable.
@@ -130,7 +139,7 @@ def call_api(
 
         return r, r.status_code
 
-    def get(self, url, params=None, **kwargs):
+    def get(self, url: str, params: Optional[dict] = None, **kwargs: Any) -> Tuple[requests.Response, int]:
         """Call the API with a GET request.
 
         Args:
@@ -142,7 +151,7 @@ def get(self, url, params=None, **kwargs):
         """
         return self.call_api("GET", url, params=params, **kwargs)
 
-    def delete(self, url, params=None, **kwargs):
+    def delete(self, url: str, params: Optional[dict] = None, **kwargs: Any) -> Tuple[requests.Response, int]:
         """Call the API with a DELETE request.
 
         Args:
@@ -154,7 +163,14 @@ def delete(self, url, params=None, **kwargs):
         """
         return self.call_api("DELETE", url, params=params, **kwargs)
 
-    def put(self, url, params=None, data=None, files=None, **kwargs):
+    def put(
+        self,
+        url: str,
+        params: Optional[dict] = None,
+        data: Optional[dict] = None,
+        files: Optional[dict] = None,
+        **kwargs: Any,
+    ) -> Tuple[requests.Response, int]:
         """Call the API with a PUT request.
 
         Args:
@@ -170,7 +186,14 @@ def put(self, url, params=None, data=None, files=None, **kwargs):
             "PUT", url, params=params, data=data, files=files, **kwargs
         )
 
-    def post(self, url, params=None, data=None, files=None, **kwargs):
+    def post(
+        self,
+        url: str,
+        params: Optional[dict] = None,
+        data: Optional[dict] = None,
+        files: Optional[dict] = None,
+        **kwargs: Any,
+    ) -> Tuple[requests.Response, int]:
         """Call the API with a POST request.
 
         Args:
@@ -186,7 +209,7 @@ def post(self, url, params=None, data=None, files=None, **kwargs):
             method="POST", url=url, params=params, data=data, files=files, **kwargs
         )
 
-    def service_status(self, **kwargs):
+    def service_status(self, **kwargs: Any) -> Tuple[requests.Response, int]:
         """Call the API to get the status of the service.
 
         Returns: