flam.attrutils

This page documents the flam.attrutils module. It contains utilities for implementing custom attributes with minimal boilerplate.

class EasyAttributeParams

Parameters used to create an EasyAttribute.

name_without_type: str

aliases_without_type: list[str]

findable_type: FindableType

type_handler: TypeHandler

is_ascending: bool

truncation_style: TruncationStyle: Indicates how this attribute’s values should be truncated if their string representation is too long.

default_max_len: int: The maximum length beyond which attribute values as strings get truncated.

__init__(name_without_type: str, aliases_without_type: list[str], findable_type: FindableType, type_handler: TypeHandler, is_ascending: bool, truncation_style: TruncationStyle, default_max_len: int) → None

Parameters:

name_without_type (str)
aliases_without_type (list[str])
findable_type (FindableType)
type_handler (TypeHandler)
is_ascending (bool)
truncation_style (TruncationStyle)
default_max_len (int)

Return type:

None

class EasyAttribute

Utility for easily implementing an attribute. You always have the option of inheriting directly from Attribute, but if you inherit from this instead you will have to do a lot less work. You only need to implement an extractor function for getting the attribute value:

class MovieTitleAttribute(EasyAttribute):
    def _extract_from_movie(self, movie: Movie, mlf_movie: MLFMovie) -> None | str:
        return mlf_movie.title

register(MovieTitleAttribute(EasyAttributeParams(
    name_without_type = 'title',
    aliases_without_type = ['name', 'movie'],
    findable_type = FindableType.MOVIES,
    type_handler = STR_HANDLER,
    is_ascending = True,
    truncation_style = TruncationStyle.TRIM_END,
    default_max_len = 45,
)))

__init__(params: EasyAttributeParams) → None

Parameters:: params (EasyAttributeParams) – dataclass with all this attribute’s parameters.
Return type:: None

str_of_value(value: AttributeValue, abbreviate: bool = False, **extras: Any) → str

See Attribute.str_of_value. EasyAttributes support two optional extras:

max_len - the maximum length beyond which the string will be truncated down to this length.
ellipsis - short string to use to indicate a truncated part of the string.

Parameters:

value (AttributeValue)
abbreviate (bool)
extras (Any)

Return type:

str

type MovieExtractor = Callable[[EasyAttribute, Movie, MLFMovie], T]: Type signature for _extract_from_movie.

type PeopleExtractor = Callable[[EasyAttribute, People, list[MLFPerson]], T]: Type signature for _extract_from_people.

type RoleExtractor = Callable[[EasyAttribute, Role, MLFRolesDict, MLFMovie, list[MLFPerson]], T]: Type signature for _extract_from_role.

type Extractor = MovieExtractor | PeopleExtractor | RoleExtractor: Type signature for any extractor method.

easy_attribute(params: EasyAttributeParams) → Callable[[Extractor[TRet]], EasyAttribute]

Decorator you can apply to an extractor function to create an EasyAttribute from it and return an instance of that class. This is an extra layer of convenience so you don’t even have to explicitly inherit from EasyAttribute or instantiate it:

@register
@easy_attribute(EasyAttributeParams(
    name_without_type = 'title',
    aliases_without_type = ['name', 'movie'],
    findable_type = FindableType.MOVIES,
    type_handler = STR_HANDLER,
    is_ascending = True,
    truncation_style = TruncationStyle.TRIM_END,
    default_max_len = 45,
))
def _movie_title_extractor(self, movie: Movie, mlf_movie: MLFMovie) -> None | str:
    return mlf_movie.title

Parameters:: params (EasyAttributeParams) – dataclass with all the attribute’s parameters.
Return type:: Callable[[Extractor[TRet]], EasyAttribute]

class TypeHandler

Utility for operations pertaining to the type of an attribute’s values, so you don’t have to repeat the same code for each attribute of that type.

Note that all attributes are assumed to also possibly return None or a list of values. So even if your attribute returns list[None | float], it may still use FLOAT_HANDLER, for example.

abstract property default_op: ComparisonOp: The default comparison operator that makes sense for this type.

abstractmethod parse(primitive_str: str) → AttributePrimitive

Parse a string representing a single primitive of this handler’s type. You do not need to handle None or lists in this function.

Parameters:: primitive_str (str) – a string representation of a single primitive value.
Return type:: AttributePrimitive

abstractmethod str_of(primitive: AttributePrimitive, abbreviate: bool, extras: dict[str, Any]) → str

Return a string representation of a single primitive value of this handler’s type. You do not need to handle None or lists in this function.

If abbreviate is false, then this method must be the inverse of parse().

Parameters:

primitive (AttributePrimitive) – a single primitive value. You may assume this is not None.
abbreviate (bool) – indicates if the string should be abbreviated. Abbreviation can mean different things for different types. It’s allowed to be lossy.
extras (dict[str, Any]) – additional optional arguments to control the string conversion.

