pyansistring 0.2.0

A library for string color styling using ANSI escape sequences.

pyansistring

About The Project

pyansistring is a library for string color styling using ANSI escape sequences. The base class inherits from Python's str. You can split, join, or slice the string while preserving the styling.

Features

• Preservation of the str methods.
• Support for 4-, 8-, and 24-bit (True Color) color modes.
• Per-word coloring.
• Left, right, and center alignment without problems caused by string length.
• Support for multiple SGR (Select Graphic Rendition) parameters.
• Support for both the traditional ";" and the modern ":" SGR parameter separators.
• Automated coloring functionality, e.g., rainbow text.

For a more comprehensive list of what's been done so far, see the TODO section.

Inspired by rich and colorama Python libraries.

Getting Started

Prerequisites

• Python 3.11 or higher
  • Linux: https://docs.python.org/3/using/unix.html
  • Windows: https://docs.python.org/3/using/windows.html
  • macOS: https://docs.python.org/3/using/mac.html
• Git (for local installation)
  • Linux: https://git-scm.com/downloads/linux
  • Windows: https://git-scm.com/downloads/win
  • macOS: https://git-scm.com/downloads/mac

Installation

You can install the package via pip:

pip install pyansistring # or pip3 install pyansistring
pip install pyansistring[svg] # for SVG conversion support

Or locally via git:

1. Clone the repository

   git clone https://github.com/l1asis/pyansistring
   

2. Navigate to the cloned directory

   cd pyansistring
   

3. Change git remote url to avoid accidental pushes to base project

   git remote set-url origin github_username/repo_name
   # Verify the changes
   git remote -v
   

4. (Optional) Create and activate a virtual environment

   python -m venv venv
   # On Windows
   .\venv\Scripts\activate
   # On Unix or MacOS
   source venv/bin/activate
   

5. Install the package

   pip install .
   pip install .[svg] # for SVG conversion support
   

(back to top)

Usage

Import the necessary classes and initialize an ANSIString instance:

from pyansistring.pyansistring import ANSIString
from pyansistring.constants import SGR, Foreground, Background, UnderlineMode

Unstyled plain string:

text = ANSIString("Hello, World!")
print(text)

Style the whole string:

print(
    ANSIString("Hello, World!")
        .fg_4b(Foreground.YELLOW)
        .bg_4b(Background.BLUE)
        .fm(SGR.BOLD)
)

Style by slice (indices are [start, end, step]):

print(
    ANSIString("Hello, World!")
        .fg_4b(Foreground.YELLOW, (0, 5), (7, 12))  # "Hello" and "World"
        .bg_4b(Background.BLUE, (7, 12))            # "World"
        .fm(SGR.BOLD, (7, 12))                      # "World"
)

Style by words:

print(
    ANSIString("Hello, World!")
        .fg_4b_w(Foreground.YELLOW, "Hello", "World")
        .bg_4b_w(Background.BLUE, "World")
        .fm_w(SGR.BOLD, "Hello", "World")
)

SGR parameters like bold and underline:

print(
    ANSIString("Hello, World!")
        .fm(SGR.BOLD)
        .fm(SGR.UNDERLINE)
)

4-bit examples (doesn't exist for underline):

print(
    ANSIString("Hello, World!")
        .fg_4b(Foreground.YELLOW)
        .bg_4b(Background.BLUE)
)

8-bit examples:

print(
    ANSIString("Hello, World!")
        .fg_8b(11)  # Bright Yellow
        .bg_8b(4)   # Blue
        .ul_8b(74)  # Muted Sky Blue
)

24-bit (True Color) example:

print(
    ANSIString("Hello, World!")
        .fg_24b(255, 255, 0)    # Bright Yellow
        .bg_24b(0, 0, 238)      # Blue
        .ul_24b(135, 175, 215)  # Light Steel Blue
)

Underline modes (not "styles" to avoid confusion with other styling):

print(
    ANSIString("Hello, World!")
        .bg_24b(255, 255, 255)  # White
        .ul_24b(255, 0, 0)      # Red
        .fm(UnderlineMode.DOUBLE)
)

Lengths and plain text:

styled = ANSIString("Hello, World!").fg_4b(Foreground.MAGENTA)

print(len(styled) == len("Hello, World!"))
# True (logical length ignores ANSI)
print(len(styled.styled_text) == len("Hello, World!"))
# False (includes ANSI codes)
print(styled.actual_length == len("Hello, World!"))
# False (includes ANSI codes)
print(styled.plain)
# "Hello, World!"

ANSIString conversion to SVG text:

from fontTools.ttLib import TTFont

styled = ANSIString("Hello, World!").fg_4b(Foreground.MAGENTA)
styled.to_svg(
    font=TTFont("path/to/font.ttf"),
    font_size_px=16,
    output_file="hello_world.svg"
)

ANSIString conversion to SVG path (for better compatibility when font is not guaranteed to be present):

from fontTools.ttLib import TTFont

styled = ANSIString("Hello, World!").fg_4b(Foreground.MAGENTA)
styled.to_svg(
    font=TTFont("path/to/font.ttf"),
    font_size_px=16,
    convert_text_to_path=True,
    output_file="hello_world_path.svg"
)

[!NOTE] Please note that when convert_text_to_path is set to True, the characters will be converted into vector shapes, which can help ensure that the appearance of the text remains consistent across different platforms and devices, even if the specified font is not available. However, this also means that the text will no longer be selectable or searchable in the SVG file, as it will be treated as graphical elements rather than text. Neither will it be 100% identical to how it looks in the terminal or being rendered as text in the SVG.

[!WARNING] Supported SGR parameters for SVG conversion include:

• Foreground and background colors (4-bit, 8-bit, and 24-bit)
• Underline colors with all modes (single, double, curly, dotted, dashed)
• Bold and italic font styles Unsupported SGR parameters (e.g., strikethrough, inverse, etc.) will be ignored during SVG conversion.

Rainbow text as a separate function:

print(
    ANSIString("Hello, World! This is rainbow text!")
        .rainbow(fg=True)
)

Colored text using multicolor functionality:

print(
    ANSIString("Hello, World! This is multicolor text!")
        .multicolor((
            "r=0:|g=0:|b=255:   $ "  # Start with blue
            "b>0:repeat(auto)   # "  # Decrease blue
            "r>255:repeat(auto) | "  # Increase green and combine with...
            "g>255:repeat(auto)   "  # Increase red
            "                   &*"  # Cycle & Start without apply flags
        ))
)

For more examples, see the examples directory.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

P.S. I would love to see your arts made with pyansistring in the arts.py file, with proper attribution, of course!

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Acknowledgements

• Othneil Drew's Best README Template

(back to top)