Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/`:
Expand Down
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
30 changes: 30 additions & 0 deletions src/knowledge_mapper/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
Literal,
PostExchangeInfo,
RdfLiteral,
UndefinedLiteral,
Uri,
validate_kb_id,
)
Expand All @@ -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
Expand Down
2 changes: 2 additions & 0 deletions src/knowledge_mapper/ke/__init__.py
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
from .client import Client, ClientProtocol

__all__ = ["Client", "ClientProtocol"]
2 changes: 2 additions & 0 deletions src/knowledge_mapper/testing/__init__.py
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
from .fake_client import TestClient

__all__ = ["TestClient"]
40 changes: 40 additions & 0 deletions tests/typing/public_api.py
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions tests/typing/pyrightconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{}
Loading