Source

flatland / docs / source / schema / properties.rst

Full commit

Annotations & Properties

Flatland provides two options for annotating schemas and data.

Standard Python

Element schemas are normal Python classes and can be extended in all of the usual ways. For example, you can add an attribute when subclassing:

Once an attribute has been added to an element class, its value can be overridden by further subclassing or, more compactly, with the :meth:`~Element.using` schema constructor:

Both are equivalent, and the custom tooltip will be inherited by any subclasses of Password. Likewise, instances of Password will have the attribute as well.

And because the :meth:`Element` constructor allows overriding any schema attribute by keyword argument, individual element instances can be constructed with own values, masking the value provided by their class.

Properties

Another option for annotation is the :attr:`~Element.properties` mapping of element classes and instances. Unlike class attributes, almost any object you like can be used as the key in the mapping.

The unique feature of :attr:`~Element.properties` is data inheritance:

Annotations made on a schema are visible to itself and any subclasses, but not to its parents.

Annotating With Properties

To create a new schema that includes additional properties, construct it with :meth:`~Element.with_properties`:

Or if the schema has already been created, manipulate its :attr:`~Element.properties` mapping:

The :attr:`~Element.properties` mapping is implemented as a view over the Element schema inheritance hierarchy. If annotations are added to a superclass such as :class:`~flatland.schema.scalars.String`, they are visible immediately to all Strings and subclasses.

Private Annotations

To create a schema with completely unrelated properties, not inheriting from its superclass at all, declare it with :meth:`~Element.using`:

Or when subclassing longhand, construct a :class:`~flatland.schema.properties.Properties` collection explicitly.

An instance may also have a private collection of properties. This can be done either at or after construction: