diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8694775..f7ed7d1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -45,6 +45,10 @@ jobs: - name: Run tests run: uv run pytest tests/ + - name: Type-check public API as a consumer + working-directory: tests/typing + run: uvx pyright --pythonpath ../../.venv/bin/python + build: name: Build package runs-on: ubuntu-latest diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7de24e1..e935d6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,6 +31,15 @@ Unit tests use `TestClient`, an in-memory fake Smart Connector. No external serv uv run pytest ``` +### Public API Type Check + +`tests/typing/public_api.py` imports the public API the way a downstream project would. Pyright must run from that directory so it treats `knowledge_mapper` as an installed typed package and reports re-exports missing from `__all__`: + +```bash +uv sync +cd tests/typing && uvx pyright --pythonpath ../../.venv/bin/python +``` + ### Integration Tests Integration tests require a live Knowledge Engine runtime. Use the Docker Compose file in `examples/`: diff --git a/README.md b/README.md index 2451d9f..6eff3ee 100644 --- a/README.md +++ b/README.md @@ -224,6 +224,16 @@ if incoming.age is not None and incoming.age is not UNDEFINED_LITERAL: next_year = incoming.age + 1 # narrowed to int ``` +The sentinel's type, `UndefinedLiteral`, is also exported for annotating helpers: + +```python +from knowledge_mapper import UNDEFINED_LITERAL, UndefinedLiteral + + +def value_or_undefined(value: int | None) -> int | UndefinedLiteral: + return UNDEFINED_LITERAL if value is None else value +``` + ### `Depends` — Dependency Injection Handlers can declare dependencies using `Depends()` in `Annotated` type hints. The framework resolves them at call time. diff --git a/src/knowledge_mapper/__init__.py b/src/knowledge_mapper/__init__.py index 483ea3f..977b46e 100644 --- a/src/knowledge_mapper/__init__.py +++ b/src/knowledge_mapper/__init__.py @@ -18,6 +18,7 @@ Literal, PostExchangeInfo, RdfLiteral, + UndefinedLiteral, Uri, validate_kb_id, ) @@ -26,6 +27,35 @@ __version__ = "0.1.0rc1" +# Explicit `__all__` so type checkers (e.g. pyright) treat these re-exports as +# public API of this typed (py.typed) package. +__all__ = [ + "UNDEFINED", + "UNDEFINED_LITERAL", + "AnyExchangeInfo", + "AskExchangeInfo", + "BindingModel", + "BindingSet", + "Datatype", + "Depends", + "ExchangeInfo", + "ExchangeResult", + "KnowledgeBase", + "KnowledgeBaseBuilder", + "KnowledgeBaseId", + "KnowledgeBaseSettings", + "KnowledgeInteraction", + "KnowledgeInteractionId", + "Literal", + "PostExchangeInfo", + "RdfLiteral", + "UndefinedLiteral", + "Uri", + "__version__", + "get_requesting_kb_id", + "validate_kb_id", +] + # The package attaches its own handler/formatter so log output is sensible # out of the box, even if the host application never calls # `logging.basicConfig()`. Propagation to ancestor loggers (e.g. the root diff --git a/src/knowledge_mapper/ke/__init__.py b/src/knowledge_mapper/ke/__init__.py index 740f681..ba48e33 100644 --- a/src/knowledge_mapper/ke/__init__.py +++ b/src/knowledge_mapper/ke/__init__.py @@ -1 +1,3 @@ from .client import Client, ClientProtocol + +__all__ = ["Client", "ClientProtocol"] diff --git a/src/knowledge_mapper/testing/__init__.py b/src/knowledge_mapper/testing/__init__.py index 24e57bb..d5c917b 100644 --- a/src/knowledge_mapper/testing/__init__.py +++ b/src/knowledge_mapper/testing/__init__.py @@ -1 +1,3 @@ from .fake_client import TestClient + +__all__ = ["TestClient"] diff --git a/tests/typing/public_api.py b/tests/typing/public_api.py new file mode 100644 index 0000000..1aea076 --- /dev/null +++ b/tests/typing/public_api.py @@ -0,0 +1,40 @@ +# ruff: noqa: F401 +"""Type-checked as a downstream consumer would see the package (see #82). + +Checked by pyright in CI, not executed by pytest. Pyright only applies its +re-export rules (reportPrivateImportUsage) to installed typed packages, so it +must run with this directory as project root. +""" + +from knowledge_mapper import ( + UNDEFINED, + UNDEFINED_LITERAL, + AnyExchangeInfo, + AskExchangeInfo, + BindingModel, + BindingSet, + Datatype, + Depends, + ExchangeInfo, + ExchangeResult, + KnowledgeBase, + KnowledgeBaseBuilder, + KnowledgeBaseId, + KnowledgeBaseSettings, + KnowledgeInteraction, + KnowledgeInteractionId, + Literal, + PostExchangeInfo, + RdfLiteral, + UndefinedLiteral, + Uri, + __version__, + get_requesting_kb_id, + validate_kb_id, +) +from knowledge_mapper.ke import Client, ClientProtocol +from knowledge_mapper.testing import TestClient + + +def value_or_undefined(value: float | None) -> float | UndefinedLiteral: + return UNDEFINED_LITERAL if value is None else value diff --git a/tests/typing/pyrightconfig.json b/tests/typing/pyrightconfig.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/tests/typing/pyrightconfig.json @@ -0,0 +1 @@ +{}