escape-colors 0.1.0__tar.gz

escape_colors-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.3
+Name: escape-colors
+Version: 0.1.0
+Summary: ANSI colors, nested text styles, and portable terminal printing
+Author: ellainng
+Author-email: ellainng <299958882+ellainng@users.noreply.github.com>
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/outside-labs/escape_colors
+Project-URL: Issues, https://github.com/outside-labs/escape_colors/issues
+Description-Content-Type: text/markdown
+
+# Escape Colors
+
+Readable ANSI colors and nested text styles for Python 3.14+, with no runtime
+dependencies.
+
+```python
+from escape_colors import ansi_print, blue, escape, escape_ansi, init_windows
+
+ansi_print("blue(hello world)")
+ansi_print("bold(blue(hello red(world) again))")
+
+# For direct print/f-string output on Windows:
+init_windows()
+print(escape_ansi("blue(hello red(world))"))
+print(f"{blue}hello world{escape}")
+```
+
+`escape_ansi` returns a string containing real ANSI SGR codes. `ansi_print` renders
+markup and chooses whether to use color for the destination stream. Redirected
+output is plain by default; use `color=True` to force ANSI sequences.
+
+## Install and develop
+
+Install from PyPI with Python 3.14 or later:
+
+```sh
+python -m pip install escape-colors
+```
+
+From this checkout:
+
+```sh
+uv sync --locked
+uv run python examples/basic.py
+python tools/review_source.py
+uv run python -m unittest discover -s tests -v
+uv build
+uv run python tools/verify_distribution.py
+```
+
+Install a built wheel into another Python environment with
+`uv pip install /path/to/escape_colors-0.1.0-py3-none-any.whl`.
+
+## Releases
+
+Publish a GitHub release with a tag matching the package version, such as
+`v0.1.0`. `.github/workflows/release.yaml` tests and verifies the distributions
+before publishing to PyPI through the `pypi` environment using Trusted Publishing.
+The workflow can also be run manually against an existing release tag.
+
+## Colors and styles
+
+The 16 named foreground colors are `black`, `red`, `green`, `yellow`, `blue`,
+`magenta`, `cyan`, and `white`, plus `bright_black`, `bright_red`, `bright_green`,
+`bright_yellow`, `bright_blue`, `bright_magenta`, `bright_cyan`, and `bright_white`.
+Add `bg_` for a background: `bg_blue`, `bg_bright_white`, and so on. Each name is
+both a markup expression and an importable ANSI string constant.
+
+```python
+from escape_colors import background, color, escape, escape_ansi
+
+text = escape_ansi("bright_blue(hello bg_white(world))")
+indexed = escape_ansi("15(white) 196(red) bg_232(dark background)")
+direct = f"{color(196)}red {background(232)}on dark{escape}"
+```
+
+Numeric markup selects a **256-color palette index**, not an SGR parameter:
+`15(text)` means `ESC[38;5;15m`, and `bg_15(text)` means `ESC[48;5;15m`.
+Indices 0–15 address the base palette, 16–231 the color cube, and 232–255 the
+grayscale ramp. The terminal controls the actual palette and appearance.
+`color(index)` and `background(index)` accept integers 0–255; booleans, floats,
+strings, and values outside that range are rejected.
+
+| Expression / constant | SGR | Effect |
+| --- | --- | --- |
+| `bold` | 1 | Bold/increased intensity |
+| `faint`, `dim` | 2 | Decreased intensity |
+| `italic`, `italics` | 3 | Italic |
+| `underline` | 4 | Underline |
+| `double_underline` | 21 | Double underline |
+| `blink` | 5 | Slow blink |
+| `reverse` | 7 | Swap foreground/background |
+| `conceal` | 8 | Conceal text |
+| `strike`, `strikethrough` | 9 | Strike through |
+| `overline` | 53 | Overline |
+| `font0` … `font9` | 10 … 19 | Default/alternative terminal font |
+| `escape`, `reset` | 0 | Reset constant for direct output |
+
+Use `bold(text)`, `underline(text)`, `italics(text)`, or combine them by nesting.
+When an inner expression closes, its enclosing styles are restored. A top-level
+expression ends with a reset. Font selection, italics, blink, and other attributes
+depend on terminal support. SGR does not select arbitrary installed typefaces or
+font sizes; older terminals may treat SGR 21 as an intensity change.
+`escape` and `reset` are constants, rather than markup expressions.
+
+## Grammar and literal text
+
+Markup is case-sensitive. A standalone ASCII name or decimal index immediately
+followed by `(` opens an expression. Whitespace between a name and `(` makes it
+ordinary text. Unknown names and ordinary parentheses remain in the output;
+recognized expressions inside unknown parentheses still work.
+
+```python
+from escape_colors import escape_ansi, strip_ansi
+
+assert strip_ansi(escape_ansi("blue(hello (world))")) == "hello (world)"
+assert escape_ansi("unknown(hello)") == "unknown(hello)"
+assert escape_ansi(r"blue\(literal\)") == "blue(literal)"
+assert strip_ansi(escape_ansi(r"blue(a\) b\( c\\d)")) == "a) b( c\\d"
+```
+
+`\(` and `\)` quote parentheses; `\\` quotes a backslash. Other backslashes,
+Unicode characters, line breaks, and tabs are preserved. Recognized unclosed
+expressions and invalid numeric color indices raise `ValueError` with a
+zero-based character position. Unmatched ordinary parentheses remain literal.
+The parser is iterative and does not evaluate Python or depend on its recursion
+limit. Existing raw SGR codes pass through; scope restoration tracks markup
+styles, rather than arbitrary control sequences embedded in the input.
+
+## Unicode, hex, and octal notation
+
+These three Python literals hold exactly the same one-character string:
+
+```python
+assert "\u001b" == "\x1b" == "\033" == chr(27)
+```
+
+The spelling is consumed by Python when it creates the string. No format warning
+is emitted, and normal terminal output is identical for all three choices.
+`ESCAPE_COLOR_FORMAT` controls the visible representation produced by
+`literal=True` or `format_ansi`, and defaults to `"unicode"`.
+
+```python
+import escape_colors
+
+escape_colors.ESCAPE_COLOR_FORMAT = "octal"
+assert escape_colors.escape_ansi("blue(hello)", literal=True) == r"\033[34mhello\033[0m"
+assert escape_colors.escape_ansi("blue(hello)", literal=True, format="hex") == r"\x1b[34mhello\x1b[0m"
+
+# The live runtime string always contains actual ESC characters.
+assert escape_colors.escape_ansi("blue(hello)") == "\u001b[34mhello\u001b[0m"
+escape_colors.ESCAPE_COLOR_FORMAT = "unicode"
+```
+
+Alternatively set the environment variable **before importing**:
+
+```sh
+ESCAPE_COLOR_FORMAT=octal uv run python examples/basic.py
+```
+
+On PowerShell, use `$env:ESCAPE_COLOR_FORMAT = 'octal'` before starting Python.
+Accepted values are exactly `unicode`, `hex`, and `octal`. A per-call `format`
+overrides the package setting. Assign `escape_colors.ESCAPE_COLOR_FORMAT` on the
+module; assigning a separately imported local name does not update the module.
+Invalid settings raise an error when rendering or serializing.
+
+```python
+from escape_colors import blue, escape, escape_ansi, format_ansi, normalize_ansi
+
+assert format_ansi(f"{blue}café{escape}", format="unicode") == r"\u001b[34mcafé\u001b[0m"
+assert normalize_ansi(r"\x1b[34mcafé\033[0m") == f"{blue}café{escape}"
+assert escape_ansi(r"\u001b[34mcafé\033[0m", decode=True) == f"{blue}café{escape}"
+```
+
+Textual notation decoding is opt-in. `normalize_ansi` and `decode=True` recognize
+only `\u001b`, `\x1b` (also with uppercase `B`), and `\033` followed by complete
+numeric SGR sequences. They do not decode general Python escapes, change Unicode,
+or decode a backslash-prefixed spelling. Literal output replaces ESC only: it is
+readable escape notation, not a complete quoted/escaped Python string literal.
+
+## Printing and Windows
+
+`ansi_print(*objects, sep=" ", end="\n", file=None, flush=False, color=None)`
+renders each object's string representation and supports the usual `print`
+arguments, including `sep=None` and `end=None`. It returns `None`.
+
+```python
+import io
+from escape_colors import ansi_print
+
+capture = io.StringIO()
+ansi_print("blue(hello)", "bold(world)", sep=" / ", end="!", file=capture)
+assert capture.getvalue() == "hello / world!"
+ansi_print("196(forced ANSI)", color=True)
+ansi_print("blue(plain text)", color=False)
+```
+
+- `color=None`: use color for a TTY unless `NO_COLOR` is nonempty or `TERM=dumb`.
+  Streams without a working `isatty()` get plain text. Windows also needs
+  successful VT initialization.
+- `color=True`: attempt Windows initialization and emit ANSI, even on redirection
+  or if initialization fails. This overrides environment color preferences.
+- `color=False`: remove rendered SGR codes, including existing SGR in objects,
+  separators, and endings.
+
+`ansi_print` initializes Windows automatically for the destination stream.
+`init_windows(file=None)` is available for direct `print`/f-string output and can
+also initialize stderr or another console stream. It preserves existing console
+mode bits and enables processed output and virtual-terminal processing. Repeated
+calls are safe. It returns `True` on Windows success and `False` on other systems,
+unsupported consoles, or redirected/invalid handles. Importing the module does
+not change console state. Obsolete Windows consoles without VT support are not
+emulated; automatic printing uses plain text there.
+
+`strip_ansi` removes numeric SGR sequences only. These APIs format text and do not
+sanitize arbitrary terminal control commands in untrusted input.
+
+## Verification and references
+
+`python tools/review_source.py` performs a static review using only Python's
+standard library. It checks first-party Python files for syntax errors and
+`SyntaxWarning`s, checks runtime imports against the standard library and local
+modules, and reports missing internal modules. It compiles source for validation
+without executing the inspected code. Use `--format json` for structured results
+or `--root /path/to/checkout` for another source tree. Findings exit with status 1;
+invalid invocation exits with status 2. Review covers ordinary import statements,
+including conditional imports; dynamic imports and imported attributes are
+outside these checks. Runtime behavior is covered by the test suite.
+
+CI tests Python 3.14 on Linux, macOS, and Windows, builds the wheel and source
+distribution, and runs the suite from freshly installed wheel artifacts outside
+the checkout. The verification script also rebuilds a wheel from the source
+archive. Tests cover nested restoration, every indexed color, notation, Unicode,
+printing, and Windows API behavior. Visual support still depends on the terminal.
+
+- [Python string escapes](https://docs.python.org/3.14/reference/lexical_analysis.html#escape-sequences)
+- [ANSI escape code overview](https://en.wikipedia.org/wiki/ANSI_escape_code)
+- [Xterm control sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html)
+- [Windows VT sequences](https://learn.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences)
+- [SetConsoleMode](https://learn.microsoft.com/en-us/windows/console/setconsolemode)

escape_colors-0.1.0/README.md

@@ -0,0 +1,230 @@
+# Escape Colors
+
+Readable ANSI colors and nested text styles for Python 3.14+, with no runtime
+dependencies.
+
+```python
+from escape_colors import ansi_print, blue, escape, escape_ansi, init_windows
+
+ansi_print("blue(hello world)")
+ansi_print("bold(blue(hello red(world) again))")
+
+# For direct print/f-string output on Windows:
+init_windows()
+print(escape_ansi("blue(hello red(world))"))
+print(f"{blue}hello world{escape}")
+```
+
+`escape_ansi` returns a string containing real ANSI SGR codes. `ansi_print` renders
+markup and chooses whether to use color for the destination stream. Redirected
+output is plain by default; use `color=True` to force ANSI sequences.
+
+## Install and develop
+
+Install from PyPI with Python 3.14 or later:
+
+```sh
+python -m pip install escape-colors
+```
+
+From this checkout:
+
+```sh
+uv sync --locked
+uv run python examples/basic.py
+python tools/review_source.py
+uv run python -m unittest discover -s tests -v
+uv build
+uv run python tools/verify_distribution.py
+```
+
+Install a built wheel into another Python environment with
+`uv pip install /path/to/escape_colors-0.1.0-py3-none-any.whl`.
+
+## Releases
+
+Publish a GitHub release with a tag matching the package version, such as
+`v0.1.0`. `.github/workflows/release.yaml` tests and verifies the distributions
+before publishing to PyPI through the `pypi` environment using Trusted Publishing.
+The workflow can also be run manually against an existing release tag.
+
+## Colors and styles
+
+The 16 named foreground colors are `black`, `red`, `green`, `yellow`, `blue`,
+`magenta`, `cyan`, and `white`, plus `bright_black`, `bright_red`, `bright_green`,
+`bright_yellow`, `bright_blue`, `bright_magenta`, `bright_cyan`, and `bright_white`.
+Add `bg_` for a background: `bg_blue`, `bg_bright_white`, and so on. Each name is
+both a markup expression and an importable ANSI string constant.
+
+```python
+from escape_colors import background, color, escape, escape_ansi
+
+text = escape_ansi("bright_blue(hello bg_white(world))")
+indexed = escape_ansi("15(white) 196(red) bg_232(dark background)")
+direct = f"{color(196)}red {background(232)}on dark{escape}"
+```
+
+Numeric markup selects a **256-color palette index**, not an SGR parameter:
+`15(text)` means `ESC[38;5;15m`, and `bg_15(text)` means `ESC[48;5;15m`.
+Indices 0–15 address the base palette, 16–231 the color cube, and 232–255 the
+grayscale ramp. The terminal controls the actual palette and appearance.
+`color(index)` and `background(index)` accept integers 0–255; booleans, floats,
+strings, and values outside that range are rejected.
+
+| Expression / constant | SGR | Effect |
+| --- | --- | --- |
+| `bold` | 1 | Bold/increased intensity |
+| `faint`, `dim` | 2 | Decreased intensity |
+| `italic`, `italics` | 3 | Italic |
+| `underline` | 4 | Underline |
+| `double_underline` | 21 | Double underline |
+| `blink` | 5 | Slow blink |
+| `reverse` | 7 | Swap foreground/background |
+| `conceal` | 8 | Conceal text |
+| `strike`, `strikethrough` | 9 | Strike through |
+| `overline` | 53 | Overline |
+| `font0` … `font9` | 10 … 19 | Default/alternative terminal font |
+| `escape`, `reset` | 0 | Reset constant for direct output |
+
+Use `bold(text)`, `underline(text)`, `italics(text)`, or combine them by nesting.
+When an inner expression closes, its enclosing styles are restored. A top-level
+expression ends with a reset. Font selection, italics, blink, and other attributes
+depend on terminal support. SGR does not select arbitrary installed typefaces or
+font sizes; older terminals may treat SGR 21 as an intensity change.
+`escape` and `reset` are constants, rather than markup expressions.
+
+## Grammar and literal text
+
+Markup is case-sensitive. A standalone ASCII name or decimal index immediately
+followed by `(` opens an expression. Whitespace between a name and `(` makes it
+ordinary text. Unknown names and ordinary parentheses remain in the output;
+recognized expressions inside unknown parentheses still work.
+
+```python
+from escape_colors import escape_ansi, strip_ansi
+
+assert strip_ansi(escape_ansi("blue(hello (world))")) == "hello (world)"
+assert escape_ansi("unknown(hello)") == "unknown(hello)"
+assert escape_ansi(r"blue\(literal\)") == "blue(literal)"
+assert strip_ansi(escape_ansi(r"blue(a\) b\( c\\d)")) == "a) b( c\\d"
+```
+
+`\(` and `\)` quote parentheses; `\\` quotes a backslash. Other backslashes,
+Unicode characters, line breaks, and tabs are preserved. Recognized unclosed
+expressions and invalid numeric color indices raise `ValueError` with a
+zero-based character position. Unmatched ordinary parentheses remain literal.
+The parser is iterative and does not evaluate Python or depend on its recursion
+limit. Existing raw SGR codes pass through; scope restoration tracks markup
+styles, rather than arbitrary control sequences embedded in the input.
+
+## Unicode, hex, and octal notation
+
+These three Python literals hold exactly the same one-character string:
+
+```python
+assert "\u001b" == "\x1b" == "\033" == chr(27)
+```
+
+The spelling is consumed by Python when it creates the string. No format warning
+is emitted, and normal terminal output is identical for all three choices.
+`ESCAPE_COLOR_FORMAT` controls the visible representation produced by
+`literal=True` or `format_ansi`, and defaults to `"unicode"`.
+
+```python
+import escape_colors
+
+escape_colors.ESCAPE_COLOR_FORMAT = "octal"
+assert escape_colors.escape_ansi("blue(hello)", literal=True) == r"\033[34mhello\033[0m"
+assert escape_colors.escape_ansi("blue(hello)", literal=True, format="hex") == r"\x1b[34mhello\x1b[0m"
+
+# The live runtime string always contains actual ESC characters.
+assert escape_colors.escape_ansi("blue(hello)") == "\u001b[34mhello\u001b[0m"
+escape_colors.ESCAPE_COLOR_FORMAT = "unicode"
+```
+
+Alternatively set the environment variable **before importing**:
+
+```sh
+ESCAPE_COLOR_FORMAT=octal uv run python examples/basic.py
+```
+
+On PowerShell, use `$env:ESCAPE_COLOR_FORMAT = 'octal'` before starting Python.
+Accepted values are exactly `unicode`, `hex`, and `octal`. A per-call `format`
+overrides the package setting. Assign `escape_colors.ESCAPE_COLOR_FORMAT` on the
+module; assigning a separately imported local name does not update the module.
+Invalid settings raise an error when rendering or serializing.
+
+```python
+from escape_colors import blue, escape, escape_ansi, format_ansi, normalize_ansi
+
+assert format_ansi(f"{blue}café{escape}", format="unicode") == r"\u001b[34mcafé\u001b[0m"
+assert normalize_ansi(r"\x1b[34mcafé\033[0m") == f"{blue}café{escape}"
+assert escape_ansi(r"\u001b[34mcafé\033[0m", decode=True) == f"{blue}café{escape}"
+```
+
+Textual notation decoding is opt-in. `normalize_ansi` and `decode=True` recognize
+only `\u001b`, `\x1b` (also with uppercase `B`), and `\033` followed by complete
+numeric SGR sequences. They do not decode general Python escapes, change Unicode,
+or decode a backslash-prefixed spelling. Literal output replaces ESC only: it is
+readable escape notation, not a complete quoted/escaped Python string literal.
+
+## Printing and Windows
+
+`ansi_print(*objects, sep=" ", end="\n", file=None, flush=False, color=None)`
+renders each object's string representation and supports the usual `print`
+arguments, including `sep=None` and `end=None`. It returns `None`.
+
+```python
+import io
+from escape_colors import ansi_print
+
+capture = io.StringIO()
+ansi_print("blue(hello)", "bold(world)", sep=" / ", end="!", file=capture)
+assert capture.getvalue() == "hello / world!"
+ansi_print("196(forced ANSI)", color=True)
+ansi_print("blue(plain text)", color=False)
+```
+
+- `color=None`: use color for a TTY unless `NO_COLOR` is nonempty or `TERM=dumb`.
+  Streams without a working `isatty()` get plain text. Windows also needs
+  successful VT initialization.
+- `color=True`: attempt Windows initialization and emit ANSI, even on redirection
+  or if initialization fails. This overrides environment color preferences.
+- `color=False`: remove rendered SGR codes, including existing SGR in objects,
+  separators, and endings.
+
+`ansi_print` initializes Windows automatically for the destination stream.
+`init_windows(file=None)` is available for direct `print`/f-string output and can
+also initialize stderr or another console stream. It preserves existing console
+mode bits and enables processed output and virtual-terminal processing. Repeated
+calls are safe. It returns `True` on Windows success and `False` on other systems,
+unsupported consoles, or redirected/invalid handles. Importing the module does
+not change console state. Obsolete Windows consoles without VT support are not
+emulated; automatic printing uses plain text there.
+
+`strip_ansi` removes numeric SGR sequences only. These APIs format text and do not
+sanitize arbitrary terminal control commands in untrusted input.
+
+## Verification and references
+
+`python tools/review_source.py` performs a static review using only Python's
+standard library. It checks first-party Python files for syntax errors and
+`SyntaxWarning`s, checks runtime imports against the standard library and local
+modules, and reports missing internal modules. It compiles source for validation
+without executing the inspected code. Use `--format json` for structured results
+or `--root /path/to/checkout` for another source tree. Findings exit with status 1;
+invalid invocation exits with status 2. Review covers ordinary import statements,
+including conditional imports; dynamic imports and imported attributes are
+outside these checks. Runtime behavior is covered by the test suite.
+
+CI tests Python 3.14 on Linux, macOS, and Windows, builds the wheel and source
+distribution, and runs the suite from freshly installed wheel artifacts outside
+the checkout. The verification script also rebuilds a wheel from the source
+archive. Tests cover nested restoration, every indexed color, notation, Unicode,
+printing, and Windows API behavior. Visual support still depends on the terminal.
+
+- [Python string escapes](https://docs.python.org/3.14/reference/lexical_analysis.html#escape-sequences)
+- [ANSI escape code overview](https://en.wikipedia.org/wiki/ANSI_escape_code)
+- [Xterm control sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html)
+- [Windows VT sequences](https://learn.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences)
+- [SetConsoleMode](https://learn.microsoft.com/en-us/windows/console/setconsolemode)

escape_colors-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "escape-colors"
+version = "0.1.0"
+description = "ANSI colors, nested text styles, and portable terminal printing"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = []
+
+[[project.authors]]
+name = "ellainng"
+email = "299958882+ellainng@users.noreply.github.com"
+
+[project.urls]
+Repository = "https://github.com/outside-labs/escape_colors"
+Issues = "https://github.com/outside-labs/escape_colors/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"

escape_colors-0.1.0/pyproject.toml.orig

@@ -0,0 +1,18 @@
+[project]
+name = "escape-colors"
+version = "0.1.0"
+description = "ANSI colors, nested text styles, and portable terminal printing"
+readme = "README.md"
+authors = [
+    { name = "ellainng", email = "299958882+ellainng@users.noreply.github.com" }
+]
+requires-python = ">=3.14"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/outside-labs/escape_colors"
+Issues = "https://github.com/outside-labs/escape_colors/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.19,<0.13.0"]
+build-backend = "uv_build"

escape_colors-0.1.0/src/escape_colors/__init__.py

@@ -0,0 +1,84 @@
+"""ANSI colors and formatting without runtime dependencies."""
+
+import os as _os
+import sys as _sys
+from typing import TextIO as _TextIO
+
+from ._codes import NAMED_CODES as _NAMED_CODES
+from ._codes import RESET as escape
+from ._codes import background, color
+from ._notation import normalize_ansi, strip_ansi
+from ._notation import require_text as _require_text
+from ._notation import serialize as _serialize
+from ._notation import validate_format as _validate_format
+from ._parser import render as _render
+from ._terminal import color_enabled as _color_enabled
+from ._terminal import init_windows
+
+ESCAPE_COLOR_FORMAT = _os.environ.get("ESCAPE_COLOR_FORMAT", "unicode")
+reset = escape
+
+# Named constants are ordinary strings, suitable for direct f-string use.
+globals().update(_NAMED_CODES)
+
+
+def format_ansi(text: str, *, format: str | None = None) -> str:
+    """Write ESC using unicode, hex, or octal notation, preserving other text."""
+    return _serialize(text, ESCAPE_COLOR_FORMAT if format is None else format)
+
+
+def escape_ansi(
+    text: str,
+    *,
+    format: str | None = None,
+    literal: bool = False,
+    decode: bool = False,
+) -> str:
+    """Render nested styles; optionally decode or serialize textual ESC notation."""
+    _require_text(text)
+    selected = _validate_format(ESCAPE_COLOR_FORMAT if format is None else format)
+    if not isinstance(literal, bool) or not isinstance(decode, bool):
+        raise TypeError("literal and decode must be bools")
+    rendered = _render(normalize_ansi(text) if decode else text)
+    return _serialize(rendered, selected) if literal else rendered
+
+
+def ansi_print(
+    *objects: object,
+    sep: str | None = " ",
+    end: str | None = "\n",
+    file: _TextIO | None = None,
+    flush: bool = False,
+    color: bool | None = None,
+) -> None:
+    """Print nested markup, choosing color automatically unless overridden."""
+    if sep is not None and not isinstance(sep, str):
+        raise TypeError("sep must be None or a string")
+    if end is not None and not isinstance(end, str):
+        raise TypeError("end must be None or a string")
+    stream = _sys.stdout if file is None else file
+    enabled = _color_enabled(stream, color)
+    if stream is None:
+        return
+    rendered = [escape_ansi(str(obj)) for obj in objects]
+    if not enabled:
+        rendered = [strip_ansi(text) for text in rendered]
+        sep = strip_ansi(sep) if sep is not None else None
+        end = strip_ansi(end) if end is not None else None
+    print(*rendered, sep=sep, end=end, file=stream, flush=flush)
+
+
+__all__ = [
+    "ESCAPE_COLOR_FORMAT",
+    "ansi_print",
+    "background",
+    "color",
+    "escape",
+    "escape_ansi",
+    "format_ansi",
+    "init_windows",
+    "normalize_ansi",
+    "reset",
+    "strip_ansi",
+    *_NAMED_CODES,
+]

escape_colors-0.1.0/src/escape_colors/_codes.py

@@ -0,0 +1,55 @@
+"""Select Graphic Rendition codes and indexed palette helpers."""
+
+ESC = "\u001b"
+RESET = f"{ESC}[0m"
+
+
+def _sgr(*parameters: int) -> str:
+    return f"{ESC}[{';'.join(map(str, parameters))}m"
+
+
+def _palette_index(index: int) -> int:
+    if isinstance(index, bool) or not isinstance(index, int):
+        raise TypeError("color index must be an integer")
+    if not 0 <= index <= 255:
+        raise ValueError("color index must be between 0 and 255")
+    return index
+
+
+def color(index: int) -> str:
+    """Return the foreground SGR sequence for palette index 0 through 255."""
+    return _sgr(38, 5, _palette_index(index))
+
+
+def background(index: int) -> str:
+    """Return the background SGR sequence for palette index 0 through 255."""
+    return _sgr(48, 5, _palette_index(index))
+
+
+COLOR_NAMES = ("black", "red", "green", "yellow", "blue", "magenta", "cyan", "white")
+NAMED_CODES = {}
+for _offset, _name in enumerate(COLOR_NAMES):
+    NAMED_CODES[_name] = _sgr(30 + _offset)
+    NAMED_CODES[f"bright_{_name}"] = _sgr(90 + _offset)
+    NAMED_CODES[f"bg_{_name}"] = _sgr(40 + _offset)
+    NAMED_CODES[f"bg_bright_{_name}"] = _sgr(100 + _offset)
+
+for _name, _parameter in {
+    "bold": 1,
+    "faint": 2,
+    "dim": 2,
+    "italic": 3,
+    "italics": 3,
+    "underline": 4,
+    "double_underline": 21,
+    "blink": 5,
+    "reverse": 7,
+    "conceal": 8,
+    "strike": 9,
+    "strikethrough": 9,
+    "overline": 53,
+}.items():
+    NAMED_CODES[_name] = _sgr(_parameter)
+
+for _font in range(10):
+    NAMED_CODES[f"font{_font}"] = _sgr(10 + _font)

escape_colors-0.1.0/src/escape_colors/_notation.py

@@ -0,0 +1,39 @@
+"""Represent ESC without decoding unrelated user text."""
+
+import re
+
+from ._codes import ESC
+
+SPELLINGS = {"unicode": r"\u001b", "hex": r"\x1b", "octal": r"\033"}
+SGR_PATTERN = re.compile(r"\u001b\[[0-9;]*m")
+_LITERAL_ESC = re.compile(r"(?<!\\)(?:\\u001[bB]|\\x1[bB]|\\033)(?=\[[0-9;]*m)")
+
+
+def validate_format(format: str) -> str:
+    if not isinstance(format, str):
+        raise TypeError("escape format must be a string")
+    if format not in SPELLINGS:
+        raise ValueError("escape format must be 'unicode', 'hex', or 'octal'")
+    return format
+
+
+def require_text(text: str) -> None:
+    if not isinstance(text, str):
+        raise TypeError("text must be a string")
+
+
+def serialize(text: str, format: str) -> str:
+    require_text(text)
+    return text.replace(ESC, SPELLINGS[validate_format(format)])
+
+
+def normalize_ansi(text: str) -> str:
+    """Decode textual ESC spellings only before complete numeric SGR codes."""
+    require_text(text)
+    return _LITERAL_ESC.sub(lambda match: ESC, text)
+
+
+def strip_ansi(text: str) -> str:
+    """Remove numeric SGR codes; leave other control sequences untouched."""
+    require_text(text)
+    return SGR_PATTERN.sub("", text)

escape_colors-0.1.0/src/escape_colors/_parser.py

@@ -0,0 +1,73 @@
+"""An iterative parser for nested style expressions."""
+
+import re
+
+from ._codes import NAMED_CODES, RESET, background, color
+
+_OPEN = re.compile(r"(bg_-?[0-9]+|[A-Za-z_][A-Za-z_0-9]*|-?[0-9]+)\(")
+_INDEX = re.compile(r"-?[0-9]+\Z")
+
+
+def _indexed_code(token: str, position: int, *, bg: bool = False) -> str:
+    # Avoid Python's large integer string limit and unnecessary conversion work.
+    digits = token.lstrip("0") or "0"
+    if token.startswith("-") or len(digits) > 3 or int(digits) > 255:
+        raise ValueError(f"color index must be between 0 and 255 at position {position}")
+    return background(int(digits)) if bg else color(int(digits))
+
+
+def _style_code(token: str, position: int) -> str | None:
+    if token in NAMED_CODES:
+        return NAMED_CODES[token]
+    if _INDEX.fullmatch(token):
+        return _indexed_code(token, position)
+    if token.startswith("bg_") and _INDEX.fullmatch(token[3:]):
+        return _indexed_code(token[3:], position, bg=True)
+    return None
+
+
+def render(text: str) -> str:
+    output = []
+    frames: list[tuple[str | None, int]] = []
+    active: list[str] = []
+    position = 0
+
+    while position < len(text):
+        char = text[position]
+        if char == "\\" and position + 1 < len(text) and text[position + 1] in "()\\":
+            output.append(text[position + 1])
+            position += 2
+            continue
+
+        standalone = position == 0 or not (text[position - 1].isalnum() or text[position - 1] == "_")
+        opening = _OPEN.match(text, position) if standalone else None
+        if opening:
+            code = _style_code(opening[1], position)
+            frames.append((code, position))
+            if code is None:
+                output.append(opening[0])
+            else:
+                output.append(code)
+                active.append(code)
+            position = opening.end()
+            continue
+
+        if char == "(":
+            frames.append((None, position))
+            output.append(char)
+        elif char == ")" and frames:
+            code, _ = frames.pop()
+            if code is None:
+                output.append(char)
+            else:
+                active.pop()
+                output.append(RESET)
+                output.extend(active)
+        else:
+            output.append(char)
+        position += 1
+
+    for code, start in frames:
+        if code is not None:
+            raise ValueError(f"unclosed style expression at position {start}")
+    return "".join(output)

escape_colors-0.1.0/src/escape_colors/_terminal.py

@@ -0,0 +1,59 @@
+"""Destination-specific terminal detection and Windows VT initialization."""
+
+import ctypes
+import os
+import sys
+from typing import TextIO
+
+_PROCESSED_OUTPUT = 0x0001
+_VIRTUAL_TERMINAL_PROCESSING = 0x0004
+
+
+def init_windows(file: TextIO | None = None) -> bool:
+    """Enable Windows VT output on a stream; return False when unavailable."""
+    if os.name != "nt":
+        return False
+    stream = sys.stdout if file is None else file
+    try:
+        import msvcrt
+        from ctypes import wintypes
+
+        handle = msvcrt.get_osfhandle(stream.fileno())
+        if handle in (-1, 0):
+            return False
+        kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+        get_mode = kernel.GetConsoleMode
+        get_mode.argtypes = [wintypes.HANDLE, ctypes.POINTER(wintypes.DWORD)]
+        get_mode.restype = wintypes.BOOL
+        set_mode = kernel.SetConsoleMode
+        set_mode.argtypes = [wintypes.HANDLE, wintypes.DWORD]
+        set_mode.restype = wintypes.BOOL
+
+        mode = wintypes.DWORD()
+        if not get_mode(handle, ctypes.byref(mode)):
+            return False
+        desired = mode.value | _PROCESSED_OUTPUT | _VIRTUAL_TERMINAL_PROCESSING
+        if desired == mode.value:
+            return True
+        return bool(set_mode(handle, desired))
+    except (AttributeError, ImportError, OSError, TypeError, ValueError, OverflowError):
+        return False
+
+
+def color_enabled(stream: TextIO, color: bool | None) -> bool:
+    if color is not None and not isinstance(color, bool):
+        raise TypeError("color must be True, False, or None")
+    if color is False:
+        return False
+    if color is True:
+        if os.name == "nt":
+            init_windows(stream)
+        return True
+    if os.environ.get("NO_COLOR") or os.environ.get("TERM") == "dumb":
+        return False
+    try:
+        if not stream.isatty():
+            return False
+    except (AttributeError, OSError, ValueError):
+        return False
+    return init_windows(stream) if os.name == "nt" else True