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 = (
    Color
    | typing.SupportsInt
    | tuple[
        typing.SupportsInt,
        typing.SupportsInt,
        typing.SupportsInt,
    ]
    | tuple[
        typing.SupportsFloat,
        typing.SupportsFloat,
        typing.SupportsFloat,
    ]
    | typing.Sequence[typing.SupportsInt]
    | typing.Sequence[typing.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=0x1a)

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

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

>>> 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=0x1a)

>>> 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=0x1a)

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

>>> 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 = 3,
    byteorder: Literal["little", "big"] = "big",
    *,
    signed: bool = False,
) -> bytes

Convert the color code to bytes.

PARAMETER DESCRIPTION
length

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

TYPE: SupportsIndex DEFAULT: 3

byteorder

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

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

signed

Whether the value is signed or unsigned.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
bytes

The bytes representation of the Color.

ColorGradient #

Represents a color gradient, as used for role colors.

Use hikari.colors.ColorGradient.of to build one from any hikari.colors.Colorish values.

primary_color class-attribute instance-attribute #

primary_color: Color = attrs.field(repr=True)

The primary color of the gradient.

primary_colour property #

primary_colour: Colour

Alias for the primary_color field.

secondary_color class-attribute instance-attribute #

secondary_color: Color | None = attrs.field(
    default=None, repr=True
)

The secondary color of the gradient, if set.

When used as a role's colors, this can only be set if the guild has the hikari.guilds.GuildFeature.ENHANCED_ROLE_COLORS feature.

secondary_colour property #

secondary_colour: Colour | None

Alias for the secondary_color field.

tertiary_color class-attribute instance-attribute #

tertiary_color: Color | None = attrs.field(
    default=None, repr=True
)

The tertiary color of the gradient, if set.

When used as a role's colors, this will turn the gradient into a holographic style and can only be set if the guild has the hikari.guilds.GuildFeature.ENHANCED_ROLE_COLORS feature.

tertiary_colour property #

tertiary_colour: Colour | None

Alias for the tertiary_color field.

holographic classmethod #

holographic() -> ColorGradient

Build the holographic role color style.

This is the only gradient with a tertiary color that the API accepts; setting any tertiary color will enforce these exact values.

RETURNS DESCRIPTION
ColorGradient

The holographic color gradient, with primary_color=11127295, secondary_color=16759788 and tertiary_color=16761760.

of classmethod #

of(
    primary: Colorish,
    secondary: Colorish | None = None,
    tertiary: Colorish | None = None,
) -> ColorGradient

Build a color gradient from any color-like values.

PARAMETER DESCRIPTION
primary

The primary color of the gradient.

TYPE: Colorish

secondary

The secondary color of the gradient, if any.

TYPE: Colorish | None DEFAULT: None

tertiary

The tertiary color of the gradient, if any.

TYPE: Colorish | None DEFAULT: None

RETURNS DESCRIPTION
ColorGradient

The built color gradient.