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.__dir__()

Default dir() implementation.

plumbum.colors.__format__(format_spec, /)

Default object formatter.

plumbum.colors.__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

plumbum.colors.__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

plumbum.colors.__reduce__()

Helper for pickle.

plumbum.colors.__reduce_ex__(protocol, /)

Helper for pickle.

plumbum.colors.__sizeof__()

Size of object in memory, in bytes.

plumbum.colors.__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

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.

class plumbum.colorlib.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 = True/False if you want to control color for anything using this Style.

__str__()

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

exception plumbum.colorlib.ColorNotFound

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

__weakref__

list of weak references to the object (if defined)

class plumbum.colorlib.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.

__str__()

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

class plumbum.colorlib.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

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.

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

property reset

Shortcut to access reset as a property.

__copy__()

Copy is supported, will make dictionary and colors unique.

__invert__()

This allows ~color.

__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)

__radd__(other)

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

wrap(wrap_this)

Wrap a string in this style and its inverse.

__and__(other)

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

__rand__(other)

This class supports "String:" & color syntax.

__ror__(other)

Support for “String” | color syntax

__or__(other)

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

__call__()

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

now()

Immediately writes color to stdout. (Not safe)

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.

print_(*printables, **kargs)

DEPRECATED: Shortcut from classic Python 2

__getitem__(wrapped)

The [] syntax is supported for wrapping

__enter__()

Context manager support

__exit__(_type, _value, _traceback)

Runs even if exception occurred, does not catch it.

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

__eq__(other)

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

abstract __str__()

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

classmethod from_ansi(ansi_string, filter_resets=False)

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

add_ansi(sequence, filter_resets=False)

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

classmethod string_filter_ansi(colored_string)

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

classmethod string_contains_colors(colored_string)

Checks to see if a string contains colors.

to_representation(rep)

This converts both colors to a specific representation

limit_representation(rep)

This only converts if true representation is higher

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.

__hash__ = None

class plumbum.colorlib.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.

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

filter(colored_string)

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

contains_colors(colored_string)

Checks to see if a string contains colors.

extract(colored_string)

Gets colors from an ansi string, returns those colors

plumbum.colorlib.main()

Color changing script entry. Call using python3 -m plumbum.colors, will reset if no arguments given.

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.Color(r_or_color=None, g=None, b=None, fg=True)

Loaded with (r, g, b, fg) or (color, fg=fg). The second signature is a short cut 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.

number

Number of the original color, or closest color

representation

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

exact

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

classmethod from_simple(color, fg=True)

Creates a color from simple name or color number

classmethod from_full(color, fg=True)

Creates a color from full name or color number

classmethod from_hex(color, fg=True)

Converts #123456 values to colors.

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

__eq__(other)

Reset colors are equal, otherwise rgb have to match.

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

to_representation(val)

Converts a color to any representation

limit_representation(val)

Only converts if val is lower than representation

__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.

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

property reset

Shortcut to access reset as a property.

__copy__()

Copy is supported, will make dictionary and colors unique.

__invert__()

This allows ~color.

__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)

__radd__(other)

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

wrap(wrap_this)

Wrap a string in this style and its inverse.

__and__(other)

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

__rand__(other)

This class supports "String:" & color syntax.

__ror__(other)

Support for “String” | color syntax

__or__(other)

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

__call__()

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

now()

Immediately writes color to stdout. (Not safe)

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.

print_(*printables, **kargs)

DEPRECATED: Shortcut from classic Python 2

__getitem__(wrapped)

The [] syntax is supported for wrapping

__enter__()

Context manager support

__exit__(_type, _value, _traceback)

Runs even if exception occurred, does not catch it.

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

__eq__(other)

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

abstract __str__()

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

classmethod from_ansi(ansi_string, filter_resets=False)

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

add_ansi(sequence, filter_resets=False)

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

classmethod string_filter_ansi(colored_string)

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

classmethod string_contains_colors(colored_string)

Checks to see if a string contains colors.

to_representation(rep)

This converts both colors to a specific representation

limit_representation(rep)

This only converts if true representation is higher

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.

__hash__ = None

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 = True/False if you want to control color for anything using this Style.

__str__()

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

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.

__str__()

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

exception plumbum.colorlib.styles.ColorNotFound

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

__weakref__

list of weak references to the object (if defined)

exception plumbum.colorlib.styles.AttributeNotFound

Similar to color not found, only for attributes.

__weakref__

list of weak references to the object (if defined)

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__.

full(name)

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

simple(name)

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

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

Return the extended color scheme color for a value.

hex(hexcode)

Return the extended color scheme color for a value.

ansi(ansiseq)

Make a style from an ansi text sequence

__getitem__(val)

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.

__iter__()

Iterates through all colors in extended colorset.

__invert__()

Allows clearing a color with ~

__enter__()

This will reset the color on leaving the with statement.

__exit__(_type: Any, _value: Any, _traceback: Any) → None

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

__repr__()

Simple representation of the class by name.

__weakref__

list of weak references to the object (if defined)

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.

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

filter(colored_string)

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

contains_colors(colored_string)

Checks to see if a string contains colors.

extract(colored_string)

Gets colors from an ansi string, returns those colors

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.

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.

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

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

__init__(r: int, g: int, b: int) → None

only_basic()

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

all_slow(color_slice: slice = slice(None, None, None)) → int

This is a slow way to find the nearest color.

only_colorblock() → int

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

only_simple() → int

Finds the simple color-block color.

only_grey() → int

Finds the greyscale color.

all_fast() → int

Runs roughly 8 times faster than the slow version.

__weakref__

list of weak references to the object (if defined)

plumbum.colorlib.names.from_html(color: str) → Tuple[int, int, int]

Convert html hex code to rgb.

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

Convert rgb to html hex code.