flam

This page documents the core API of flam. It includes everything you get when you import flam.

DEFAULT_FLAM_DIR

The default path where flam stores all your movie lists and configuration. Equal to the environment variable FLAM_DIR, or ~/.film_flam if it’s not defined.

class PrecachePreference

Preference for what you’d like to be cached. For use with FlamContext.precache().

DEFAULTS = 1

Generate all composite lists, and cache particularly expensive computations for all movie lists.

EVERYTHING = 2

Cache everything that can possibly be cached.

RESET = 3

Don’t cache anything, instead delete existing cache files.

class FlamContext

Represents a user of a flam directory. All API use generally begins with creating a context, and anything you might do with flam generally goes through the context.

Only one context is allowed per flam directory at any given time.

__init__(flam_dir: None | str = DEFAULT_FLAM_DIR, import_extensions: bool = False) → None
Parameters:

  • flam_dir (None | str) –

    the directory where all movie lists and configuration should be stored.

    If this is None, flam will work in “volatile mode” - everything you fetch or configure will be lost when the context dies.

  • import_extensions (bool) –

    import all configured extensions, and subscribe to globally registered extensions.

    Warning

    Only enable this if you trust the extensions in the configuration.

Return type:

None

property flam_dir: str

The directory where all movie lists and configuration are stored.

property cfg_readonly: Configuration

All configuration settings. This object can technically be modified, but that would lead to disaster. If you want to modify the configuration, use configure().

property fetchers: RegistriesOf[type[Fetcher]]

A registry object with all registered fetchers.

property predicates: RegistriesOf[type[Predicate]]

A registry object with all registered predicates.

property attributes: RegistriesOf[Attribute]

A registry object with all registered attributes.

parse_listdef(listdef: str) → CanonListdef

Parse a string representation of a listdef and canonicalize it.

Parameters:

listdef (str) –

the listdef as a string. It can have a few forms:

  • ALL

  • DEFAULTS

  • ’<name>’ - where <name> is the name of a simple or composite list

  • ’<list_type>=<address>’ - where <list_type> is SIMPLE, COMPOSITE, or the name of a fetcher.

Return type:

CanonListdef

register(item: T) → T

Register a context-level extension. Context extensions are only available from the specific context to which they were registered.

You may register an item with the same name as that of a global extension or a builtin, and it will shadow them.

Parameters:

item (T) – the item to register.

Return type:

T

get_movie_list(listdefs: str | Iterable[str], filter: None | Filter = None) → MovieList

Create or open a movie list.

Parameters:

  • listdefs (str | Iterable[str]) – indicates which lists to open, or which lists to composite into this movie list. They must all be already fetched.

  • filter (None | Filter) – a movie filter used to filter out movies from the list. If provided, the returned list will be a composite list.

Return type:

MovieList

configure() → Iterator[Configuration]

Returns the configuration settings inside a context where they may be modified. When the context exits, all changes are saved.

with ctx.configure() as cfg:
    cfg.extensions.append('my_extension.py')
Return type:

Iterator[Configuration]

fetch(listdefs: Iterable[str], refetch_pattern: None | str = None, quiet: bool = True, **fetch_params: str) → None

Fetch movie lists, i.e. download all their data from some external source and store it locally. Depending on the fetcher and the size of the list, this may run for a long time - even hours.

Parameters:

  • listdefs (Iterable[str]) –

    which lists to fetch. For composite lists, will actually fetch all simple lists which composite it. A few special values are also supported:

    • Supports ‘defaults’ to fetch all lists configured with is_default_fetch=True

    • Supports '*' to fetch all configured lists

  • refetch_pattern (None | str) – forces titles that match this regular expression (case-insensitive) to be refetched even if they are already locally stored. The expression only needs to match any part of the title, not the whole title. Intended for redownloading shows after a new season has come out.

  • quiet (bool) – indicates if progress should be printed to stdout.

  • fetch_params (str)

Return type:

None

precache(preference: PrecachePreference = PrecachePreference.DEFAULTS, quiet: bool = True) → None

Precompute some things and cache them to disk so that flam will work faster. This is strictly optional.

Parameters:

  • preference (PrecachePreference) – what you prefer to be cached.

  • quiet (bool) – if False, will print about its progress to stdout.

Return type:

None

compile_filter(tokens: list[str], find: FindableType) → Filter

Compile a string into a filter object.

Parameters:

  • tokens (list[str]) –

    the desired filter string split into tokens. Here is an example to illustrate how to split it:

    # As a string:
'-title lebowski -o -release-year 1980'

# Split into tokens:
['-title', 'lebowski', '-o', 'release-year', '1980']

  • find (FindableType) – the type of objects the filter is supposed to filter. Some predicates may be specific to a certain findable type.

Return type:

Filter

compile_movies_filter(tokens: list[str]) → Filter

Wrapper for compile_filter() when the filter is for MOVIES.

Parameters:

tokens (list[str])

Return type:

Filter

compile_people_filter(tokens: list[str]) → Filter

Wrapper for compile_filter() when the filter is for PEOPLE.

Parameters:

tokens (list[str])

Return type:

Filter

compile_roles_filter(tokens: list[str]) → Filter

Wrapper for compile_filter() when the filter is for ROLES.

Parameters:

tokens (list[str])

Return type:

Filter

class RegistriesOf

Object representing everything that is registered in a FlamContext of type T. T may be either Attribute, type[Predicate], or type[Fetcher].

__getitem__(qualified_name: str) → T

Get a registered item.

Parameters:

qualified_name (str) – the full, qualified name of the item. Qualified names include both the name and the type. E.g., instead of ‘title’, it should be ‘movies-title’.

Return type:

T

__contains__(qualified_name: str) → bool

Check if the registry contains an item with this name.

Parameters:

qualified_name (str) – the full, qualified name of the item.

Return type:

bool

__iter__() → Iterator[T]

Iterate over all unique items in the registry.

To iterate over the raw registry, see raw_iterate().

Return type:

Iterator[T]

raw_iterate() → Iterable[str]

Iterate over the names of all items in the registry. Beware:

  • Items support aliases so the same item may be returned multiple times, once for each name it is known by

  • Items may be shadowed if a different item with the same name is registered in a higher-level registry, so this may return the same name twice

To iterate over items without worrying about the above, use __iter__().

Return type:

Iterable[str]

get(name: str, type_hint: None | _ml.FindableType = None) → T

Get a registered item, with optional support for non-qualified names.

Parameters:

  • name (str) – the name of the item. It must be fully qualified unless type_hint is given.

  • type_hint (None | _ml.FindableType) –

    attempt to infer the type from a non-qualified name, with a preference for this hinted type. Multiple items can have the same name but with a different type, so this helps resolve that ambiguity.

    Warning

    This does NOT guarantee that the returned item will have the same type! It only guarantees to prefer that type if there’s ambiguity.

Return type:

T

class GroupMode

Indicates whether people who collaborate together should be grouped into a single “person”. For example, if grouping is enabled then the Coen brothers will be presented as a single entry when finding directors.

DEFAULT = 'default'

Use whichever default makes sense for the crew type.

GROUP = 'group'

Do try to group collaborators together.

SEPARATE = 'separate'

Don’t group - keep each person as a separate entry.

classmethod iterate_except_default() → Iterable[GroupMode]

Iterate over all values except DEFAULT.

Return type:

Iterable[GroupMode]

class CrewType

A job on a movie set.

DIRECTOR = 'director'
ASSISTANT_DIRECTOR = 'assistant-director'
PRODUCER = 'producer'
EXECUTIVE_PRODUCER = 'executive-producer'
COMPOSER = 'composer'
CINEMATOGRAPHER = 'cinematographer'
CHOREOGRAPHER = 'choreographer'
EDITOR = 'editor'
WRITER = 'writer'
CAST = 'cast'
STUNTCAST = 'stuntcast'
CASTING_DIRECTOR = 'casting-director'
ART_DIRECTOR = 'art-director'
ADDITIONAL = 'additional'

Catch-all category for crew types not listed above.

ANY = 'any'

No crew type in particular, only care about if the person was in the movie in any capacity.

property default_group_mode: GroupMode

The group mode which makes the most sense for this crew type.

classmethod iterate_except_any() → Iterable[CrewType]

Iterate over all values except ANY.

Return type:

Iterable[CrewType]

parse_ct_gm(ct_gm_str: str) → tuple[CrewType, GroupMode]

Parse a CTGM, short for “crew type + group mode”, and returns it as a tuple.

CTGMs can be just the crew type or also the group mode with a colon delimiter. Ex: ‘director:group’, ‘cast:separate’, ‘writer:default’ or just ‘writer’.

Parameters:

ct_gm_str (str) – the CTGM as a string.

Return type:

tuple[CrewType, GroupMode]

ct_gm_to_str(crew_type: CrewType, group_mode: GroupMode) → str

Inverse of parse_ct_gm().

Parameters:
Return type:

str

class FindableType

The type of an object which can be found in a movie list.

MOVIES = 'movies'

Each object represents a single movie from the list.

PEOPLE = 'people'

Each object may represent more than one person from the list, if grouping is enabled. They can also be limited to a specific crew type and group mode.

ROLES = 'roles'

Each object represents an appearance of a person (or several grouped people) in a specific film in some specific capacity. Think “Cristoph Waltz as a castmember in Inglorious Basterds”.

So when searching for roles, you will see an entry per people per movie.

is_applicable_to(find: FindableType) → bool

True if attributes of this findable type can be extracted from objects of type find.

Movie objects only support movie attributes.

People objects only support people attributes.

Roles are a combination of a movie and a people, so they support all attribute types.

Parameters:

find (FindableType) – the type of the object you would try to extract an attribute from.

Return type:

bool

class Findable

Base class for “findables”; objects which can be found in a movie list.

property movie_list: MovieList

The list this object came from.

abstract property type_: FindableType

The type of this object.

abstract property uid: str

A unique string identifying this object. It’s unique only per movie list.

extract(attribute: Attribute) → AttributeValue

Get the value of an attribute which is applicable to this object. See FindableType.is_applicable_to().

Parameters:

attribute (Attribute) – the attribute whose value you are interested in.

Return type:

AttributeValue

__getitem__(attribute_name: str) → AttributeValue

Same as extract(), but resolves the attribute from its name.

Parameters:

attribute_name (str) – the name of the attribute. It does not have to be a qualified name.

Return type:

AttributeValue

class Movie

Represents a movie from the list.

property type_: FindableType

The type of this object.

property uid: str

A unique string identifying this object. It’s unique only per movie list.

property underlying_file_movie_readonly: MLFMovie

Serializable object we use to store all the movie’s data to disk. It can technically be modified, but you shouldn’t do that.

Note

This is mostly an internal API; you might need it when implementing a custom extension.

For typical use cases, you should use attributes to read the movie’s data instead.

associated_people(crew_type: CrewType, group_mode: GroupMode) → Iterable[People]

Iterate over all people who were in this movie in a specific capacity. The order of iteration is guaranteed to be consistent.

Parameters:

  • crew_type (CrewType) – only find people who performed this specific job on the movie

  • group_mode (GroupMode) – indicates if collaborators should be grouped together

Return type:

Iterable[People]

associated_roles(crew_type: CrewType, group_mode: GroupMode) → Iterable[Role]

Same as associated_people(), but returns them as Role objects where the movie is this movie.

Parameters:
Return type:

Iterable[Role]

class PeopleUidParts

The parts which make up a People UID. Returned by People.decompose_uid().

mlf_people_uids: Iterable[str]
crew_type: CrewType
group_mode: GroupMode
class People

Represents a person in their capacity as a specific crew type, or several collaborating people if grouping is enabled.

property type_: FindableType

The type of this object.

property uid: str

A unique string identifying this object. It’s unique only per movie list.

property crew_type: CrewType

The job these people perform in movies.

property group_mode: GroupMode

Whether these people were searched with grouping enabled.

property underlying_file_people_readonly: list[MLFPerson]

List of serializable objects we use to store each person’s data to disk, sorted in a consistent order. It can technically be modified, but you shouldn’t do that.

Note

This is mostly an internal API; you might need it when implementing a custom extension.

For typical use cases, you should use attributes to read the people’s data instead.

associated_movies() → Iterable[Movie]

Iterate over movies these people were in as this crew type. The order of iteration is guaranteed to be consistent.

In the case of several grouped people, only movies that they were all in together will be returned.

Return type:

Iterable[Movie]

associated_roles() → Iterable[Role]

Same as associated_movies(), but returns them as Role objects where the people are these people.

Return type:

Iterable[Role]

minimal_superset_people_in_other_crew_type(crew_type: CrewType) → None | People

Returns the smallest group of people in another crew type who contain every person in this group, or None if there is no such group.

Parameters:

crew_type (CrewType) – which crew type to search for these people in.

Return type:

None | People

minimal_superset_people_in_other_list(other_list: MovieList, crew_type: None | CrewType = None) → None | People

Returns the smallest group of people in another movie list and optionally different crew type who contain every person in this group, or None if there is no such group.

Parameters:

  • other_list (MovieList) – which movie list to search for these people in.

  • crew_type (None | CrewType) – which crew type to search for these people in. By default searches in the same crew type as these people.

Return type:

None | People

are_in_movie(movie: Movie) → bool

Check if these people were in this movie. This takes the crew type into consideration.

Parameters:

movie (Movie) – the movie to check.

Return type:

bool

classmethod compose_uid(mlf_people_uids: Iterable[str], crew_type: CrewType, group_mode: GroupMode) → str

Compose a people UID which can be used to MovieList.get_people_by_uid().

Parameters:

  • mlf_people_uids (Iterable[str]) – the UID of each person in the source that the movie list was fetched from.

  • crew_type (CrewType) – the people’s crew type.

  • group_mode (GroupMode) – the people’s group mode.

Return type:

str

classmethod decompose_uid(uid: str) → PeopleUidParts

Inverse of compose_uid().

Parameters:

uid (str)

Return type:

PeopleUidParts

class RoleUidParts

The parts which make up a Role UID. Returned by Role.decompose_uid().

movie_uid: str
people_uid: str
type MLFRolesDict = dict[str, dict[CrewType, MLFRole]]

Data structure with all the raw fetch information about a role. It maps the “MLF” UID of people in the group (i.e., the UID of a person in the fetch source) and the crew type to the object with the role data.

If the Role's crew type isn’t CrewType.ANY, then that’ll be the only crew type in the dictionary. Otherwise, the dictionary will have every crew type the person occupied.

# mlf_person is a person's underlying file object, and crew_type is the crew type he was in in this role.
mlf_role = roles_dict[mlf_person.uid][crew_type]
print(mlf_role.characters)
class Role

Represents an appearance of a person (or several grouped people) in a specific film in some specific capacity. Think “Cristoph Waltz as a castmember in Inglorious Basterds”.

property type_: FindableType

The type of this object.

property uid: str

A unique string identifying this object. It’s unique only per movie list.

property movie: Movie

The movie this role was in.

property people: People

The people who performed this role.

property crew_type: CrewType

The job these people performed in this movie.

property group_mode: GroupMode

Whether these people were grouped by collaborators.

property underlying_file_roles_readonly: MLFRolesDict

Dictionary of serializable objects we use to store each role’s data to disk. It can technically be modified, but you shouldn’t do that.

Note

This is mostly an internal API; you might need it when implementing a custom extension.

For typical use cases, you should use attributes to read the role’s data instead.

classmethod compose_uid(movie: Movie, people: People) → str

Compose a role UID which can be used to MovieList.get_role_by_uid().

Parameters:

  • movie (Movie) – the movie the role was in.

  • people (People) – the people in the role.

Return type:

str

classmethod decompose_uid(uid: str) → RoleUidParts

Inverse of compose_uid().

Parameters:

uid (str)

Return type:

RoleUidParts

class MovieList

Represents a movie list with functions to inspect the objects in the list.

property underlying_file_readonly: MovieListFile

Serializable object we use to store all the list’s data to disk. It can technically be modified, but you shouldn’t do that.

Note

This is mostly an internal API; you might need it when implementing a custom extension.

For typical use cases, you should use find() to read the list’s data instead.

property ctx: FlamContext

The context used to load this list.

property abstract_listdef: CanonListdef

Listdef which describes how to get this list.

property uid_family: str

The UID family used to fetch this list or all lists compositing it. I.e., if you have multiple ways to fetch data from IMDb, they would all have the same family and be compatible with one another for compositing.

find(what: FindableType, crew_type: None | CrewType = None, group_mode: GroupMode = GroupMode.DEFAULT, filter: None | Filter = None) → Iterable[Findable]

Iterate over objects in the list. They’re guaranteed to be returned in a consistent order every time.

Parameters:
Return type:

Iterable[Findable]

find_movies(filter: None | Filter = None) → Iterable[Movie]

Wrapper for find() when searching for FindableType.MOVIES.

Parameters:

filter (None | Filter)

Return type:

Iterable[Movie]

find_people(crew_type: CrewType, group_mode: GroupMode = GroupMode.DEFAULT, filter: None | Filter = None) → Iterable[People]

Wrapper for find() when searching for FindableType.PEOPLE.

Parameters:
Return type:

Iterable[People]

find_roles(crew_type: CrewType, group_mode: GroupMode = GroupMode.DEFAULT, filter: None | Filter = None) → Iterable[Role]

Wrapper for find() when searching for FindableType.ROLES.

Parameters:
Return type:

Iterable[Role]

get_by_uid(findable_type: FindableType, uid: str) → None | Findable

Get an object by its UID, or None if it doesn’t exist.

Parameters:

  • findable_type (FindableType) – the type of object to get.

  • uid (str) – the object’s UID.

Return type:

None | Findable

get_movie_by_uid(uid: str) → None | Movie

Wrapper for get_by_uid() when searching for FindableType.MOVIES.

Parameters:

uid (str)

Return type:

None | Movie

get_people_by_uid(uid: str, ct_gm_hint: None | tuple[CrewType, GroupMode] = None) → None | People

Wrapper for get_by_uid() when searching for FindableType.PEOPLE.

Parameters:

  • ct_gm_hint (None | tuple[CrewType, GroupMode]) – the people’s crew type and group mode. This is optional because it can be deduced from uid, but it helps performance.

  • uid (str)

Return type:

None | People

get_role_by_uid(uid: str, ct_gm_hint: None | tuple[CrewType, GroupMode] = None) → None | Role

Wrapper for get_by_uid() when searching for FindableType.ROLES.

Parameters:

  • ct_gm_hint (None | tuple[CrewType, GroupMode]) – the role’s crew type and group mode. This is optional because it can be deduced from uid, but it helps performance.

  • uid (str)

Return type:

None | Role

type AttributePrimitive = None | SupportsRichComparison

Type of a single element from a value returned by an attribute. Attributes may return either a primitive or a list of primitives. None is common, so always check for that. And other than that you are guaranteed that the value will be sortable.

type AttributeValue = AttributePrimitive | list[AttributePrimitive]

Type of a value returned by an attribute.

class ComparisonOp

Enumeration of possible comparison operators for comparing attributes to values. Each operator is represented with a different sign.

LE = '-'

Less or equal.

GE = '+'

Greater or equal.

EQ = '='

Exactly equal.

LT = '.-'

Strictly less than.

GT = '.+'

Strictly greater than.

RX = '~'

str(value) matches a regular expression.

__call__(primitive_lhs: AttributePrimitive, primitive_rhs: AttributePrimitive | Pattern) → bool

Compare the left hand side to the right hand side. The order matters. To illustrate:

# Same as 10 < 15.
ComparisonOp.LE(10, 15)

# Same as re.search('the.*', 'The Big Lebowski').
ComparisonOp.RX('The Big Lebowski', re.compile('the.*'))
Parameters:
Return type:

bool

class CmpTo

Represents comparison of some attribute’s values to some constant primitive value, using a specific comparison operator.

In a filter, these would be represented as a string like so: ‘<op><value>’, where <op> is the sign of a ComparisonOp, and <value> is a possible value of an attribute. The <op> part is optional as all attributes define a default operator. To illustrate:

# As a string: '+90'. Checks if metascores are greater or equal to 90.
CmpTo(ComparisonOp.GE, 90, ctx.attributes['movies-metascore'])

# As a string: '~the.*'. Checks if stringified values match the regex 'the.*'.
# This is usually the default operator for string attributes, so the '~' can usually be omitted and you can simply write 'the.*'.
CmpTo(ComparisonOp.RX, re.compile('the.*'), ctx.attributes['movies-title'])
__init__(op: ComparisonOp, const_primitive: AttributePrimitive | Pattern, attribute: Attribute) → None
Parameters:

  • op (ComparisonOp) – the operator to use for comparisons.

  • const_primitive (AttributePrimitive | Pattern) – which constant value to compare other values to.

  • attribute (Attribute) – which attribute the values are expected to come from.

Return type:

None

__call__(primitive: AttributePrimitive) → bool

Compares primitive to the constant value. Expects primitive to come from the same attribute this object was created with.

When comparing None to a not-None value, the result is always false. That is, None is neither less, nor greater, nor equal to other values.

Parameters:

primitive (AttributePrimitive) – variable value to compare with.

Return type:

bool

class Attribute

Base class for all attributes that a findable object may have. This is a key element in interfacing with flam - any data you may be interested in obtaining about a movie, people, or role is obtained via attributes.

Attributes provide facilities for using them generically. You can extend flam by inheriting from this class and registering your own custom attributes.

NONE_STR = '-'

The string representation we use for None values.

__init__(findable_type: FindableType, name_without_type: str, aliases_without_type: None | list[str] = None)
Parameters:

  • findable_type (FindableType) – the type of objects which have this attribute.

  • name_without_type (str) – the name of the attribute without the findable type.

  • aliases_without_type (None | list[str]) – list of aliases for the attribute, also without the type.

property name_without_type: str

The name of the attribute without the findable type. E.g. ‘title’, not ‘movies-title’.

property aliases_without_type: Iterable[str]

Iterate over all aliases of the attribute, also without the findable type.

property findable_type: FindableType

The type of objects which have this attribute.

property qualified_name: str

The qualified name of the attribute. E.g. ‘movies-title’, not just ‘title’.

property qualified_aliases: Iterable[str]

Iterate over all aliases of the attribute, by their qualified name.

abstract property is_ascending: bool

Suggestion for whether you should sort this attribute in ascending or descending order.

abstract property default_op: ComparisonOp

The default comparison operator that makes sense for this attribute.

Typically, string attributes use regular expression matching by default, and other attributes check for equality.

abstractmethod _parse_primitive_not_none(primitive_str: str) → AttributePrimitive

Note

This is an internal method of attributes. Outside users shouldn’t call it, but you need to implement it as part of implementing a custom attribute.

Parse a string representing a single primitive into the value of this attribute. You do not need to handle None or lists in this function.

Parameters:

primitive_str (str) – a string representation of a single primitive value. You may assume this is not NONE_STR.

Return type:

AttributePrimitive

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

Note

This is an internal method of attributes. Outside users shouldn’t call it, but you need to implement it as part of implementing a custom attribute.

Return a string representation of a single primitive value of this attribute. 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_primitive_not_none().

Parameters:

  • primitive (AttributePrimitive) – a single primitive value. You may assume this is not None.

  • abbreviate (bool) – indicates if the string should be abbreviated. For example truncating long strings, or converting 1000000 to “1M”.

  • extras (dict[str, Any]) – additional optional arguments to control the string conversion.

Return type:

str

sort_key(value: AttributeValue, is_ascending: None | bool = None) → Any

Returns an object which may be used to safely compare values of this attribute, even if some of them are None. For example:

Parameters:

  • is_ascending (None | bool) – optionally indicate the desired sort order. This will ensure Nones are at the bottom of the sort no matter what. Defaults to is_ascending.

  • value (AttributeValue)

Return type:

Any

attr_values = [movie.extract(attr) for attr in movie_list.find_movies()]
attr_values.sort(key=attr.sort_key, reverse=(not attr.is_ascending))
Parameters:

  • value (AttributeValue) – a value extracted using this attribute.

  • is_ascending (None | bool)

Return type:

Any

parse_primitive(primitive_str: str) → AttributePrimitive

Parse a string representing a single primitive into the value of this attribute.

Parameters:

primitive_str (str) – a string representation of a single primitive value.

Return type:

AttributePrimitive

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

Return a string representation of a value of this attribute. If the value is a list, its elements will be separated by commas.

Parameters:

  • value (AttributeValue) – a value of this attribute.

  • abbreviate (bool) – indicates if the string should be abbreviated. For example truncating long strings, or converting 1000000 to “1M”.

  • extras (Any) – additional optional arguments to control the string conversion.

Return type:

str

class CanonListdef

Represents a spec for identifying a list. Listdefs as a strings have the form “<list_type>=<address>”, or sometimes just “<address>”, and internally we “canonicalize” them into this object. This process involves:

  • Inferring the list type if it’s missing - we’re only able to infer the types for configured simple or composite lists

  • Handling some special values. See SpecialListType.

Some important things to know about listdefs:

  • Once they’re past canonicalization, the special list types SpecialListType.ALL and SpecialListType.DEFAULTS are handled and you don’t have to check for them

  • Simple/composite lists are described with the address being their name, but during canonicalization we change that to their UID

  • When printing a listdef to the user, it’s best to format it pretty() because that will convert these list uids back to their names

Concrete and abstract canon listdefs:

  • Canon listdefs are “concrete” when they describe the raw address from which the data was fetched. E.g., “imdb-listid=083886771”

  • Canon listdefs are “abstract” when they describe a configured list. E.g., “list=watched”

list_type: str

The fetcher used to download information about this list. Also supports a few special values, see SpecialListType.

address: str

An address pointing to an exact list. This could be different based on the list type - it could be a path, a URL, a name, or anything else.

property is_special: bool

Whether this listdef has a special type.

property is_abstract: bool

Whether this listdef is “abstract”, meaning it describes a configured list. E.g., “list=watched”.

property is_concrete: bool

Whether this listdef is “concrete”, meaning it describes a raw address from which the data was fetched. E.g., “imdb-listid=083886771”.

pretty(ctx: FlamContext) → str

Returns a pretty string representation of this listdef. Use this so configured lists will be printed with their name instead of a long ugly UID.

Parameters:

ctx (FlamContext) – the context containing list configurations we need to know.

Return type:

str

class SpecialListType

An enumeration of special listdef types.

ALL = '*'

All configured simple lists.

DEFAULTS = 'defaults'

All configured as default lists. We have different defaults for fetch vs find.

SIMPLE = 'list'

A simple list. Lists which are just a name for the raw data list from the source. Outwardly uses the name as the address, but internally uses a uid.

COMPOSITE = 'composite'

A composite list. Lists which are a combination of other lists with a filter. Outwardly uses the name as the address, but internally uses a uid.

ANONYMOUS = 'anonymous'

FOR INTERNAL USE ONLY - anonymous composites. Composite lists which are not preconfigured but spun on-the-fly.

register(item: T) → T

Register an predicate, attribute, or fetcher as a global extension. Global extensions are available to use from any context with import_extensions=True.

You may register an item with the same name as that of a builtin, and it will shadow it.

This function is meant to be used as a decorator (i.e. with @register).

Parameters:

item (T) – the item to register.

Return type:

T

compose_qualified_attr_or_pred_name(findable_type: FindableType, name_without_type: str) → str

Compose an attribute or predicate qualified name from its parts. For example:

compose_qualified_attr_or_pred_name(FindableType.MOVIES, 'title') # Returns 'movies-title'.
Parameters:

  • findable_type (FindableType) – the item’s type.

  • name_without_type (str) – the item’s name without the type.

Return type:

str

decompose_qualified_attr_or_pred_name(qualified_name: str) → tuple[FindableType, str]

Inverse of compose_qualified_attr_or_pred_name().

Parameters:

qualified_name (str)

Return type:

tuple[FindableType, str]

class Fetcher

Base class for all fetchers. Fetchers are in charge of actually downloading data about movie lists from some source like IMDb, Letterboxd, etc.

You can extend flam by inheriting from this class and registering your own custom fetchers.

qualified_name: str

The fetcher’s name. This corresponds to a listdef’s list_type.

qualified_aliases: list[str]

List of aliases for the fetcher.

uid_family: str

The UID family this fetcher uses. Composite lists can only be formed from lists with the same UID family.

Fetchers need to assign some unique string to each movie and person they download, but what exactly they use can vary from fetcher to fetcher. Usually they’ll use the UIDs used by the source the data is fetched from.

For example, a fetcher which sources its data from IMDb might identify a movie by the same ID IMDb identifies it with. But there are multiple APIs you could use to fetch data from IMDb. So you can implement multiple fetchers which all fetch from IMDb, but in different ways. If you make all those fetchers use the same UID family, then they will all be compatible with each other.

classmethod __init_subclass__(list_type: str, qualified_aliases: None | list[str] = None, uid_family: None | str = None, **kwargs: Any) → None

Defines parameters that subclasses can (or must) pass in as part of subclassing. Ex:

class MyCustomFetcher(Fetcher, list_type='my-imdb-fetcher', uid_family='imdb'):
    # ...
Parameters:

  • list_type (str) – the name of this fetcher.

  • qualified_aliases (None | list[str]) – list of aliases for this fetcher.

  • uid_family (None | str) – which UID family this fetcher uses. Defaults to list_type, indicating this fetcher is only compatible with itself.

  • kwargs (Any)

Return type:

None

__init__(concrete_listdef: CanonListdef, abstract_listdef: CanonListdef, fetch_params: dict[str, str], ctx: FlamContext) → None
Parameters:
Return type:

None

property concrete_listdef: CanonListdef

The raw fetcher name and address to fetch from.

property abstract_listdef: CanonListdef

The simple list being fetched, if it is a simple list. Otherwise same as concrete_listdef.

get_param(param_name: str) → str

Get the value of a fetch parameter.

Parameters:

param_name (str)

Return type:

str

has_param(param_name: str) → bool

Check if fetcher has been passed this parameter.

Parameters:

param_name (str)

Return type:

bool

abstractmethod _fetch_into_file(movie_list_file: MovieListFile) → None

Note

This is an internal method of fetchers. Outside users shouldn’t call it, but you need to implement it as part of implementing a custom fetcher.

Obtain data about the list identified by concrete_listdef, and populate movie_list_file with all the data fetched about movies in the list and the people in them.

If this function raises FetchInterrupt, everything written to the file so far will be saved to disk.

There are a few sensitive points about the exact order that you populate this object with data:

  • Always add the people in a movie before you add the movie itself

  • Only add a movie object after it’s fully populated with its data

The above points ensure that the file is always in a good, saveable state. So if fetching gets interrupted or _checkpoint() is called and the file is saved, it won’t cause partially fetched movies to be in the file, which on the next fetch you won’t know you have to re-fetch.

Parameters:

movie_list_file (MovieListFile) –

serializable object to populate with all the data we can get about the movie list.

The only fields you should populate are movies_by_uid, people_by_uid. The rest are handled outside this fetcher.

If the list was previously fetched, this object will contain all the data from the previous fetch. Use this fact to only fetch movies that weren’t already fetched, which can save a lot of time.

However, it’s also your responsibility to remove movies from this file if they are no longer in the list.

When removing movies that were previously fetched, you don’t have to worry about also removing the people in those movies. That happens automatically before the file is saved.

Return type:

None

_checkpoint(movie_list_file: MovieListFile) → None

Store the work-in-progress on this file to disk, so that if a crash happens the data fetched so far won’t be lost. This method is meant to only be called internally from inside _fetch_into_file().

You should only call this function during good save points. I.e., moments when the file doesn’t contain any partially fetched movies.

Parameters:

movie_list_file (MovieListFile) – the same object that was passed to _fetch_into_file().

Return type:

None

class EatParams

Common parameters passed around during filter “eating” (i.e. compilation).

tokens: list[str]

The complete list of tokens to compile, including ones already processed.

find: FindableType

The type of objects this filter filters. Some predicates are specific to a findable type, so some filters will compile for one findable type but not another.

ctx: FlamContext

Context that this filter came from. Some filters will only compile with a specific context in which you’ve registered predicates other contexts don’t know about.

__init__(tokens: list[str], find: FindableType, ctx: FlamContext) → None
Parameters:
Return type:

None

class FilterMember

Base class for all components of a filter. Filters are essentially an AST (abstract syntax tree) of filter members.

abstractmethod excrete(findable: Findable) → bool

Returns True if the findable passes this filter.

Parameters:

findable (Findable) – the object to filter.

Return type:

bool

abstractmethod regurgitate() → Iterable[str]

Decompiles this filter into a list of tokens.

Return type:

Iterable[str]

abstractmethod colonoscopy() → Iterable[FilterMember]

Iterate over all members of the filter. They’re returned from left to right.

Return type:

Iterable[FilterMember]

classmethod eat_str(params: EatParams, at: int, description: str, error_indices: int | Iterable[int] = -1, is_terminal: bool = True) → str

Helper method to eat and return params.tokens[at], or raise FilterSyntaxError if the index is out of bounds.

Parameters:

  • params (EatParams) – general parameters of this compilation.

  • at (int) – the index of the token to eat.

  • description (str) – describes the expected meaning of this token, for raising a meaningful exception (ex: ‘a valid attribute name’).

  • error_indices (int | Iterable[int]) – indicates which indices in params.tokens to highlight as problematic in case of error.

  • is_terminal (bool) – indicates if an exception would mean that the entire compilation has failed, or is the error recoverable.

Return type:

str

classmethod eat_listof(eatfunc: Callable[[EatParams, int], T], params: EatParams, at: int, at_least_one: bool) → tuple[list[T], int]

Helper method to eat and return a list of tokens. Returns a tuple of the list and the index of the first token after the list. The syntax is as follows:

  • List of 0 or more elements enclosed in parentheses:

    ‘-any-role [ director writer composer ] -name tarantino’

  • List of size 1, no parentheses required:

    ‘-any-role director -name tarantino’

  • Empty list, both parentheses can be a single token:

    ‘-any-role [] -name tarantino’

Example of eating a list of CTGMs:

ct_gms, until = FilterMember.eat_listof(FilterMember.eat_ct_gm, params, at, at_least_one=False)
Parameters:

  • eatfunc (Callable[[EatParams, int], T]) – function which should eat only a single token at at a given index. Each list element will be consumed with this function.

  • params (EatParams) – general parameters of this compilation.

  • at (int) – index at which the list tokens are expected to begin.

  • at_least_one (bool) – indicates if this function should fail on empty lists.

Return type:

tuple[list[T], int]

classmethod eat_one_of(params: EatParams, at: int, description: str, options: set[str], is_terminal: bool = True) → str

Helper method to eat and return a single token which must be one of a set of possible values.

Parameters:

  • params (EatParams) – general parameters of this compilation.

  • at (int) – the index of the token to eat.

  • description (str) – describes the expected meaning of this token, for raising a meaningful exception (ex: ‘left parenthesis’).

  • options (set[str]) – set of possible values the token is allowed to have.

  • is_terminal (bool) – indicates if an exception would mean that the entire compilation has failed, or is the error recoverable.

Return type:

str

classmethod eat_attribute(params: EatParams, at: int) → Attribute

Helper method to eat a token representing an attribute name and return the attribute.

Parameters:

  • params (EatParams) – general parameters of this compilation.

  • at (int) – the index of the token to eat.

Return type:

Attribute

classmethod eat_cmpto(params: EatParams, at: int, attribute: Attribute) → CmpTo

Helper method to eat a token representing a CmpTo and return it.

Parameters:

  • params (EatParams) – general parameters of this compilation.

  • at (int) – the index of the token to eat.

  • attribute (Attribute) – the attribute whose values are to be compared.

Return type:

CmpTo

classmethod eat_type(params: EatParams, at: int, description: str, type_: Callable[[str], T]) → T

Helper method to eat a token which should be parseable as some specific type, and return the parsed value.

Parameters:

  • params (EatParams) – general parameters of this compilation.

  • at (int) – the index of the token to eat.

  • description (str) – describes the expected meaning of this token, for raising a meaningful exception (ex: ‘a valid attribute name’).

  • type_ (Callable[[str], T]) – function for parsing the token string. E.g., int, CrewType.

Return type:

T

classmethod eat_movie_list(params: EatParams, at: int) → tuple[MovieList, int]

Helper method to eat a list of tokens representing listdefs which together compose a MovieList. Returns a tuple of the movie list and the index of the first token after the list.

Parameters:

  • params (EatParams) – general parameters of this compilation.

  • at (int) – index at which the listdef tokens are expected to begin.

Return type:

tuple[MovieList, int]

classmethod eat_ct_gm(params: EatParams, at: int) → tuple[CrewType, GroupMode]

Helper method to eat a token representing a CrewType and optional GroupMode. See parse_ct_gm().

Parameters:

  • params (EatParams) – general parameters of this compilation.

  • at (int) – the index of the token to eat.

Return type:

tuple[CrewType, GroupMode]

classmethod eat_subfilter(params: EatParams, at: int) → tuple[Filter, int]

Helper method to eat a list of tokens representing a subfilter that is either made up of a single member or enclosed in parentheses. Returns a tuple of the subfilter and the index of the first token after the filter.

Parameters:

  • params (EatParams) –

    general parameters of this compilation. Sometimes subfilters may have a different EatParams.find than the parent filter. For example:

    sub_params = dataclasses.replace(params, find=FindableType.ROLES)
sub_filter, until = FilterMember.eat_subfilter(sub_params, at)

  • at (int) – index at which the subfilter tokens are expected to begin.

Return type:

tuple[Filter, int]

class Filter

Represents the root member of a filter.

property findable_type: FindableType

The type of objects this filter filters. Some predicates are specific to a findable type, so some filters will compile for one findable type but not another.

property ctx: FlamContext

Context that this filter came from. Some filters will only compile with a specific context in which you’ve registered predicates other contexts don’t know about.

property is_empty: bool

True if this filter checks nothing.

excrete(findable: Findable) → bool

Returns True if the findable passes this filter.

Parameters:

findable (Findable) – the object to filter.

Return type:

bool

regurgitate() → Iterable[str]

Decompiles this filter into a list of tokens.

Return type:

Iterable[str]

