Files and documents¶

Writing a spec to a file and reading it back, and rendering it for people to read. Each takes a TableSpec or a FrameSpec class, and each has a method on FrameSpec of the same name. See Specs as files for the format and what survives a round trip, and Documenting a spec for the Markdown and the diagram. A CatSpec and a Registry read and write themselves, with methods of the same names.

to_yaml¶

to_yaml ¶

to_yaml(spec: SpecLike, path: None = None) -> str

to_yaml(spec: SpecLike, path: str | Path) -> None

to_yaml(spec: SpecLike, path: str | Path | None = None) -> str | None

spec -- a TableSpec or a FrameSpec class -- as human-readable YAML: written to the file path, or, with no path, returned as text.

Defaults are omitted so the file shows only what was declared. Checks and validators over raw expressions cannot be written and warn.

from_yaml¶

from_yaml ¶

from_yaml(source: str | Path, *, categories: CatSpec | type[CatSpec] | str | Path | None = None, strict: bool = True) -> TableSpec

Reads a TableSpec from a YAML file written by to_yaml.

categories is a CatSpec registry, or a path to one, used to resolve shared Enums and Categoricals; when omitted, a categories: key in the file is loaded automatically, relative to the file. A file from an older format version is migrated on the way in.

to_dict¶

to_dict ¶

to_dict(spec: TableSpec) -> dict[str, Any]

The YAML-ready data form of spec, version first.

from_dict¶

from_dict ¶

from_dict(data: Mapping[str, Any] | None, *, categories: CatSpec | None = None, strict: bool = True, where: str = 'spec data') -> TableSpec

A TableSpec from data in any format version this polspec can read.

An unknown key is an error, naming the closest known key, unless strict=False, which downgrades it to a warning. where names the data at the front of any error -- a file's path, say -- as from_yaml names the file it read.

FORMAT_VERSION¶

FORMAT_VERSION `module-attribute` ¶

FORMAT_VERSION = 4

The spec-file format version this polspec writes, and the newest it reads.

to_python¶

to_python ¶

to_python(spec: SpecLike, path: None = None) -> str

to_python(spec: SpecLike, path: str | Path) -> None

to_python(spec: SpecLike, path: str | Path | None = None) -> str | None

spec -- a TableSpec or a FrameSpec class -- as a Python module defining a FrameSpec subclass: written to the file path, or, with no path, returned as text.

Columns are declared through __columns__, since a name straight from data is not always a valid identifier. Checks and validators over raw expressions cannot be written and warn.

The spec's own name is the class name, so it must be one: a name that is not an identifier, or is a keyword, raises SerializationError before anything is written. Rename it with spec.with_name(...), or write it with to_yaml, which keeps any name.

to_markdown¶

to_markdown ¶

to_markdown(spec: TableSpec | type, path: str | Path | None = None, *, title: str | None = None) -> str

A Markdown data dictionary of spec -- a TableSpec or a FrameSpec class: an overview, a table of its columns, and its constraints.

Parameters:

Name	Type	Description	Default
`spec`	`TableSpec \| FrameSpec class`	What to document.	required
`path`	`str \| Path`	Also write the Markdown to this file.	`None`
`title`	`str`	The document's title. Defaults to the spec's name.	`None`

Returns:

Type	Description
`str`	The Markdown. A `\|` or a newline in any name or value is escaped, so no name breaks the table.

to_mermaid¶

to_mermaid ¶

to_mermaid(spec: TableSpec | type, path: str | Path | None = None, *, title: str | None = None) -> str

A Mermaid entity-relationship diagram of spec -- a TableSpec or a FrameSpec class: one entity, its columns and keys, and the foreign keys it holds. Registry.to_mermaid draws several specs and the keys between them.