| Name | cs-ansi-colour JSON |
| Version |
20250306
JSON |
| download |
| home_page | None |
| Summary | Convenience functions for ANSI terminal colour sequences [color]. |
| upload_time | 2025-03-06 01:10:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | None |
| keywords |
python2
python3
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Convenience functions for ANSI terminal colour sequences [color].
*Latest release 20250306*:
colourise: do not colour the leading and trailing whitespace, provide colour_padding=False optional flag to disable.
Mapping and function for adding ANSI terminal colour escape sequences
to strings for colour highlighting of output.
## <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 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
Raw data
{
"_id": null,
"home_page": null,
"name": "cs-ansi-colour",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python2, python3",
"author": null,
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/05/50/2c0b8890a3cfcc2329dc9007d50c4c75bd1fd0f9e83c4cbe5607cc88b108/cs_ansi_colour-20250306.tar.gz",
"platform": null,
"description": "Convenience functions for ANSI terminal colour sequences [color].\n\n*Latest release 20250306*:\ncolourise: do not colour the leading and trailing whitespace, provide colour_padding=False optional flag to disable.\n\nMapping and function for adding ANSI terminal colour escape sequences\nto strings for colour highlighting of output.\n\n## <a name=\"colour_escape\"></a>`colour_escape(code)`\n\nReturn the ANSI escape sequence to activate the colour `code`.\n`code` may be an `int` or a `str` which indexes `COLOUR_CODES`.\n\n## <a name=\"colourise\"></a>`colourise(s, colour=None, uncolour=None, colour_padding=False)`\n\nReturn a string enclosed in colour-on and colour-off ANSI sequences.\n\nParameters:\n* `s`: the string to colour\n* `colour`: names the desired ANSI colour.\n* `uncolour`: may be used to specify the colour-off colour;\n the default is 'normal' (from `NORMAL_COLOUR`).\n* `colour_padding`: default `False`; if true colour the entire text,\n otherwise do not colour the leading and trailing whitespace of each line.\n\n## <a name=\"colourise_patterns\"></a>`colourise_patterns(s, patterns, default_colour=None)`\n\nColourise a string `s` according to `patterns`.\n\nParameters:\n* `s`: the string.\n* `patterns`: a sequence of patterns.\n* `default_colour`: if a string pattern has no colon, or starts\n with a colon, use this colour;\n default \"cyan\" (from `DEFAULT_HIGHLIGHT`).\n\nEach pattern may be:\n* a string of the form \"[colour]:regexp\"\n* a string containing no colon, taken to be a regexp\n* a tuple of the form `(colour,regexp)`\n* a regexp object\n\nReturns the string with ANSI colour escapes embedded.\n\n## <a name=\"env_no_color\"></a>`env_no_color(environ=None)`\n\nTest the `$NO_COLOR` environment variable per the specification at\nhttps://no-color.org/\n\n## <a name=\"make_pattern\"></a>`make_pattern(pattern, default_colour=None)`\n\nConvert a `pattern` specification into a `(colour,regexp)` tuple.\n\nParameters:\n* `pattern`: the pattern to parse\n* `default_colour`: the highlight colour,\n default \"cyan\" (from `DEFAULT_HIGHLIGHT`).\n\nEach `pattern` may be:\n* a string of the form \"[colour]:regexp\"\n* a string containing no colon, taken to be a regexp\n* a tuple of the form `(colour,regexp)`\n* a regexp object\n\n## <a name=\"make_patterns\"></a>`make_patterns(patterns, default_colour=None)`\n\nConvert an iterable of pattern specifications into a list of\n`(colour,regexp)` tuples.\n\nParameters:\n* `patterns`: an iterable of patterns to parse\n* `default_colour`: the highlight colour,\n default \"cyan\" (from `DEFAULT_HIGHLIGHT`).\n\nEach pattern may be:\n* a string of the form \"[colour]:regexp\"\n* a string containing no colon, taken to be a regexp\n* a tuple of the form (colour, regexp)\n* a regexp object\n\n## <a name=\"TerminalColors\"></a>Class `TerminalColors`\n\nA parser for `/etc/terminal-colors.d'` files.\n\n*`TerminalColors.__init__(self, util_name=None, term_name=None, type_name=None, colors_dirpath=None, envvar=None)`*:\nInitialise the `TerminalColors` instance.\n\nParameters:\n* `util_name`: optional utility name, default from `sys.argv[0]`\n* `term_name`: optional terminal name, default from the `$TERM` envvar\n* `type_name`: optional type name, default `'enable'`\n* `colors_dirpath`: optional specification files directory path,\n default from `TerminalColors.TERMINAL_COLORS_D`\n* `envvar`: environment variable to override matches;\n the default `util_name+'_COLORS'`,\n thus `$LS_COLORS` if `util_name=='ls'`.\n That may be the value `False` if no environment variable should be an override.\n\n*`TerminalColors.convert_sequence(sequence)`*:\nConvert a colour specification to an escape sequence.\n\n*`TerminalColors.find_specfile(self)`*:\nLocate the most specific specification file matching our criteria.\nReturn `None` if no file matches.\n\n*`TerminalColors.mapping`*:\nThe mapping of `name` to escape sequence.\n\n*`TerminalColors.scan(self, path=None)`*:\nScan the colour specification in `path`\nand yield `(name,escape_sequence)` tuples.\n\n# Release Log\n\n\n\n*Release 20250306*:\ncolourise: do not colour the leading and trailing whitespace, provide colour_padding=False optional flag to disable.\n\n*Release 20220227*:\n* New TerminalColors class parsing /etc/terminal-colors.d and honouring $*_COLORS.\n* New colour_escape(code) to make the escape sequence for a colour code.\n* New COLOUR_CODES mapping of known colour names.\n\n*Release 20200729*:\n* New env_no_color() test function honouring the $NO_COLOUR envvar per https://no-color.org/\n* colourise: get the \"normal\" default from the global NORMAL_COLOUR.\n\n*Release 20180726*:\ngreater markdowning of docstrings\n\n*Release 20180725.2*:\nsome markdown, still release testing\n\n*Release 20180725.1*:\nTrivial changes, testing release process.\n\n*Release 20180725*:\nrename second colourise function to colourise_patterns, was shadowing things\n\n*Release 20180422*:\n* New function colourise to colour strings with regexp matches.\n* New helper functions make_pattern and make_patterns to construct (colour, regexp)s from specifications.\n* New public names NORMAL_COLOUR and DEFAULT_HIGHLIGHT.\n\n*Release 20170902*:\nRelease metadata changes.\n\n*Release 20160828*:\nAdd PyPI category, other minor tweaks.\n\n*Release 20150112*:\nPyPI release.\n\n*Release 20150107*:\nfirst standalone pypi release\n",
"bugtrack_url": null,
"license": null,
"summary": "Convenience functions for ANSI terminal colour sequences [color].",
"version": "20250306",
"project_urls": {
"MonoRepo Commits": "https://bitbucket.org/cameron_simpson/css/commits/branch/main",
"Monorepo Git Mirror": "https://github.com/cameron-simpson/css",
"Monorepo Hg/Mercurial Mirror": "https://hg.sr.ht/~cameron-simpson/css",
"Source": "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/ansi_colour.py"
},
"split_keywords": [
"python2",
" python3"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "79818b2c9e85a5f7d05b457172573b519bf93e1b8108ebc961cff374591cb637",
"md5": "f41e925f3197a20a6e113ea27b122044",
"sha256": "4824d25df75c94beab47da25d23d47c74bda778fe019637a1def88d27fa85019"
},
"downloads": -1,
"filename": "cs_ansi_colour-20250306-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f41e925f3197a20a6e113ea27b122044",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6236,
"upload_time": "2025-03-06T01:10:06",
"upload_time_iso_8601": "2025-03-06T01:10:06.059441Z",
"url": "https://files.pythonhosted.org/packages/79/81/8b2c9e85a5f7d05b457172573b519bf93e1b8108ebc961cff374591cb637/cs_ansi_colour-20250306-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "05502c0b8890a3cfcc2329dc9007d50c4c75bd1fd0f9e83c4cbe5607cc88b108",
"md5": "cf3aaccd935340aa80789224fc9ed2cb",
"sha256": "aa41c391cb77a0bb287487c75234b801b70a25e6d800865d06699b27a6d2529f"
},
"downloads": -1,
"filename": "cs_ansi_colour-20250306.tar.gz",
"has_sig": false,
"md5_digest": "cf3aaccd935340aa80789224fc9ed2cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5106,
"upload_time": "2025-03-06T01:10:07",
"upload_time_iso_8601": "2025-03-06T01:10:07.976963Z",
"url": "https://files.pythonhosted.org/packages/05/50/2c0b8890a3cfcc2329dc9007d50c4c75bd1fd0f9e83c4cbe5607cc88b108/cs_ansi_colour-20250306.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-06 01:10:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cameron-simpson",
"github_project": "css",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cs-ansi-colour"
}
