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
Usage
To begin, import AnsiString from the ansi_string module.
from ansi_string import en_tty_ansi, AnsiFormat, AnsiString
Construction
The AnsiString class contains the following __init__
method. 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.BOOL
) - An rgb() function directive as a string (ex:
"rgb(255, 255, 255)"
)- rgb() or fg_rgb() to adjust text color
- bg_rgb() to adjust background color
- ul_rgb() to enable underline and set the underline color
- Value given may be either a 24-bit value or 3 x 8-bit values, separated by commas
- Each given value within the parenthesis is treated as a hexadecimal value if it starts with "0x", otherwise it will be 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 and verified unless the character "[" is the first character of the string
- A single ANSI directive as an integer
class AnsiString:
def __init__(self, s:str='', *setting_or_settings:Union[List[str], str, List[int], int, List[AnsiFormat], AnsiFormat]): ...
Concatenation
- The static method
AnsiString.join()
is provided to join together 0 to manystr
ansAnsiString
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
Formatting
The method AnsiString.apply_formatting()
is provided to append formatting to a previously constructed AnsiString
.
A format string may be used to format an AnsiString before printing (ex: "{:>10:bold;red}".format(ansi_str)
). 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 (ex: "{::bold;red}".format(ansi_str)
). This can also be set as a F-String (ex: f"{ansi_str::bold;red}"
).
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.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 07f7d1b0626406f1cf37e838a68089d0ccb04a0522d898c4579aefdeb76e2dbf |
|
MD5 | 7cb66e15fa337efdce953a3e317f2559 |
|
BLAKE2b-256 | 21c756f2c5f259ad9b77015644b5d8c7fc96583aebc597d6c37472a1472fb793 |