Package plumbum.colors

Factory for styles. Holds font styles, FG and BG objects representing colors, and imitates the FG ColorFactory to a large degree.

plumbum.colors.ansi(ansiseq)

Make a style from an ansi text sequence

Return type:

TypeVar(S, bound= Style)

plumbum.colors.contains_colors(colored_string)

Checks to see if a string contains colors.

Return type:

bool

plumbum.colors.extract(colored_string)

Gets colors from an ansi string, returns those colors

Return type:

TypeVar(S, bound= Style)

plumbum.colors.filter(colored_string)

Filters out colors in a string, returning only the name.

Return type:

str

plumbum.colors.from_ansi(ansi_sequence)

Calling this is a shortcut for creating a style from an ANSI sequence.

Return type:

TypeVar(S, bound= Style)

plumbum.colors.from_ansi_string(ansi_string)

Calling this is a shortcut for creating a style from an ANSI string.

Added in version 2.0.

Return type:

Iterator[TypeVar(S, bound= Style) | str]

plumbum.colors.full(name)

Gets the style for a color, using standard name procedure: either full color name, html code, or number.

Return type:

TypeVar(S, bound= Style)

plumbum.colors.get_colors_from_string(color='')

Sets color based on string, use . or space for separator, and numbers, fg/bg, htmlcodes, etc all accepted (as strings).

Return type:

TypeVar(S, bound= Style)

plumbum.colors.hex(hexcode)

Return the extended color scheme color for a value.

Return type:

TypeVar(S, bound= Style)

plumbum.colors.rgb(r, g=None, b=None)

Return the extended color scheme color for a value.

Return type:

TypeVar(S, bound= Style)

plumbum.colors.sequence_to_string(sequence)

Converts a sequence of styles and strings into a single string with ANSI codes.

Added in version 2.0.

Return type:

str

plumbum.colors.simple(name)

Return the extended color scheme color for a value or name.

Return type:

TypeVar(S, bound= Style)

plumbum.colorlib

The ansicolor object provides bg and fg to access colors, and attributes like bold and underlined text. It also provides reset to recover the normal font.

plumbum.colorlib.styles

This file provides two classes, Color and Style.

Color is rarely used directly, but merely provides the workhorse for finding and manipulating colors.

With the Style class, any color can be directly called or given to a with statement.

class plumbum.colorlib.styles.ANSIStyle(attributes=None, fgcolor=None, bgcolor=None, reset=False)

This is a subclass for ANSI styles. Use it to get color on sys.stdout tty terminals on posix systems.

Set use_color = 0 # up to 4 if you want to control color for anything using this Style.

use_color = 0

The color level. This is a default value that subclasses may override. For example, ANSIStyle uses this to control color output, while other styles may always use the maximum level (4).

__str__()

Base Style does not implement a __str__ representation. This is the one required method of a subclass.

Return type:

str

exception plumbum.colorlib.styles.AttributeNotFound

Similar to color not found, only for attributes.

__weakref__

list of weak references to the object

class plumbum.colorlib.styles.Color(r_or_color=None, g=None, b=None, /, *, fg=True)

Loaded with (r, g, b, fg=fg) or (color, fg=fg). The second signature is a shortcut and will try full and hex loading.

This class stores the idea of a color, rather than a specific implementation. It provides as many different tools for representations as possible, and can be subclassed to add more representations, though that should not be needed for most situations. .from_ class methods provide quick ways to create colors given different representations. You will not usually interact with this class.

Possible colors:

reset = Color() # The reset color by default
background_reset = Color(fg=False) # Can be a background color
blue = Color(0,0,255) # Red, Green, Blue
green = Color.from_full("green") # Case insensitive name, from large colorset
red = Color.from_full(1) # Color number
white = Color.from_html("#FFFFFF") # HTML supported
yellow = Color.from_simple("red") # Simple colorset

The attributes are:

reset

True it this is a reset color (following attributes don’t matter if True)

rgb

The red/green/blue tuple for this color

simple

If true will stay to 16 color mode.

number

The color number given the mode, closest to rgb if not rgb not exact, gives position of closest name.

fg

This is a foreground color if True. Background color if False.

__init__(r_or_color=None, g=None, b=None, /, *, fg=True)

This works from color values, or tries to load non-simple ones.

exact

This is false if the named color does not match the real color

representation

0 for off, 1 for 8 colors, 2 for 16 colors, 3 for 256 colors, 4 for true color

classmethod from_simple(color, fg=True)

Creates a color from simple name or color number

Return type:

Self

classmethod from_full(color, fg=True)

Creates a color from full name or color number

Return type:

Self

classmethod from_hex(color, fg=True)

Converts #123456 values to colors.

Return type:

Self

property name

The (closest) name of the current color

property name_camelcase

The camelcase name of the color

__repr__()

This class has a smart representation that shows name and color (if not unique).

Return type:

str

__eq__(other)

Reset colors are equal, otherwise rgb have to match.

Return type:

bool

__hash__()

Return hash(self).

