Skip to content

hikari.colors#

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

Colorish module-attribute #

Colorish = Union[Color, SupportsInt, tuple[SupportsInt, SupportsInt, SupportsInt], tuple[SupportsFloat, SupportsFloat, SupportsFloat], Sequence[SupportsInt], Sequence[SupportsFloat], str]

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.

Color #

Color(raw_rgb: SupportsInt)

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 hikari.colors.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)

hex_code property #

hex_code: str

Six-digit hexadecimal color code for this Color.

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

Examples:

#1A2B3C

is_web_safe property #

is_web_safe: bool

Whether this color is web safe.

raw_hex_code property #

raw_hex_code: str

Raw hex code.

Examples:

1A2B3C

rgb property #

rgb: tuple[int, int, int]

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)][]

rgb_float property #

rgb_float: tuple[float, float, float]

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)][]

from_hex_code classmethod #

from_hex_code(hex_code: str) -> Color

Convert the given hexadecimal color code to a hikari.colors.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).

PARAMETER DESCRIPTION
hex_code

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

TYPE: str

RETURNS DESCRIPTION
Color

A corresponding Color object.
RAISES DESCRIPTION
ValueError

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

from_int classmethod #

from_int(integer: SupportsInt) -> Color

Convert the given typing.SupportsInt to a hikari.colors.Color.

PARAMETER DESCRIPTION
integer

The raw color integer.

TYPE: SupportsInt

RETURNS DESCRIPTION
Color

The Color object.

from_rgb classmethod #

from_rgb(red: int, green: int, blue: int) -> Color

Convert the given RGB to a hikari.colors.Color object.

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

PARAMETER DESCRIPTION
red

Red channel.

TYPE: int

green

Green channel.

TYPE: int

blue

Blue channel.

TYPE: int

RETURNS DESCRIPTION
Color

A Color object.
RAISES DESCRIPTION
ValueError

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

from_rgb_float classmethod #

from_rgb_float(red: float, green: float, blue: float) -> Color

Convert the given RGB to a hikari.colors.Color object.

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

PARAMETER DESCRIPTION
red

Red channel.

TYPE: float

green

Green channel.

TYPE: float

blue

Blue channel.

TYPE: float

RETURNS DESCRIPTION
Color

A Color object.
RAISES DESCRIPTION
ValueError

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

from_tuple_string classmethod #

from_tuple_string(tuple_str: str) -> Color

Convert a string in a tuple-like format to a hikari.colors.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.

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}"
PARAMETER DESCRIPTION
tuple_str

The string to parse.

TYPE: str

RETURNS DESCRIPTION
Color

The parsed colour object.
RAISES DESCRIPTION
ValueError

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

of classmethod #

of(value: Colorish) -> Color

Convert the value to a hikari.colors.Color.

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

PARAMETER DESCRIPTION
value

A color compatible values.

TYPE: Colorish

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)
RETURNS DESCRIPTION
Color

The Color object.

to_bytes #

to_bytes(length: SupportsIndex, byteorder: Literal['little', 'big'], *, signed: bool = True) -> bytes

Convert the color code to bytes.

PARAMETER DESCRIPTION
length

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

TYPE: SupportsIndex

byteorder

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

TYPE: Literal['little', 'big']

signed

Whether the value is signed or unsigned.

TYPE: bool DEFAULT: True

RETURNS DESCRIPTION
bytes

The bytes representation of the Color.