Skip to content

Install mathspec#

This guide shows how to install mathspec, pin its version and set up your editor to complete the keys of a specification file (spec). You need Python 3.12 or above.

Install the package#

Install the released package from the Python Package Index (PyPI) with the tool that manages your environment:

pip install mathspec

uv add mathspec

pixi add --pypi mathspec

The package is now installed in that environment, and you can check that it runs before you write a spec.

To work on mathspec itself from a clone, instead follow setting up a development environment.

Pin the version#

The current language version is 0, and the current release is 0.4.0. To pin what a spec file means, set its version: key to the language version you wrote it for. If you build software that reads a spec (a tool) on the Python API, such as specsolve, pin one exact mathspec release:

pip install mathspec==0.4.0

Set up editor completion#

mathspec ships the file schema/mathspec.schema.json, which lists the keys of a spec file in a machine-readable format description (a JSON Schema). Your editor reads the schema to complete keys as you type. In VS Code:

  1. Install the Red Hat YAML extension.

  2. In .vscode/settings.json, map the schema to your spec files for the whole workspace:

    // .vscode/settings.json
"yaml.schemas": { "https://raw.githubusercontent.com/energy-models/mathspec/v0.4.0/schema/mathspec.schema.json": ["specs/*.yaml"] }

    To map the schema for one file only, instead put a comment with the schema address (a modeline) on the first line of that file:

    # yaml-language-server: $schema=https://raw.githubusercontent.com/energy-models/mathspec/v0.4.0/schema/mathspec.schema.json

The editor now completes the keys of a spec file, and marks a key that the schema does not list.

Check that mathspec runs#

Run the command line:

python -m mathspec --help

The command prints the six commands that mathspec has.

See also