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.
You can either download wheels from the Releases tab or install it from PyPI:
pip install antsiThe 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 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.
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 (\).
Important
Putting any character(s) between the style specifier and content is explicitly disallowed.
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.
Tip
When nesting styled markup, the styles of the parent markup will also be applied unless explicitly overridden. However, there is currently no way to remove text decorations from the children of nested markup.
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:
| Style Specifier | Meaning |
|---|---|
[fg:red] |
Red foreground |
[bg:blue] |
Blue background |
[deco:bold] |
Bold text |
[deco:bold,blink] |
Bold and blinking |
[fg:red;bg:white] |
Red foreground and white background |
[bg:blue;fg:white;deco:bold] |
White foreground, blue background, and bold |
[deco:bold,underline;fg:cyan] |
Cyan foreground, bold, and underlined |
[fg:red;bg:white;fg:blue] |
Blue foreground and white background (last specifier wins) |
Important
If any tags are repeated in the specifier, the value of the last tag takes precedence. This means that tags which can
accept multiple values (i.e. deco) are not merged.
As show above, there are currently three specifiers that are allowed: fg (
foreground), bg (background), and deco (decoration).
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-.
Tip
Colors will appear differently depending on the terminal being used.
| Color | Standard Code | Bright Code |
|---|---|---|
| Default | default |
N/A |
| Black | black |
bright-black |
| Red | red |
bright-red |
| Green | green |
bright-green |
| Yellow | yellow |
bright-yellow |
| Blue | blue |
bright-blue |
| Magenta | magenta |
bright-magenta |
| Cyan | cyan |
bright-cyan |
| White | white |
bright-white |
Format: bg:<color>
Changes the color of the text background. It accepts the same colors as fg.
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.
Tip
Support for decorations may differ between terminals.
| Decoration | Code(s) |
|---|---|
| Bold | bold |
| Dim | dim, faint |
| Italic | italic |
| Underline | underline |
| Fast Blink | fast-blink, blink-fast |
| Slow Blink | slow-blink, blink-slow |
| Invert | invert, reverse |
| Hide | hide, conceal |
| Strikethrough | strike-through, strikethrough |
There are a handful of control characters that must be escaped to include them anywhere in your text. This includes text outside styled markup.
| Character | Sequence |
|---|---|
\ |
\\ |
[ |
\[ |
] |
\] |
( |
\( |
) |
\) |
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 (\).
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!
Licensed under the MIT license (or http://opensource.org/licenses/MIT).