API Reference¶

class chide.Collection(mapping: dict[Type[Any], dict[str, Any]] | None = None)¶

A collection of attributes to use to make sample objects.

Parameters:: mapping – A dictionary mapping object types to a dictionary of attributes to make a sample object of that type.

add(obj: T, simplifier: Simplifier[T] = <chide.simplifiers.ObjectSimplifier object>, annotated: Type[T] | None = None, constructor: Type[T] | None = None) → None¶

Add the attributes from the supplied object to this collection and use them when samples of the type of that object are required.

Parameters:

obj – The sample object from which to extract attributes.
simplifier – The Simplifier to use to extract attributes from obj.
annotated – If obj is an instance of a simple type such as a dict, it may be necessary to provided the annotated type for data instance such that it can be correctly added to the collection with that type.
constructor – The class to use when constructing objects of this type. This is useful when the type is a parameterized generic but you want to construct using the origin class to avoid __orig_class__ being set.

attributes(type_: Type[T], **attrs: Any) → dict[str, Any]¶

Make the attributes for a sample object of the specified type_ using the default attributes for that type in this Collection.

The attrs mapping will be overlaid onto the sample attributes and returned as a dict.

make(type_: Type[T], override: Type[T] | None = None, /, **attrs: Any) → T¶

Make a sample object of the specified type_ using the default attributes for that type in this Collection.

The attrs mapping will be overlaid onto the sample attributes before being used with type_ to instantiate and return a new sample object.

If override is provided, it will be used to construct the object in place of the supplied type.

bind(type_: Type[T], **attrs: Any) → Factory[T]¶: Bind the supplied attributes into a Factory for the requested type_ by overlaying them onto the sample attributes for that type_ in this Collection.

class chide.Set(collection: Collection, identify: Callable[[Type[Any], dict[str, Any]], Hashable | None] | None = None)¶

A collection of sample objects where only one object with a given identity may exist at one time.

Parameters:

collection – The Collection instance used to create sample objects when necessary.
identify –
An Identifier callable that takes type_ and attrs parameters.

type_, usually a class, is the type of the sample object being requested.

attrs is a dict of the attributes being requested for the sample object to have.

The callable should return a hashable value that indicates the identity to use for the requested sample object. For each unique hashable value, only one sample object will be instantiated and returned each time a sample is requested where this callable returns the given identity.

None may be returned to indicate that a new object should always be returned for the provided parameters.

identify: Callable[[Type[Any], dict[str, Any]], Hashable | None]¶: You may also want to subclass Set and implement an identify() method, see chide.sqlalchemy.Set for an example.

get(type_: Type[T], **attrs: Any) → T¶

Return an appropriate sample object of the specified type_.

The attrs mapping will be overlaid onto the sample attributes found in this set’s Collection before checking if an appropriate sample object already exists in the set.

If one exists, it is returned. If not, one is created using this set’s Collection, added to the set and then returned.

chide.call(factory: Callable[[], T]) → T¶

Mark a zero-argument callable so that it is invoked fresh each time a sample object is made via make().

Parameters:: factory – A zero-argument callable returning T.
Returns:: A marker object typed as T so that mypy accepts it at call sites.

chide.nest(type_: type[T]) → T¶

Mark a registered type so that it is resolved to a sample object when an enclosing sample is made via make().

Parameters:: type – The type to resolve via the collection at make-time.
Returns:: A marker object typed as T so that mypy accepts it at call sites.

class chide.factory.Factory(collection: Collection, type_: Type[T], attrs: dict[str, Any])¶

A factory for objects of a particular type. These are created by either chide.Collection.bind() or chide.factory.Factory.bind().

attributes(**attrs: Any) → dict[str, Any]¶

Make the attributes for a sample object of this factory’s type using the default attributes for the type in this factory’s Collection overlaid with any attributes bound into the factory.

The attrs mapping will be overlaid onto those attributes and returned as a dict.

make(type_: Type[T] | None = None, /, **attrs: Any) → T¶

Make a sample object of this factory’s type using the default attributes for the type in this factory’s Collection overlaid with any attributes bound into the factory.

The attrs mapping will be overlaid onto the sample attributes before being used to instantiate and return a new sample object of this factory’s type.

If a type is provided, it will be used to construct the object in place of the factory’s type.

bind(**attrs: Any) → Self¶: Bind the supplied attributes into a new Factory by overlaying them onto the sample attributes this factory would use.

Markers¶

chide.markers.nest(type_: type[T]) → T¶

Mark a registered type so that it is resolved to a sample object when an enclosing sample is made via make().

Parameters:: type – The type to resolve via the collection at make-time.
Returns:: A marker object typed as T so that mypy accepts it at call sites.

chide.markers.call(factory: Callable[[], T]) → T¶

Mark a zero-argument callable so that it is invoked fresh each time a sample object is made via make().

