Getting Started

Welcome to Chalky!
This page should hopefully provide you with enough information to get you started using Chalky.

Installation and Setup

Installing the package should be super duper simple as we utilize Python’s setuptools.

$ poetry add chalky
$ # or if you're old school...
$ pip install chalky

Or you can build and install the package from the git repo.

$ git clone https://github.com/stephen-bunn/chalky.git
$ cd ./chalky
$ python setup.py install

Usage

Now with Chalky installed we can start applying some styles to text. Styles and colors are applied to text through a single Chalk instance that contains the desired format for styling a string. This instance is reusable and does not require the user to manually define when reset escape sequences need to be sent.

Creating Chalk

The Chalk class is simply a container storing the basic styles and colors that can be applied to a string. The stored rules try as best as possible to be agnostic to the interfaces the styles are going to be built with.

Chalk instances can contain:

Constructing instances is pretty straightforward:

1
2
3
4
5
6
7
8
9
from chalky import Chalk
from chalky.style import Style
from chalky.color import Color

my_chalk = Chalk(
   styles={Style.BOLD, Style.ITALIC},
   foreground=Color.GREEN,
   background=Color.WHITE
)

Applying Chalk to Strings

Now that you have a Chalk instance to work with, you can apply it to a string using either the | or + operators. Or you can simply call the chalk instance with the desired string.

print(my_chalk | "Hello, World!")
print(my_chalk + "Hello, World!")
print(my_chalk("Hello, World!"))

When applying the chalk instance to a string, it will build the appropriate ANSI escape sequences to style the string and automatically add the reset sequence to the end of the string.

Composing Chalk

These Chalk instances can be composed together using the & or + operators.

1
2
3
4
5
6
from chalky import Chalk
from chalky.style import Style
from chalky.color import Color

my_chalk = Chalk(style={Style.BOLD}) & Chalk(foreground=Color.RED)
my_chalk = Chalk(style={Style.BOLD}) + Chalk(foreground=Color.RED)

The styles provided in the instance being applied will override any existing styles on the starting instance.

1
2
my_chalk = Chalk(foreground=Color.RED) & Chalk(foreground=Color.BLUE)
assert my_chalk.foreground == Color.BLUE

Chaining Chalk

Chaining together multiple styles and colors is another typical interface that people like to use for text coloring. We provide a Chain class that produces a Chalk for quick and easy production:

1
2
3
4
from chalky import chain

print(chain.green.bold | "I'm bold green text")
print(chain.italic.white.bg.blue | "I'm italic white text on blue background")

Using Chain classes should be pretty similar to how you use Chalk instances. You can compose them with other chains or chalks and apply them to strings just like chalk instances. They ultimately just provide a different interface for constructing the chalk instance and quickly consuming it.

Chalk Shortcuts

Since it can be pretty darn tedious to create instances of Chalk all the time, I threw in some pre-initialized chalk in the shortcuts module.

From this module we export fg (foreground), bg (background), and sty (style) namespaces to make it easy and quick to compose custom chalk instances:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from chalky import fg, bg, sty

debug = sty.dim & fg.white
success = fg.green & sty.bold
error = fg.red & sty.bold
critical = bg.red & fg.white


print(debug | "This is a DEBUG message")
print(success | "This is a SUCCESS message")
print(error | "This is a ERROR message")
print(critical | "This is a CRITICAL message")

You can quickly produce truecolor’s as well (if your terminal supports them) by using the hex() or rgb() functions to quickly produce TrueColor instances:

1
2
3
4
5
6
7
from chalky import hex, rgb

custom_rgb = rgb(102, 102, 255) & sty.underline
custom_hex = hex("#90ff9c", background=True) & fg.black & sty.bold

print(custom_rgb | "Potential link text")
print(custom_hex | "Black on green text")