Expressions

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:

Color.from_text(ref=None)

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:

class thcolor.Reference.number(value)

Syntaxical element for expression decoding, representing a number, integer or decimal, positive or negative.

This element is usually used to represent a byte value, a factor (usually from 0.0 to 1.0), a color or an angle in degrees.

to_byte()

Make a byte (from 0 to 255) out of the number.

to_factor()

Make a factor (usually from 0.0 to 1.0) out of the number.

to_hue()

Make an angle in degrees out of the number.

class thcolor.Reference.percentage(value)

Syntaxical element for expression decoding, representing a percentage (number followed by a ‘%’ sign).

This element is usually used to represent a factor (usually from 0% to 100%) or anything that can be factored such as a byte value (where 0% represents 0 and 100% represents 255).

to_byte()

Make a byte (from 0 to 255) out of the number.

to_factor()

Make a factor (usually from 0.0 to 1.0) out of the number.

class thcolor.Reference.angle(value)

Syntaxical element for expression decoding, representing an angle (a number followed by an angle unit: degrees, gradiants, radiants or turns).

to_hue()

Get the thcolor.Angle object.

class thcolor.Reference.color(value)

Syntaxical element for expression decoding, representing a color using several methods:

  • a hexadecimal code preceeded by a ‘#’, e.g. “#123ABC”.

  • a natural color (see NCol).

  • a color name as defined by a Reference.

  • a legacy color name using the legacy color algorithm (or ‘Netscape’ color algorithm).

to_color()

Get the thcolor.Color object.

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.

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.

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.

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.

_color(name)

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.

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) 
default()

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.

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:

class thcolor.CSS1Reference(*args, **kwargs)

Named colors from CSS Level 1.

class thcolor.CSS2Reference(*args, **kwargs)

Named colors from CSS Level 2 (Revision 1).

class thcolor.CSS3Reference(*args, **kwargs)

Named colors and functions from CSS Color Module Level 3.

class thcolor.CSS4Reference(*args, **kwargs)

Named colors and functions from CSS Color Module Level 4.

class thcolor.DefaultReference(*args, **kwargs)

Functions extending the CSS Color Module Level 4 reference.