Skip to content

Latest commit

 

History

History
95 lines (78 loc) · 5.31 KB

CONTRIBUTING.md

File metadata and controls

95 lines (78 loc) · 5.31 KB

Contributing to tensicai

Thanks for helping improve the tensic.ai Python SDK. This page covers the local workflow, the quality bar every change has to meet, and how pull requests are reviewed.

Prerequisites

  • Python 3.10 or newer (the test matrix runs 3.10 through 3.14).
  • uv — the only tool you need; it manages the virtualenv, the interpreters for the matrix, and builds.

Set up

git clone https://github.com/tensicai/python-sdk
cd python-sdk
make install            # = uv sync --extra dev  (creates .venv with the SDK installed editable)

uv.lock is committed: uv sync reproduces the exact development environment used in CI, and CI installs with uv sync --locked, so a lock file that no longer matches pyproject.toml fails the run instead of being silently re-resolved. The lock only pins the development environment — the published wheel keeps its loose httpx>=0.25,<1 requirement. When you add or bump a dev dependency in pyproject.toml, run uv lock and commit the updated lock file with the change.

Everyday commands

Command What it runs
make lint ruff check src tests examples + ruff format --check
make format ruff format + ruff check --fix (auto-fixes imports etc.)
make typecheck mypy src examples (strict)
make test pytest -q on the current interpreter
make test-all pytest -q on Python 3.10, 3.11, 3.12, 3.13 and 3.14
make check lint + typecheck + test — what CI runs
make build uv build + twine check dist/*
make clean removes build artefacts and caches

Everything is a thin wrapper over uv run <tool>, so uv run pytest tests/test_chat.py -k send works as you would expect.

Tests

  • Unit tests live in tests/ and never touch the network: tests/conftest.py provides MockAPI, an in-memory router behind httpx.MockTransport, and the client / aclient fixtures. Assert on the recorded requests (api.last, request_json(...), request_multipart(...)) as well as on the parsed result.
  • Cover both the sync and the async client. tests/test_parity.py fails if a sync resource gains a method or a parameter that its async twin lacks.
  • tests/test_readme_snippets.py compiles every ```python block in README.md and `examples/*.py`, and executes the README snippets tagged `` against the mock server. If you change a documented signature, update the README in the same PR.
  • Live tests in tests/integration/ run only when TENSIC_URL and TENSIC_API_KEY are set (optionally TENSIC_PROJECT_ID for chat).

Code conventions

  • from __future__ import annotations in every module; full type hints; mypy --strict must stay clean for src/, for examples/ and for every ```python block in README.md (`tests/test_readme_snippets.py` type-checks the documented code, so copy-pasting it into a strictly typed project never produces errors).
  • Optional request parameters are keyword-only and default to NOT_GIVEN (omitted from the wire); an explicit None is sent as JSON null. No mutable default arguments.
  • A resource method is a module-level builder returning a RequestSpec plus a pure parser; the sync and async classes call the same pair. See docs/INTERNALS.md for the full guide and src/tensicai/resources/chat.py for the worked example.
  • Response models are lenient dataclasses (TensicModel): unknown keys go to .extra, missing keys read as None. Never raise on unexpected server output.
  • Every name a public signature mentions must be importable from tensicai, tensicai.types or tensicai.resources, so a Literal alias (Splitter, Privacy, Probe, ...) is defined once in its domain types/ module and imported back by the resource — tests/test_packaging.py checks this by introspection.
  • Every public class and method has a docstring naming the endpoint it calls.
  • Never log or repr() an API key.

The server source of truth for the HTTP contract is the tensic.ai OpenAPI document (GET /openapi.json on any server, with the Swagger UI at /docs and ReDoc at /redoc — all three require authentication). When in doubt, match the server, then update this SDK's docs.

Pull requests

  1. Branch from main; keep PRs focused (one feature or fix per PR).
  2. Run make check locally — CI runs the same commands on all supported Python versions and also builds and installs the wheel.
  3. Add tests for new behaviour and a line under Unreleased in CHANGELOG.md (Keep a Changelog format).
  4. Public API changes need README updates in the same PR; the snippet test will remind you.
  5. Do not bump src/tensicai/_version.py in feature PRs — maintainers do that in the release commit (see "Releasing" in the README).
  6. Commit messages: imperative mood, short subject, body explaining why when it is not obvious.

By contributing you agree that your contributions are licensed under the Apache-2.0 license that covers this repository.