Skip to content

Latest commit

 

History

History
64 lines (49 loc) · 2.67 KB

NOTES_FOR_MAINTAINERS.md

File metadata and controls

64 lines (49 loc) · 2.67 KB
Raw

Notes for Maintainers of Altair

Auto-generating the Python code

The core Python API for Altair can be found in the following locations:

  • altair/vegalite/v5/schema/

All the files within these directories are created automatically by running the following script from the root of the repository:

$ python tools/generate_schema_wrapper.py

This script does a couple things:

  • downloads the appropriate schema files from the specified vega-lite release versions & copies the JSON file to the appropriate schema directory
  • generates basic low-level schemapi wrappers from the definitions within the schema: this is put in the schema/core.py file
  • generates a second layer of higher level wrappers for some vega-lite functionality; this is put in schema/channels.py and schema/mixins.py

The script output is designed to be deterministic; if the vega-lite version is not changed, then running the script should overwrite the schema wrappers with identical copies.

Updating the Vega-Lite version

The vega & vega-lite versions for the Python code can be updated by manually changing the SCHEMA_VERSION definition within tools/generate_schema_wrapper.py, and then re-running the script.

This will update all of the automatically-generated files in the schema directory for each version, but please note that it will not update other pieces (for example, the core of the Altair API, including methods and doc strings within altair/vegalite/v5/api.py. These additional methods have fairly good test coverage, so running the test suite should identify any inconsistencies:

hatch run test

Generally, minor version updates (e.g. Vega-Lite 2.3->2.4) have been relatively painless, maybe requiring the addition of a few chart methods or modification of some docstrings. Major version updates (e.g. Vega-Lite 1.X->2.X) have required substantial rewrites, because the internal structure of the schema changed appreciably.

Updating vl-convert version bound

When updating the version of Vega-Lite, it's important to ensure that vl-convert includes support for the new Vega-Lite version. Check the vl-convert releases to find the minimum version of vl-convert that includes support for the desired version of Vega-Lite (and open an issue if this version hasn't been included in a released yet.). Update the vl-convert version check in altair/utils/_importers.py with the new minimum required version of vl-convert.

Releasing the Package

To cut a new release of Altair, follow the steps outlined in RELEASING.md.