Reference

Documentation for the color50 package and its constituent features, each listed by module.

Color class

class color50.color.Color[source]

A class for representing color in RGB format.

Represents any given color by storing its RGB values—that is, its red level (0-255), green level (0-255), and blue level (0-255). Once a Color object has its RGB values set, it can be used to add color to strings via concatenation.

Also designed to be used in conjunction with other key components of the package, like the ColorStr class or the colorize decorator function.

Example:

# Normal print statement (behaves as expected)
print("Not in Color.")

my_color = rgb(128, 0, 128)

# Colorized print statement (prints string contents in purple)
print(my_color + "Now in Color!" + constants.RESET)

Note

Make sure to use the RESET constant when combining strings with Color objects; the color settings of your terminal environment may not revert to defaults unless explicitly specified!

__add__(string: str) → str[source]

Support concatenation of Color and str objects.

Example:

my_color = rgb(0, 255, 0)
my_message = "Hello, Green World!"
print(my_color + my_message + constants.RESET)

Note

Concatenation of Color and str objects only supports operations where the first operand is a Color. This means that any operation of the type Color + str is valid, whereas any operation of the type str + Color is not.

__eq__(other) → bool[source]

Support equality comparisons of two Color objects.

Two objects of type Color are defined to be equal if and only if:

color1.red == color2.red is True,

color1.green == color2.green is True,

and color1.blue == color2.blue is True.

Both equality operators (== and !=) are supported.

Example:

color1 = rgb(255, 255, 0)
color2 = hexcode("#ffff00")
color3 = css("blue")

print(color1 == color2)     # True
print(color2 == color3)     # False
print(color1 == color3)     # False

__init__()[source]

Initialize a Color object with red, green, and blue values all set to 0.

Note that there are no parameterized __init___ functions for the Color class; instead, it is recommended to use one of the associated core functions that come with the package as opposed to calling the initializer explicitly.

That said, the default initializer can still be called. Upon initialization, each of the object properties (red, green, blue) can be tweaked individually from their default values of 0.

Example:

# Normal print statement (behaves as expected)
print("Not in Color.")

my_color = Color()
my_color.red = 128
my_color.green = 0
my_color.blue = 128

# Colorized print statement (prints string contents in purple)
print(my_color + "Now in Color!" + constants.RESET)

__str__()[source]

Return a string representation of the color. Functionally identical to calling the fg method.

Example:

my_color = rgb(0, 0, 255)
print(f"{my_color}f-strings make me feel blue.{constants.RESET}")

bg() → str[source]

Return the stored color as a string representing its corresponding background ANSI color code sequence.

Returns:: The ANSI color code sequence representation of the object, specifically to use as a background color.

Example:

my_color = rgb(30, 120, 15)
print(my_color.bg() + "What a gorgeous background!" + constants.RESET)

property blue

A numeric value (0-255) representing the color’s blue levels. Supports both get and set operations.

Raises:

TypeError – If the property is set to a non-integer value.
ValueError – If the property is set to an out-of-range integer (e.g., not in range 0-255).

Type:

int

fg() → str[source]

Return the stored color as a string representing its corresponding foreground ANSI color code sequence.

The return value of this function is the default behavior of converting a Color object to a string. The option to call fg explicitly has been included for completeness, readability, and consistency.

Returns:: The ANSI color code sequence representation of the object, specifically for use as a foreground color.

Example:

my_color = rgb(0, 128, 64)
print(my_color.fg() + "This text is so colorful!" + constants.RESET)

property green

A numeric value (0-255) representing the color’s green levels. Supports both get and set operations.

Raises:

TypeError – If the property is set to a non-integer value.
ValueError – If the property is set to an out-of-range integer (e.g., not in range 0-255).

Type:

int

property red

A numeric value (0-255) representing the color’s red levels. Supports both get and set operations.

Raises:

TypeError – If the property is set to a non-integer value.
ValueError – If the property is set to an out-of-range integer (e.g., not in range 0-255).

Type:

int

Core functions

color50.core_functions.rgb(red: int, green: int, blue: int) → Color[source]

Return a Color object based on specified RGB values.

One of three recommended methods for creating Color objects. Because the Color class stores RGB values internally, this function essentially mirrors the behavior of a would-be parameterized __init__ function.

Parameters:

red – A numeric value (0-255) representing the color’s red levels.
green – A numeric value (0-255) representing the color’s green levels.
blue – A numeric value (0-255) representing the color’s blue levels.

Returns:

