Skip to content

API Stability & Deprecation Policy

This page defines what pycharter considers its supported public surface, how that surface evolves under SemVer, and how deprecations are signalled. It is the source of truth for both maintainers and downstream consumers.

The supported public surface

The supported, stable surface is the set of names exported from the top-level package:

import pycharter

pycharter.__all__  # the curated public API

These names are defined in src/pycharter/_exports.py (__all__ + a lazy-import map) and re-exported from pycharter/__init__.py. A name is part of the public contract only if it appears in pycharter.__all__.

Everything else is internal:

  • Modules and packages prefixed with _ (e.g. pycharter._exports, pycharter._format_migrations).
  • Submodule members not re-exported at the top level. Importing them (from pycharter.semantic.bindings._store import ...) is unsupported and may break in any release.

When adding public API, add it to _exports.py deliberately — keep the surface intentionally small.

SemVer commitment

pycharter follows Semantic Versioning. Once the project reaches 0.1/1.0:

  • Patch (x.y.Z): bug fixes; no public-API changes.
  • Minor (x.Y.z): backward-compatible additions to the public surface. Existing public names keep working.
  • Major (X.y.z): may remove or change public names that completed the deprecation cycle below.

During 0.0.x the surface may still churn; the artifact format versioning header is what lets consumers depend on persisted documents through that churn.

Deprecation cycle

Deprecations use the helpers in pycharter._deprecation so every warning is consistent and actionable:

from pycharter._deprecation import deprecated, warn_deprecated

@deprecated(replacement="new_function", removal_version="0.2.0")
def old_function(...): ...

Rules:

  1. Always DeprecationWarning — never a bare UserWarning — with stacklevel set so the warning points at the caller.
  2. Name a removal version. Every deprecation states the version in which the symbol will be removed (e.g. "0.2.0").
  3. Name a replacement when one exists.
  4. Keep the deprecated symbol working until its removal version (no behavior change beyond the warning).
  5. Document the deprecation in the changelog / migration notes.

Removal only happens in the version named by removal_version (a major bump for breaking removals once ≥ 1.0).

Persisted artifacts

Persisted artifact documents (contracts, concept schemes, lineage) carry a format_version and are upgraded on read — see Artifact Format Versioning. The format header is part of the stable contract: within a major version, an artifact written by an older minor loads under a newer minor.