Skip to content

Versioning and stability (0.x and 1.x)

PydanTable is 1.x today. This page states how maintainers use semver on the stable train. Behavioral guarantees for transforms, nulls, joins, windows, materialization, and interchange live in INTERFACE_CONTRACT—treat that document as the semantics source of truth.

0.x.y releases (historical)

  • Patch (y) — Bug fixes, documentation-only updates, internal refactors, and test hardening that do not change documented public behavior.
  • Minor (0.x) — Additive changes: new Expr methods, new optional parameters with safe defaults, new documented APIs, or clarified contracts that align docs with long-standing behavior. Changelog entries should call out anything users might need to adopt consciously.

Breaking changes before 1.0 should be rare. When they are necessary, ship them in a minor bump with explicit migration notes in CHANGELOG (and, if large, a short section in ROADMAP).

Python package and Rust extension

pydantable.__version__, pydantable_protocol.__version__, and pydantable_native._core.rust_version() are kept equal to pyproject.toml / pydantable-protocol/pyproject.toml / pydantable-core/Cargo.toml on every release (see tests/test_version_alignment.py). The core package is pure Python; engine protocols ship in pydantable-protocol (no dependencies); the native extension ships in the pydantable-native distribution, which pins pydantable-protocol but does not depend on pydantable.

Path to 1.0

The production-ready v1.0.0 bar—semver policy for 1.x, packaging checklist, support matrix, and comms—is described under Planned v1.0.0 in ROADMAP.

1.x policy (effective at v1.0.0)

For 1.x, pydantable follows semantic versioning with the boundaries below.

Source of truth

  • Behavioral semantics (joins, null handling, windows, materialization, reshape rules) are defined in INTERFACE_CONTRACT.
  • Versioning policy (what kind of release is required for a change) is defined here.
  • If these documents conflict, maintainers must update one of them before release.

Patch releases (1.x.y)

Patch releases are for non-breaking changes such as:

  • Bug fixes that restore documented behavior.
  • Documentation clarifications that do not change runtime behavior.
  • Internal refactors/performance improvements with no public API/contract change.
  • Dependency/security updates with no user-visible contract change.

Minor releases (1.x)

Minor releases are additive and backward compatible, including:

  • New methods or helpers on DataFrame / DataFrameModel / Expr.
  • New optional parameters with backward-compatible defaults.
  • New optional integrations/extras and new documented I/O helpers.
  • Additional dtype support where existing behavior is unchanged.

Major releases (2.0.0+)

Major releases are required for breaking changes, including:

  • Removing/renaming public methods or parameters.
  • Changing default behavior in a way that can alter outputs or errors for existing code.
  • Changing documented semantics in INTERFACE_CONTRACT incompatibly.

Rust extension boundary (pydantable_native._core)

  • pydantable_native._core internals are not a stable API for direct user imports.
  • Stability commitments apply to documented Python-facing APIs in pydantable.
  • pydantable.__version__ and pydantable_native._core.rust_version() remain aligned on releases.

Practical examples

  • Patch: fix a null-propagation regression so runtime matches documented contract.
  • Minor: add DataFrame.read_foo(...) with default-off behavior and docs/tests.
  • Major: change collect() default return shape or remove a long-standing method.

Planned removals (2.0.0)

The following deprecated parameters are scheduled for removal in 2.0.0 (a major release per the policy above):

  • as_polars= on DataFrame.collect, DataFrame.acollect, and the DataFrameModel collection shims — use to_polars() / ato_polars() (and collect(as_lists=True) / to_dict() for columnar dicts).

The following legacy string-SQL I/O names are deprecated as of v1.13.0; they emit DeprecationWarning at runtime. Use fetch_sql_raw, iter_sql_raw, write_sql_raw, afetch_sql_raw, aiter_sql_raw, awrite_sql_raw, or SQLModel-first fetch_sqlmodel / iter_sqlmodel / write_sqlmodel (and DataFrameModel mirrors) instead. These aliases are scheduled for removal in 2.0.0 (exact timeline subject to SQLMODEL_SQL_ROADMAP):

  • fetch_sql, iter_sql, write_sql, afetch_sql, aiter_sql, awrite_sql, write_sql_batches, awrite_sql_batches

Lazy SQL and Mongo façade names (preview)

Deprecated (remove in 2.0.0) Replacement
moltres_engine= on SqlDataFrame / SqlDataFrameModel helpers sql_engine= (same object; see SQL_ENGINE)
EnteiDataFrame, EnteiDataFrameModel, EnteiPydantableEngine (lazy imports / pydantable.mongo_entei) MongoDataFrame, MongoDataFrameModel, MongoPydantableEngine from pydantable or pydantable.mongo_dataframe (MONGO_ENGINE)

After 2.0.0, update imports and kwargs using the table above; run tests with PYTHONWARNINGS=error::DeprecationWarning before upgrading to catch stragglers.