A valid Color object.

Note

This function creates a Color object and attempts to assign the parameter values to said object’s properties. This means that any possible exceptions raised by setting the properties explicitly can also be raised by calling this function.

To avoid exceptional cases, ensure that each parameter is a valid integer with a value from 0-255.

Examples:

color1 = rgb(0, 0, 0)        # black
color2 = rgb(255, 255, 255)  # white
color3 = rgb(128, 0, 128)    # purple

color50.core_functions.hexcode(code: str) → Color[source]

Return a Color object based on a specified HEX color code.

One of three recommended methods for creating Color objects. Designed to offer flexibility insofar as the format of specifying color, especially since RGB values and HEX color codes are often used alongside one another.

Parameters:

code – A string representation of a HEX color code. Can contain optional leading hash sign ('#') and can make use of uppercase or lowercase letters.

Returns:

A valid Color object.

Raises:

TypeError – If code is not a string.
ValueError – If code is not a valid HEX color code or is formatted incorrectly.

Examples:

color1 = hexcode("#000000")   # black
color2 = hexcode("FFFFFF")    # white
color3 = hexcode("#00ffff")   # cyan

color50.core_functions.css(colorname: str) → Color[source]

Return a Color object based on a specified CSS color name.

One of three recommended methods for creating Color objects. Designed to offer a simpler alternative to explicit RGB values/HEX color codes, and to enable cross-compatibility of color choice between projects.

Parameters:

colorname – A valid CSS color name.

Returns:

A valid Color object.

Raises:

TypeError – If colorname is not a string.
ValueError – If colorname is not among the list of recognized CSS color names.

Examples:

color1 = css("black")     # black
color2 = css("white")     # white
color3 = css("seagreen")  # seagreen

For a comprehensive list of valid CSS color names, visit the official listing from the MDN Web Docs.

color50.core_functions.colorize(color: Color | str)[source]

Alter the color of a given function’s standard output.

This function is designed to be used as a decorator as a more readable and re-usable means of editing any given function’s output as opposed to simply altering the output of a specific print call.

Parameters:

color – A valid Color object or its equivalent string representation.

Raises:

TypeError – If color is not a Color or string, or if the decorated object is not callable.
ValueError – If color is a string representing an invalid ANSI color code character sequence

Consider this example:

@colorize(css("red"))
def print_warning(msg):
    print(msg)

This would ensure that all contents of msg are printed to standard output as red-colored text. colorize behaves such that the color of standard output resets to default after the function terminates, so the RESET constant is not necessary in this context.

Another example using a background color:

@colorize(constants.GREEN_BG)
def print_success(msg):
    print(msg)

This would ensure that all contents of msg are printed to standard output as plain text with a green-colored background. As with before, colorize appropriately resets the terminal output color upon function termination.

ColorStr class

class color50.colorstr.ColorStr(content: str, fg: Color | None = None, bg: Color | None = None)[source]

A class for representing specialized strings with custom color properties.

Stores text content alongside a foreground color and background color for use when printing said text to the console.

Note

The use of the RESET constant is NOT required when working with ColorStr objects. The class is designed to handle that logic internally.

Example:

msg = "Warning: An error has occurred."
fg = css("red")
bg = css("darkgray")

my_color_str = ColorStr(msg, fg, bg)
print(my_color_str)     # Prints red text on dark gray background

__add__(addend) → str[source]

Support concatenation of ColorStr objects with str objects and of ColorStr objects with other ColorStr objects.

Note

Unlike with Color objects, the order of operations here does not matter. Any order of valid operands is acceptable, including:

ColorStr + str

str + ColorStr

ColorStr + ColorStr

Example 1:

str1 = ColorStr("This text is colorful, and... ", rgb(100, 120, 140))
str2 = "this text is plain."
print(str1 + str2)

Example 2:

str1 = "This text is plain, and... "
str2 = ColorStr("this text is colorful!", rgb(140, 120, 100))
print(str1 + str2)

Example 3:

str1 = ColorStr("This text is colorful, and... ", rgb(100, 120, 140))
str2 = ColorStr("this text is also colorful!", rgb(140, 120, 100))
print(str1 + str2)

__eq__(other) → bool[source]

Support equality comparisons of two ColorStr objects.

Two objects of type ColoStrr are defined to be equal if and only if:

str1.content == str2.content is True (e.g., text content is identical),

str1.fg == str2.fg is True,

and str1.bg == str2.bg is True.

Both equality operators (== and !=) are supported.

Example:

str1 = ColorStr("Hello, World!", css("red"), css("beige"))
str2 = ColorStr("Hello, World", css("red"), css("beige"))
str3 = ColorStr("Hello, World!", css("red"), css("blanchedalmond"))

print(str1 == str2)     # False
print(str2 == str3)     # False
print(str1 == str3)     # False

str4 = ColorStr("Hello, World!", css("red"), css("beige"))

print(str1 == str4)     # True

__init__(content: str, fg: Color | None = None, bg: Color | None = None)[source]

Initialize a ColorStr object with content and optional foreground/ background colors.

Note that None is acceptable for both the fg and bg parameters. When set to None, that property will be ignored when the ColorStr is displayed.

Parameters:

content – A standard string that will display in the specified color.
fg – (optional) A Color object denoting the desired foreground color.
bg – (optional) A Color object denoting the desired background color.

Example:

message = "Hello, World!"
message_colorful = ColorStr(message, hexcode("0000FF"))

print(message)          # Prints message like normal
print(message_colorful) # Prints same message, but in blue

__str__()[source]

Return a string representation of the ColorStr object.

Converting a ColorStr to a pure str will retain the associated color properties, but such properties will no longer be directly editable.

Example 1:

my_color_str = ColorStr("Hello, World!", None, css("crimson"))
print(str(my_color_str) + " ...and goodbye, color.")

# my_color_str can still be edited, like so:
my_color_str.fg = hexcode("a0a0ff")
print(str(my_color_str) + " ..and goodbye, color.")

Example 2:

my_color_str = str(ColorStr("Hello, World!", None, css("crimson")))
print(my_color_str + " ...and goodbye, color.")

# my_color_str is now a normal string, so fg/bg can no longer be edited

property bg

A Color object denoting the desired background color. If set to None, the property will be disregarded when the object is displayed. Supports both get and set operations.

Raises:: TypeError – If the property is not set to a valid Color object.
Type:: Color

property content

The string to be displayed in color. Supports both get and set operations.

Raises:: TypeError – If the property is not set to a str value.
Type:: str

property fg

A Color object denoting the desired foreground color. If set to None, the property will be disregarded when the object is displayed. Supports both get and set operations.

Raises:: TypeError – If the property is not set to a valid Color object.
Type:: Color

Constants

A series of string literal constants for both simpler and more granular color control.

Note

Because these constants are not encapsulated in any class or error-checking logic, using them may result in unintended side effects if not familiar with ANSI color code sequencing. Consult this Wikipedia article for more information.

For ANSI escape sequence manipulation:

Use these constants to directly interface with the lower-level implementation of ANSI color code sequencing. RESET will also be very useful when working with Color objects and not ColorStr objects.

Constant	String value
ANSI_PREFIX	`"\u001b"`
RESET	`"\u001b[0m"`

Example:

# Print a message with magenta-colored text
print(f"{constants.ANSI_PREFIX}[35mHello, World!{constants.RESET}")

For standard colors (foreground):

Use these constants as shorthand for the eight standard ANSI color codes, specifically those that alter the foreground color. Make sure to use RESET after using the desired color to avoid unexpected behavior.

Constant	String value
BLACK	`"\u001b[30m"`
RED	`"\u001b[31m"`
GREEN	`"\u001b[32m"`
YELLOW	`"\u001b[33m"`
BLUE	`"\u001b[34m"`
MAGENTA	`"\u001b[35m"`
CYAN	`"\u001b[36m"`
WHITE	`"\u001b[37m"`

Example:

# Print a message with magenta-colored text
print(f"{constants.MAGENTA}Hello, World!{constants.RESET}")

For standard colors (background):

Use these constants as shorthand for the eight standard ANSI color codes, specifically those that alter the background color. Make sure to use RESET after using the desired color to avoid unexpected behavior.

Constant	String value
BLACK_BG	`"\u001b[40m"`
RED_BG	`"\u001b[41m"`
GREEN_BG	`"\u001b[42m"`
YELLOW_BG	`"\u001b[43m"`
BLUE_BG	`"\u001b[44m"`
MAGENTA_BG	`"\u001b[45m"`
CYAN_BG	`"\u001b[46m"`
WHITE_BG	`"\u001b[47m"`

Example:

# Print a message with a magenta-colored background
print(constants.MAGENTA_BG + "Hello, World!" + constants.RESET)

For bright standard colors (foreground):

Use these constants as shorthand for the eight standard ANSI bright color codes, specifically those that alter the foreground color. Make sure to use RESET after using the desired color to avoid unexpected behavior.