colonoscopy() → Iterable[FilterMember]

Iterate over all members of the filter. They’re returned from left to right.

Return type:

Iterable[FilterMember]

class Pipeline

Represents a sequence of filter members combined with an implicit logical AND.

LPAREN = {'(', '-lparen', '['}

Set of accepted strings representing a left parenthesis. Use min(LPAREN) as the representative for regurgitation.

RPAREN = {')', '-rparen', ']'}

Set of accepted strings representing a right parenthesis. There is no requirement for the left and right parentheses to use matching strings.

BOTHPAREN = {'()', '[]'}

Set of accepted strings representing an empty list.

excrete(findable: Findable) → bool

Returns True if the findable passes this filter.

Parameters:

findable (Findable) – the object to filter.

Return type:

bool

regurgitate() → Iterable[str]

Decompiles this filter into a list of tokens.

Return type:

Iterable[str]

colonoscopy() → Iterable[FilterMember]

Iterate over all members of the filter. They’re returned from left to right.

Return type:

Iterable[FilterMember]

class Negative

Represents a single filter member whose result is logically negated (true becomes false, false becomes true).

NEGATE = {'!', '-n', '-not'}

Set of accepted strings representing “not”.

excrete(findable: Findable) → bool

Returns True if the findable passes this filter.

Parameters:

findable (Findable) – the object to filter.

Return type:

bool

regurgitate() → Iterable[str]

Decompiles this filter into a list of tokens.

Return type:

Iterable[str]

colonoscopy() → Iterable[FilterMember]

Iterate over all members of the filter. They’re returned from left to right.

Return type:

Iterable[FilterMember]

class Conjoined

Represents a single fitler member combined to its previous member with logical AND. This class is never actually instantiated, since members are combined with AND by default.

CONJOIN = {'&', '-a', '-and'}

Set of accepted strings representing “and”.

class Disjoined

Represents a single fitler member combined to its previous member with logical OR.

DISJOIN = {'-o', '-or', '|'}

Set of accepted strings representing “or”.

excrete(findable: Findable) → bool

Returns True if the findable passes this filter.

Parameters:

findable (Findable) – the object to filter.

Return type:

bool

regurgitate() → Iterable[str]

Decompiles this filter into a list of tokens.

Return type:

Iterable[str]

colonoscopy() → Iterable[FilterMember]

Iterate over all members of the filter. They’re returned from left to right.

Return type:

Iterable[FilterMember]

class Predicate

Base class for all predicates - filter members which check something about a findable object.

You can extend flam by inheriting from this class and registering your own custom predicates.

PREFIX = '-'

All predicate names in a filter should begin with this string.

qualified_name: str

The predicate’s name (not including PREFIX). For predicates specific to some findable type, this also includes the type (e.g., ‘movies-any-role’, not ‘any-role’).

qualified_aliases: list[str]

List of aliases for the predicate.

findable_type: None | FindableType

Which type of objects this predicate is for. If this is None, all types are supported.

classmethod __init_subclass__(name_without_type: str, aliases_without_type: None | list[str] = None, findable_type: None | FindableType = None, **kwargs: Any) → None

Defines parameters that subclasses can (or must) pass in as part of subclassing. Ex:

class MyCustomPredicate(Predicate, name_without_type='my-predicate', findable_type=FindableType.MOVIES):
    # ...
Parameters:

  • name_without_type (str) – the name of the predicate without the findable type.

  • qualified_aliases – list of aliases for the predicate, also without the type.

  • findable_type (None | FindableType) – which type of objects this predicate is for, or None if it’s for all types.

  • aliases_without_type (None | list[str])

  • kwargs (Any)

Return type:

None

classmethod eat(params: EatParams, at: int) → tuple[Predicate, int]

Eats tokens which are arguments to this predicate starting from params.tokens[at]. Returns the consumed predicate and the index of the first token after it.

Subclasses must override this with their own custom logic. You don’t have to worry about eating the predicate name itself. For example:

@classmethod
def eat(cls, params: EatParams, at: int) -> tuple[Predicate, int]:
    # This predicate takes an attribute and a CMPTO as its arguments.
    attribute = cls.eat_attribute(params, at)
    cmpto = cls.eat_cmpto(params, at + 1, attribute)
    return cls(attribute, cmpto), at + 2
Parameters:

  • params (EatParams) – general parameters of this compilation.

  • at (int) – index at which the predicate tokens are expected to begin.

Return type:

tuple[Predicate, int]

excrete(findable: Findable) → bool

Returns True if the findable passes this filter.

Parameters:

findable (Findable) – the object to filter.

Return type:

bool

regurgitate() → Iterable[str]

Decompiles this filter into a list of tokens.

Return type:

Iterable[str]

colonoscopy() → Iterable[FilterMember]

Iterate over all members of the filter. They’re returned from left to right.

Return type:

Iterable[FilterMember]

looks_like_filter_token(s: str) → bool

Checks if a string matches one of the known forms of a filter token. Use this to split an args list where you expect a filter to start somewhere in the middle of the list.

Parameters:

s (str) – the string which might belong in a filter.

Return type:

bool

class SimpleList

Serializable object with configuration data about a simple list.

uid: str
name: str
concrete_listdef: CanonListdef
is_default_fetch: bool
is_default_find: bool
fetch_params: dict[str, str]
property abstract_listdef: CanonListdef
class CompositeList

Serializable object with configuration data about a composite list.

uid: str
name: str
simple_list_uids: list[str]
filter_tokens: list[str]
is_default_find: bool
property abstract_listdef: CanonListdef
class Configuration

Serializable object with all the configuration data.

version: str
simple_lists_raw: list[SimpleList]
composite_lists_raw: list[CompositeList]
extensions: list[str]
property simple_lists: ConfigurationLists[SimpleList]

Data structure of all simple lists with some niceities that aren’t serialized. Prefer this over simple_lists_raw.

property composite_lists: ConfigurationLists[CompositeList]

Data structure of all composite lists with some niceities that aren’t serialized. Prefer this over composite_lists_raw.

lists_of_type(list_type: str) → ConfigurationLists[SimpleList] | ConfigurationLists[CompositeList]

Generic wrapper for composite_lists, composite_lists.

Parameters:

list_type (str) – SIMPLE or COMPOSITE.

Return type:

ConfigurationLists[SimpleList] | ConfigurationLists[CompositeList]

get_list_by_abstract_listdef(abstract_listdef: CanonListdef) → SimpleList | CompositeList

Returns a configured list based on the listdef.

Parameters:

