Table

The immutable sequence every reader returns: one dataclass type per table, with lookups, queries and export to pandas, polars, CSV, JSON and JSON Lines.

class fmsave.Table(records, record_type)

An immutable sequence of records of one dataclass type, with queries and export.

Indexing with an int returns a record and slicing returns a Table of the same record type. Queries return new tables and never change this one. Tables compare equal when they have the same record type and equal records, are not hashable, and can be pickled and deep-copied.

Parameters:

• records (Iterable[RecordT])

• record_type (type[RecordT])

property record_type: type[RecordT]

The dataclass the records are instances of.

index(value, start=0, stop=None)

Return the position of the first record equal to value between start and stop.

A stop of None means the end of the table. Negative start and stop count from the end.

Raises:

ValueError – No such record.

Parameters:

• value (object)

• start (int)

• stop (int | None)

Return type:

int

count(value)

Return how many records equal value.

Parameters:

value (object)

Return type:

int

where(**equals)

Return the records whose named top-level fields all equal the given values.

Nested group columns such as “contract_wage” are not field names; use filter for them.

A coded-value field holds a CodedValue, which carries the number the save stores and the label fmsave reads it as. Passing a whole CodedValue matches the records whose label and raw number both equal it. Passing the label alone, as in where(cause=InjuryCause.IN_MATCH), matches every record carrying that label whatever its raw number, so where(cause=InjuryCause.UNKNOWN) is how you ask for the records whose code fmsave does not recognise. A label of another enum never matches. A field holding a tuple of coded values, such as a player’s traits, matches only an equal whole tuple, and a label passed to one raises rather than coming back empty, because no tuple can equal a label; the message names the filter that looks inside the tuple.

Raises:

• TypeError – A field holding a tuple of coded values was given a bare label.

• ValueError – A name is not a field of the record type. The message lists every such name and the valid field names.

Parameters:

equals (object)

Return type:

Table[RecordT]

filter(predicate)

Return the records for which predicate returns true, in order.

Parameters:

predicate (Callable[[RecordT], bool])

Return type:

Table[RecordT]

sorted_by(key, *, reverse=False)

Return the records ordered by key, smallest first, or largest first when reverse.

key is called once per record and its values are compared to each other, so they must be comparable: sorted_by(lambda player: player.ability.current) orders by current ability, and a key returning None for some records raises TypeError. Records with equal keys keep the order they have here.

Raises:

TypeError – Two key values cannot be compared to each other.

Parameters:

• key (Callable[[RecordT], Any])

• reverse (bool)

Return type:

Table[RecordT]

find(*, name)

Return the records whose name equals name, ignoring case and surrounding whitespace.

Both names are compared after NFKC normalization and casefolding, so “NORTHBRIDGE FC” finds “Northbridge FC”. The whole name must match: “northbridge” does not. Records whose name is None never match.

Raises:

ValueError – The record type has no name field.

Parameters:

name (str)

Return type:

Table[RecordT]

by_uid(uid)

Return the first record with this uid.

Tables of people, clubs and grounds key on uid; the rest key on id, and say so.

Raises:

• KeyError – No record has this uid.

• ValueError – The record type has no uid field. The message names by_id and get_by_id when the record type keys on id.

Parameters:

uid (int)

Return type:

RecordT

get_by_uid(uid)

Return the first record with this uid, or None when no record has it.

Raises:

ValueError – The record type has no uid field. The message names by_id and get_by_id when the record type keys on id.

Parameters:

uid (int)

Return type:

RecordT | None

by_id(id)

Return the first record with this id.

Competitions, stages and injury types key on id; tables of people, clubs and grounds key on uid instead, and say so.

Raises:

• KeyError – No record has this id.

• ValueError – The record type has no id field. The message names by_uid and get_by_uid when the record type keys on uid.

Parameters:

id (int)

Return type:

RecordT

get_by_id(id)

Return the first record with this id, or None when no record has it.

Raises:

ValueError – The record type has no id field. The message names by_uid and get_by_uid when the record type keys on uid.

Parameters:

id (int)

Return type:

RecordT | None

property coverage: Mapping[str, float]

The share of records whose value is not None, for each flat column.

Keys are export.column_names(record_type). An empty tuple counts as present, and every column of a missing group counts as missing. An empty table gives 0.0 for every column.

to_columns()

Return flat columns of Python values; see export.to_columns.

Return type:

dict[str, list[object]]

to_dicts(*, json_ready=False)

Return one nested dict per record; see export.record_to_dict.

Parameters:

json_ready (bool)

Return type:

list[dict[str, object]]

to_pandas()

Return a pandas.DataFrame of the flat columns; see export.to_pandas.

Raises:

ImportError – pandas is not installed.

Return type:

Any

to_polars()

Return a polars.DataFrame of the flat columns; see export.to_polars.

Raises:

ImportError – polars is not installed.

Return type:

Any

write_csv(path)

Write every flat column as UTF-8 CSV; see export.write_csv for how cells are written.

Parameters:

path (str | PathLike[str])

Return type:

None

write_json(path)

Write the JSON-ready nested dicts as one JSON array; see export.write_json.

Parameters:

path (str | PathLike[str])

Return type:

None

write_jsonl(path)

Write the JSON-ready nested dicts as JSON Lines; see export.write_jsonl.

Parameters:

path (str | PathLike[str])

Return type:

None