Chalky Package¶

Simple ANSI terminal text coloring.

Compose multiple of the included chalk instances to produce a style that can be applied directly to strings. Compose multiple chalk instances together with & and apply it to a string using |:

from chalky import sty, fg
print(sty.bold & fg.green | "Hello, World!")

Chalk¶

Contains the base chalk class that is used to group some style and colors.

class chalky.chalk.Chalk(style=<factory>, foreground=None, background=None)[source]¶

Describes the style and color to use for styling some printable text.

Chalk can be composed using & and can be applied to strings with |. You can create your own instance of chalk by setting your desired Style and Color when creating a new instance.

Examples

Creating custom instances of chalk looks like the following:

>>> my_chalk = Chalk(
...     style={Style.BOLD, Style.UNDERLINE},
...     foreground=Color.RED,
... )

Composing two chalk instances can be done through either using & or +:

>>> bold_chalk = Chalk(style={Style.BOLD})
>>> error_chalk = bold_chalk & Chalk(foreground=Color.RED)

Using chalk instances to style strings can be done using either | or +:

>>> error_chalk | "Hello, World!"
Hello, World!

Important

When composing two chalk instances together, the chalk being applied to the base chalk instance will override the foreground and background colors. This means that if you apply a new chalk with a different foreground color it will override the starting foreground color:

>>> red = Chalk(foreground=Color.RED)
>>> blue = Chalk(foreground=Color.BLUE)
>>> assert blue == (red & blue)

Parameters

style (Set[Style]) –
foreground (Union[Color, TrueColor, None]) –
background (Union[Color, TrueColor, None]) –

__add__(other: chalky.chalk.Chalk) → chalky.chalk.Chalk [source]¶

__add__(other: str) → str

Handle applying chalk instances to things.

Parameters: other (Union[Chalk, str]) – Either another chalk instance or a string.
Returns: The combined chalk instances or a styled string.
Return type: Union[Chalk, str]

__and__(other)[source]¶

Create a new chalk instance from the composition of two chalk.

Parameters: other (Chalk) – Another chalk to combine with the current chalk.
Returns: The newly created chalk instance.
Return type: Chalk

__call__(value)[source]¶

Handle applying chalk instances to strings.

Parameters: value (str) – The string to apply the current styles to.
Returns: The newly styled string.
Return type: str

__or__(value)[source]¶

Style some given string with the current chalk instance.

Tip

If a non-string value is provided, we will attempt to get the most appropriate string from the value by simply calling str(value). So if you are passing in an object, make sure to use an appropriate __str__ or __repr__.

Parameters: value (Any) – The value to apply the current chalk styles to.
Returns: The newly styled string.
Return type: str

property reverse¶

Color reverse of the current chalk instance.

Returns: The revsered chalk instance
Return type: Chalk

Style¶

Contains the available styles we can use for chalk.

class chalky.style.Style(value)[source]¶

Enum of the available styles that can be applied to some printable text.

RESET¶: Resets all styles and colors to the original terminal style.

BOLD¶: Emphasizes the text by increasing the font weight.

DIM¶: Dims the text color and sometimes decreases font weight.

ITALIC¶: Italicize the text.

UNDERLINE¶: Underlines the text (works in most modern terminals).

SLOW_BLINK¶: Flash the text slowly (doesn’t work in most modern terminals).

RAPID_BLINK¶: Flash the text very quickly (doesn’t work in most modern terminals).

REVERSED¶: Reversed the current style of the terminal for the text.

CONCEAL¶: Hide the text.

STRIKETHROUGH¶: Draw a line through the text (works in most modern terminals).

NORMAL¶: Normalizes the text for the current terminal.

Color¶

Contains the available tools to define the colors that can be used for chalk.

class chalky.color.Color(value)[source]¶

Enum of the available colors that can be used to color some printable text.

BLACK¶

RED¶

GREEN¶

YELLOW¶

BLUE¶

MAGENTA¶

CYAN¶

WHITE¶

BRIGHT_BLACK¶: Otherwise known as gray.

BRIGHT_RED¶

BRIGHT_GREEN¶

BRIGHT_YELLOW¶

BRIGHT_BLUE¶

BRIGHT_MAGENTA¶

BRIGHT_CYAN¶

BRIGHT_WHITE¶: Otherwise known as actual white.

class chalky.color.TrueColor(red, green, blue)[source]¶

Describes a true color that can be displayed on compatible terminals.

Parameters

red (int) – The value of red (0-255).
green (int) – The value of green (0-255).
blue (int) – The value of blue (0-255).

__hash__()[source]¶

Generate a comparable hash for the current instance.

Returns: The appropriate hash of the current instance.
Return type: int

classmethod from_hex(color)[source]¶

Create an instance from a given hex color string.

Parameters: color (str) – The hex color string of the color to create.
Raises: ValueError – If the given hex color string is not a length of 3 or 6
Returns: The created instance.
Return type: TrueColor

to_bytes()[source]¶

Convert the current color to a tuple of RGB bytes.

Returns: The corresponding bytes of the current instance (red, green, blue).
Return type: Tuple[bytes, bytes, bytes]

Chain¶

Contains the chain class that can be used to quickly produce styles and colors.

class chalky.chain.Chain(_chalk=<factory>, _background=False)[source]¶

Quickly produce a chain of styles and colors that can be applied to a string.

Parameters: chalk (Chalk) – The container chalk instance that contains the current chain style.

Examples

Chaining styles together should be fairly straightforward:

