Colr
====
A python module for using terminal colors. It contains a simple
``color`` function that accepts style and color names, and outputs a
string with escape codes, but also has all colors and styles as
chainable methods on the ``Colr`` object.
--------------
Dependencies:
-------------
System
~~~~~~
- **Python 3.5+** - This library uses ``yield from`` and the ``typing``
module. `Python 2 support is not planned. <#python-2>`__
Modules
~~~~~~~
There are no dependencies required for importing this library, however:
- `Docopt <https://github.com/docopt/docopt>`__ - Only required for the
command line tools (`colr <#colr-tool>`__ and
`colr-run <#colr-run>`__) and the `colr.docopt
wrapper <#colrdocopt>`__, not the library itself.
Installation:
-------------
Colr is listed on `PyPi <https://pypi.python.org/pypi/Colr>`__, and can
be installed using `pip <https://pip.pypa.io/en/stable/installing/>`__:
::
pip install colr
Or you can clone the repo on
`GitHub <https://github.com/welbornprod/colr>`__ and install it from the
command line:
::
git clone https://github.com/welbornprod/colr.git
cd colr
python3 setup.py install
--------------
Examples:
---------
Simple:
~~~~~~~
.. code:: python
from colr import color
print(color('Hello world.', fore='red', style='bright'))
Chainable:
~~~~~~~~~~
.. code:: python
from colr import Colr as C
print(
C()
.bright().red('Hello ')
.normal().blue('World')
)
# Background colors start with 'bg', and AttributeError will be raised on
# invalid method names.
print(C('Hello ', fore='red').bgwhite().blue('World'))
Examples (256 Colors):
----------------------
Simple:
~~~~~~~
.. code:: python
from colr import color
# Invalid color names/numbers raise a ValueError.
print(color('Hello world', fore=125, back=80))
Chainable:
~~~~~~~~~~
.. code:: python
from colr import Colr as C
# Foreground colors start with 'f_'
# Background colors start with 'b_'
print(C().f_125().b_80('Hello World'))
Examples (True Color):
----------------------
Simple:
~~~~~~~
.. code:: python
from colr import color
print(color('Hello there.', fore=(255, 0, 0), back=(0, 0, 0)))
Chainable:
~~~~~~~~~~
.. code:: python
from colr import Colr as C
# Foreground colors are set with the `rgb()` method.
# Background colors are set with the `b_rgb()` method.
# Text for the chained methods should be chained after or during
# the call to the methods.
print(C().b_rgb(0, 0, 0).rgb(255, 0, 0, 'Hello there.'))
Examples (Hex):
---------------
Simple:
~~~~~~~
.. code:: python
from colr import color
# When not using the Colr.hex method, the closest matching extended code
# is used. For true color, just use:
# fore=hex2rgb('ff0000')
# or
# Colr.hex('ff0000', rgb_mode=True)
print(color('Hello there.', fore='ff0000', back='000'))
Chainable:
~~~~~~~~~~
.. code:: python
from colr import Colr as C
# Foreground colors are set with the `hex()` method.
# Background colors are set with the `b_hex()` method.
# Text for the chained methods should be chained after or during
# the call to the methods.
print(C().b_hex('#000').hex('ff0000', 'Hello there.'))
# With rgb_mode set, these are the same:
print(C().hex('ff0000', 'test', rgb_mode=True))
print(C().rgb(255, 0, 0, 'test'))
--------------
Documentation:
--------------
Documentation for the ``colr`` API can be found in the GitHub repo
(`github.com/welbornprod/colr <https://github.com/welbornprod/colr>`__):
+-------------------------------------+--------------------------------------+
| Module/Object | Description |
+=====================================+======================================+
| `colr.Colr <https://github.com/welb | Methods for the ``Colr`` object, to |
| ornprod/colr/blob/dev/docs/colr.Col | colorize text. |
| r.md>`__ | |
+-------------------------------------+--------------------------------------+
| `colr.Control <https://github.com/w | Functions, classes, and methods for |
| elbornprod/colr/blob/dev/docs/colr. | the ``Control`` object, to control |
| controls.md>`__ | the cursor/screen. |
+-------------------------------------+--------------------------------------+
| colr.ColrControl | ``Colr`` and ``Control`` merged into |
| | one class. See ``colr.Colr`` and |
| | ``colr.Control``. |
+-------------------------------------+--------------------------------------+
| `colr.progress <https://github.com/ | Progress updates, bars, or spinners. |
| welbornprod/colr/blob/dev/docs/colr | |
| .progress.md>`__ | |
+-------------------------------------+--------------------------------------+
| `colr.trans <https://github.com/wel | Color code translation/detection. |
| bornprod/colr/blob/dev/docs/colr.tr | |
| ans.md>`__ | |
+-------------------------------------+--------------------------------------+
--------------
Colr Tool:
----------
The ``colr`` package can be used as a command line tool. An entry point
script named ``colr`` is created when installed with pip. Otherwise it
can be executed using the ``python -m colr`` method.
.. code:: bash
colr --help
Basic usage involves passing text, or piping stdin data and setting the
colors by position or flag.
.. code:: bash
# These all do the same thing:
colr "Test" "red" "white" "bright"
colr "Test" -f "red" -b "white" -s "bright"
printf "Test" | colr -f "red" -b "white" -s "bright"
Using the positional arguments is faster for just setting fore colors,
but the flag method is needed for stdin data, or for picking just the
background color or style:
.. code:: bash
colr "Test" -s "bright"
Extended and True colors are supported:
.. code:: bash
colr "Test" 124 255
colr "Test" "255, 0, 0" "255, 255, 255"
# Use true color (rgb) escape codes to generate a gradient, and then
# center it in the terminal (0 means use terminal width).
colr "Test" -G "255,0,0" -G "0,0,255" -c 0
It will do fore, back, style, gradients, rainbows, justification, and
translation. It can strip codes from text (as an argument or stdin), or
explain the codes found in the text.
`lolcat <https://github.com/busyloop/lolcat>`__ emulation:
.. code:: bash
fortune | colr --rainbow
The colr tool does not read files, but it's not a problem:
.. code:: bash
cat myfile.txt | colr --gradient red
Also see `ccat <https://github.com/welbornprod/ccat>`__.
Colr-run:
---------
A small command-runner is included, called ``colr-run``. This program
will run another program, printing an animated message instead of the
normal output.
It is used to turn "noisy" commands into a nice single-line animation.
Basic Example:
~~~~~~~~~~~~~~
To run a program with the default settings, ``--`` is still required:
.. code:: bash
colr-run -- bash -c 'x=0; while ((x<1000000)); do let x+=1; done'
Any stderr output from the program will ruin the animation, which may be
fine if you are only looking for errors.
You can silence stderr output with ``-e`` if you don't need it:
.. code:: bash
colr-run -e -- some-long-running-command
The exit status of ``colr-run`` is the exit status of the command being
executed. For ``colr-run`` errors, the exit status is ``1`` for basic
errors, and ``2`` for cancelled commands.
Colr.docopt:
------------
Colr provides a wrapper for docopt that will automatically colorize
usage strings. If you provide it a script name it will add a little more
color by colorizing the script name too.
.. code:: python
from colr import docopt
argd = docopt(USAGE, script='mycommand')
--------------
Contributing:
-------------
As always contributions are welcome here. If you think you can improve
something, or have a good idea for a feature, please file an
`issue <https://github.com/welbornprod/colr/issues/new>`__ or a `pull
request <https://github.com/welbornprod/colr/compare>`__.
--------------
Notes:
------
Reasons
~~~~~~~
In the past, I used a simple ``color()`` function because I'm not fond
of the string concatenation style that other libraries use. The 'clor'
javascript library uses method chaining because that style suits
javascript, but I wanted to make it available to Python also, at least
as an option.
Reset Codes
~~~~~~~~~~~
The reset code is appended only if some kind of text was given, and
colr/style args were used. The only values that are considered 'no text'
values are ``None`` and ``''`` (empty string). ``str(val)`` is called on
all other values, so ``Colr(0, 'red')`` and ``Colr(False, 'blue')`` will
work, and the reset code will be appended.
This makes it possible to build background colors and styles, but also
have separate styles for separate pieces of text.
Python 2
~~~~~~~~
I don't really have the desire to back-port this to Python 2. It
wouldn't need too many changes, but I like the Python 3 features
(``yield from``, ``str/bytes``).
Windows
~~~~~~~
Windows 10 finally has support for ANSI escape codes. Colr can now be
used on Windows 10+ by calling ``SetConsoleMode``. Older Windows
versions are not supported and haven't been tested. If you are using
Colr for a tool that needs to support older Windows versions, you will
need to detect the current Windows version and call ``colr.disable()``
for those that aren't supported. Otherwise you will have "junk"
characters printed to the screen.
Misc.
~~~~~
This library may be a little too flexible:
.. code:: python
from colr import Colr as C
warnmsg = lambda s: C('warning', 'red').join('[', ']')(' ').green(s)
print(warnmsg('The roof is on fire again.'))
.. figure:: https://welbornprod.com/static/media/img/colr-warning.png
:alt: The possibilities are endless.
The possibilities are endless.
Raw data
{
"_id": null,
"home_page": "https://github.com/welbornprod/colr",
"name": "Colr",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python module library 2 3 terminal escape codes color",
"author": "Christopher Welborn",
"author_email": "cj@welbornprod.com",
"download_url": "https://files.pythonhosted.org/packages/43/a9/75bcc155e0bf57062e77974a5aea724123de3becd69fca6f8572127c09a2/Colr-0.9.1.tar.gz",
"platform": "",
"description": "Colr\n====\n\nA python module for using terminal colors. It contains a simple\n``color`` function that accepts style and color names, and outputs a\nstring with escape codes, but also has all colors and styles as\nchainable methods on the ``Colr`` object.\n\n--------------\n\nDependencies:\n-------------\n\nSystem\n~~~~~~\n\n- **Python 3.5+** - This library uses ``yield from`` and the ``typing``\n module. `Python 2 support is not planned. <#python-2>`__\n\nModules\n~~~~~~~\n\nThere are no dependencies required for importing this library, however:\n\n- `Docopt <https://github.com/docopt/docopt>`__ - Only required for the\n command line tools (`colr <#colr-tool>`__ and\n `colr-run <#colr-run>`__) and the `colr.docopt\n wrapper <#colrdocopt>`__, not the library itself.\n\nInstallation:\n-------------\n\nColr is listed on `PyPi <https://pypi.python.org/pypi/Colr>`__, and can\nbe installed using `pip <https://pip.pypa.io/en/stable/installing/>`__:\n\n::\n\n pip install colr\n\nOr you can clone the repo on\n`GitHub <https://github.com/welbornprod/colr>`__ and install it from the\ncommand line:\n\n::\n\n git clone https://github.com/welbornprod/colr.git\n cd colr\n python3 setup.py install\n\n--------------\n\nExamples:\n---------\n\nSimple:\n~~~~~~~\n\n.. code:: python\n\n from colr import color\n print(color('Hello world.', fore='red', style='bright'))\n\nChainable:\n~~~~~~~~~~\n\n.. code:: python\n\n from colr import Colr as C\n print(\n C()\n .bright().red('Hello ')\n .normal().blue('World')\n )\n\n # Background colors start with 'bg', and AttributeError will be raised on\n # invalid method names.\n print(C('Hello ', fore='red').bgwhite().blue('World'))\n\nExamples (256 Colors):\n----------------------\n\nSimple:\n~~~~~~~\n\n.. code:: python\n\n from colr import color\n # Invalid color names/numbers raise a ValueError.\n print(color('Hello world', fore=125, back=80))\n\nChainable:\n~~~~~~~~~~\n\n.. code:: python\n\n from colr import Colr as C\n # Foreground colors start with 'f_'\n # Background colors start with 'b_'\n print(C().f_125().b_80('Hello World'))\n\nExamples (True Color):\n----------------------\n\nSimple:\n~~~~~~~\n\n.. code:: python\n\n from colr import color\n print(color('Hello there.', fore=(255, 0, 0), back=(0, 0, 0)))\n\nChainable:\n~~~~~~~~~~\n\n.. code:: python\n\n from colr import Colr as C\n # Foreground colors are set with the `rgb()` method.\n # Background colors are set with the `b_rgb()` method.\n # Text for the chained methods should be chained after or during\n # the call to the methods.\n print(C().b_rgb(0, 0, 0).rgb(255, 0, 0, 'Hello there.'))\n\nExamples (Hex):\n---------------\n\nSimple:\n~~~~~~~\n\n.. code:: python\n\n from colr import color\n # When not using the Colr.hex method, the closest matching extended code\n # is used. For true color, just use:\n # fore=hex2rgb('ff0000')\n # or\n # Colr.hex('ff0000', rgb_mode=True)\n print(color('Hello there.', fore='ff0000', back='000'))\n\nChainable:\n~~~~~~~~~~\n\n.. code:: python\n\n from colr import Colr as C\n # Foreground colors are set with the `hex()` method.\n # Background colors are set with the `b_hex()` method.\n # Text for the chained methods should be chained after or during\n # the call to the methods.\n print(C().b_hex('#000').hex('ff0000', 'Hello there.'))\n\n # With rgb_mode set, these are the same:\n print(C().hex('ff0000', 'test', rgb_mode=True))\n print(C().rgb(255, 0, 0, 'test'))\n\n--------------\n\nDocumentation:\n--------------\n\nDocumentation for the ``colr`` API can be found in the GitHub repo\n(`github.com/welbornprod/colr <https://github.com/welbornprod/colr>`__):\n\n+-------------------------------------+--------------------------------------+\n| Module/Object | Description |\n+=====================================+======================================+\n| `colr.Colr <https://github.com/welb | Methods for the ``Colr`` object, to |\n| ornprod/colr/blob/dev/docs/colr.Col | colorize text. |\n| r.md>`__ | |\n+-------------------------------------+--------------------------------------+\n| `colr.Control <https://github.com/w | Functions, classes, and methods for |\n| elbornprod/colr/blob/dev/docs/colr. | the ``Control`` object, to control |\n| controls.md>`__ | the cursor/screen. |\n+-------------------------------------+--------------------------------------+\n| colr.ColrControl | ``Colr`` and ``Control`` merged into |\n| | one class. See ``colr.Colr`` and |\n| | ``colr.Control``. |\n+-------------------------------------+--------------------------------------+\n| `colr.progress <https://github.com/ | Progress updates, bars, or spinners. |\n| welbornprod/colr/blob/dev/docs/colr | |\n| .progress.md>`__ | |\n+-------------------------------------+--------------------------------------+\n| `colr.trans <https://github.com/wel | Color code translation/detection. |\n| bornprod/colr/blob/dev/docs/colr.tr | |\n| ans.md>`__ | |\n+-------------------------------------+--------------------------------------+\n\n--------------\n\nColr Tool:\n----------\n\nThe ``colr`` package can be used as a command line tool. An entry point\nscript named ``colr`` is created when installed with pip. Otherwise it\ncan be executed using the ``python -m colr`` method.\n\n.. code:: bash\n\n colr --help\n\nBasic usage involves passing text, or piping stdin data and setting the\ncolors by position or flag.\n\n.. code:: bash\n\n # These all do the same thing:\n colr \"Test\" \"red\" \"white\" \"bright\"\n colr \"Test\" -f \"red\" -b \"white\" -s \"bright\"\n printf \"Test\" | colr -f \"red\" -b \"white\" -s \"bright\"\n\nUsing the positional arguments is faster for just setting fore colors,\nbut the flag method is needed for stdin data, or for picking just the\nbackground color or style:\n\n.. code:: bash\n\n colr \"Test\" -s \"bright\"\n\nExtended and True colors are supported:\n\n.. code:: bash\n\n colr \"Test\" 124 255\n colr \"Test\" \"255, 0, 0\" \"255, 255, 255\"\n # Use true color (rgb) escape codes to generate a gradient, and then\n # center it in the terminal (0 means use terminal width).\n colr \"Test\" -G \"255,0,0\" -G \"0,0,255\" -c 0\n\nIt will do fore, back, style, gradients, rainbows, justification, and\ntranslation. It can strip codes from text (as an argument or stdin), or\nexplain the codes found in the text.\n\n`lolcat <https://github.com/busyloop/lolcat>`__ emulation:\n\n.. code:: bash\n\n fortune | colr --rainbow\n\nThe colr tool does not read files, but it's not a problem:\n\n.. code:: bash\n\n cat myfile.txt | colr --gradient red\n\nAlso see `ccat <https://github.com/welbornprod/ccat>`__.\n\nColr-run:\n---------\n\nA small command-runner is included, called ``colr-run``. This program\nwill run another program, printing an animated message instead of the\nnormal output.\n\nIt is used to turn \"noisy\" commands into a nice single-line animation.\n\nBasic Example:\n~~~~~~~~~~~~~~\n\nTo run a program with the default settings, ``--`` is still required:\n\n.. code:: bash\n\n colr-run -- bash -c 'x=0; while ((x<1000000)); do let x+=1; done'\n\nAny stderr output from the program will ruin the animation, which may be\nfine if you are only looking for errors.\n\nYou can silence stderr output with ``-e`` if you don't need it:\n\n.. code:: bash\n\n colr-run -e -- some-long-running-command\n\nThe exit status of ``colr-run`` is the exit status of the command being\nexecuted. For ``colr-run`` errors, the exit status is ``1`` for basic\nerrors, and ``2`` for cancelled commands.\n\nColr.docopt:\n------------\n\nColr provides a wrapper for docopt that will automatically colorize\nusage strings. If you provide it a script name it will add a little more\ncolor by colorizing the script name too.\n\n.. code:: python\n\n from colr import docopt\n argd = docopt(USAGE, script='mycommand')\n\n--------------\n\nContributing:\n-------------\n\nAs always contributions are welcome here. If you think you can improve\nsomething, or have a good idea for a feature, please file an\n`issue <https://github.com/welbornprod/colr/issues/new>`__ or a `pull\nrequest <https://github.com/welbornprod/colr/compare>`__.\n\n--------------\n\nNotes:\n------\n\nReasons\n~~~~~~~\n\nIn the past, I used a simple ``color()`` function because I'm not fond\nof the string concatenation style that other libraries use. The 'clor'\njavascript library uses method chaining because that style suits\njavascript, but I wanted to make it available to Python also, at least\nas an option.\n\nReset Codes\n~~~~~~~~~~~\n\nThe reset code is appended only if some kind of text was given, and\ncolr/style args were used. The only values that are considered 'no text'\nvalues are ``None`` and ``''`` (empty string). ``str(val)`` is called on\nall other values, so ``Colr(0, 'red')`` and ``Colr(False, 'blue')`` will\nwork, and the reset code will be appended.\n\nThis makes it possible to build background colors and styles, but also\nhave separate styles for separate pieces of text.\n\nPython 2\n~~~~~~~~\n\nI don't really have the desire to back-port this to Python 2. It\nwouldn't need too many changes, but I like the Python 3 features\n(``yield from``, ``str/bytes``).\n\nWindows\n~~~~~~~\n\nWindows 10 finally has support for ANSI escape codes. Colr can now be\nused on Windows 10+ by calling ``SetConsoleMode``. Older Windows\nversions are not supported and haven't been tested. If you are using\nColr for a tool that needs to support older Windows versions, you will\nneed to detect the current Windows version and call ``colr.disable()``\nfor those that aren't supported. Otherwise you will have \"junk\"\ncharacters printed to the screen.\n\nMisc.\n~~~~~\n\nThis library may be a little too flexible:\n\n.. code:: python\n\n from colr import Colr as C\n warnmsg = lambda s: C('warning', 'red').join('[', ']')(' ').green(s)\n print(warnmsg('The roof is on fire again.'))\n\n.. figure:: https://welbornprod.com/static/media/img/colr-warning.png\n :alt: The possibilities are endless.\n\n The possibilities are endless.\n",
"bugtrack_url": null,
"license": "",
"summary": "Easy terminal colors, with chainable methods.\n",
"version": "0.9.1",
"project_urls": {
"Homepage": "https://github.com/welbornprod/colr"
},
"split_keywords": [
"python",
"module",
"library",
"2",
"3",
"terminal",
"escape",
"codes",
"color"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "43a975bcc155e0bf57062e77974a5aea724123de3becd69fca6f8572127c09a2",
"md5": "c47900f50404000ef3d800ed974b99e2",
"sha256": "8c15437eeb2ec8821c6df24b62946dfc6b79f69a1d84c1a6c131945a5ff4623c"
},
"downloads": -1,
"filename": "Colr-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "c47900f50404000ef3d800ed974b99e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 116430,
"upload_time": "2019-08-31T01:36:22",
"upload_time_iso_8601": "2019-08-31T01:36:22.856032Z",
"url": "https://files.pythonhosted.org/packages/43/a9/75bcc155e0bf57062e77974a5aea724123de3becd69fca6f8572127c09a2/Colr-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-08-31 01:36:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "welbornprod",
"github_project": "colr",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "colr"
}
JSON