Parameters:: factory – A zero-argument callable returning T.
Returns:: A marker object typed as T so that mypy accepts it at call sites.

Typing¶

chide.typing.Attrs¶

A dictionary of attributes that can be used to create a sample object

alias of dict[str, Any]

chide.typing.Identifier¶

A callable for uniquely identifying a sample object in a Set

alias of Callable[[Type[Any], dict[str, Any]], Hashable | None]

Formats¶

class chide.formats.Format(*args, **kwargs)¶

Bases: Protocol

Protocol for formats.

parse(text: str) → list[dict[str, Any]]¶: Parse the supplied text into a list of Attrs.

render(attrs: Iterable[dict[str, Any]]) → str¶: Render the supplied Attrs into a str.

chide.formats.ValueParse¶

Type of a callable to parse a value from a str.

alias of Callable[[str], Any]

chide.formats.ValueRender¶

Type of a callable to render a value into a str.

alias of Callable[[Any], str]

chide.formats.ParseMapping¶

A mapping of column or type names to the ValueParse to use.

alias of dict[str, Callable[[str], Any]]

chide.formats.TypeRenderMapping¶

A mapping of data types to the ValueRender to use.

alias of dict[Type[Any], Callable[[Any], str]]

chide.formats.TypeNameMapping¶

A mapping of data types to the name to use for them when rendering a table.

alias of dict[Type[Any], str | None]

chide.formats.ColumnRenderMapping¶

A mapping of column name to the ValueRender to use.

alias of dict[str, Callable[[Any], str]]

chide.formats.default_parse(text: str) → Any¶: The default ValueParse.

chide.formats.default_render(value: Any) → str¶: The default ValueRender.

class chide.formats.TypeLocation(value)¶

Bases: Enum

HEADER = 1¶: The types are located in parentheses, after the column name, in the row containing the column names.

ROW = 2¶: The types are located in their own row.

chide.formats.HEADER = TypeLocation.HEADER¶: Shortcut for TypeLocation.HEADER.

chide.formats.ROW = TypeLocation.ROW¶: Shortcut for TypeLocation.ROW.

class chide.formats.TabularFormat(type_parse: dict[str, ~typing.Callable[[str], ~typing.Any]] | None = None, default_type_parse: ~typing.Callable[[str], ~typing.Any] = <function default_parse>, column_parse: dict[str, ~typing.Callable[[str], ~typing.Any]] | None = None, type_render: dict[~typing.Type[~typing.Any], ~typing.Callable[[~typing.Any], str]] | None = None, default_type_render: ~typing.Callable[[~typing.Any], str] = <function default_render>, type_names: dict[~typing.Type[~typing.Any], str | None] | None = None, column_render: dict[str, ~typing.Callable[[~typing.Any], str]] | None = None, types_location: ~chide.formats.TypeLocation | None = None)¶

Bases: Format

A base class for tabular formats.

class chide.formats.PrettyParsed(attrs: list[dict[str, Any]], widths: list[int])¶

Bases: list[dict[str, Any]]

A list of Attrs that also keeps track of the widths required to render the columns, if they are known.

widths: dict[str, int]¶: The widths required for the columns needed by these ~chide.typing.Attrs.

class chide.formats.PrettyFormat(type_parse: dict[str, ~typing.Callable[[str], ~typing.Any]] | None = None, default_type_parse: ~typing.Callable[[str], ~typing.Any] = <function default_parse>, column_parse: dict[str, ~typing.Callable[[str], ~typing.Any]] | None = None, type_render: dict[~typing.Type[~typing.Any], ~typing.Callable[[~typing.Any], str]] | None = None, default_type_render: ~typing.Callable[[~typing.Any], str] = <function default_render>, type_names: dict[~typing.Type[~typing.Any], str | None] | None = None, column_render: dict[str, ~typing.Callable[[~typing.Any], str]] | None = None, types_location: ~chide.formats.TypeLocation | None = None, minimum_column_widths: dict[str, int] | None = None, padding: int = 1)¶

Bases: TabularFormat

A pretty Format for tabular data, where tables look something like:

+-----+------+
| x   | y    |
+-----+------+
|float| str  |
+-----+------+
| 1   | foo  |
| 2   | bar  |
+-----+------+

Parameters:

type_parse – A mapping of type name, as found in either a row or column heading, dependent on the types_location, to a function that parses the text of a cell into a value.
default_type_parse – The default function to use when parsing the text of a cell into a value.
column_parse – A mapping of column names to functions that will be used to parse the text of cells in that column into values.
type_render – A mapping of type objects to functions that will be used to render values of that type to text for cells.
default_type_render – The default function to use when rendingering values to text for cells.
type_names – A mapping of type objects to names to use for those types when including types in either column headings or their own own. If a type is mapped to None, then no type name will be rendered for columns containing date of that type.
column_render – A mapping of column names to functions that will be used to render values in that column to text for cells.
types_location – An optional location from which type information will be parsed or to which it will be rendered. Must be HEADER, ROW or None.
minimum_column_widths – An optional mapping of column name to the minimum width to use for a column.
padding – The number of space to put to the left and right of values of cells.