abstract_listdef (CanonListdef) – listdef with the type and UID of the list.

Return type:

SimpleList | CompositeList

class ConfigurationLists

Data structure for generically interfacing with Configuration.simple_lists_raw or Configuration.composite_lists_raw.

__iter__() → Iterator[T]

Iterate over all configured lists of this type.

Return type:

Iterator[T]

get_idx_by_uid(uid: str) → int

Get a list’s index in the configuration using its UID.

Parameters:

uid (str) – the list’s UID.

Return type:

int

get_idx_by_name(name: str) → int

Get a list’s index in the configuration using its name.

Parameters:

name (str) – the list’s name.

Return type:

int

get_by_uid(uid: str) → T

Get a list’s configuration using its UID.

Parameters:

uid (str) – the list’s UID.

Return type:

T

get_by_name(name: str) → T

Get a list’s configuration using its name.

Parameters:

name (str) – the list’s name.

Return type:

T

class MLFRole

Serializable object with data about a role in a movie.

person_uid: str
is_star: None | bool
episodes_num: None | int
oscar_noms: list[str]
oscar_wins: list[str]
characters: list[str]
jobs: list[str]

For crew type ADDITIONAL, this describes what the roles were.

class MLFCrew

Serializable object with data about the crew of a specific type in a movie.

crew_type: CrewType
roles_by_uid: dict[str, MLFRole]
class MLFPerson

Serializable object with data about a person who appeared in one or more movies from the list.

uid: str
name: None | str
gender: None | str

The exact strings representing each gender may vary based on where the data was fetched from.

height_cm: None | float
birthday: None | date
deathday: None | date
death_reason: None | str
countries: list[str]
class MLFMoviePerSourceData

Serializable object with data about a movie which is specific to the list from which it came, not universal data about that movie.

canon_listdef: CanonListdef

The list this data belongs to. Fetchers should make this equal to the MovieListFile.abstract_listdef.

list_index: None | int
list_note: None | str

This field is for notes specifically attached to the occurrence of the film in this list.

For the user’s notes about the film in general, use MLFMovie.my_notes.

listing_date: None | date

The date this movie was added to this list.

class MLFMovie

Serializable object with data about a movie.

uid: str
per_src_data: list[MLFMoviePerSourceData]

Data about a movie which is specific to the list from which it came. Fetchers should build this list with only one element.

media_type: None | str
title: None | str
original_title: None | str
tagline: None | str
synopsis: None | str
url: None | str
runtime_minutes: None | int
metascore_votes: None | int
metascore: None | int
votes: None | int
rating: None | float
my_rating: None | float
likes: None | int
is_liked: None | bool
budget_usd: None | int
revenue_usd: None | int
content_rating: None | str
release_date: None | date
watch_dates: list[date]

The date(s) you watched this movie. It’s a list in case you’ve seen it more than once and have that data.

my_notes: list[str]

What constitutes a “note” is up to the fetcher. For instance, in Letterboxd fetcher it’s the user’s reviews of the film.

episodes_num: None | int
seasons_num: None | int
end_date: None | date
genres: list[str]
studios: list[str]
languages: list[str]
countries: list[str]
crew: dict[CrewType, MLFCrew]
class MovieListFile

Serializable object with all the data about a movie list.

version: str
abstract_listdef: CanonListdef
uid_family: str

Files are “compatible” if they have a matching family. For instance, different IMDb fetchers might all rely on IMDb IDs, so they can all have the same family.

movies_by_uid: dict[str, MLFMovie]

All the movies in the list. Note that we don’t support multiple occurrences of the same movie. Fetchers are free to choose one occurrence to keep at random.

expiration_date: None | date

Some APIs legally require us to not cache data forever. When this date hits, the file will be deleted and everything will have to be re-fetched.

people_by_uid: dict[str, MLFPerson]
class FlamEnv

Collection of environment variables used by flam.

DEBUG = 'FLAM_DEBUG'

If is_truthy, flam will operate in debug mode. We’re more strict with exceptions in debug mode.

LOG2CONSOLE = 'FLAM_LOG2CONSOLE'

If is_truthy, logs will be printed not just to their log file but also to the console.

LOGLEVEL = 'FLAM_LOGLEVEL'

Suppresses logs below this level. See the python docs on logging levels.

CTX_DIR = 'FLAM_DIR'

Overrides the default path used to store files.

DOWNLOADS_DIR = 'FLAM_DOWNLOADS'

Overrides the default path searched for files downloaded from the browser when fetching from IMDb.

BROWSER = 'FLAM_BROWSER'

Manually decide which browser to use to download CSVs from IMDb: ‘chrome’, ‘edge’, or ‘firefox’.

BROWSER_PROFILE = 'FLAM_BROWSER_PROFILE'

Path to a browser profile to open the browser with when downloading CSVs from IMDb.

This is only needed if your list is set to private so a profile is needed where you are expected to be already logged in.

TMDB_API_TOKEN = 'FLAM_TMDB_API_TOKEN'

The API read access token granted to you by TMDB for using their API.

property is_defined: bool

True if this environment variable is defined.

property is_truthy: bool

True if this environment variable is defined, not empty, and not ‘0’.

get_or_default(default: str = '') → str

Return the value of this environment variable, or some default if it is not defined.

Parameters:

default (str)

Return type:

str

is_debug() → bool

True if flam is in debug mode.

Return type:

bool

get_log_file_path() → str

Returns the path where flam stores its logs:

  • Windows: %LOCALAPPDATA%/film_flam/output.log

  • Linux: ~/.local/state/film_flam/output.log

  • macOS: ~/Library/Logs/film_flam/output.log

  • On unidentified platforms, uses the current directory (./output.log)

Return type:

str

logger

The logger flam uses for all its logs. It is thread-safe and multiprocess-safe, and you may also use it.

exception FlamError

Base class for all errors raised by flam.

exception InputError

Base class for errors raised by flam because of bad input from the user.

exception CloseInputError

Input error with suggestions for similar values to help with typos.

exception FilterSyntaxError

Input error for filters that don’t compile.

classmethod join_tokens(tokens: list[str], error_indices: int | Iterable[int]) → str
Parameters:

  • tokens (list[str])

  • error_indices (int | Iterable[int])

Return type:

str

classmethod format_token(token: str, is_error: bool = False) → str
Parameters:

  • token (str)

  • is_error (bool)

Return type:

str

exception FetchInterrupt

Error used to gracefully exit fetch() in the middle of work.

exception FileValidationError

Error indicating that a file loaded by flam was corrupted or tampered with.