Constant	String value
BRIGHT_BLACK (or GRAY or GREY)	`"\u001b[90m"`
BRIGHT_RED	`"\u001b[91m"`
BRIGHT_GREEN	`"\u001b[92m"`
BRIGHT_YELLOW	`"\u001b[93m"`
BRIGHT_BLUE	`"\u001b[94m"`
BRIGHT_MAGENTA	`"\u001b[95m"`
BRIGHT_CYAN	`"\u001b[96m"`
BRIGHT_WHITE	`"\u001b[97m"`

Example:

# Print a message with bright, magenta-colored text
print(constants.BRIGHT_MAGENTA + "Hello, World!" + constants.RESET)

For bright standard colors (background):

Use these constants as shorthand for the eight standard ANSI bright color codes, specifically those that alter the background color. Make sure to use RESET after using the desired color to avoid unexpected behavior.

Constant	String value
BRIGHT_BLACK_BG (or GRAY_BG or GREY_BG)	`"\u001b[100m"`
BRIGHT_RED_BG	`"\u001b[101m"`
BRIGHT_GREEN_BG	`"\u001b[102m"`
BRIGHT_YELLOW_BG	`"\u001b[103m"`
BRIGHT_BLUE_BG	`"\u001b[104m"`
BRIGHT_MAGENTA_BG	`"\u001b[105m"`
BRIGHT_CYAN_BG	`"\u001b[106m"`
BRIGHT_WHITE_BG	`"\u001b[107m"`

Example:

# Print a message with a bright, magenta-colored background
print(f"{constants.BRIGHT_MAGENTA_BG}Hello, World!{constants.RESET}")

The source code for the module is included below for completeness. Reference it as you wish:

# constants.py
# Constants for use across files

# ANSI escape sequence manipulation
ANSI_PREFIX = "\u001b"
RESET = f"{ANSI_PREFIX}[0m"

# Standard colors (foreground)
BLACK = f"{ANSI_PREFIX}[30m"
RED = f"{ANSI_PREFIX}[31m"
GREEN = f"{ANSI_PREFIX}[32m"
YELLOW = f"{ANSI_PREFIX}[33m"
BLUE = f"{ANSI_PREFIX}[34m"
MAGENTA = f"{ANSI_PREFIX}[35m"
CYAN = f"{ANSI_PREFIX}[36m"
WHITE = f"{ANSI_PREFIX}[37m"

# Standard colors (background)
BLACK_BG = f"{ANSI_PREFIX}[40m"
RED_BG = f"{ANSI_PREFIX}[41m"
GREEN_BG = f"{ANSI_PREFIX}[42m"
YELLOW_BG = f"{ANSI_PREFIX}[43m"
BLUE_BG = f"{ANSI_PREFIX}[44m"
MAGENTA_BG = f"{ANSI_PREFIX}[45m"
CYAN_BG = f"{ANSI_PREFIX}[46m"
WHITE_BG = f"{ANSI_PREFIX}[47m"

# Bright standard colors (foreground)
BRIGHT_BLACK = GREY = GRAY = f"{ANSI_PREFIX}[90m"
BRIGHT_RED = f"{ANSI_PREFIX}[91m"
BRIGHT_GREEN = f"{ANSI_PREFIX}[92m"
BRIGHT_YELLOW = f"{ANSI_PREFIX}[93m"
BRIGHT_BLUE = f"{ANSI_PREFIX}[94m"
BRIGHT_MAGENTA = f"{ANSI_PREFIX}[95m"
BRIGHT_CYAN = f"{ANSI_PREFIX}[96m"
BRIGHT_WHITE = f"{ANSI_PREFIX}[97m"

# Bright standard colors (background)
BRIGHT_BLACK_BG = GREY_BG = GRAY_BG = f"{ANSI_PREFIX}[100m"
BRIGHT_RED_BG = f"{ANSI_PREFIX}[101m"
BRIGHT_GREEN_BG = f"{ANSI_PREFIX}[102m"
BRIGHT_YELLOW_BG = f"{ANSI_PREFIX}[103m"
BRIGHT_BLUE_BG = f"{ANSI_PREFIX}[104m"
BRIGHT_MAGENTA_BG = f"{ANSI_PREFIX}[105m"
BRIGHT_CYAN_BG = f"{ANSI_PREFIX}[106m"
BRIGHT_WHITE_BG = f"{ANSI_PREFIX}[107m"