Compatibility¶

Stable Inklet 4.10.0 uses the environments and rendering paths below. Experimental capabilities are identified separately. The matrix distinguishes installed-package checks from full integration tests.

Test coverage¶

The release workflow is the current source of automated coverage. Python 3.11 is the minimum; later versions outside the matrix are not yet verified. A successful smoke test checks installation and representative exports, not every OS-specific behavior or font substitution.

Blender CI downloads fixed builds from the official release archive and verifies pinned SHA-256 hashes. It requires the requested version before running tests, so a failed installation cannot turn the scene tests into a green skipped run. Each version also creates and renders all three templates from an installed wheel in an isolated environment.

API and saved-file policy¶

4.0.0 released the supported scope below, frozen during RC1; 4.1.0 and 4.2.0 add plot types within it, and 4.3 moves four packages out of inklet.experimental. The same acceptance, distribution and performance gates apply to later releases.

• The documented top-level inklet authoring/export API remains supported. Internal modules, names beginning with _ and generated output bytes are not compatibility interfaces. Existing 3.1 recipes do not require a new API.
• From 4.3, the stable packages below are covered by the same policy as top-level inklet. Their public names are those in each package's __all__, listed in the API reference. import inklet does not import them; import each package you use.

• The earlier inklet.experimental paths stay as aliases through 4.x and return the same objects. From 4.4, importing one raises inklet._compat.InkletDeprecationWarning, a DeprecationWarning subclass that names the new path. They are removed in 5.0. The compiled scene viewer runtime moved to the private inklet.render._viewer; use RenderScene.to_html(). The layout editor's HTTP/JSON protocol and snapshot() payload are private; the class and saved overrides are the contract.
• Deprecations (4.4). 4.4 adds American-spelling names and one keyword per idea on Panel: color=, name= and size=. The old names keep working and warn once per call. See the rename table. A deprecated name keeps its released call shape until 5.0, and the compatibility checker still verifies it. Giving an old and a new spelling together is a TypeError. Inklet's own code and tests use only the new names; the test suite turns InkletDeprecationWarning into an error.
• The rest of inklet.experimental remains opt-in: browser documents (browser), mesh and grid fields (fields, grid), engineering drawings (engineering, deprecated in 4.4 and removed in 5.0), image measurement (measurement) and the figure planner (figure_planner, planner_geometry). BrowserScatter is deprecated in favour of BrowserFigure. Their signatures, report schemas and saved formats may change; keep an exact package pin and source recipe for archived work. See experimental features.
• tools/check_compatibility.py compares public call shapes with inventories captured from the released 3.1.0 and 4.2.0 wheels. The 4.2 baseline includes every public inklet.experimental module, so the aliases above are checked too. It checks names, parameter kinds, positional order and required arguments, not defaults or rendering.
• Moving a package does not change its saved formats: schema identifiers such as inklet.selection/0.1 and inklet.figure-project/0.1 are unchanged in 4.3.
• Readers validate schema identifiers and reject unsupported versions. A future incompatible format needs a new schema identifier and migration guidance; changing the identifier by hand is not a migration.
• A readable schema does not guarantee identical rendering. Fonts, external assets, renderers and trusted recipes remain part of a reproducible project. Export caches are disposable; source data and saved decisions are not.

The supported composition inspector edits placement, dimensions, labels, registered styles and native-camera parameters. Linked cross-content views use explicit keyed tables and the documented drawing, labelled-image, mesh-field and grid-field adapters. Each adapter retains its own picking and geometry limits.

Individual axis-label editing, direct camera dragging, depth-aware browser 3D picking, interactive volumes, additional projections and broader GPU primitives are deferred beyond 4.0. Arbitrary Python object serialization and general geometry constraints are outside the project-bundle contract.

See migration for existing recipes and saved files.

Optional dependencies¶

Importing Inklet and reading scene_templates() does not discover or start Blender. Scene creation and rendering run Blender in a separate process.

Known boundaries¶

Table adapters¶

The pandas and Polars adapters (KeyedTable.from_pandas, from_polars) arrived in the 4.0 release and are part of the stable inklet.selection from 4.3; they were not part of 3.1.0. Their pandas and polars extras are separate from core dependencies. The adapter CI jobs use Linux/Python 3.12 with pandas 2.2.0 / Polars 1.0.0 and the versions pinned in requirements-tables.txt. Both paths check scalar/identity contracts and saved-state SVG reconstruction. The core wheel checks that neither integration is required or imported.

Browser workflows and local editor¶

Inklet 4.0 includes standalone linked HTML and a Python-backed composition editor. The supported browser target is Chrome/Chromium on Linux; release evidence uses pinned Chrome 145.0.7632.45. Keyboard controls and data-table selection are automated acceptance checks, not a claim of a complete accessibility audit. Firefox, Safari, mobile browsers and browser interaction on Windows/macOS are not covered by that integration matrix. Windows/macOS wheel checks verify installed editor assets and representative static exports; they are not browser certification.

The composition editor requires a running local Python session and binds to loopback. Its saved choices are JSON overrides for an existing Python recipe, not a standalone project. Linked HTML has a separate saved-selection format. See the editor and saved layouts.

Rendering¶

The legacy vector line-art backend uses Blender's pre-4.3 Grease Pencil API. Blender documents that incompatible transition in its migration guide. Inklet reports the required 4.2 version before starting a new line-art bake. This is separate from complete .blend scene rendering and the raster sketch style, both tested with 4.5.

Cycles GPU selection depends on the installed Blender build and drivers. AUTO falls back when no usable GPU is discovered; it does not conceal a render failure by retrying on CPU. EEVEE needs a working graphics context and has no headless CI guarantee. See device behavior.

Depth-tested overlays sample the saved depth image. Glass, thin geometry, silhouettes and object-index masks have documented precision limits. Scene masks are not Cryptomatte. User compositors, embedded Python execution, animation/video export and arbitrary simulation bindings are outside the 3.1 feature set.

Template creation preserves existing files on failure. Its default atomic no-overwrite commit requires filesystem hard-link support; explicit overwrite=True uses atomic replacement. See template creation.

Release acceptance¶

Before a stable tag:

1. Require green figure, wheel and Blender jobs on the exact release commit.
2. Build the wheel and source archive, check metadata with Twine, and run isolated wheel checks against those files. Build the wheel from the source archive too.
3. Review the rendered examples and verify latest docs point to the release commit. Follow the 4.0 migration guidance.
4. Freeze the release files with SHA256SUMS, then attach those exact files to the release. The publishing workflow is a separate manual step.

Package publication is separate from validation. These checks do not upload anything to PyPI.