parse(text: str) → PrettyParsed¶: Parse the supplied text into a PrettyParsed.

render(attrs: Iterable[dict[str, Any]], ref: list[dict[str, Any]] | PrettyParsed | None = None) → str¶

Render the supplied Attrs into a str.

If supplied, ref is used for reference to make sure:

the reference columns are always present.
columns are rendered in the order specified in the reference.
columns widths will be at least as wide as those in the reference.

class chide.formats.CSVFormat(type_parse: dict[str, ~typing.Callable[[str], ~typing.Any]] | None = None, default_type_parse: ~typing.Callable[[str], ~typing.Any] = <function default_parse>, column_parse: dict[str, ~typing.Callable[[str], ~typing.Any]] | None = None, type_render: dict[~typing.Type[~typing.Any], ~typing.Callable[[~typing.Any], str]] | None = None, default_type_render: ~typing.Callable[[~typing.Any], str] = <function default_render>, type_names: dict[~typing.Type[~typing.Any], str | None] | None = None, column_render: dict[str, ~typing.Callable[[~typing.Any], str]] | None = None, types_location: ~chide.formats.TypeLocation | None = None)¶

Bases: TabularFormat

A Format that parses and renders comma separated values.

Parameters:

type_parse – A mapping of type name, as found in either a row or column heading, dependent on the types_location, to a function that parses the text of a cell into a value.
default_type_parse – The default function to use when parsing the text of a cell into a value.
column_parse – A mapping of column names to functions that will be used to parse the text of cells in that column into values.
type_render – A mapping of type objects to functions that will be used to render values of that type to text for cells.
default_type_render – The default function to use when rendingering values to text for cells.
type_names – A mapping of type objects to names to use for those types when including types in either column headings or their own own. If a type is mapped to None, then no type name will be rendered for columns containing date of that type.
column_render – A mapping of column names to functions that will be used to render values in that column to text for cells.
types_location – An optional location from which type information will be parsed or to which it will be rendered. Must be HEADER, ROW or None.

parse(text: str) → list[dict[str, Any]]¶: Parse the supplied text into a list of Attrs.

render(attrs: Iterable[dict[str, Any]], ref: list[dict[str, Any]] | None = None) → str¶

Render the supplied Attrs into a str.

If supplied, ref is used for reference to make sure:

the reference columns are always present.
columns are rendered in the order specified in the reference.

Simplifiers¶

class chide.simplifiers.Simplifier(*args, **kwargs)¶

Bases: Protocol[T]

Protocol for simplifiers.

one(obj: T) → dict[str, Any]¶: Simplify one object into its Attrs.

many(objs: Iterable[T]) → list[dict[str, Any]]¶: Simplify many objects into a list of their Attrs.

class chide.simplifiers.ObjectSimplifier¶

Bases: Simplifier[object]

A simplifier that can extract attributes from object-based classes that have either a __dict__ or __slots__.

one(obj: object) → dict[str, Any]¶: Simplify one object into its Attrs.

many(objs: Iterable[T]) → list[dict[str, Any]]¶: Simplify many objects into a list of their Attrs.

SQLAlchemy¶

class chide.sqlalchemy.Set(collection: Collection, identify: Callable[[Type[Any], dict[str, Any]], Hashable | None] | None = None)¶

Bases: Set

A specialised chide.Set for getting sample declaratively mapped objects when using SQLAlchemy.

static identify(type_: Type[Any], attrs: dict[str, Any]) → tuple[Any, ...] | None¶

This method returns the primary key that will be used for the returned object, meaning that only one sample object will exist and be returned for each primary key in a table.

If any element of the primary key is None, a new object is always returned.

get(type_: Type[T], **attrs: Any) → T¶

Return an appropriate sample object of the specified type_.

The attrs mapping will be overlaid onto the sample attributes found in this set’s Collection before checking if an appropriate sample object already exists in the set.

If one exists, it is returned. If not, one is created using this set’s Collection, added to the set and then returned.

class chide.sqlalchemy.RowSimplifier(*args, **kwargs)¶

Bases: Simplifier[Row[Any]]

A simplifier for SQLAlchemy Row objects.

one(row: Row[Any]) → dict[str, Any]¶: Simplify one object into its Attrs.

many(objs: Iterable[T]) → list[dict[str, Any]]¶: Simplify many objects into a list of their Attrs.

class chide.sqlalchemy.MappedSimplifier¶

Bases: Simplifier[DeclarativeBase]

A simplifier for SQLAlchemy ORM-mapped objects.

one(obj: DeclarativeBase) → dict[str, Any]¶: Simplify one object into its Attrs.

many(objs: Iterable[T]) → list[dict[str, Any]]¶: Simplify many objects into a list of their Attrs.