Package plumbum.colors

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


default object formatter

plumbum.colors.__new__(S, ...) → a new object with type S, a subtype of T

helper for pickle


helper for pickle

plumbum.colors.__sizeof__() → int

size of object in memory, in bytes


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


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.


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


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

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:


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


The red/green/blue tuple for this color


If true will stay to 16 color mode.


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


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


Reset colors are equal, otherwise rgb have to match.

__init__(r_or_color=None, g=None, b=None, fg=True)[source]

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


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


This just prints it’s simple name


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


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

classmethod from_full(color, fg=True)[source]

Creates a color from full name or color number

classmethod from_hex(color, fg=True)[source]

Converts #123456 values to colors.

classmethod from_simple(color, fg=True)[source]

Creates a color from simple name or color number


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


Only converts if val is lower than representation


The (closest) name of the current color


The camelcase name of the color


Converts a color to any representation

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

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.


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)


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


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


Copy is supported, will make dictionary and colors unique.


Context manager support


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

__exit__(type, value, traceback)[source]

Runs even if exception occurred, does not catch it.


The [] syntax is supported for wrapping

__init__(attributes=None, fgcolor=None, bgcolor=None, reset=False)[source]

This is usually initialized from a factory.


This allows ~color.


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


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


This class supports "String:" & color syntax, excpet in Python 2.6 due to bug with that Python.


Support for “String” | color syntax


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


list of weak references to the object (if defined)

add_ansi(sequence, filter_resets=False)[source]

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


Generates the full ANSI code sequence for a Style


This is the string ANSI sequence.


The color in the 8 color representation.


alias of Color

classmethod from_ansi(ansi_string, filter_resets=False)[source]

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


The color in the 256 color representation.


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


This only converts if true representation is higher


Immediately writes color to stdout. (Not safe)

print(*printables, **kargs)[source]

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)

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


Shortcut to access reset as a property.


The color in the 16 color representation.


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

classmethod string_contains_colors(colored_string)[source]

Checks to see if a string contains colors.

classmethod string_filter_ansi(colored_string)[source]

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


This converts both colors to a specific representation


The color in the true color representation.


Wrap a sting in this style and its inverse.

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

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.

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

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

exception plumbum.colorlib.styles.ColorNotFound[source]

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


list of weak references to the object (if defined)

exception plumbum.colorlib.styles.AttributeNotFound[source]

Similar to color not found, only for attributes.


list of weak references to the object (if defined)


Color-related factories. They produce Styles.

class plumbum.colorlib.factories.ColorFactory(fg, style)[source]

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


Full color names work, but do not populate __dir__.


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


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

rgb(r, g=None, b=None)[source]

Return the extended color scheme color for a value.


Return the extended color scheme color for a value.


Make a style from an ansi text sequence


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

Shortcut to provide way to access colors.


Iterates through all colors in extended colorset.


Allows clearing a color with ~


This will reset the color on leaving the with statement.

__exit__(type, value, traceback)[source]

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


Simple representation of the class by name.


list of weak references to the object (if defined)

class plumbum.colorlib.factories.StyleFactory(style)[source]

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


Shortcut for setting color usage on Style


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


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


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


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


Checks to see if a string contains colors.


Gets colors from an ansi string, returns those colors


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, g, b)[source]

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


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

all_slow(color_slice=slice(None, None, None))[source]

This is a slow way to find the nearest color.


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


Finds the simple color-block color.


Finds the greyscale color.


Runs roughly 8 times faster than the slow version.


list of weak references to the object (if defined)


Convert html hex code to rgb.

plumbum.colorlib.names.to_html(r, g, b)[source]

Convert rgb to html hex code.