Metadata-Version: 2.4
Name: cs-ansi_colour
Version: 20260531
Summary: Convenience functions for ANSI terminal colour sequences [color].
Keywords: python2,python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Description-Content-Type: text/markdown
Classifier: Development Status :: 6 - Mature
Classifier: Environment :: Console
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Terminals
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Dist: cs.gimmicks>=20260311
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/ansi_colour.py

Convenience functions for ANSI terminal colour sequences [color].

*Latest release 20260531*:
Add a bunch of other SGR parameters, though terminal support for these is very spotty.

Mapping and function for adding ANSI terminal colour escape sequences
to strings for colour highlighting of output.

Short summary:
* `colour_escape`: Return the ANSI escape sequence to activate the colour `code`. `code` may be an `int` or a `str` which indexes `COLOUR_CODES`.
* `colourise`: Return a string enclosed in colour-on and colour-off ANSI sequences.
* `colourise_patterns`: Colourise a string `s` according to `patterns`.
* `env_no_color`: Test the `$NO_COLOR` environment variable per the specification at https://no-color.org/.
* `make_pattern`: Convert a `pattern` specification into a `(colour,regexp)` tuple.
* `make_patterns`: Convert an iterable of pattern specifications into a list of `(colour,regexp)` tuples.
* `TerminalColors`: A parser for `/etc/terminal-colors.d'` files.

Module contents:
- <a name="colour_escape"></a>`colour_escape(code)`: Return the ANSI escape sequence to activate the colour `code`.
  `code` may be an `int` or a `str` which indexes `COLOUR_CODES`.
- <a name="colourise"></a>`colourise(s, colour=None, uncolour=None, colour_padding=False)`: Return a string enclosed in colour-on and colour-off ANSI sequences.

  Parameters:
  * `s`: the string to colour
  * `colour`: names the desired ANSI colour.
  * `uncolour`: may be used to specify the colour-off colour;
    the default is 'normal' (from `NORMAL_COLOUR`).
  * `colour_padding`: default `False`; if true colour the entire text,
    otherwise do not colour the leading and trailing whitespace of each line.
- <a name="colourise_patterns"></a>`colourise_patterns(s, patterns, default_colour=None)`: Colourise a string `s` according to `patterns`.

  Parameters:
  * `s`: the string.
  * `patterns`: a sequence of patterns.
  * `default_colour`: if a string pattern has no colon, or starts
    with a colon, use this colour;
    default "cyan" (from `DEFAULT_HIGHLIGHT`).

  Each pattern may be:
  * a string of the form "[colour]:regexp"
  * a string containing no colon, taken to be a regexp
  * a tuple of the form `(colour,regexp)`
  * a regexp object

  Returns the string with ANSI colour escapes embedded.
- <a name="env_no_color"></a>`env_no_color(environ=None)`: Test the `$NO_COLOR` environment variable per the specification at
  https://no-color.org/
- <a name="make_pattern"></a>`make_pattern(pattern, default_colour=None)`: Convert a `pattern` specification into a `(colour,regexp)` tuple.

  Parameters:
  * `pattern`: the pattern to parse
  * `default_colour`: the highlight colour,
    default "cyan" (from `DEFAULT_HIGHLIGHT`).

  Each `pattern` may be:
  * a string of the form "[colour]:regexp"
  * a string containing no colon, taken to be a regexp
  * a tuple of the form `(colour,regexp)`
  * a regexp object
- <a name="make_patterns"></a>`make_patterns(patterns, default_colour=None)`: Convert an iterable of pattern specifications into a list of
  `(colour,regexp)` tuples.

  Parameters:
  * `patterns`: an iterable of patterns to parse
  * `default_colour`: the highlight colour,
    default "cyan" (from `DEFAULT_HIGHLIGHT`).

  Each pattern may be:
  * a string of the form "[colour]:regexp"
  * a string containing no colon, taken to be a regexp
  * a tuple of the form (colour, regexp)
  * a regexp object
- <a name="TerminalColors"></a>`class TerminalColors`: A parser for `/etc/terminal-colors.d'` files.

*`TerminalColors.__init__(self, util_name=None, term_name=None, type_name=None, colors_dirpath=None, envvar=None)`*:
Initialise the `TerminalColors` instance.

Parameters:
* `util_name`: optional utility name, default from `sys.argv[0]`
* `term_name`: optional terminal name, default from the `$TERM` envvar
* `type_name`: optional type name, default `'enable'`
* `colors_dirpath`: optional specification files directory path,
  default from `TerminalColors.TERMINAL_COLORS_D`
* `envvar`: environment variable to override matches;
  the default `util_name+'_COLORS'`,
  thus `$LS_COLORS` if `util_name=='ls'`.
  That may be the value `False` if no environment variable should be an override.

*`TerminalColors.convert_sequence(sequence)`*:
Convert a colour specification to an escape sequence.

*`TerminalColors.find_specfile(self)`*:
Locate the most specific specification file matching our criteria.
Return `None` if no file matches.

*`TerminalColors.mapping`*:
The mapping of `name` to escape sequence.

*`TerminalColors.scan(self, path=None)`*:
Scan the colour specification in `path`
and yield `(name,escape_sequence)` tuples.

# Release Log



*Release 20260531*:
Add a bunch of other SGR parameters, though terminal support for these is very spotty.

*Release 20250306*:
colourise: do not colour the leading and trailing whitespace, provide colour_padding=False optional flag to disable.

*Release 20220227*:
* New TerminalColors class parsing /etc/terminal-colors.d and honouring $*_COLORS.
* New colour_escape(code) to make the escape sequence for a colour code.
* New COLOUR_CODES mapping of known colour names.

*Release 20200729*:
* New env_no_color() test function honouring the $NO_COLOUR envvar per https://no-color.org/
* colourise: get the "normal" default from the global NORMAL_COLOUR.

*Release 20180726*:
greater markdowning of docstrings

*Release 20180725.2*:
some markdown, still release testing

*Release 20180725.1*:
Trivial changes, testing release process.

*Release 20180725*:
rename second colourise function to colourise_patterns, was shadowing things

*Release 20180422*:
* New function colourise to colour strings with regexp matches.
* New helper functions make_pattern and make_patterns to construct (colour, regexp)s from specifications.
* New public names NORMAL_COLOUR and DEFAULT_HIGHLIGHT.

*Release 20170902*:
Release metadata changes.

*Release 20160828*:
Add PyPI category, other minor tweaks.

*Release 20150112*:
PyPI release.

*Release 20150107*:
first standalone pypi release
