Antsi

A quick and user-friendly way to style your text using ANSI codes.

Built around a delightfully simple markup language, there's no messing about with codes or style resets. All the ANSI code conversion, handling of overlapping styles, and terminal support is automatically handled for you.

Usage

You can either download wheels from the Releases tab or install it from PyPI:

pip install antsi

The function you'll most likely care about is colorize. Colorize is responsible for converting any styled markup within the provided source to ANSI escape sequences. The styled markup syntax can be found below.

You can use the following code to test that it's working as expected.

import antsi

print(antsi.colorize("Hello [fg:green](there!)"))
print(antsi.colorize("It looks like [fg:black;bg:white;deco:bold,blink](antsi) is working!"))

If you're planning on doing any string manipulation or templating with styled markup, you'll want to escape the substituted text to prevent any unexpected colors or errors. The escape function ensures that any control characters are properly escaped.

Styled Markup

Styled markup is a decidedly simple language that is make for ease of use and readability. There's no unruly sequences of numbers and characters that you'll forget what they mean in a week, just words and a couple memorable abbreviations.

Styled markup can appear anywhere within a piece of text. It can even be nested infinitely! The only requirements are that it start with a style specifier and is followed by some content. It will always be in the form:

[ <style specifier(s)> ]( <content> )

For example, Hello [fg:green](there), user! which will make only "there" be colored green. Everything else will be the default text color.

Content

The content is what the style specifier applies to. It always immediately follows a style specifier and must be wrapped in parentheses. Any whitespace within the content will be emitted as-is unless escaped using a backslash (\).

The content can contain any characters, and it can even contain other styled markup! If you want to use any square brackets or parentheses in the content, they must be escaped.

Style Specifiers

Style specifiers are surrounded by square brackets ([]) and contain the directives for applying style to the content immediately following them. They are essentially a list of key-value pairs, where the key denotes the type of style.

The styles within a specifier will ignore whitespace to facilitate readability. However, whitespace cannot exist in the middle of a key or value (i.e. bl ue will cause an error). The benefit of this is that [ fg: red ; bg: blue ] will be parsed the same as [fg:red;bg:blue], so use whatever style you prefer.

Examples:

As show above, there are currently three specifiers that are allowed: fg ( foreground), bg (background), and deco (decoration).

Foreground color (fg)

Format: fg:<color>

Changes the color of the text itself. Currently only the standard color pallet is implemented, providing 8 colors with a standard and a bright variant. The bright variant can be chosen by prefixing the color with bright-.

Background color (bg)

Format: bg:<color>

Changes the color of the text background. It accepts the same colors as fg.

Text decoration (deco)

Format: deco:<decoration>,[<decoration>...]

Applies additional text decorations like bolding, dimming, blinking, etc. Unlike the foreground and background, multiple text decorations can be applied at the same time using a comma-separated list.

Escape Sequences

There are a handful of control characters that must be escaped to include them anywhere in your text. This includes text outside styled markup.

Beyond these characters, you can also escape any whitespace (i.e. spaces, tabs, newlines, and carriage returns) to make writing multi-line text easier. All you need to do is prefix it with a backslash (\).

Contributing

Any and all contributions are welcome! Some ideas if you can't think of anything:

• Improve the documentation
• Add some functionality that might be missing
• Report (or even fix) any bugs

If you don't have time to contribute yourself but still wish to support the project, sponsorship would be greatly appreciated!

License

Licensed under the MIT license (or http://opensource.org/licenses/MIT).