Return type:

str

class IntHandler: Type handler for integers with support for pretty strings.

class FloatHandler: Type handler for floats with support for rounding off small decimal digits.

class BoolHandler: Type handler for booleans with support for various, case-insensitive ways you might describe them (‘true’, ‘yes’, ‘no’, ‘n’, etc.).

class StrHandler: Type handler for strings.

class MinutesHandler: Type handler for minutes with support for pretty formatting of hours:minutes.

class DateHandler

Type handler for dates in many possible formats.

property name: str: Name of the date format which can be appended to an attribute name to create a name for that attribute with that date format. Ex: ‘-year’, ‘-day-of-month’.

property datefmt: str: Format string for this date handler. See datetime.strftime in the python docs for format syntax.

property is_ascending: bool: Suggestion for whether you should sort this attribute in ascending or descending order.

strip(date: date) → date

Takes a date and “zeroes out” the parts of the date which are irrelevant to this handler’s datefmt.

For instance, a handler which returns the year only doesn’t care about the day and month. So by stripping those out, dates which have the same year but different days and months can be considered equal.

Parameters:: date (date)
Return type:: date

SMALL_INT_HANDLER = <flam.attrutils.IntHandler object>: Handler object you can use for attributes which return small integers that do not need to be abbreviated.

BIG_INT_HANDLER = <flam.attrutils.IntHandler object>: Handler object you can use for attributes which return big integers that sometimes need to be abbreviated.

FLOAT_HANDLER = <flam.attrutils.FloatHandler object>: Handler object you can use for attributes which return floats.

BOOL_HANDLER = <flam.attrutils.BoolHandler object>: Handler object you can use for attributes which return booleans.

STR_HANDLER = <flam.attrutils.StrHandler object>: Handler object you can use for attributes which return strings.

MINUTES_HANDLER = <flam.attrutils.MinutesHandler object>: Handler object you can use for attributes which return a minutes duration.

DATE_HANDLERS

List of date handlers in many date formats available to use.

class ArrayLengthAttribute

Attribute which returns the number of elements in another attribute’s return value. For attributes which don’t return a list, the length is 1:

register(ArrayLengthAttribute(my_attr))

__init__(wrapped_attr: Attribute) → None

Initializes this attribute with the name ‘num-<wrapped_attr.name_without_type>’.

Parameters:: wrapped_attr (Attribute) – the attribute whose num of elements will be returned.
Return type:: None

class StringLengthAttribute

Attribute which returns length of another attribute’s return value as a string.

__init__(wrapped_attr: Attribute) → None

Initializes this attribute with the name ‘len-<wrapped_attr.name_without_type>’.

Parameters:: wrapped_attr (Attribute) – the attribute whose string length will be returned.
Return type:: None

class AverageAttribute

Attribute which returns the average of another attribute’s value.

For movie attributes, this will be a people attribute with the average across all movies those people were in.
For people attributes, this will be a movie attribute with the average across all people in the movie with the same crew type.

register(AverageAttribute(my_attr))

for ct in CrewType:
    register(AverageAttribute(my_attr, as_crew_type=ct))

__init__(wrapped_attr: Attribute, as_crew_type: None | CrewType = None) → None

Initializes this attribute with the name ‘avg-<wrapped_attr.name_without_type>’.

Parameters:

wrapped_attr (Attribute) – the attribute whose average will be returned.
as_crew_type (None | CrewType) –
optional modifier for this attribute. If provided, the attribute’s name will be ‘avg-<wrapped_attr.name_without_type>-as-<crew_type>’:
- For movie attributes, this will be a people attribute with the average across all movies those people were in as this crew type.
- For people attributes, this will be a movie attribute with the average across all people in the movie with this crew type.

Return type:

None

class SumAttribute

Attribute which returns the sum of another attribute’s value.

For movie attributes, this will be a people attribute with the sum across all movies those people were in.
For people attributes, this will be a movie attribute with the sum across all people in the movie with the same crew type.

__init__(wrapped_attr: Attribute, type_handler: TypeHandler, as_crew_type: None | CrewType = None) → None

Initializes this attribute with the name ‘sum-<wrapped_attr.name_without_type>’.

Parameters:

wrapped_attr (Attribute) – the attribute whose sum will be returned.
as_crew_type (None | CrewType) –
optional modifier for this attribute. If provided, the attribute’s name will be ‘sum-<wrapped_attr.name_without_type>-as-<crew_type>’:
- For movie attributes, this will be a people attribute with the sum across all movies those people were in as this crew type.
- For people attributes, this will be a movie attribute with the sum across all people in the movie with this crew type.
type_handler (TypeHandler)

Return type:

None