ANSI String Formatter in Python for CLI Color and Style Formatting
Project description
ansi-string
ANSI String Formatter in Python for CLI Color and Style Formatting
Introduction
This code was originally written for greplica, but I felt it deserved its own, separate library.
The main goals for this project are:
- To provide a simple way to construct an object with ANSI formatting without requiring the developer to know how ANSI formatting works
- Provide a way to further format the object using format string
- Allow for concatenation of the object
Contribution
Feel free to open a bug report or make a merge request on github.
Installation
This project is uploaded to PyPI at https://pypi.org/project/ansi-string
To install, ensure you are connected to the internet and execute: python3 -m pip install ansi-string --upgrade
Examples
Refer to the test file for more examples on how to use the AnsiString class.
Usage
To begin, import AnsiString from the ansi_string module.
from ansi_string import en_tty_ansi, AnsiFormat, AnsiString
Enabling ANSI Formatting
Windows requires ANSI formatting to be enabled before it can be used. This can either be set in the environment or by simply calling the following before printing so that ANSI is enabled locally.
en_tty_ansi()
If this also needs to be enabled for stderr, stderr may also be passed to this method.
import sys
en_tty_ansi(sys.stderr)
For Windows, this returns True if the given IO is a TTY (i.e. not piped to a file) and enabling ANSI was successful. For all other operating systems, this will return True if and only if the given IO is a TTY; no other action is taken.
Construction
The AnsiString class contains the following __init__
method.
class AnsiString:
def __init__(self, s:str='', *setting_or_settings:Union[List[str], str, List[int], int, List[AnsiFormat], AnsiFormat]): ...
The first argument, s
, is a string to be formatted. The next 0 to N arguments are formatting directives that can be applied to the entire string. These arguments can be in the form of any of the following:
- A string color name for a formatting directive (i.e. any name of the AnsiFormat enum in lower or upper case)
- An AnsiFormat directive (ex:
AnsiFormat.BOLD
) - An
rgb(...)
function directive as a string (ex:"rgb(255, 255, 255)"
)rgb(...)
orfg_rgb(...)
to adjust text colorbg_rgb(...)
to adjust background colorul_rgb(...)
to enable underline and set the underline color- Value given may be either a 24-bit integer or 3 x 8-bit integers, separated by commas
- Each given value within the parenthesis is treated as hexadecimal if the value starts with "0x", otherwise it is treated as a decimal value
- A string containing known ANSI directives (ex:
"01;31"
for BOLD and FG_RED)- The string will normally be parsed into their individual values and verified unless the character "[" is the first character of the string (ex:
"[01;31"
)
- The string will normally be parsed into their individual values and verified unless the character "[" is the first character of the string (ex:
- A single ANSI directive as an integer
Examples:
# Set foreground to light_sea_green using string directive
# Set background to chocolate using AnsiFormat directive
# Underline in gray using ul_rgb() directive
# Enable italics using explicit string directive ("3")
# Enable bold using explicit integer directive (1)
s = AnsiString("This is an ANSI string", "light_sea_green", AnsiFormat.BG_CHOCOLATE, "ul_rgb(0x808080)", "3", 1)
print(s)
Concatenation
- The static method
AnsiString.join()
is provided to join together 0 to manystr
andAnsiString
values into a singleAnsiString
. - The
+
operator may be used to join anAnsiString
with anotherAnsiString
orstr
into a newAnsiString
- The
+
operator may not be used if the left-hand-side value is astr
and the right-hand-side values is anAnsiString
- The
- The
+=
operator may be used to append anAnsiString
orstr
to anAnsiString
Examples:
s = AnsiString.join("This ", AnsiString("string", AnsiFormat.BOLD))
s += AnsiString(" contains ") + AnsiString("multiple", AnsiFormat.BG_BLUE)
s += AnsiString(" color ", AnsiFormat.FG_ORANGE, AnsiFormat.ITALIC) + "settings accross different ranges"
print(s)
Formatting
The method AnsiString.apply_formatting()
is provided to append formatting to a previously constructed AnsiString
.
Example:
s = AnsiString("This string contains multiple color settings across different ranges")
s.apply_formatting(AnsiFormat.BOLD, 5, 11)
s.apply_formatting(AnsiFormat.BG_BLUE, 21, 29)
s.apply_formatting([AnsiFormat.FG_ORANGE, AnsiFormat.ITALIC], 21, 35)
print(s)
A format string may be used to format an AnsiString before printing. The format specification string must be in the format "[string_format][:ansi_format]"
where string_format
is the standard string format specifier and ansi_format
contains 0 or more ANSI directives separated by semicolons (;). The ANSI directives may be any of the same string values that can be passed to the AnsiString
constructor. If no string_format
is desired, then it can be set to an empty string.
Examples:
ansi_str = AnsiString("This is an ANSI string")
# Right justify with width of 100, formatted bold and red
print("{:>100:bold;red}".format(ansi_str))
# No justification settings, formatted bold and red
print("{::bold;red}".format(ansi_str))
# No justification settings, formatted bold and red
print("{::bold;rgb(255, 0, 0)}".format(ansi_str))
# No justification settings, formatted bold and red
print(f"{ansi_str::bold;red}")
# Format text, background, and underline with custom colors
fg_color = 0x8A2BE2
bg_colors = [100, 232, 170]
ul_colors = [0xFF, 0x63, 0x47]
print(f"{ansi_str::rgb({fg_color});bg_rgb({bg_colors});ul_rgb({ul_colors})}")
The method AnsiString.format_matching()
is provided to apply formatting to an AnsiString
based on a match specification.
Example:
s = AnsiString("Here is a strING that I will match formatting")
# This will make the word "formatting" cyan with a pink background
s.format_matching("[A-Za-z]+ing", "cyan", AnsiFormat.BG_PINK, regex=True, match_case=True)
print(s)
Other String Manipulation Methods
Many other methods that are found in the str
class such as replace()
are available in AnsiString
which manipulate the string while applying formatting where necessary.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ansi_string-1.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 57d93c18ddde36beb4f0577148a7bffa63e7fede34a7a131d9162bece9686c53 |
|
MD5 | 55b79beeb3380a57a06f1e3d7609dea0 |
|
BLAKE2b-256 | 617dcffa80e789b01ac0a7206384e132ac44721509f69e9e798f411e6147ba1c |