foley.index.taxonomy.ucs

UCS table loading + the UCS-filename CatID parse (report 04 §5.2, §6.4).

A UCS filename is underscore-delimited with the CatID first:

CatID_FXName_CreatorID_SourceID[_UserCategory_UserData].ext

Only token 0 (the CatID) carries the controlled taxonomy; it is looked up in the table (never string-split, since the category prefix is variable-length). The loader merges the in-code seed with an optional full-table JSON drop under taxonomy/data/ucs_full.json (JSON wins on CatID collision) — open/closed.

foley.index.taxonomy.ucs.default_ucs_table() → UcsTable[source]

The process-wide default UCS table (seed + any JSON drop), built once.

foley.index.taxonomy.ucs.load_ucs_table(*, data_dir=None, include_seed: bool = True) → UcsTable[source]

Build the UCS lookup: the seed rows, overridden/extended by a JSON drop.

Parameters:

  • data_dir – Directory to look for ucs_full.json in (defaults to the package’s taxonomy/data/). When present, its rows override the seed on CatID collision and add the rest of the ~750-row master.

  • include_seed – Start from the in-code seed table (default True).

Returns:

A ready UcsTable.

foley.index.taxonomy.ucs.parse_catid_token(filename) → str | None[source]

Return token 0 (the CatID candidate) of a UCS-style filename, else None.

Strips directory and extension; requires at least one _ (the field delimiter). Does not validate the token against the table.

foley.index.taxonomy.ucs.parse_ucs_filename(filename, *, table: UcsTable | None = None) → tuple[str | None, str | None][source]

Parse a UCS-conformant filename to (ucs_category, ucs_subcategory).

Fail-quiet: returns (None, None) when the name is not UCS-conformant or its CatID token is unknown (so a wrong subcategory is never emitted).

Parameters:

  • filename – A path or filename (only the basename’s token 0 is used).

  • table – The UCS table to resolve against (defaults to default_ucs_table()).