colour.utilities Package — Colour 0.3.0 documentation

# colour.utilities Package

## Sub-Modules

- colour.utilities.common Module
  - Common Utilities
- colour.utilities.data_structures Module
  - Data Structures
- colour.utilities.verbose Module
  - Verbose

## Module Contents

`colour.utilities.` `is_scipy_installed`(raise_exception=False)

  Returns if scipy is installed and available.

  Parameters: | raise_exception (bool) – Raise exception if scipy is unavailable.
  Returns: | Is scipy installed.
  Return type: | bool
  Raises: | `ImportError` – If scipy is not installed.

`colour.utilities.` `is_string`(data)

  Returns if given data is a string_like variable

  Parameters: | data (object) – Data to test.
  Returns: | Is string_like variable.
  Return type: | bool

  Examples

      >>> is_string('I`m a string!')
      True
      >>> is_string(['I`m a string!'])
      False

class `colour.utilities.` `Lookup`

  Bases: `dict`

  Extends dict type to provide a lookup by value(s).

  References

  [2] | https://github.com/KelSolaar/Foundations/blob/develop/foundations/data_structures.py

  Examples

      >>> person = Lookup(firstName='Doe', lastName='John', gender='male')
      >>> person.first_key_from_value('Doe')
      'firstName'
      >>> persons = Lookup(John='Doe', Jane='Doe', Luke='Skywalker')
      >>> sorted(persons.keys_from_value('Doe'))
      ['Jane', 'John']

  `first_key_from_value`(value)

    Gets the first key with given value.

    Parameters: | value (object) – Value.
    Returns: | Key.
    Return type: | object

  `keys_from_value`(value)

    Gets the keys with given value.

    Parameters: | value (object) – Value.
    Returns: | Keys.
    Return type: | object

class `colour.utilities.` `Structure`(*args, **kwargs)

  Bases: `dict`

  Defines an object similar to C/C++ structured type.

  Parameters: | *args (*) – Arguments. **kwargs (dict) – Key / Value pairs.

  References

  [1] | https://github.com/KelSolaar/Foundations/blob/develop/foundations/data_structures.py

  Examples

      >>> person = Structure(firstName='Doe', lastName='John', gender='male')
      >>> # Doctests skip for Python 2.x compatibility.
      >>> person.firstName
      'Doe'
      >>> sorted(person.keys())
      ['firstName', 'gender', 'lastName']
      >>> # Doctests skip for Python 2.x compatibility.
      >>> person['gender']
      'male'

  `__delattr__`(attribute)

    Deletes both key and sibling attribute.

    Parameters: | attribute (object) – Attribute.

    Notes

    - Reimplements the `dict.__delattr__()` method.
  `__delitem__`(attribute)

    Deletes both key and sibling attribute.

    Parameters: | attribute (object) – Attribute.

    Notes

    - Reimplements the `dict.__delattr__()` method.
  `__getattr__`(attribute)

    Returns given attribute value.

    Parameters: | attribute (unicode) – Attribute name.

    Notes

    - Reimplements the `dict.__getattr__()` method.

    Returns: | Attribute value.
    Return type: | object
    Raises: | `AttributeError` – If the attribute is not defined.

  `__setattr__`(attribute, value)

    Sets both key and sibling attribute with given value.

    Parameters: | attribute (object) – Attribute. value (object) – Value.

    Notes

    - Reimplements the `dict.__setattr__()` method.
  `__setitem__`(attribute, value)

    Sets both key and sibling attribute with given value.

    Parameters: | attribute (object) – Attribute. value (object) – Value.

    Notes

    - Reimplements the `dict.__setattr__()` method.
  `update`(*args, **kwargs)

    Updates both keys and sibling attributes.

    Parameters: | *args (*) – Arguments. **kwargs (**) – Keywords arguments.

    Notes

    - Reimplements the `dict.update()` method.

class `colour.utilities.` `CaseInsensitiveMapping`(data=None, **kwargs)

  Bases: `_abcoll.MutableMapping`

  Implements a case-insensitive mutable mapping / dict object.

  Allows values retrieving from keys while ignoring the key case. The keys are expected to be unicode or string-like objects supporting the `str.lower()` method.

  Parameters: | data (dict) – dict of data to store into the mapping at initialisation. **kwargs (dict) – Key / Value pairs to store into the mapping at initialisation.

  Warning

  The keys are expected to be unicode or string-like objects.

  References

  [3] | https://github.com/kennethreitz/requests/blob/v1.2.3/requests/structures.py#L37

  Examples

      >>> methods = CaseInsensitiveMapping({'McCamy': 1, 'Hernandez': 2})
      >>> methods['mccamy']
      1

  `__contains__`(item)

    Returns if the mapping contains given item.

    Parameters: | item (unicode) – Item name.
    Returns: | Is item in mapping.
    Return type: | bool

    Notes

    - Reimplements the `MutableMapping.__contains__()` method.
  `__delitem__`(item)

    Deletes the item with given name.

    The item is deleted from the mapping using its lower name.

    Parameters: | item (unicode) – Item name.

    Notes

    - Reimplements the `MutableMapping.__delitem__()` method.
  `__eq__`(item)

    Returns the equality with given object.

    Parameters: | item – Object item.
    Returns: | Equality.
    Return type: | bool

    Notes

    - Reimplements the `MutableMapping.__eq__()` method.
  `__getitem__`(item)

    Returns the value of given item.

    The item value is retrieved using its lower name in the mapping.

    Parameters: | item (unicode) – Item name.
    Returns: | Item value
    Return type: | object

    Notes

    - Reimplements the `MutableMapping.__getitem__()` method.
  `__iter__`()

    Iterates over the items names in the mapping.

    The item names returned are the original input ones.

    Returns: | Item names.
    Return type: | generator

    Notes

    - Reimplements the `MutableMapping.__iter__()` method.
  `__len__`()

    Returns the items count.

    Returns: | Items count.
    Return type: | int

    Notes

    - Reimplements the `MutableMapping.__iter__()` method.
  `__ne__`(item)

    Returns the inequality with given object.

    Parameters: | item – Object item.
    Returns: | Inequality.
    Return type: | bool

    Notes

    - Reimplements the `MutableMapping.__ne__()` method.
  `__repr__`()

    Returns the mapping representation with the original item names.

    Returns: | Mapping representation.
    Return type: | unicode

    Notes

    - Reimplements the `MutableMapping.__repr__()` method.
  `__setitem__`(item, value)

    Sets given item with given value.

    The item is stored as lower in the mapping while the original name and its value are stored together as the value in a tuple:

    {“item.lower()”: (“item”, value)}

    Parameters: | item (object) – Attribute. value (object) – Value.

    Notes

    - Reimplements the `MutableMapping.__setitem__()` method.
  `copy`()

    Returns a copy of the mapping.

    Returns: | Mapping copy.
    Return type: | CaseInsensitiveMapping

    Notes

    - The `CaseInsensitiveMapping` class copy returned is a simple copy not a deepcopy.
  `lower_items`()

    Iterates over the lower items names.

    Returns: | Lower item names.
    Return type: | generator

`colour.utilities.` `warning`(*args, **kwargs)

  Issues a warning.

  Parameters: | *args (*) – Arguments. **kwargs (**) – Keywords arguments.
  Returns: | Definition success.
  Return type: | bool

  Examples

      >>> colour.utilities.warning('This is a warning!')
      /Users/.../colour/utilities/verbose.py:42: UserWarning: This is a warning!