hikari.colors#

Model that represents a common RGB color and provides simple conversions to other common color systems.

Module Contents#

class hikari.colors.Color(raw_rgb)[source]#

Bases: int

Representation of a color.

This value is immutable.

This is a specialization of int which provides alternative overrides for common methods and color system conversions.

This currently supports:

  • RGB

  • RGB (float)

  • 3-digit hex codes (e.g. 0xF1A – web safe)

  • 6-digit hex codes (e.g. 0xFF11AA)

  • 3-digit RGB strings (e.g. #1A2 – web safe)

  • 6-digit RGB hash strings (e.g. #1A2B3C)

Examples

Examples of conversions to given formats include:

>>> c = Color(0xFF051A)
Color(r=0xff, g=0x5, b=0x1a)

>>> hex(c)
0xff051a

>>> c.hex_code
#FF051A

>>> str(c)
#FF051A

>>> int(c)
16712986

>>> c.rgb
(255, 5, 26)

>>> c.rgb_float
(1.0, 0.0196078431372549, 0.10196078431372549)

Alternatively, if you have an arbitrary input in one of the above formats that you wish to become a color, you can use Color.of on the class itself to automatically attempt to resolve the color:

>>> Color.of(0xFF051A)
Color(r=0xff, g=0x5, b=0x1a)

>>> Color.of(16712986)
Color(r=0xff, g=0x5, b=0x1a)

>>> c = Color.of((255, 5, 26))
Color(r=0xff, g=0x5, b=1xa)

>>> c = Color.of(255, 5, 26)
Color(r=0xff, g=0x5, b=1xa)

>>> c = Color.of([0xFF, 0x5, 0x1a])
Color(r=0xff, g=0x5, b=1xa)

>>> c = Color.of("#1a2b3c")
Color(r=0x1a, g=0x2b, b=0x3c)

>>> c = Color.of("#1AB")
Color(r=0x11, g=0xaa, b=0xbb)

>>> c = Color.of((1.0, 0.0196078431372549, 0.10196078431372549))
Color(r=0xff, g=0x5, b=0x1a)

>>> c = Color.of([1.0, 0.0196078431372549, 0.10196078431372549])
Color(r=0xff, g=0x5, b=0x1a)

Examples of initialization of Color objects from given formats include:

>>> c = Color(16712986)
Color(r=0xff, g=0x5, b=0x1a)

>>> c = Color.from_rgb(255, 5, 26)
Color(r=0xff, g=0x5, b=1xa)

>>> c = Color.from_hex_code("#1a2b3c")
Color(r=0x1a, g=0x2b, b=0x3c)

>>> c = Color.from_hex_code("#1AB")
Color(r=0x11, g=0xaa, b=0xbb)

>>> c = Color.from_rgb_float(1.0, 0.0196078431372549, 0.10196078431372549)
Color(r=0xff, g=0x5, b=0x1a)
property hex_code: str[source]#

Six-digit hexadecimal color code for this Color.

This is prepended with a # symbol, and will be in upper case.

Examples

#1A2B3C

property is_web_safe: bool[source]#

Whether this color is web safe.

property raw_hex_code: str[source]#

Raw hex code.

Examples

1A2B3C

property rgb: Tuple[int, int, int][source]#

The RGB representation of this Color.

Represented as a tuple of R, G, B. Each value is in the range [0, 0xFF].

Examples

(123, 234, 47)

property rgb_float: Tuple[float, float, float][source]#

Return the floating-point RGB representation of this Color.

Represented as a tuple of R, G, B. Each value is in the range [0, 1].

Examples

(0.1, 0.2, 0.76)

classmethod from_hex_code(hex_code, /)[source]#

Convert the given hexadecimal color code to a Color.

The inputs may be of the following format (case insensitive): 1a2, #1a2, 0x1a2 (for web-safe colors), or 1a2b3c, #1a2b3c, 0x1a2b3c (for regular 3-byte color-codes).

Parameters:
hex_codestr

A hexadecimal color code to parse. This may optionally start with a case insensitive 0x or #.

Returns:
Color

A corresponding Color object.

Raises:
ValueError

If hex_code is not a hexadecimal or is a invalid length.

classmethod from_int(integer, /)[source]#

Convert the given typing.SupportsInt to a Color.

Parameters:
integertyping.SupportsInt

The raw color integer.

Returns:
Color

The Color object.

classmethod from_rgb(red, green, blue, /)[source]#

Convert the given RGB to a Color object.

Each channel must be within the range [0, 255] (0x0, 0xFF).

Parameters:
redint

Red channel.

greenint

Green channel.

blueint

Blue channel.

Returns:
Color

A Color object.

Raises:
ValueError

If red, green, or blue are outside the range [0x0, 0xFF].

classmethod from_rgb_float(red, green, blue, /)[source]#

Convert the given RGB to a Color object.

The color-space represented values have to be within the range [0, 1].

Parameters:
redfloat

Red channel.

greenfloat

Green channel.

bluefloat

Blue channel.

Returns:
Color

A Color object.

Raises:
ValueError

If red, green or blue are outside the range [0, 1].

classmethod from_tuple_string(tuple_str, /)[source]#

Convert a string in a tuple-like format to a Color.

This allows formats that are optionally enclosed by (), {}, or [], and contain three floats or ints, either space separated or comma separated.

If comma separated, trailing and leading whitespace around each member is truncated.

This is provided to allow command frontends to directly pass user input for representing a given colour into this class safely.

Parameters:
tuple_strstr

The string to parse.

Returns:
Color

The parsed colour object.

Raises:
ValueError

If an invalid format is given, or if any values exceed 1.0 for floats or 255 for ints.

Examples

# Floats
"1.0 1.0 1.0"
"(1.0 1.0 1.0)"
"[1.0 1.0 1.0]"
"{1.0 1.0 1.0}"
"1.0, 1.0, 1.0"
"(1.0, 1.0, 1.0)"
"[1.0, 1.0, 1.0]"
"{1.0, 1.0, 1.0}"

# Ints
"252 252 252"
"(252 252 252)"
"[252 252 252]"
"{252 252 252}"
"252, 252, 252"
"(252, 252, 252)"
"[252, 252, 252]"
"{252, 252, 252}"
classmethod of(value, /)[source]#

Convert the value to a Color.

This attempts to determine the correct data format based on the information provided.

Parameters:
valueColorish

A color compatible values.

Returns:
Color

The Color object.

Examples

>>> Color.of(0xFF051A)
Color(r=0xff, g=0x5, b=0x1a)

>>> Color.of(16712986)
Color(r=0xff, g=0x5, b=0x1a)

>>> c = Color.of((255, 5, 26))
Color(r=0xff, g=0x5, b=1xa)

>>> c = Color.of([0xFF, 0x5, 0x1a])
Color(r=0xff, g=0x5, b=1xa)

>>> c = Color.of("#1a2b3c")
Color(r=0x1a, g=0x2b, b=0x3c)

>>> c = Color.of("#1AB")
Color(r=0x11, g=0xaa, b=0xbb)

>>> c = Color.of((1.0, 0.0196078431372549, 0.10196078431372549))
Color(r=0xff, g=0x5, b=0x1a)

>>> c = Color.of([1.0, 0.0196078431372549, 0.10196078431372549])
Color(r=0xff, g=0x5, b=0x1a)

# Commas and brackets are optional, whitespace is ignored, and these
# are compatible with all-ints between 0-255 or all-floats between
# 0.0 and 1.0 only.
>>> c = Color.of("5, 22, 33")
Color(r=0x5, g=0x16, b=0x21)
>>> c = Color.of("(5, 22, 33)")
Color(r=0x5, g=0x16, b=0x21)
>>> c = Color.of("[5, 22, 33]")
Color(r=0x5, g=0x16, b=0x21)
>>> c = Color.of("{5, 22, 33}")
Color(r=0x5, g=0x16, b=0x21)
to_bytes(length, byteorder, *, signed=True)[source]#

Convert the color code to bytes.

Parameters:
lengthint

The number of bytes to produce. Should be around 3, but not less.

byteorderstr

The endianness of the value represented by the bytes. Can be "big" endian or "little" endian.

signedbool

Whether the value is signed or unsigned.

Returns:
bytes

The bytes representation of the Color.

hikari.colors.Colorish[source]#

Type hint representing types of value compatible with a colour type.

This may be:

  1. hikari.colors.Color

  2. hikari.colours.Colour (an alias for hikari.colors.Color).

  3. A value that can be cast to an int (RGB hex-code).

  4. a 3-tuple of int (RGB integers in range 0 through 255).

  5. a 3-tuple of float (RGB floats in range 0 through 1).

  6. a list of int.

  7. a list of float.

  8. a str hex colour code.

A hex colour code is expected to be in one of the following formats. Each of the following examples means the same thing semantically.

  1. (web-safe) "12F" (equivalent to "1122FF")

  2. (web-safe) "0x12F" (equivalent to "0x1122FF")

  3. (web-safe) "0X12F" (equivalent to "0X1122FF")

  4. (web-safe) "#12F" (equivalent to "#1122FF")

  5. "1122FF"

  6. "0x1122FF"

  7. "0X1122FF"

  8. "#1122FF"

Web-safe colours are three hex-digits wide, XYZ becomes XXYYZZ in full-form.