clitint 0.1.0__tar.gz

clitint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christos Synodinos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clitint-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: clitint
+Version: 0.1.0
+Summary: Coloured terminal text with no dependencies, plain wherever it isn't read on a terminal.
+License-Expression: MIT
+Keywords: terminal,colour,color,ansi,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# clitint
+
+Coloured terminal text for Python 3.13+, with no dependencies. Text is coloured only when someone is reading it
+on a terminal: redirect the output to a file, a pipe or a CI log and it comes out plain.
+
+```python
+from clitint import formatter
+
+print(formatter("error:", "bold_red"), "file not found")
+print(formatter("warning", "underline_black_highlight_yellow"))
+```
+
+## Install
+
+```bash
+pip install clitint
+```
+
+## Specs
+
+A spec is a set of styles joined by `_`, in any order: `"red"`, `"bold_red"`, `"red_bold"`, `"italic_white_highlight_blue"`.
+
+| Kind | Names |
+|---|---|
+| Attributes | `bold`, `dim`, `italic`, `underline` |
+| Colours | `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `grey`, `orange` |
+| Backgrounds | `highlight_` followed by a colour: `highlight_blue` |
+
+
+You can also combine: bold_highlight_blue, italic_red, underline_green, etc.
+
+An unknown name, two colours or two backgrounds raise a `ValueError` that names the problem. `formatter` takes any
+object and writes its `str`. Each spec is worked out once and remembered.
+
+## When text is coloured
+
+`formatter` decides at every call, in this order:
+
+1. what the program chose: `turn_colours_off()` or `turn_colours_on()` (`let_the_environment_decide()` undoes it);
+2. `CLITINT_COLOURS_OFF=1`, `NO_COLOR` or `ANSI_COLORS_DISABLED`: plain;
+3. `FORCE_COLOR`: coloured;
+4. `TERM=dumb`: plain;
+5. otherwise, coloured only when **both** stdout and stderr are terminals.
+
+The last rule is there because a string doesn't know where it is going. An error message might be printed,
+logged or raised. `2> errors.log` with stdout on a terminal still gives a plain message, so no escape codes end up
+in the log.
+
+`colours_on()` tells you the answer now.
+
+## Other tools
+
+```python
+from clitint import strip_colours, escapes, one_decision, coloured
+
+strip_colours(formatter("x", "red"))        # 'x': every ANSI style sequence removed (for tests and logs)
+
+with one_decision():                        # one message: decide once, not at every formatter call
+    line = formatter("a", "red") + " " + formatter("b", "blue")
+
+red, reset = escapes("red")                 # the raw sequences, for a hot f-string
+text = f"{red}x{reset}" if coloured() else "x"
+```
+
+## Licence
+
+MIT

clitint-0.1.0/README.md

@@ -0,0 +1,67 @@
+# clitint
+
+Coloured terminal text for Python 3.13+, with no dependencies. Text is coloured only when someone is reading it
+on a terminal: redirect the output to a file, a pipe or a CI log and it comes out plain.
+
+```python
+from clitint import formatter
+
+print(formatter("error:", "bold_red"), "file not found")
+print(formatter("warning", "underline_black_highlight_yellow"))
+```
+
+## Install
+
+```bash
+pip install clitint
+```
+
+## Specs
+
+A spec is a set of styles joined by `_`, in any order: `"red"`, `"bold_red"`, `"red_bold"`, `"italic_white_highlight_blue"`.
+
+| Kind | Names |
+|---|---|
+| Attributes | `bold`, `dim`, `italic`, `underline` |
+| Colours | `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `grey`, `orange` |
+| Backgrounds | `highlight_` followed by a colour: `highlight_blue` |
+
+
+You can also combine: bold_highlight_blue, italic_red, underline_green, etc.
+
+An unknown name, two colours or two backgrounds raise a `ValueError` that names the problem. `formatter` takes any
+object and writes its `str`. Each spec is worked out once and remembered.
+
+## When text is coloured
+
+`formatter` decides at every call, in this order:
+
+1. what the program chose: `turn_colours_off()` or `turn_colours_on()` (`let_the_environment_decide()` undoes it);
+2. `CLITINT_COLOURS_OFF=1`, `NO_COLOR` or `ANSI_COLORS_DISABLED`: plain;
+3. `FORCE_COLOR`: coloured;
+4. `TERM=dumb`: plain;
+5. otherwise, coloured only when **both** stdout and stderr are terminals.
+
+The last rule is there because a string doesn't know where it is going. An error message might be printed,
+logged or raised. `2> errors.log` with stdout on a terminal still gives a plain message, so no escape codes end up
+in the log.
+
+`colours_on()` tells you the answer now.
+
+## Other tools
+
+```python
+from clitint import strip_colours, escapes, one_decision, coloured
+
+strip_colours(formatter("x", "red"))        # 'x': every ANSI style sequence removed (for tests and logs)
+
+with one_decision():                        # one message: decide once, not at every formatter call
+    line = formatter("a", "red") + " " + formatter("b", "blue")
+
+red, reset = escapes("red")                 # the raw sequences, for a hot f-string
+text = f"{red}x{reset}" if coloured() else "x"
+```
+
+## Licence
+
+MIT

clitint-0.1.0/clitint/__init__.py

@@ -0,0 +1,42 @@
+"""clitint: coloured terminal text with no dependencies, plain wherever it isn't read on a terminal."""
+from ._tint import (
+    formatter,
+    strip_colours,
+    colours_on,
+    turn_colours_off,
+    turn_colours_on,
+    let_the_environment_decide,
+    coloured,
+    decide,
+    decision,
+    release,
+    add_off_switch,
+    escapes,
+    one_decision,
+    ATTRIBUTES,
+    COLOURS,
+    BACKGROUNDS,
+    RESET,
+    )
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "formatter",
+    "strip_colours",
+    "colours_on",
+    "turn_colours_off",
+    "turn_colours_on",
+    "let_the_environment_decide",
+    "one_decision",
+    "coloured",
+    "decide",
+    "decision",
+    "release",
+    "add_off_switch",
+    "escapes",
+    "ATTRIBUTES",
+    "COLOURS",
+    "BACKGROUNDS",
+    "RESET",
+    ]

clitint-0.1.0/clitint/_tint.py

@@ -0,0 +1,291 @@
+from typing import Any
+import re
+import os
+import sys
+
+
+#* The variables that decide whether text is coloured (see ``colours_on``), in the order they are asked.
+COLOURS_OFF = "CLITINT_COLOURS_OFF"
+NO_COLOR = "NO_COLOR"
+ANSI_COLORS_DISABLED = "ANSI_COLORS_DISABLED"
+FORCE_COLOR = "FORCE_COLOR"
+TERM = "TERM"
+
+#* The attributes a spec may name, and the sequence that switches each on. Written in front of a colour.
+ATTRIBUTES: dict[str, str] = {
+    "bold": "\x1b[1m", "dim": "\x1b[2m", "italic": "\x1b[3m", "underline": "\x1b[4m",
+    }
+#* The colours, as the text's colour. ``highlight_<colour>`` is the same colour as its background.
+#* The sequences are the ones termcolor writes (``orange`` is its (255, 165, 0)), so text made
+#* with termcolor and with clitint is the same, byte for byte.
+COLOURS: dict[str, str] = {
+    "black": "\x1b[30m", "red": "\x1b[31m", "green": "\x1b[32m", "yellow": "\x1b[33m", "blue": "\x1b[34m",
+    "magenta": "\x1b[35m", "cyan": "\x1b[36m", "white": "\x1b[37m", "grey": "\x1b[90m",
+    "orange": "\x1b[38;2;255;165;0m",
+    }
+BACKGROUNDS: dict[str, str] = {
+    "black": "\x1b[40m", "red": "\x1b[41m", "green": "\x1b[42m", "yellow": "\x1b[43m", "blue": "\x1b[44m",
+    "magenta": "\x1b[45m", "cyan": "\x1b[46m", "white": "\x1b[47m", "grey": "\x1b[100m",
+    "orange": "\x1b[48;2;255;165;0m",
+    }
+RESET = "\x1b[0m"
+
+
+#* What ``turn_colours_off`` or ``turn_colours_on`` chose, or None: the environment and the streams decide.
+_CHOSEN: bool | None = None
+
+
+def turn_colours_off() -> None:
+    """Plain text from now on, whatever the environment and the streams say (as ``CLITINT_COLOURS_OFF=1``)."""
+    global _CHOSEN
+    _CHOSEN = False
+
+
+def turn_colours_on() -> None:
+    """Coloured text from now on, also where it goes to no terminal (as ``FORCE_COLOR``)."""
+    global _CHOSEN
+    _CHOSEN = True
+
+
+def let_the_environment_decide() -> None:
+    """Undo ``turn_colours_off`` / ``turn_colours_on``: the environment and the streams decide again."""
+    global _CHOSEN
+    _CHOSEN = None
+
+
+def add_off_switch(name: str) -> None:
+    """
+    Make ``name=1`` switch colours off too, as ``CLITINT_COLOURS_OFF=1`` does: for a library
+    that offers its users a variable of its own (``add_off_switch("MYLIB_COLOURS_OFF")``). Only
+    the value ``"1"`` counts. Asked with the other off switches, before ``FORCE_COLOR``.
+    """
+    global _OFF, _K_OFFS
+    if not isinstance(name, str) or not name:
+        raise TypeError(f"an off switch is the name of an environment variable, not {name!r}")
+    if name in _OFF:
+        return
+    _OFF = (*_OFF, name)
+    if _FAST:
+        _K_OFFS = (*_K_OFFS, _encode_key(name))
+
+
+def colours_on() -> bool:
+    """
+    Whether text is coloured now.
+
+    A string doesn't know where it will end up: an uncaught error goes to stderr, ``print`` to
+    stdout, a logger to a file. So colours are used only when both standard streams are
+    terminals. Redirect either one (``2> errors.log``, ``| less``, a CI job) and text is plain:
+    no escape sequence lands in a file.
+
+    ``turn_colours_off`` and ``turn_colours_on`` decide before anything else. Then the
+    environment, in this order: ``CLITINT_COLOURS_OFF=1`` (and each ``add_off_switch``), ``NO_COLOR`` and
+    ``ANSI_COLORS_DISABLED`` switch colours off, ``FORCE_COLOR`` switches them on whatever the
+    streams are, and ``TERM=dumb`` switches them off. Read at every call, so a change takes
+    effect at once.
+    """
+    if _CHOSEN is not None:                             # turn_colours_off / turn_colours_on: the program has said
+        return _CHOSEN
+    env = os.environ
+    #* Read from ``os.environ`` as it is now: a program may have put another mapping in its place.
+    data = getattr(env, "_data", None) if _FAST else None
+    if type(data) is not dict:
+        if NO_COLOR in env or ANSI_COLORS_DISABLED in env:
+            return False
+        for name in _OFF:
+            if env.get(name) == "1":
+                return False
+        if FORCE_COLOR in env:
+            return True
+        if env.get(TERM) == "dumb":
+            return False
+        return _both_terminals()
+    if _K_NO_COLOR in data or _K_ANSI in data:
+        return False
+    for key in _K_OFFS:
+        if data.get(key) == _V_ONE:
+            return False
+    if _K_FORCE in data:
+        return True
+    if data.get(_K_TERM) == _V_DUMB:
+        return False
+    return _both_terminals()
+
+
+#* ``os.environ`` encodes the name at every lookup and decodes the value: five of them took 1 µs.
+#* Below it is the dictionary it keeps, which is asked directly, with the names and the two
+#* values encoded once, the way ``os.environ`` does it on this platform. It is the same data:
+#* what ``os.environ`` is given lands there. Where a Python has no such dictionary (it is a
+#* CPython detail), ``os.environ`` is asked as usual.
+#* The variables that switch colours off with the value "1": clitint's own, then each ``add_off_switch``.
+_OFF: tuple[str, ...] = (COLOURS_OFF,)
+_K_OFFS: tuple[Any, ...] = ()
+_FAST = False
+try:
+    _encode_key, _encode_value = os.environ.encodekey, os.environ.encodevalue
+    _K_OFFS = (_encode_key(COLOURS_OFF),)
+    _K_NO_COLOR, _K_ANSI, _K_FORCE, _K_TERM = (
+        _encode_key(name) for name in (NO_COLOR, ANSI_COLORS_DISABLED, FORCE_COLOR, TERM)
+        )
+    _V_ONE, _V_DUMB = _encode_value("1"), _encode_value("dumb")
+    _FAST = type(os.environ._data) is dict                                          # type: ignore[attr-defined]
+except Exception:
+    _FAST = False
+
+
+#* (sys.stdout, sys.stderr, whether both are terminals): asked again only when a stream was replaced.
+_streams: tuple[Any, Any, bool] = (None, None, False)
+
+
+def _both_terminals() -> bool:
+    global _streams
+    out, err = sys.stdout, sys.stderr
+    if _streams[0] is out and _streams[1] is err:
+        return _streams[2]
+    answer = _is_terminal(out) and _is_terminal(err)
+    _streams = (out, err, answer)
+    return answer
+
+
+def _is_terminal(stream: Any) -> bool:
+    try:
+        return bool(stream.isatty())
+    except Exception:                   # no stream at all (pythonw), a closed one, an object without isatty
+        return False
+
+
+#* While one message is built: the answer of ``colours_on`` for all of it (None: ask each time).
+_decided: bool | None = None
+
+
+def decide() -> bool:
+    """
+    Ask ``colours_on`` once and keep the answer: every ``formatter`` and ``coloured`` call gives
+    it until ``release()``. For a message built of many coloured words (the environment is slow
+    to read). The functions are the fast form of ``one_decision``; mind to call ``release``.
+    """
+    global _decided
+    _decided = answer = colours_on()
+    return answer
+
+
+def decision() -> bool | None:
+    """The answer ``decide`` kept, or None where nothing has been decided."""
+    return _decided
+
+
+def release() -> None:
+    """Forget the answer ``decide`` kept: each call asks ``colours_on`` again."""
+    global _decided
+    _decided = None
+
+
+class one_decision:
+    """
+    ``with one_decision():`` around the building of one message asks once whether it is
+    coloured, where every ``formatter`` call in it would ask again. Inside another one it keeps
+    the outer answer, and leaves it in place. Not for threads that build messages at once: the
+    decision is the module's.
+    """
+    __slots__ = ("_outer",)
+
+    def __enter__(self) -> bool:
+        global _decided
+        self._outer = _decided
+        if _decided is None:
+            _decided = colours_on()
+        return _decided
+
+    def __exit__(self, *_: Any) -> None:
+        global _decided
+        _decided = self._outer
+        return
+
+
+def coloured() -> bool:
+    """Whether the message being built is coloured: the one decision made for it, or ``colours_on()``."""
+    return colours_on() if _decided is None else _decided
+
+
+def _escapes(spec: str) -> tuple[str, str]:
+    """
+    What is written in front of and behind a text for ``spec``: the attributes' sequences, then
+    the colour's, then the background's, and the sequence that switches everything off.
+    """
+    attributes: list[str] = []
+    colour = background = ""
+    names = spec.split("_")
+    i = 0
+    while i < len(names):
+        name = names[i]
+        if name == "highlight" and i + 1 < len(names) and names[i + 1] in BACKGROUNDS:
+            if background:
+                raise ValueError(f"two backgrounds in {spec!r}")
+            background = BACKGROUNDS[names[i + 1]]
+            i += 2
+            continue
+        if name in ATTRIBUTES:
+            if ATTRIBUTES[name] not in attributes:
+                attributes.append(ATTRIBUTES[name])
+        elif name in COLOURS:
+            if colour and colour != COLOURS[name]:
+                raise ValueError(f"two colours in {spec!r}: name one, and 'highlight_<colour>' for a background")
+            colour = COLOURS[name]
+        else:
+            raise ValueError(
+                f"unknown style {name!r} in {spec!r}: a spec is made of {', '.join(ATTRIBUTES)}, "
+                f"{', '.join(COLOURS)} and highlight_<colour>, joined by '_'"
+                )
+        i += 1
+    order = list(ATTRIBUTES.values())
+    attributes.sort(key = order.index)
+    return "".join(attributes) + colour + background, RESET
+
+
+#* spec -> what ``_escapes`` answered.
+_ESCAPES: dict[str, tuple[str, str]] = {}
+
+
+def formatter(text: Any, spec: str) -> str:
+    """
+    ``text`` in the styles ``spec`` names, or as it is when colours are off (see ``colours_on``).
+
+    Args:
+        text (Any): The text, or any object: its ``str`` is what is written.
+        spec (str): Styles joined by ``_``, in any order: ``"bold_red"``, ``"cyan"``,
+            ``"underline_white_highlight_blue"``. Attributes: ``bold``, ``dim``, ``italic``,
+            ``underline``. Colours: ``black``, ``red``, ``green``, ``yellow``, ``blue``,
+            ``magenta``, ``cyan``, ``white``, ``grey``, ``orange``; ``highlight_<colour>`` is a
+            background. Anything else is a ``ValueError``.
+
+    Returns:
+        str: The text between the escape sequences of its styles, or the plain text.
+
+    Example:
+        >>> formatter("hello", "bold_red")
+        '\\x1b[1m\\x1b[31mhello\\x1b[0m'
+    """
+    if not (colours_on() if _decided is None else _decided):
+        return str(text)
+    escapes = _ESCAPES.get(spec)
+    if escapes is None:
+        escapes = _ESCAPES[spec] = _escapes(spec)
+    return escapes[0] + str(text) + escapes[1]
+
+
+def escapes(*specs: str) -> tuple[str, ...]:
+    """
+    What is written in front of and behind a text for each of ``specs``, in one flat tuple:
+    ``before, after, before, after ...``. For a message put together in one f-string, with the
+    sequences as constants: cheaper than a ``formatter`` call per coloured word. Always the
+    sequences, whatever ``colours_on`` says: the caller decides (``coloured()``).
+    """
+    return tuple([part for spec in specs for part in _escapes(spec)])
+
+
+_ANSI = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def strip_colours(text: str) -> str:
+    """``text`` without its colours: every ANSI style sequence taken out, the words left as they are."""
+    return _ANSI.sub("", text)

