Skip to content
New: Star-import, signal unraveling, Python 3.12 support, and more

#
decorators module

Class decorators for records.

## attach_fields function

    attach_fields(
        *args,
        on_conflict='raise'
    )

Class decorator to attach field properties in a Records class.

Will extract `dtype` and other relevant information from Records.field_config and map its fields as properties. This behavior can be changed by using `config`.

Note

Make sure to run attach_fields() after override_field_config().

`config` must contain fields (keys) and dictionaries (values) with the following keys:

- `attach`: Whether to attach the field property. Can be provided as a string to be used as a target attribute name. Defaults to True.
- `defaults`: Dictionary with default keyword arguments for Records.map_field(). Defaults to an empty dict.
- `attach_filters`: Whether to attach filters based on the field's values. Can be provided as a dict to be used instead of the mapping (filter value -> target filter name). Defaults to False. If True, defaults to `mapping` in Records.field_config.
- `filter_defaults`: Dictionary with default keyword arguments for Records.apply_mask(). Can be provided by target filter name. Defaults to an empty dict.
- `on_conflict`: Overrides global `on_conflict` for both field and filter properties.

Any potential attribute name is prepared by placing underscores between capital letters and converting to the lower case.

If an attribute with the same name already exists in the class but the name is not listed in the field config:

- it will be overridden if `on_conflict` is 'override'
- it will be ignored if `on_conflict` is 'ignore'
- an error will be raised if `on_conflict` is 'raise'

## attach_shortcut_properties function

    attach_shortcut_properties(
        config
    )

Class decorator to attach shortcut properties.

`config` must contain target property names (keys) and settings (values) with the following keys:

- `method_name`: Name of the source method. Defaults to the target name prepended with the prefix `get_`.
- `obj_type`: Type of the returned object. Can be 'array' for 2-dim arrays, 'red_array' for 1-dim arrays, 'records' for record arrays, and 'mapped_array' for mapped arrays. Defaults to 'records'.
- `group_aware`: Whether the returned object is aligned based on the current grouping. Defaults to True.
- `method_kwargs`: Keyword arguments passed to the source method. Defaults to None.
- `decorator`: Defaults to cached_property for object types 'records' and 'red_array'. Otherwise, to cacheable_property.
- `decorator_kwargs`: Keyword arguments passed to the decorator. By default, includes options `obj_type` and `group_aware`.
- `docstring`: Method docstring.

The class must be a subclass of Records.

## override_field_config function

    override_field_config(
        config,
        merge_configs=True
    )

Class decorator to override the field config of a class subclassing Records.

Instead of overriding `_field_config` class attribute, you can pass `config` directly to this decorator.

Disable `merge_configs` to not merge, which will effectively disable field inheritance.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings