colour.utilities.CanonicalMapping#

class colour.utilities.CanonicalMapping(data: Generator | Mapping | None = None, **kwargs: Any)[source]#

Bases: MutableMapping

Represent a delimiter and case-insensitive dict-like object supporting both slug keys (SEO-friendly, human-readable versions with delimiters) and canonical keys (slugified keys without delimiters).

This class extends MutableMapping to provide flexible key matching that accepts various transformations of the original key while maintaining the original key structure for storage. Item keys must be str-like objects supporting the str.lower() method. Set items using the specified original keys. Retrieve, delete, or test item existence by transforming the query key through the following sequence:

  • Original Key

  • Lowercase Key

  • Slugified Key

  • Canonical Key

For example, using the McCamy 1992 key:

  • Original Key : McCamy 1992

  • Lowercase Key : mccamy 1992

  • Slugified Key : mccamy-1992

  • Canonical Key : mccamy1992

Parameters:

  • data (Generator | Mapping | None) – Data to store into the delimiter and case-insensitive dict-like object at initialisation.

  • kwargs (Any) – Key / value pairs to store into the mapping at initialisation.

Attributes

Methods

Examples

>>> methods = CanonicalMapping({"McCamy 1992": 1, "Hernandez 1999": 2})
>>> methods["mccamy 1992"]
1
>>> methods["MCCAMY 1992"]
1
>>> methods["mccamy-1992"]
1
>>> methods["mccamy1992"]
1
__init__(data: Generator | Mapping | None = None, **kwargs: Any) → None[source]#
Parameters:
Return type:

None

property data: dict#

Getter for the delimiter and case-insensitive dict-like object data.

Returns:

Internal data storage.

Return type:

dict

__repr__() → str[source]#

Return an evaluable string representation of the delimiter and case-insensitive dict-like object.

Returns:

Evaluable string representation.

Return type:

str

__setitem__(item: str | Any, value: Any) → None[source]#

Set the specified item with the specified value in the delimiter and case-insensitive dict-like object.

Parameters:

  • item (str | Any) – Item to set in the delimiter and case-insensitive dict-like object.

  • value (Any) – Value to store in the delimiter and case-insensitive dict-like object.

Return type:

None

__getitem__(item: str | Any) → Any[source]#

Return the value of the specified item from the delimiter and case-insensitive dict-like object.

Parameters:

item (str | Any) – Item to retrieve the value of from the delimiter and case-insensitive dict-like object.

Returns:

Item value.

Return type:

object

Notes

  • The item value can be retrieved by using either its lower-case, slugified or canonical variant.

__delitem__(item: str | Any) → None[source]#

Delete the specified item from the delimiter and case-insensitive dict-like object.

Parameters:

item (str | Any) – Item to delete from the delimiter and case-insensitive dict-like object.

Return type:

None

Notes

  • The item can be deleted by using either its lower-case, slugified or canonical variant.

__contains__(item: str | Any) → bool[source]#

Return whether the delimiter and case-insensitive dict-like object contains the specified item.

Parameters:

item (str | Any) – Item to check for presence in the delimiter and case-insensitive dict-like object.

Returns:

Whether the specified item exists in the delimiter and case-insensitive dict-like object.

Return type:

bool

Notes

  • Item presence can be checked using its lower-case, slugified, or canonical variant.

__iter__() → Generator[source]#

Iterate over the items of the delimiter and case-insensitive dict-like object.

Yields:

Generator – Item generator.

Return type:

Generator

Notes

  • The iterated items are the original items.

__len__() → int[source]#

Return the item count of the container.

Returns:

Item count.

Return type:

int

__hash__ = None#
__eq__(other: object) → bool[source]#

Test whether the delimiter and case-insensitive dict-like object equals the specified object.

Parameters:

other (object) – Object to test for equality with the delimiter and case-insensitive dict-like object.

Returns:

Whether the specified object equals the delimiter and case-insensitive dict-like object.

Return type:

bool

__ne__(other: object) → bool[source]#

Test whether the delimiter and case-insensitive dict-like object is not equal to the specified other object.

Parameters:

other (object) – Object to test whether it is not equal to the delimiter and case-insensitive dict-like object.

Returns:

Whether the specified object is not equal to the delimiter and case-insensitive dict-like object.

Return type:

bool

copy() → CanonicalMapping[source]#

Return a copy of the delimiter and case-insensitive dict-like object.

Returns:

Case-insensitive dict-like object copy.

Return type:

CanonicalMapping

Warning

  • The CanonicalMapping class copy returned is a copy of the object not a deepcopy!

lower_keys() → Generator[source]#

Iterate over the lower-case keys of the delimiter and case-insensitive dict-like object.

Yields:

Generator – Lower-case key generator.

Return type:

Generator

lower_items() → Generator[source]#

Iterate over the lower-case items of the delimiter and case-insensitive dict-like object.

Yields:

Generator – Item generator.

Return type:

Generator

slugified_keys() → Generator[source]#

Iterate over the slugified keys of the delimiter and case-insensitive dict-like object.

Yields:

Generator – Item generator.

Return type:

Generator

slugified_items() → Generator[source]#

Iterate over the slugified items of the delimiter and case-insensitive dict-like object.

Yields:

Generator – Item generator.

Return type:

Generator

canonical_keys() → Generator[source]#

Iterate over the canonical keys of the delimiter and case-insensitive dict-like object.

Yields:

Generator – Item generator.

Return type:

Generator

canonical_items() → Generator[source]#

Iterate over the canonical items of the delimiter and case-insensitive dict-like object.

Yields:

Generator – Item generator.

Return type:

Generator

__weakref__#

list of weak references to the object