clitint-0.1.0/clitint.egg-info/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: clitint
+Version: 0.1.0
+Summary: Coloured terminal text with no dependencies, plain wherever it isn't read on a terminal.
+License-Expression: MIT
+Keywords: terminal,colour,color,ansi,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# clitint
+
+Coloured terminal text for Python 3.13+, with no dependencies. Text is coloured only when someone is reading it
+on a terminal: redirect the output to a file, a pipe or a CI log and it comes out plain.
+
+```python
+from clitint import formatter
+
+print(formatter("error:", "bold_red"), "file not found")
+print(formatter("warning", "underline_black_highlight_yellow"))
+```
+
+## Install
+
+```bash
+pip install clitint
+```
+
+## Specs
+
+A spec is a set of styles joined by `_`, in any order: `"red"`, `"bold_red"`, `"red_bold"`, `"italic_white_highlight_blue"`.
+
+| Kind | Names |
+|---|---|
+| Attributes | `bold`, `dim`, `italic`, `underline` |
+| Colours | `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `grey`, `orange` |
+| Backgrounds | `highlight_` followed by a colour: `highlight_blue` |
+
+
+You can also combine: bold_highlight_blue, italic_red, underline_green, etc.
+
+An unknown name, two colours or two backgrounds raise a `ValueError` that names the problem. `formatter` takes any
+object and writes its `str`. Each spec is worked out once and remembered.
+
+## When text is coloured
+
+`formatter` decides at every call, in this order:
+
+1. what the program chose: `turn_colours_off()` or `turn_colours_on()` (`let_the_environment_decide()` undoes it);
+2. `CLITINT_COLOURS_OFF=1`, `NO_COLOR` or `ANSI_COLORS_DISABLED`: plain;
+3. `FORCE_COLOR`: coloured;
+4. `TERM=dumb`: plain;
+5. otherwise, coloured only when **both** stdout and stderr are terminals.
+
+The last rule is there because a string doesn't know where it is going. An error message might be printed,
+logged or raised. `2> errors.log` with stdout on a terminal still gives a plain message, so no escape codes end up
+in the log.
+
+`colours_on()` tells you the answer now.
+
+## Other tools
+
+```python
+from clitint import strip_colours, escapes, one_decision, coloured
+
+strip_colours(formatter("x", "red"))        # 'x': every ANSI style sequence removed (for tests and logs)
+
+with one_decision():                        # one message: decide once, not at every formatter call
+    line = formatter("a", "red") + " " + formatter("b", "blue")
+
+red, reset = escapes("red")                 # the raw sequences, for a hot f-string
+text = f"{red}x{reset}" if coloured() else "x"
+```
+
+## Licence
+
+MIT

clitint-0.1.0/clitint.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+clitint/__init__.py
+clitint/_tint.py
+clitint/py.typed
+clitint.egg-info/PKG-INFO
+clitint.egg-info/SOURCES.txt
+clitint.egg-info/dependency_links.txt
+clitint.egg-info/requires.txt
+clitint.egg-info/top_level.txt
+tests/test_tint.py

clitint-0.1.0/clitint.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clitint-0.1.0/clitint.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest
+mypy
+build
+twine

clitint-0.1.0/clitint.egg-info/top_level.txt

@@ -0,0 +1 @@
+clitint

clitint-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clitint"
+dynamic = ["version"]
+description = "Coloured terminal text with no dependencies, plain wherever it isn't read on a terminal."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+keywords = ["terminal", "colour", "color", "ansi", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Terminals",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "mypy", "build", "twine"]
+
+[tool.setuptools.dynamic]
+version = { attr = "clitint.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["clitint*"]
+
+[tool.setuptools.package-data]
+clitint = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

clitint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clitint-0.1.0/tests/test_tint.py

@@ -0,0 +1,318 @@
+from clitint import formatter, strip_colours, escapes, one_decision, coloured
+from typing import Any
+import clitint
+import clitint._tint as tint
+import subprocess
+import sys
+import os
+import pytest
+
+
+@pytest.fixture(autouse = True)
+def colours_wanted(monkeypatch):
+    """
+    Most tests are about what a spec is turned into, so they need colours on: whatever the shell
+    exports, and although pytest's captured output is no terminal.
+    """
+    for name in ("CLITINT_COLOURS_OFF", "NO_COLOR", "ANSI_COLORS_DISABLED"):
+        monkeypatch.delenv(name, raising = False)
+    monkeypatch.setenv("FORCE_COLOR", "1")
+    monkeypatch.setattr(tint, "_CHOSEN", None)
+    monkeypatch.setattr(tint, "_decided", None)
+
+
+#* The escape sequences, written out here a second time: what a terminal is to be sent.
+CODES = {"bold": "\x1b[1m", "dim": "\x1b[2m", "italic": "\x1b[3m", "underline": "\x1b[4m",
+         "black": "\x1b[30m", "red": "\x1b[31m", "green": "\x1b[32m", "yellow": "\x1b[33m", "blue": "\x1b[34m",
+         "magenta": "\x1b[35m", "cyan": "\x1b[36m", "white": "\x1b[37m", "grey": "\x1b[90m",
+         "orange": "\x1b[38;2;255;165;0m"}
+BACK = {"black": "\x1b[40m", "red": "\x1b[41m", "green": "\x1b[42m", "yellow": "\x1b[43m", "blue": "\x1b[44m",
+        "magenta": "\x1b[45m", "cyan": "\x1b[46m", "white": "\x1b[47m", "grey": "\x1b[100m",
+        "orange": "\x1b[48;2;255;165;0m"}
+COLOURS = ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "grey", "orange"]
+ATTRS = ["bold", "dim", "italic", "underline"]
+
+
+def styled(text: str, color: Any = None, attrs: Any = (), on: Any = None) -> str:
+    """``text`` as ``formatter`` has to return it: attributes, colour, background, and a reset behind."""
+    return ("".join(CODES[attr] for attr in attrs) + (CODES[color] if color else "") + (BACK[on] if on else "")
+            + text + "\x1b[0m")
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+#  WHAT A SPEC IS TURNED INTO
+# ═════════════════════════════════════════════════════════════════════════════
+
+class TestFormatter:
+
+    def test_returns_the_text_between_the_sequences(self):
+        assert formatter("hello", "red") == "\x1b[31mhello\x1b[0m"
+        assert formatter("hello", "bold_red") == "\x1b[1m\x1b[31mhello\x1b[0m"
+        assert formatter("hello", "bold") == "\x1b[1mhello\x1b[0m"
+
+    def test_the_tables_are_the_sequences_written_here(self):
+        assert clitint.ATTRIBUTES | clitint.COLOURS == CODES
+        assert clitint.BACKGROUNDS == BACK
+
+    @pytest.mark.parametrize("color", COLOURS)
+    def test_each_colour_alone_with_each_attribute_and_as_a_background(self, color):
+        assert formatter("text", color) == styled("text", color)
+        for attr in ATTRS:
+            assert formatter("text", f"{attr}_{color}") == styled("text", color, [attr])
+        assert formatter("text", f"highlight_{color}") == styled("text", on = color)
+        assert formatter("text", f"bold_white_highlight_{color}") == styled("text", "white", ["bold"], color)
+
+    @pytest.mark.parametrize("color", COLOURS)
+    def test_the_order_in_a_spec_does_not_matter(self, color):
+        expected = styled("t", color, ["bold", "underline"], "blue")
+        for spec in (f"bold_underline_{color}_highlight_blue", f"highlight_blue_{color}_underline_bold", f"underline_highlight_blue_bold_{color}"):
+            assert formatter("t", spec) == expected
+
+    def test_a_style_named_twice_is_written_once(self):
+        assert formatter("t", "bold_red_bold_red") == styled("t", "red", ["bold"])
+
+    # --- text variants ---
+
+    def test_empty_text(self):
+        assert formatter("", "red") == styled("", "red")
+
+    def test_text_with_special_characters(self):
+        assert formatter("hi\nthere", "red") == styled("hi\nthere", "red")
+
+    @pytest.mark.parametrize("text", [5, 2.5, None, ("a", 1), ["x"], b"raw", ValueError("no")], ids = repr)
+    def test_text_that_is_no_string(self, text):
+        assert formatter(text, "bold_red") == styled(str(text), "red", ["bold"])
+
+    @pytest.mark.parametrize("text", ["\x1b[31mred\x1b[0m", "%d %s", "{0}", "\x00x\x00", "a\x00b"])
+    def test_text_is_never_read_as_anything_else(self, text):
+        assert formatter(text, "bold_green") == styled(text, "green", ["bold"])
+
+    # --- what there is no style for ---
+
+    @pytest.mark.parametrize("spec", ["purple", "", "bold_purple", "highlight", "highlight_bold", "light_red", "teal", "red_highlight", "on_blue"])
+    def test_an_unknown_style_is_refused_by_name(self, spec):
+        for _ in range(2):                                          # the refusal is not remembered as an answer
+            with pytest.raises(ValueError, match = "unknown style"):
+                formatter("text", spec)
+
+    @pytest.mark.parametrize("spec, why", [("red_blue", "two colours"), ("highlight_red_highlight_blue", "two backgrounds")])
+    def test_two_colours_or_two_backgrounds_are_refused(self, spec, why):
+        with pytest.raises(ValueError, match = why):
+            formatter("text", spec)
+
+    def test_with_colours_off_the_spec_is_not_read(self, monkeypatch):
+        monkeypatch.setenv("CLITINT_COLOURS_OFF", "1")
+        assert formatter("text", "bold_red") == "text" and formatter(5, "purple") == "5"
+
+
+def test_the_sequences_are_the_ones_termcolor_writes():
+    #* Where termcolor happens to be installed: text is, to the byte, what it makes.
+    termcolor = pytest.importorskip("termcolor")
+    for color in COLOURS:
+        name: Any = (255, 165, 0) if color == "orange" else ("light_grey" if color == "white" else color)
+        if color in ("grey", "white"):
+            continue                                                # termcolor's names for 90 / 37 changed across versions
+        assert formatter("x", color) == termcolor.colored("x", name, force_color = True)
+        assert formatter("x", f"bold_{color}") == termcolor.colored("x", name, attrs = ["bold"], force_color = True)
+    assert formatter("x", "bold") == termcolor.colored("x", attrs = ["bold"], force_color = True)
+
+
+def test_the_package_imports_nothing_but_the_standard_library():
+    code = ("import sys; before = set(sys.modules); import clitint\n"
+            "new = {name.split('.')[0] for name in set(sys.modules) - before}\n"
+            "print(sorted(new - set(sys.stdlib_module_names) - {'clitint'}))")
+    done = subprocess.run([sys.executable, "-c", code], capture_output = True, text = True)
+    assert done.stdout.strip() == "[]", done.stdout + done.stderr
+
+
+def test_a_spec_is_worked_out_once_not_once_per_text(monkeypatch):
+    asked = []
+    real = tint._escapes
+    monkeypatch.setattr(tint, "_escapes", lambda spec: asked.append(spec) or real(spec))
+    monkeypatch.setattr(tint, "_ESCAPES", {})
+    texts = [formatter(word, "bold_yellow") for word in ("int", "str", "float")] + [formatter("x", "bold_red")]
+    assert texts == [styled(w, "yellow", ["bold"]) for w in ("int", "str", "float")] + [styled("x", "red", ["bold"])]
+    assert asked == ["bold_yellow", "bold_red"]
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+#  STRIPPING, ESCAPES, ONE DECISION
+# ═════════════════════════════════════════════════════════════════════════════
+
+@pytest.mark.parametrize("spec", ["red", "bold_orange", "underline_white_highlight_grey", "highlight_orange"])
+def test_strip_colours_gives_the_text_back(spec):
+    assert strip_colours(formatter("a b\nc", spec)) == "a b\nc"
+    assert strip_colours("plain") == "plain"
+    assert strip_colours(formatter("x", "red") + " and " + formatter("y", "bold")) == "x and y"
+
+
+def test_escapes_are_the_formatter_s_sequences_whatever_colours_say(monkeypatch):
+    before, after, bold_before, bold_after = escapes("red", "bold")
+    assert f"{before}x{after}" == formatter("x", "red") and f"{bold_before}x{bold_after}" == formatter("x", "bold")
+    monkeypatch.setenv("CLITINT_COLOURS_OFF", "1")
+    assert escapes("red") == ("\x1b[31m", "\x1b[0m")
+    with pytest.raises(ValueError):
+        escapes("purple")
+
+
+def test_one_decision_asks_once_and_leaves_nothing_behind(monkeypatch):
+    asked = []
+    real = tint.colours_on
+    monkeypatch.setattr(tint, "colours_on", lambda: asked.append(1) or real())
+    with one_decision():
+        words = [formatter(w, "bold") for w in "abcde"]
+        assert coloured()
+    assert len(asked) == 1 and all("\x1b[" in w for w in words)
+    assert tint._decided is None
+    monkeypatch.setenv("CLITINT_COLOURS_OFF", "1")
+    with one_decision():
+        assert formatter("x", "bold") == "x" and not coloured()
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+#  WHEN TEXT IS COLOURED
+# ═════════════════════════════════════════════════════════════════════════════
+
+class _Stream:
+    def __init__(self, terminal: bool) -> None:
+        self.terminal = terminal
+
+    def isatty(self) -> bool:
+        return self.terminal
+
+    def write(self, text: str) -> int:
+        return len(text)
+
+    def flush(self) -> None:
+        pass
+
+
+def _streams(monkeypatch, out: bool, err: bool) -> None:
+    monkeypatch.delenv("FORCE_COLOR", raising = False)
+    monkeypatch.delenv("TERM", raising = False)
+    monkeypatch.setattr(sys, "stdout", _Stream(out))
+    monkeypatch.setattr(sys, "stderr", _Stream(err))
+
+
+@pytest.mark.parametrize("out, err, expected", [
+    (True, True, True),             # a terminal: someone is reading
+    (True, False, False),           # 2> errors.log
+    (False, True, False),           # | less, > out.txt
+    (False, False, False),          # a CI job, a service
+    ])
+def test_colours_need_both_streams_to_be_terminals(monkeypatch, out, err, expected):
+    _streams(monkeypatch, out, err)
+    assert clitint.colours_on() is expected
+    assert (formatter("x", "bold") != "x") is expected
+
+
+def test_the_environment_decides_before_the_streams(monkeypatch):
+    _streams(monkeypatch, True, True)
+    for name, value in (("CLITINT_COLOURS_OFF", "1"), ("NO_COLOR", "1"), ("ANSI_COLORS_DISABLED", "1"), ("TERM", "dumb")):
+        monkeypatch.setenv(name, value)
+        assert clitint.colours_on() is False, name
+        monkeypatch.delenv(name)
+    _streams(monkeypatch, False, False)
+    monkeypatch.setenv("FORCE_COLOR", "1")
+    assert clitint.colours_on() is True
+    monkeypatch.setenv("CLITINT_COLOURS_OFF", "1")           # off wins over forced
+    assert clitint.colours_on() is False
+
+
+def test_the_program_decides_before_the_environment(monkeypatch):
+    _streams(monkeypatch, False, False)
+    clitint.turn_colours_on()
+    assert clitint.colours_on() and formatter("x", "red") == styled("x", "red")
+    monkeypatch.setenv("FORCE_COLOR", "1")
+    clitint.turn_colours_off()
+    assert not clitint.colours_on() and formatter("x", "red") == "x"
+    clitint.let_the_environment_decide()
+    assert clitint.colours_on()                                # FORCE_COLOR again
+
+
+def test_a_stream_without_isatty_is_no_terminal(monkeypatch):
+    monkeypatch.delenv("FORCE_COLOR", raising = False)
+    monkeypatch.setattr(sys, "stdout", None)                    # pythonw, a detached process
+    monkeypatch.setattr(sys, "stderr", object())
+    assert clitint.colours_on() is False and formatter("x", "red") == "x"
+
+
+def test_the_environment_is_read_as_it_is_now(monkeypatch):
+    #* colours_on reads the dictionary below os.environ. That is the same data, whichever way it is
+    #* changed, and another mapping put in the place of os.environ is read as well.
+    for name in ("CLITINT_COLOURS_OFF", "NO_COLOR", "ANSI_COLORS_DISABLED", "FORCE_COLOR", "TERM"):
+        monkeypatch.delenv(name, raising = False)
+    monkeypatch.setattr(tint, "_both_terminals", lambda: True)
+    assert tint._FAST and tint.colours_on()
+    steps = [("TERM", "dumb", False), ("FORCE_COLOR", "1", True), ("ANSI_COLORS_DISABLED", "", False)]
+    for name, value, expected in steps:
+        os.environ[name] = value
+        assert tint.colours_on() is expected
+    for name, _, _ in steps:
+        del os.environ[name]
+    assert tint.colours_on()
+    os.environ.update({"CLITINT_COLOURS_OFF": "1"})
+    assert not tint.colours_on()
+    os.environ.pop("CLITINT_COLOURS_OFF")
+    monkeypatch.setattr(os, "environ", {"NO_COLOR": "1"})           # a plain dictionary in its place
+    assert not tint.colours_on()
+    monkeypatch.setattr(os, "environ", {"TERM": "xterm"})
+    assert tint.colours_on()
+    monkeypatch.setattr(tint, "_FAST", False)                       # a Python without that dictionary: the same answers
+    assert tint.colours_on()
+    monkeypatch.setattr(os, "environ", {"TERM": "dumb"})
+    assert not tint.colours_on()
+
+
+def test_a_child_process_is_plain_when_piped_and_coloured_when_forced():
+    code = "from clitint import formatter; print(repr(formatter('x', 'red')))"
+    env = {k: v for k, v in os.environ.items() if k not in ("FORCE_COLOR", "NO_COLOR", "CLITINT_COLOURS_OFF")}
+    piped = subprocess.run([sys.executable, "-c", code], capture_output = True, text = True, env = env)
+    forced = subprocess.run([sys.executable, "-c", code], capture_output = True, text = True, env = env | {"FORCE_COLOR": "1"})
+    assert piped.stdout.strip() == "'x'"
+    assert forced.stdout.strip() == repr(styled("x", "red"))
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+#  WHAT A LIBRARY BUILT ON CLITINT USES
+# ═════════════════════════════════════════════════════════════════════════════
+
+@pytest.mark.parametrize("fast", [True, False])
+def test_an_off_switch_of_a_library_s_own(monkeypatch, fast):
+    monkeypatch.setattr(tint, "_OFF", tint._OFF)
+    monkeypatch.setattr(tint, "_K_OFFS", tint._K_OFFS)
+    monkeypatch.setattr(tint, "_FAST", fast and tint._FAST)
+    clitint.add_off_switch("MYLIB_COLOURS_OFF")
+    clitint.add_off_switch("MYLIB_COLOURS_OFF")                    # twice is once
+    assert tint._OFF == ("CLITINT_COLOURS_OFF", "MYLIB_COLOURS_OFF")
+    assert clitint.colours_on()                                    # FORCE_COLOR, from the fixture
+    for value, on in (("0", True), ("", True), ("yes", True), ("1", False)):
+        monkeypatch.setenv("MYLIB_COLOURS_OFF", value)
+        assert clitint.colours_on() is on, value                   # "1" and nothing else
+    monkeypatch.setenv("CLITINT_COLOURS_OFF", "1")
+    monkeypatch.delenv("MYLIB_COLOURS_OFF")
+    assert not clitint.colours_on()                                # clitint's own still counts
+
+
+@pytest.mark.parametrize("name", ["", None, 5])
+def test_an_off_switch_is_a_name(name):
+    with pytest.raises(TypeError):
+        clitint.add_off_switch(name)
+
+
+def test_decide_keeps_the_answer_until_release(monkeypatch):
+    assert clitint.decision() is None
+    assert clitint.decide() is True
+    monkeypatch.setenv("CLITINT_COLOURS_OFF", "1")
+    assert clitint.decision() is True and coloured() and formatter("x", "red") == styled("x", "red")
+    clitint.release()
+    assert clitint.decision() is None and formatter("x", "red") == "x"
+
+
+def test_one_decision_inside_another_keeps_the_outer_answer(monkeypatch):
+    with one_decision() as outer:
+        monkeypatch.setenv("CLITINT_COLOURS_OFF", "1")
+        with one_decision() as inner:
+            assert outer is inner is True
+        assert clitint.decision() is True                          # the inner one left it in place
+    assert clitint.decision() is None