Parameter files, schema and reference#

Text generated from the parameter declarations (toycoronagraph.params and the source modules), so it never goes out of date:

new_config()          a parameter file holding only the chosen modules (+ the JSON schema)
json_schema()         the JSON schema: editor hover, completion and checks (Even Better TOML)
write_schema(path)    the JSON schema written to a file
reference_markdown()  the parameter reference tables
describe(query)       where a key is set, its unit, default, allowed values and users
migrate(path)         an old-layout file rewritten in the new layout

Command line: python -m toycoronagraph new | describe | migrate | schema | reference

toycoronagraph.params_docs.new_config(sources=('fits_image',), coronagraphs=('vortex:2',), path=None, full=False, schema=True, header=True)[source]#

A parameter file holding only what the chosen modules use.

[observation] and [grid] are always written (“auto” from an image source if one provides the pixel scale, else sampling and fov); [star] holds the keys the sources require (and temperature, radius, distance if the sources are in different unit families). Then one [[source]] table per source (its keys without a default are marked “(required)”), one [[coronagraph]] per coronagraph, and [method] if there are several sources. With a lazuli coronagraph, the wavelength is LAZULI_WAVELENGTH (in the r’ band of the Lazuli camera) and the image’s size is made odd (_odd_image_size), so the file runs as written.

Parameters:

sources (list) – Source kinds (str), or dicts {kind: …, key: value} whose values are written instead of the defaults.
coronagraphs (list) – “type:charge” strings (e.g. “vortex:2”; “” type = vortex), or dicts {type: …, charge: …}.
path (str) – Write it there (and the JSON schema next to it, if schema); None = only return it.
full (bool) – Also list the optional (advanced) keys and the other sections, commented out.
schema (bool) – Refer to the JSON schema in the header (“#:schema” line) and write it next to path.
header (bool) – Start with the header comment lines.

Returns:

the TOML text.

Return type:

str

Raises:

ParamError – an unknown source kind.

toycoronagraph.params_docs.json_schema()[source]#

JSON schema of the parameter file (editor hover, completion and checks; e.g. Even Better TOML).

[[source]] tables accept the keys of every kind (a key shared by several kinds: “anyOf” their schemas), then each kind is limited to its own keys; an unknown kind needs module. [[coronagraph]] tables likewise, each type also checking the values of its own keys (e.g. a vortex charge >= 2, a lazuli charge >= 0).

Returns:: the schema (draft-07), ready for json.dump.
Return type:: dict

toycoronagraph.params_docs.write_schema(path)[source]#

Write json_schema() to a file (indented JSON).

Parameters:: path (str) – the file (overwritten), normally SCHEMA_FILE next to the parameter file.

toycoronagraph.params_docs.reference_markdown()[source]#

Parameter reference tables (README / docs), generated from the declarations.

Returns:: Markdown: the core sections, [[source]] (common keys, then each kind), [[coronagraph]] types, and the rules when values disagree.
Return type:: str

toycoronagraph.params_docs.describe(query)[source]#

Where a key is set, its unit, default and allowed values, and who uses it.

Parameters:: query (str) – “section” or “section.key” (e.g. “grid”, “star.distance”; brackets are ignored), “kind” or “kind.key” of a source module (e.g. “wind”, “wind.mdot”), “type” or “type.key” of a coronagraph (e.g. “vortex.charge”), or a bare key name searched everywhere (e.g. “charge”).
Returns:: one block per match, separated by blank lines; if nothing matches, “Nothing called …” with the closest names.
Return type:: str

toycoronagraph.params_docs.migrate(path, out_path=None)[source]#

Rewrite an old-layout file in the new layout (only the values set there are kept).

Parameters:

path (str) – the old file: a .toml file, or a .py parameter file (read by config._from_legacy).
out_path (str) – where to write the new file (and the JSON schema next to it); None = only return it.

Returns:

the TOML text in the new layout.

Return type:

str

Raises:

ParamError – the .toml file is already in the new layout, or the mapped parameters are not valid (from_data()).