From b63b23abbd21fc4f29759f768f167051338a38f4 Mon Sep 17 00:00:00 2001 From: david Date: Tue, 27 Oct 2026 14:54:07 +0100 Subject: [PATCH 1/3] fix(api): declare __all__ and export UndefinedLiteral Since py.typed is shipped, pyright applies re-export rules and flagged documented top-level imports as private (reportPrivateImportUsage). UndefinedLiteral is needed to annotate helpers returning the sentinel. Fixes #82 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 9 +++++++ src/knowledge_mapper/__init__.py | 30 ++++++++++++++++++++++++ src/knowledge_mapper/ke/__init__.py | 2 ++ src/knowledge_mapper/testing/__init__.py | 2 ++ 4 files changed, 43 insertions(+) diff --git a/README.md b/README.md index 2451d9f..9a7dbd2 100644 --- a/README.md +++ b/README.md @@ -224,6 +224,15 @@ 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"] From 41a04e53014a8e0cba9924ee1fee1035b8905145 Mon Sep 17 00:00:00 2001 From: david Date: Tue, 27 Oct 2026 14:54:08 +0100 Subject: [PATCH 2/3] ci: type-check public API as a consumer with pyright Catches re-export regressions that pyright only reports for installed typed packages, not for the project's own sources. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/ci.yml | 4 ++++ CONTRIBUTING.md | 9 ++++++++ tests/typing/public_api.py | 40 +++++++++++++++++++++++++++++++++ tests/typing/pyrightconfig.json | 1 + 4 files changed, 54 insertions(+) create mode 100644 tests/typing/public_api.py create mode 100644 tests/typing/pyrightconfig.json 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/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 @@ +{} From 9851f6099eb324f729a4c2ad325074e0ad032347 Mon Sep 17 00:00:00 2001 From: david Date: Tue, 27 Oct 2026 15:09:39 +0100 Subject: [PATCH 3/3] style(docs): fix README snippet formatting for ruff 0.17 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 9a7dbd2..6eff3ee 100644 --- a/README.md +++ b/README.md @@ -229,6 +229,7 @@ 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 ```