Return type:

int

property ansi_sequence

This is the ansi sequence as a string, ready to use.

property ansi_codes

This is the full ANSI code, can be reset, simple, 256, or full color.

property hex_code

This is the hex code of the current color, html style notation.

__str__()

This just prints it’s simple name

Return type:

str

to_representation(val)

Converts a color to any representation

Return type:

Self

limit_representation(val)

Only converts if val is lower than representation

Return type:

Self

exception plumbum.colorlib.styles.ColorNotFound

Thrown when a color is not valid for a particular method.

__weakref__

list of weak references to the object

class plumbum.colorlib.styles.HTMLStyle(attributes=None, fgcolor=None, bgcolor=None, reset=False)

This was meant to be a demo of subclassing Style, but actually can be a handy way to quickly color html text.

end = '<br/>\n'

The endline character. Override if needed in subclasses.

classmethod sequence_to_string(sequence)

This is the opposite of from_ansi_string, it takes a list of styles and strings and concatenates them.

Added in version 2.0.

Return type:

str

__str__()

Base Style does not implement a __str__ representation. This is the one required method of a subclass.

Return type:

str

__eq__(other)

Equality is true only if reset, or if attributes, fg, and bg match.

Return type:

bool

__hash__ = None

class plumbum.colorlib.styles.Style(attributes=None, fgcolor=None, bgcolor=None, reset=False)

This class allows the color changes to be called directly to write them to stdout, [] calls to wrap colors (or the .wrap method) and can be called in a with statement.

color_class

The class of color to use. Never hardcode Color call when writing a Style method.

alias of Color

end = '\n'

The endline character. Override if needed in subclasses.

ANSI_REG = re.compile('\x1b\\[([\\d;]+)m')

The regular expression that finds ansi codes in a string.

use_color = 4

The color level. This is a default value that subclasses may override. For example, ANSIStyle uses this to control color output, while other styles may always use the maximum level (4).

property stdout

This property will allow custom, class level control of stdout. It will use current sys.stdout if set to None (default). Unfortunately, it only works on an instance..

__init__(attributes=None, fgcolor=None, bgcolor=None, reset=False)

This is usually initialized from a factory.

invert()

This resets current color(s) and flips the value of all attributes present

Return type:

Self

__copy__()

Copy is supported, will make dictionary and colors unique.

Return type:

Self

__invert__()

This allows ~color.

Return type:

Self

__add__(other)

Adding two matching Styles results in a new style with the combination of both. Adding with a string results in the string concatenation of a style.

Addition is non-commutative, with the rightmost Style property being taken if both have the same property. (Not safe)

Return type:

TypeVar(S, Style, str)

__radd__(other)

This only gets called if the string is on the left side. (Not safe)

Return type:

str

wrap(wrap_this)

Wrap a string in this style and its inverse.

Return type:

str

__and__(other)

This class supports color & color2 syntax, and color & "String" syntax too.

Return type:

TypeVar(S, Style, str)

__rand__(other)

This class supports "String:" & color syntax.

Return type:

str

__ror__(other)

Support for “String” | color syntax

Return type:

str

__or__(other)

This class supports color | color2 syntax. It also supports "color | "String" syntax too.

Return type:

TypeVar(S, Style, str)

__call__()

This is a shortcut to print color immediately to the stdout. (Not safe)

Return type:

None

now()

Immediately writes color to stdout. (Not safe)

Return type:

None

print(*printables, **kargs)

This acts like print; will print that argument to stdout wrapped in Style with the same syntax as the print function in 3.4.

Return type:

None

print_(*printables, **kargs)

DEPRECATED: Shortcut from classic Python 2; use .print instead.

Return type:

None

__getitem__(wrapped)

The [] syntax is supported for wrapping

Return type:

str

__enter__()

Context manager support

Return type:

None

__exit__(_type, _value, _traceback)

Runs even if exception occurred, does not catch it.

Return type:

Literal[False]

property ansi_codes

Generates the full ANSI code sequence for a Style

property ansi_sequence

This is the string ANSI sequence.

__repr__()

Return repr(self).

Return type:

str

__eq__(other)

Equality is true only if reset, or if attributes, fg, and bg match.

Return type:

bool

__hash__ = None

abstractmethod __str__()

Base Style does not implement a __str__ representation. This is the one required method of a subclass.

Return type:

str

classmethod from_ansi(ansi_string, filter_resets=False)

This generated a style from an ansi string. Will ignore resets if filter_resets is True.

Return type:

Self

classmethod from_ansi_string(ansi_string)

This will read in a string with interleaved codes

Added in version 2.0.

Return type:

Iterator[str | Self]

classmethod sequence_to_string(sequence)

This is the opposite of from_ansi_string, it takes a list of styles and strings and concatenates them.

Added in version 2.0.

Return type:

str

add_ansi(sequence, filter_resets=False)

Adds a sequence of ansi numbers to the class. Will ignore resets if filter_resets is True.

Return type:

None

classmethod string_filter_ansi(colored_string)

Filters out colors in a string, returning only the name.

Return type:

str

classmethod string_contains_colors(colored_string)

Checks to see if a string contains colors.

Return type:

bool

to_representation(rep)

This converts both colors to a specific representation

Return type:

Self

limit_representation(rep)

This only converts if true representation is higher

Return type:

Self

property basic

The color in the 8 color representation.

property simple

The color in the 16 color representation.

property full

The color in the 256 color representation.

property true

The color in the true color representation.

plumbum.colorlib.factories

Color-related factories. They produce Styles.

class plumbum.colorlib.factories.ColorFactory(fg, style)

This creates color names given fg = True/False. It usually will be called as part of a StyleFactory.

__init__(fg, style)

__getattr__(item)

Full color names work, but do not populate __dir__.

Return type:

TypeVar(S, bound= Style)

full(name)

Gets the style for a color, using standard name procedure: either full color name, html code, or number.

Return type:

TypeVar(S, bound= Style)

simple(name)

Return the extended color scheme color for a value or name.

Return type:

TypeVar(S, bound= Style)

rgb(r, g=None, b=None)

Return the extended color scheme color for a value.

Return type:

TypeVar(S, bound= Style)

hex(hexcode)

Return the extended color scheme color for a value.

Return type:

TypeVar(S, bound= Style)

ansi(ansiseq)

Make a style from an ansi text sequence

Return type:

TypeVar(S, bound= Style)

__getitem__(val)

Overloads:

• self, val (slice) → list[S]

• self, val (tuple[int, int, int] | str | int) → S

Shortcut to provide way to access colors numerically or by slice. If end <= 16, will stay to simple ANSI version.

__call__(val_or_r=None, g=None, b=None)

Shortcut to provide way to access colors.

Return type:

TypeVar(S, bound= Style)

__iter__()

Iterates through all colors in extended colorset.

Return type:

Iterator[TypeVar(S, bound= Style)]

__invert__()

Allows clearing a color with ~

Return type:

TypeVar(S, bound= Style)

__enter__()

This will reset the color on leaving the with statement.

Return type:

Self

__exit__(_type, _value, _traceback)

This resets a FG/BG color or all styles, due to different definition of RESET for the factories.

Return type:

None

__repr__()

Simple representation of the class by name.

Return type:

str

__weakref__

list of weak references to the object

class plumbum.colorlib.factories.StyleFactory(style)

Factory for styles. Holds font styles, FG and BG objects representing colors, and imitates the FG ColorFactory to a large degree.

__init__(style)

property use_color

Shortcut for setting color usage on Style

from_ansi(ansi_sequence)

Calling this is a shortcut for creating a style from an ANSI sequence.

Return type:

TypeVar(S, bound= Style)

from_ansi_string(ansi_string)

Calling this is a shortcut for creating a style from an ANSI string.

Added in version 2.0.

Return type:

Iterator[TypeVar(S, bound= Style) | str]

sequence_to_string(sequence)

Converts a sequence of styles and strings into a single string with ANSI codes.

Added in version 2.0.

Return type:

str

property stdout

This is a shortcut for getting stdout from a class without an instance.

get_colors_from_string(color='')

Sets color based on string, use . or space for separator, and numbers, fg/bg, htmlcodes, etc all accepted (as strings).

Return type:

TypeVar(S, bound= Style)

filter(colored_string)

Filters out colors in a string, returning only the name.

Return type:

str

contains_colors(colored_string)

Checks to see if a string contains colors.

Return type:

bool

extract(colored_string)

Gets colors from an ansi string, returns those colors

Return type:

TypeVar(S, bound= Style)

plumbum.colorlib.names

Names for the standard and extended color set. Extended set is similar to vim wiki, colored, etc. Colors based on wikipedia.

You can access the index of the colors with names.index(name). You can access the rgb values with r=int(html[n][1:3],16), etc.

class plumbum.colorlib.names.FindNearest(r, g, b)

This is a class for finding the nearest color given rgb values. Different find methods are available.

__init__(r, g, b)

only_basic()

This will only return the first 8 colors! Breaks the colorspace into cubes, returns color

Return type:

int

all_slow(color_slice=slice(None, None, None))

This is a slow way to find the nearest color.

Return type:

int

only_colorblock()

This finds the nearest color based on block system, only works for 17-232 color values.

Return type:

int

only_simple()

Finds the simple color-block color.

Return type:

int

only_grey()

Finds the greyscale color.

Return type:

int

all_fast()

Runs roughly 8 times faster than the slow version.

Return type:

int

plumbum.colorlib.names.color_codes_simple = [0, 1, 2, 3, 4, 5, 6, 7, 60, 61, 62, 63, 64, 65, 66, 67]

Simple colors, remember that reset is #9, second half is non as common.

plumbum.colorlib.names.from_html(color)

Convert html hex code to rgb.

Return type:

tuple[int, int, int]

plumbum.colorlib.names.to_html(r, g, b)

Convert rgb to html hex code.

Return type:

str