One of the aims of the thcolor module was to decode text-based expressions representing colors with possibilities challenging and even outdo CSS color expression possibilities. This is what the following static method is for:


Create a color from a string using a Reference object. If the ref argument is None, then the default reference is loaded.

An example:

>>> Color.from_text("#123456")
... Color(type = Color.Type.RGB, red = 18, green = 52, blue = 86, alpha = 1.0) 

Expression concepts

The goal of these expressions was to embrace and extend CSS syntax, so they are basically either basic expressions or function calls, with the following argument types:

These elements are separated by separators (either commas, slashes, or simple spaces) and can be passed to functions, and the calls themselves can be passed to other functions. A function call is made in the following fashion:

<function name>(<number | percentage | angle | color> [<separator> …])

If at least one separator (even simple spaces) are required between arguments, extraneous separators between and after the arguments are ignored. Other than if spaces are used as separators, spaces around the parenthesis or the separators (and “between” the separators as spaces are recognized as separators) are ignored.

Here are some example calls:

rgb(1, 2, 3)
rgb  ( 1 22 //// 242 , 50.0% ,/,)
hsl (0 1 50 % / 22)
gray ( red( #123456 )/0.2/)

In case of incorrectly formatted string, the following exception is returned:

exception thcolor.ColorExpressionDecodingError(text, column=None, func=None)

A color decoding error has occurred on the text.

property column

Column of the expression at which the exception has occurred, None if the error has occurred on an unknown column or on the whole exception.

property func

Function name we were calling when the error has occurred, either on arguments decoding or erroneous argument type or value, None if the context is unknown or the error hasn’t occurred while calling a function or decoding its arguments.

property text

Exception message, usually linked to the context.

Defining a reference

Functions and color names are defined in a reference:

  • color names are defined behind an overload of thcolor.Reference._color().

  • functions are defined as reference class methods and use type hints to describe the types they are expecting.

The reference must be a derivative of the following class:

class thcolor.Reference

Function reference for color parsing and operations.


Name color getter used behind the thcolor.Reference.colors getter, ought to be overriden by superseeding classes.

These classes should return super()._color(name) in case they have no match for the given name.

property colors

Colors getter, which can be used as .colors[value]. For example, with a classical CSS reference named ref:

>>> ref.colors['blue']
... Color(type = Color.Type.RGB, red = 0, green = 0, blue = 255, alpha = 1.0)
>>> ref.colors[thcolor.Reference.color(thcolor.Color.from_text('#123456'))]
... Color(type = Color.Type.RGB, red = 18, green = 52, blue = 86, alpha = 1.0) 

Static method for gathering the default reference, by default thcolor.DefaultReference. Is only used on the base thcolor.Reference type and shall not be overriden.

property functions

Function getter, which can be used as .functions[name](args…).

Provides a wrapper to the method which checks the argument types and perform the necessary conversions before passing them to the functions.

For example, with a classical CSS reference named ref:

>>> ref.functions['rgb'](ref.number(18), ref.number(52), ref.number(86))
... Color(type = Color.Type.RGB, red = 18, green = 52, blue = 86, alpha = 1.0) 

Builtin references

The following references are defined: