API#

adorable#

adorable.ANSI_REGEX = re.compile('\x1b\\[.*?[ABCDEFGHJKfnsumlh]')#: Regex pattern that matches most ansi escape sequences.

adorable.use(terminal)[source]#

New in version 0.2.0b1.

A quick way of overriding the current color system manually.

Parameters:: terminal (str) – The color system as a string. This might be "NOCOLOR", "BIT3", "BIT8 or "BIT24".
Return type:: None

adorable.filter_ansi(style)[source]#

Filters all ansi objects inside a mapping. Useful when ansi objects are defined in a module so that locals() or module.__dict__ can be used.

Parameters:: style (Mapping[str, Any]) –
Return type:: dict[str, adorable.ansi.Ansi]

color#

Utilities for creating color objects.

class adorable.color.Color(**data)[source]#

Abstract Base Class for terminal dependent colors.

Attention

Directly initializing this class is prohibited. Use one of the available class methods such as from_name(), from_rgb() or from_hex().

Parameters:: data (Any) – Various metadata set by subclasses for internal use.

__or__(other)[source]#

Returns the color that is supported. Returns the color with a larger color palette when both are supported. Returns the color with a smaller color palette when neither is supported.

Parameters:: other (Color) –
Return type:: Color

__add__(other)[source]#

Combines two styles.

Parameters:: other (Ansi) –
Return type:: Ansi

__iadd__(other)[source]#

Combines this and another style.

Parameters:: other (Ansi) –
Return type:: Ansi

__call__(*args, **kwargs)[source]#

Styles a string.

Parameters:

args (Any) – Objects to
sep – String that separates args.
kwargs (Any) –

Return type:

The styled string.

enable_str()[source]#

Returns escape sequence to enable the ansi style.

Return type:: str

disable_str()[source]#

Returns escape sequence to disable the ansi style.

Return type:: str

is_initialized()[source]#

New in version 0.1.0.

Checks if the color is initialized or not.

Return type:: bool

is_supported()[source]#

New in version 0.1.1.

Checks if the color system is supported or not.

Return type:: bool

property fg: Color#: Sets the color to foreground mode.

property bg: Color#: Sets the color to background mode.

on(other)[source]#

Sets the color to foreground mode and adds another color as background mode.

Parameters:: other (Color) – Background color to set for this style. May already be initialized as background mode.
Return type:: Color

classmethod from_rgb(rgb)[source]#

Get color from RGB value.

See also

Creating Colors

Parameters:: rgb (Union[tuple[int, int, int], RGB, tuple[float, float, float]]) –
Return type:: Color

classmethod from_name(name)[source]#

Get color from Web Color name.

See also

Creating Colors

Parameters:: name (str) –
Return type:: Color

classmethod from_hex(hex)[source]#

Get color from HEX value.

See also

Creating Colors

Parameters:: hex (Union[str, int]) –
Return type:: Color

disable(file=None)#

Disables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

enable(file=None)#

Enables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

extend(*others)#

Adds other ansi styles to this style.

Parameters:: others (Ansi) –
Return type:: Ansi

class adorable.color.Color0bit(**data)[source]#

Attention

Directly initializing this class is prohibited. Use one of the available class methods such as from_name(), from_rgb() or from_hex().

Parameters:: data (Any) – Various metadata set by subclasses for internal use.

__add__(other)#

Combines two styles.

Parameters:: other (Ansi) –
Return type:: Ansi

__call__(*args, **kwargs)#

Styles a string.

Parameters:

args (Any) – Objects to
sep – String that separates args.
kwargs (Any) –

Return type:

The styled string.

__iadd__(other)#

Combines this and another style.

Parameters:: other (Ansi) –
Return type:: Ansi

__or__(other)#

Returns the color that is supported. Returns the color with a larger color palette when both are supported. Returns the color with a smaller color palette when neither is supported.

Parameters:: other (Color) –
Return type:: Color

property bg: Color#: Sets the color to background mode.

disable(file=None)#

Disables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

disable_str()#

Returns escape sequence to disable the ansi style.

Return type:: str

enable(file=None)#

Enables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

enable_str()#

Returns escape sequence to enable the ansi style.

Return type:: str

extend(*others)#

Adds other ansi styles to this style.

Parameters:: others (Ansi) –
Return type:: Ansi

property fg: Color#: Sets the color to foreground mode.

classmethod from_hex(hex)#

Get color from HEX value.

See also

Creating Colors

Parameters:: hex (Union[str, int]) –
Return type:: Color

classmethod from_name(name)#

Get color from Web Color name.

See also

Creating Colors

Parameters:: name (str) –
Return type:: Color

classmethod from_rgb(rgb)#

Get color from RGB value.

See also

Creating Colors

Parameters:: rgb (Union[tuple[int, int, int], RGB, tuple[float, float, float]]) –
Return type:: Color

is_initialized()#

New in version 0.1.0.

Checks if the color is initialized or not.

Return type:: bool

is_supported()#

New in version 0.1.1.

Checks if the color system is supported or not.

Return type:: bool

on(other)#

Sets the color to foreground mode and adds another color as background mode.

Parameters:: other (Color) – Background color to set for this style. May already be initialized as background mode.
Return type:: Color

class adorable.color.Color3bit(**data)[source]#

Attention

Directly initializing this class is prohibited. Use one of the available class methods such as from_name(), from_rgb() or from_hex().

Parameters:: data (Any) – Various metadata set by subclasses for internal use.

__add__(other)#

Combines two styles.

Parameters:: other (Ansi) –
Return type:: Ansi

__call__(*args, **kwargs)#

Styles a string.

Parameters:

args (Any) – Objects to
sep – String that separates args.
kwargs (Any) –

Return type:

The styled string.

__iadd__(other)#

Combines this and another style.

Parameters:: other (Ansi) –
Return type:: Ansi

__or__(other)#

Returns the color that is supported. Returns the color with a larger color palette when both are supported. Returns the color with a smaller color palette when neither is supported.

Parameters:: other (Color) –
Return type:: Color

property bg: Color#: Sets the color to background mode.

disable(file=None)#

Disables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

disable_str()#

Returns escape sequence to disable the ansi style.

Return type:: str

enable(file=None)#

Enables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

enable_str()#

Returns escape sequence to enable the ansi style.

Return type:: str

extend(*others)#

Adds other ansi styles to this style.

Parameters:: others (Ansi) –
Return type:: Ansi

property fg: Color#: Sets the color to foreground mode.

classmethod from_hex(hex)#

Get color from HEX value.

See also

Creating Colors

Parameters:: hex (Union[str, int]) –
Return type:: Color

classmethod from_name(name)#

Get color from Web Color name.

See also

Creating Colors

Parameters:: name (str) –
Return type:: Color

classmethod from_rgb(rgb)#

Get color from RGB value.

See also

Creating Colors

Parameters:: rgb (Union[tuple[int, int, int], RGB, tuple[float, float, float]]) –
Return type:: Color

is_initialized()#

New in version 0.1.0.

Checks if the color is initialized or not.

Return type:: bool

is_supported()#

New in version 0.1.1.

Checks if the color system is supported or not.

Return type:: bool

on(other)#

Sets the color to foreground mode and adds another color as background mode.

Parameters:: other (Color) – Background color to set for this style. May already be initialized as background mode.
Return type:: Color

class adorable.color.Color8bit(**data)[source]#

Attention

Directly initializing this class is prohibited. Use one of the available class methods such as from_name(), from_rgb() or from_hex().

Parameters:: data (Any) – Various metadata set by subclasses for internal use.

__add__(other)#

Combines two styles.

Parameters:: other (Ansi) –
Return type:: Ansi

__call__(*args, **kwargs)#

Styles a string.

Parameters:

args (Any) – Objects to
sep – String that separates args.
kwargs (Any) –

Return type:

The styled string.

__iadd__(other)#

Combines this and another style.

Parameters:: other (Ansi) –
Return type:: Ansi

__or__(other)#

Returns the color that is supported. Returns the color with a larger color palette when both are supported. Returns the color with a smaller color palette when neither is supported.

Parameters:: other (Color) –
Return type:: Color

property bg: Color#: Sets the color to background mode.

disable(file=None)#

Disables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

disable_str()#

Returns escape sequence to disable the ansi style.

Return type:: str

enable(file=None)#

Enables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

enable_str()#

Returns escape sequence to enable the ansi style.

Return type:: str

extend(*others)#

Adds other ansi styles to this style.

Parameters:: others (Ansi) –
Return type:: Ansi

property fg: Color#: Sets the color to foreground mode.

classmethod from_hex(hex)#

Get color from HEX value.

See also

Creating Colors

Parameters:: hex (Union[str, int]) –
Return type:: Color

classmethod from_name(name)#

Get color from Web Color name.

See also

Creating Colors

Parameters:: name (str) –
Return type:: Color

classmethod from_rgb(rgb)#

Get color from RGB value.

See also

Creating Colors

Parameters:: rgb (Union[tuple[int, int, int], RGB, tuple[float, float, float]]) –
Return type:: Color

is_initialized()#

New in version 0.1.0.

Checks if the color is initialized or not.

Return type:: bool

is_supported()#

New in version 0.1.1.

Checks if the color system is supported or not.

Return type:: bool

on(other)#

Sets the color to foreground mode and adds another color as background mode.

Parameters:: other (Color) – Background color to set for this style. May already be initialized as background mode.
Return type:: Color

class adorable.color.Color24bit(**data)[source]#

Attention

Directly initializing this class is prohibited. Use one of the available class methods such as from_name(), from_rgb() or from_hex().

Parameters:: data (Any) – Various metadata set by subclasses for internal use.

__add__(other)#

Combines two styles.

Parameters:: other (Ansi) –
Return type:: Ansi

__call__(*args, **kwargs)#

Styles a string.

Parameters:

args (Any) – Objects to
sep – String that separates args.
kwargs (Any) –

Return type:

The styled string.

__iadd__(other)#

Combines this and another style.

Parameters:: other (Ansi) –
Return type:: Ansi

__or__(other)#

Returns the color that is supported. Returns the color with a larger color palette when both are supported. Returns the color with a smaller color palette when neither is supported.

Parameters:: other (Color) –
Return type:: Color

property bg: Color#: Sets the color to background mode.

disable(file=None)#

Disables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

disable_str()#

Returns escape sequence to disable the ansi style.

Return type:: str

enable(file=None)#

Enables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

enable_str()#

Returns escape sequence to enable the ansi style.

Return type:: str

extend(*others)#

Adds other ansi styles to this style.

Parameters:: others (Ansi) –
Return type:: Ansi

property fg: Color#: Sets the color to foreground mode.

classmethod from_hex(hex)#

Get color from HEX value.

See also

Creating Colors

Parameters:: hex (Union[str, int]) –
Return type:: Color

classmethod from_name(name)#

Get color from Web Color name.

See also

Creating Colors

Parameters:: name (str) –
Return type:: Color

classmethod from_rgb(rgb)#

Get color from RGB value.

See also

Creating Colors

Parameters:: rgb (Union[tuple[int, int, int], RGB, tuple[float, float, float]]) –
Return type:: Color

is_initialized()#

New in version 0.1.0.

Checks if the color is initialized or not.

Return type:: bool

is_supported()#

New in version 0.1.1.

Checks if the color system is supported or not.

Return type:: bool

on(other)#

Sets the color to foreground mode and adds another color as background mode.

Parameters:: other (Color) – Background color to set for this style. May already be initialized as background mode.
Return type:: Color

adorable.color.get_color()[source]#

Return type:: type[adorable.color.Color]

adorable.color.from_hex(*args, **kwargs)[source]#

Get color from HEX value.

See also

Creating Colors

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Color

adorable.color.from_rgb(*args, **kwargs)[source]#

Get color from RGB value.

See also

Creating Colors

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Color

adorable.color.from_name(*args, **kwargs)[source]#

Get color from Web Color name.

See also

Creating Colors

Parameters:

args (Any) –
kwargs (Any) –

Return type:

Color

adorable.color.empty()[source]#

New in version 0.1.0.

Returns a new instance of Color0bit.

Return type:: Color0bit

markup#

Markup utilities for adorable.

Warning

Using XML for markup is likely going to be replaced in the future by a more friendly optimized markup language.

adorable.markup.insert(*args, **kwargs)[source]#

Returns args and kwargs as is.

Parameters:

args (Any) –
kwargs (Any) –

Return type:

tuple[tuple[Any, …], dict[str, Any]]

adorable.markup.markup_xml(string, style=None, insert=None)[source]#

Warning

Using XML for markup is likely going to be replaced in the future by a more friendly optimized markup language.

Use XML to style a string. In order to format the string, provide the variables directly to this function. All variables will be escaped automatically unless !r is added at the end. You can also use !e to explicitly specify that the variable has to be escaped.

Parameters:

string (str) – The markup text.
style (Optional[dict[str, adorable.ansi.Ansi]]) – Mapping of keys and the style to use. You may want to use adorable.filter_ansi().
insert (Optional[tuple[tuple[Any, ...], dict[str, Any]]]) –
Insert variables to string.

See also

insert()

Return type:

Styled text.

stylesheet#

New in version 0.1.0.

Load ansi objects from a stylesheet file in your project.

adorable.stylesheet.remove_style(name)[source]#

Removes a style.

Parameters:: name (str) – The name of the style object.
Return type:: None

adorable.stylesheet.remove_all()[source]#

Removes all styles.

Return type:: None

adorable.stylesheet.export(**styles)[source]#

Loads all objects.

This usually called from a stylesheet module in order to make the ansi objects globally available.

Preference

This method is preferred over load_stylesheet().

Caution

This will not filter out ansi objects but rather raise a TypeError.

Parameters:: styles (Ansi) – Ansi objects and an associated name.
Return type:: None

adorable.stylesheet.load_stylesheet(source=None, force=False)[source]#

Loads a stylesheet.

Preference

export() is preferred over this method.

Tip

The safest method is to import the stylesheet module and use it as the source argument.

Alternatively the export() function may be used which is also safe.

Parameters:

source (Optional[Union[Path, module, str]]) –
When a Path or str is given, it will load all style objects from that file by importing it. If the path is a directory it will try to find a file named _stylesheet.py or stylesheet.py (in that order) and use it as a stylesheet.

This function will attempt to load all style objects mentioned in the __all__ variable. If that variable is not defined, it will filter all style objects defined in the module.

Caution

This will include built-in style objects such as ones imported from adorable.style.

When no source is provided (default) the function will attempt to search the stylesheet file by querying the module that called this function. Then it will use the directory where the caller’s source file is as the path. After that the same process takes place as when defining source with a Path.
force (bool) – This function caches already loaded stylesheets - no matter what value the source parameter previously had. Forcing a rerun may be done by setting this to True.

Raises:

RuntimeError – Could not find source file.

Return type:

None

term#

Utilities for working with the terminal color system.

class adorable.term.Terminal(value)[source]#

Changed in version 0.1.1: Removed BIT4 value.

Enumeration for specifying the color system to use.

NOCOLOR = 1#

BIT3 = 2#

BIT8 = 3#

BIT24 = 4#

classmethod get_term(stream=None, remember=True)[source]#

Returns the color system that is supported by the end user’s terminal.

The color system is checked in the following order:

Is stream a valid terminal?
Environment variable ADORABLE_COLOR
Environment variable NO_COLOR
Environment variable COLORTERM
Environment variable TERM
Fallback: NOCOLOR

Caution

The result of this function will be saved in the cache variable. The next time this function is called, the result in the cache will be returned if it is not None. You can clear the cache at any time by setting cache to None:

from adorable import term
term.cache = None

New in version 0.1.1.

Parameters:

stream (Optional[Iterable[TextIO]]) –
The streams to query.

If all of the streams provided are invalid terminal, RuntimeError is raised. Defaults to stdout and stderr.

If you want to skip checking for a valid terminal you may set this to an empty iterable such as [].
remember (bool) –

New in version 0.1.1.

Caches the result.

Return type:

Terminal

Examples

# check if either stdout or stderr is valid
Terminal.get_term()

# skip terminal check
Terminal.get_term([])

# only check stdout
Terminal.get_term([sys.stdout])

Raises:

RuntimeError – Standard output is not a valid terminal.

Parameters:

stream (Optional[Iterable[TextIO]]) –
remember (bool) –

Return type:

Terminal

is_supported()[source]#

New in version 0.1.1.

Checks if the color system is supported by the terminal.

Return type:: bool

ansi#

adorable.ansi.paint(*args, style=None, sep=' ')[source]#

Styles a string.

Parameters:

args (Any) – Objects to style. The str() function will be called on each object.
style (Optional[Ansi]) – Ansi object that styles the string.
sep (str) – String that separates args.

Return type:

The styled string.

adorable.ansi.formatc(*args, style=None, sep=' ')#

Alias of paint().

Parameters:

args (Any) –
style (Optional[Ansi]) –
sep (str) –

Return type:

str

adorable.ansi.printc(*args, **kwargs)[source]#

Prints a styled string.

This function takes the same arguments as the built-in print function. It also provides an extra parameter.

Parameters:

args (Any) – Positional arguments passed to print
kwargs (Any) – Keyword arguments passed to print
style – Ansi objects that styles the string.

Return type:

None

class adorable.ansi.Ansi[source]#

__call__(*args, **kwargs)[source]#

Styles a string.

Parameters:

args (Any) – Objects to
sep – String that separates args.
kwargs (Any) –

Return type:

The styled string.

__add__(other)[source]#

Combines two styles.

Parameters:: other (Ansi) –
Return type:: Ansi

__iadd__(other)[source]#

Combines this and another style.

Parameters:: other (Ansi) –
Return type:: Ansi

extend(*others)[source]#

Adds other ansi styles to this style.

Parameters:: others (Ansi) –
Return type:: Ansi

enable_str()[source]#

Returns escape sequence to enable the ansi style.

Return type:: str

enable(file=None)[source]#

Enables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

disable_str()[source]#

Returns escape sequence to disable the ansi style.

Return type:: str

disable(file=None)[source]#

Disables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

class adorable.ansi.AnsiNull[source]#

An implementation of an ansi object that contains no data.

Examples

A simplified example could look like this:

from typing import Optional
from adorable.ansi import Ansi, AnsiNull

def apply_ansi(text: str, ansi: Optional[Ansi] = None) -> str:
    if ansi is None:
        ansi = AnsiNull()

    return ansi(text)

__add__(other)#

Combines two styles.

Parameters:: other (Ansi) –
Return type:: Ansi

__call__(*args, **kwargs)#

Styles a string.

Parameters:

args (Any) – Objects to
sep – String that separates args.
kwargs (Any) –

Return type:

The styled string.

__iadd__(other)#

Combines this and another style.

Parameters:: other (Ansi) –
Return type:: Ansi

disable(file=None)#

Disables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

disable_str()#

Returns escape sequence to disable the ansi style.

Return type:: str

enable(file=None)#

Enables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

enable_str()#

Returns escape sequence to enable the ansi style.

Return type:: str

extend(*others)#

Adds other ansi styles to this style.

Parameters:: others (Ansi) –
Return type:: Ansi

style#

Common ansi styles.

class adorable.style.Style(enable, disable)[source]#

Parameters:

enable (Any) –
disable (Any) –

disable(file=None)#

Disables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

disable_str()#

Returns escape sequence to disable the ansi style.

Return type:: str

enable(file=None)#

Enables the ansi style.

Parameters:: file (Optional[TextIO]) – File to write to. Defaults to standard output.
Return type:: None

enable_str()#

Returns escape sequence to enable the ansi style.

Return type:: str

extend(*others)#

Adds other ansi styles to this style.

Parameters:: others (Ansi) –
Return type:: Ansi

adorable.style.BOLD = <adorable.style.Style object>#

Bold style

Parameters:

args (Any) –
kwargs (Any) –

Return type:

str

adorable.style.DIM = <adorable.style.Style object>#

Dim style

Parameters:

args (Any) –
kwargs (Any) –

Return type:

str

adorable.style.ITALIC = <adorable.style.Style object>#

Italic style

Parameters:

args (Any) –
kwargs (Any) –

Return type:

str

adorable.style.UNDERLINE = <adorable.style.Style object>#

Underline style

Parameters:

args (Any) –
kwargs (Any) –

Return type:

str

adorable.style.BLINK = <adorable.style.Style object>#

Blink style

Parameters:

args (Any) –
kwargs (Any) –

Return type:

str

adorable.style.INVERSE = <adorable.style.Style object>#

Inverse style

Parameters:

args (Any) –
kwargs (Any) –

Return type:

str

adorable.style.INVISIBLE = <adorable.style.Style object>#

Invisible style

Parameters:

args (Any) –
kwargs (Any) –

Return type:

str

adorable.style.STRIKETHROUGH = <adorable.style.Style object>#

Strike through style

Parameters:

args (Any) –
kwargs (Any) –

Return type:

str