>>> from chalk import chain
>>> print(chain.bold.blue | "Bold blue text")
>>> print(chain.black.bg.green.italic | "Italic black text on green background")

Once a Chain instance is applied to a string, the styles are consumed and the chain instance is reset.

Parameters

_chalk (Chalk) –
_background (bool) –

__add__(other: Union[chalky.chalk.Chalk, chalky.chain.Chain]) → chalky.chain.Chain [source]¶

__add__(other: str) → str

Handle applying chain instances to things.

Parameters: other (Union[Chalk, Chain, str]) – Either a chalk instance, a chain instance, or a string.
Returns: The updated chain or the applied string.
Return type: Union[Chain, str]

__and__(other)[source]¶

Compose the chain with another chain or a chalk instance.

Parameters: other (Union[Chalk, Chain]) – Another Chain or Chalk instance to compose with the current chain.
Returns: The newly updated chain.
Return type: Chain

__call__(value)[source]¶

Handle applying a chain to a strings.

Parameters: value (str) – The string to apply the current chain to.
Returns: The newly styled string.
Return type: str

__or__(value)[source]¶

Style some given string with the current chain.

Parameters: value (str) – THe string to apply the current chain to.
Returns: The newly styled string.
Return type: str

property bg¶

Following colors will be applied as the background color.

Return type: Chain

property chalk¶

Extract the currently built chalk instance.

Important

Consuming this property will reset the current chain’s styles. We are assuming that if you need the Chalk, you have finished constructing it through the chaining syntax.

Returns: The current chalk instance from the chained styles and colors.
Return type: Chalk

property fg¶

Following colors will be applied as the foreground color.

Return type: Chain

hex(color)[source]¶

Add a truecolor chalk from a hex string.

Parameters: color (str) – The hex color string (#ffffff)
Returns: The newly updated chain.
Return type: Chain

rgb(red, green, blue)[source]¶

Add a truecolor chalk from an RGB tuple.

Parameters

red (int) – The intensity of red (0-255).
green (int) – The intensity of green (0-255).
blue (int) – The intensity of blue (0-255).

Returns

The newly updated chain.

Return type

Chain

Shortcuts¶

Contains shortcuts for quickly utilizing chalk.

Simply combine colors and styles using & or + to produce a style that can used to format a string with | or +.

Examples

>>> from chalky import bg, fg, sty
>>> my_style = bg.red & fg.black & sty.bold
>>> print(my_style | "I'm bold black on red text")
I'm bold black on red text

Many chalk styles can be combined together:

Examples

>>> from chalky import sty
>>> my_style = sty.bold & sty.underline
>>> print(my_style | "I'm bold and underlined")
I'm bold and underlined

The last applied foreground or background color will be used when applied to a string:

Examples

>>> from chalky import bg
>>> my_style = bg.red & bg.blue  # BLUE will override RED when styling the string
>>> print(my_style | "My background is BLUE")
My background is BLUE

chalky.shortcuts.hex(hexcolor, background=False)[source]¶

Generate a new truecolor chalk from a HEX color (#ffffff) string.

Parameters

hexcolor (str) – The hex color string.
background (bool, optional) – If True will generate the new chalk to be applied as background color. Defaults to False.

Returns

The new chalk instance.

Return type

Chalk

chalky.shortcuts.rgb(red, green, blue, background=False)[source]¶

Generate a new truecolor chalk from an RGB tuple.

Parameters

red (int) – The intensity of red (0-255).
green (int) – The intensity of green (0-255).
blue (int) – The intensity of blue (0-255).
background (bool, optional) – If True will generate the new chalk to be applied as a background color. Defaults to False.

Returns

The new chalk instance.

Return type

Chalk

Interface¶

Contains the actual implementation of interacting with a type of terminal buffer.

chalky.interface.get_interface(io=None)[source]¶

Get the appropriate interface to interact with some terminal buffer.

Examples

Get the default interface for interacting with the terminal buffer. This defaults to using sys.stdout

>>> from chalky.interface import get_interface
>>> interface = get_interface()

To get an interface using a different text io buffer, pass it in:

>>> import sys
>>> stderr_interface = get_interface(sys.stderr)

Parameters: io (Optional[TextIO], optional) – The io to build an interface for. Defaults to sys.stdout.
Returns: The created interface for the given io buffer.
Return type: BaseInterface

Constants¶

Contains package constants that modify the global functions of the package.

Utilize the configure() method to quickly and easily disable all future application of Chalk to strings.

>>> from chalky import configure, fg
>>> configure(disable=True)
>>> print(fg.green | "I'm NOT green text")

chalky.constants.configure(disable=False)[source]¶

Configure the global state of the chalky module.

Parameters: disable (bool, optional) – If True, will disable all future application of colors and styles. Defaults to False.

chalky.constants.is_disabled()[source]¶

Callable to evaluate the disabled conditional.

Returns: True if chalky is disabled, otherwise False.
Return type: bool

Helpers¶

Contains some miscellaneous helpers for the rest of the package.

chalky.helpers.int_to_bytes(value)[source]¶

Convert a given number to its representation in bytes.

Parameters: value (int) – The value to convert.
Returns: The representation of the given number in bytes.
Return type: bytes

chalky.helpers.supports_posix()[source]¶

Check if the current machine supports basic posix.

Returns: True if the current machine is MacOSX or Linux.
Return type: bool

chalky.helpers.supports_truecolor()[source]¶

Attempt to check if the current terminal supports truecolor.

Returns: True if the current terminal supports truecolor, otherwise False.
Return type: bool