1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
# 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:
```bash
$ 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:
```
$ make 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.
## Releasing the Package
To cut a new release of Altair, follow the steps outlined in
[RELEASING.md](RELEASING.md).
|
