Skip to main content

colorful - Terminal string styling done right, in Python.

Project description

colorful
========

Terminal string styling done right, in Python :tada:

Here's a tease
--------------

.. figure:: examples/basic_example.png
:alt: colorful example

colorful example

.. code:: python

import colorful

# create a colored string using clever method translation
print(colorful.bold_white('Hello World'))
# create a colored string using `str.format()`
print('{c.bold}{c.lightCoral_on_white}Hello World{c.reset}'.format(c=colorful))

# use true colors
colorful.use_true_colors()

# extend default color palette
colorful.update_palette({'mint': '#c5e8c8'})
print(colorful.mint_on_snow('Wow, this is actually mint'))

# choose a predefined style
colorful.use_style('solarized')
# print the official solarized colors
print(colorful.yellow('yellow'), colorful.orange('orange'),
colorful.red('red'), colorful.magenta('magenta'),
colorful.violet('violet'), colorful.blue('blue'),
colorful.cyan('cyan'), colorful.green('green'))

# choose specific color mode for one block
with colorful.with_8bit_ansi_colors() as c:
print(c.bold_green('colorful is awesome!'))

# create and choose your own color palette
MY_COMPANY_PALETTE = {
'companyOrange': '#f4b942',
'companyBaige': '#e8dcc5'
}
with colorful.with_palette(my_company_palette) as c:
print(c.companyOrange_on_companyBaige('Thanks for choosing our product!'))

Key Features
------------

- expressive and consistent API
- support for different color modes (8bit ANSI, 256 ANSI, true colors)
- support for predefined awesome styles (solarized, ...)
- support for custom color palettes
- support for different platforms (using colorama on windows)
- context managers for clean color mode, color palette or style switch
- no dependencies

Usage
-----

**colorful** supports all major Python versions: *2.7*, *3.2*, *3.3*,
*3.4*, *3.5* and *3.6*. We recommend to use the latest version released
on `PyPI <https://pypi-hypernode.com/pypi/colorful>`__:

.. code:: bash

pip install colorful

*Note: on a Windows system it will install ``colorama`` as a dependency
to ensure proper ANSI support.*

**colorful** does not require any special setup in order to be used:

.. code:: python

import colorful

print(colorful.italic_coral_on_beige('Hello World'))
print('{c.italic_coral_on_beige}Hello World{c.reset}'.format(c=colorful))

Color modes
~~~~~~~~~~~

These days terminals not only support the ancient 8 bit ANSI colors but
often they support up to 16 Million colors with *`true
color <https://en.wikipedia.org/wiki/Color_depth#True_color_.2824-bit.29>`__*.
And if they don't support *true color* they might support the *`256 ANSI
color
palette <https://en.wikipedia.org/wiki/ANSI_escape_code#Colors>`__* at
least.

**colorful** supports the following color modes:

- no colors / disable (``colorful.NO_COLORS``)
- 8 colors -> 8 bit ANSI colors (``colorful.ANSI_8BIT_COLORS``)
- 256 colors -> 256 ANSI color palette (24bit
``colorful.ANSI_256_COLORS``)
- 16'777'215 colors -> true color (``colorful.TRUE_COLORS``)

By default *colorful* tries to auto detect the best supported color mode
by your terminal. Consult
```colorful.terminal`` <https://github.com/timofurrer/colorful/blob/master/colorful/terminal.py>`__
for more details.

However, sometimes it makes sense to specify what color mode should be
used. **colorful** provides multiple ways to do so:

**(1) specify color mode globally via Python API**

.. code:: python

colorful.disable()
colorful.use_8bit_ansi_colors()
colorful.use_256_ansi_colors()
colorful.use_true_colors()

If you change the color mode during runtime it takes affect immediately
and globally.

**(2) enforce color mode globally via environment variable**

.. code:: bash

COLORFUL_DISABLE=1 python eggs.py # this process will not use ANY coloring
COLORFUL_FORCE_8BIT_COLORS=1 python eggs.py # this process will use 8 bit ANSI colors by default
COLORFUL_FORCE_256_COLORS=1 python eggs.py # this process will use 256 ANSI colors by default
COLORFUL_FORCE_TRUE_COLORS=1 python eggs.py # this process will use true colors by default

**(3) specify color mode locally via Python API (contextmanager)**

.. code:: python

with colorful.with_8bit_ansi_colors() as c:
print(c.italic_coral_on_beige('Hello world'))

with colorful.with_256_ansi_colors() as c:
print(c.italic_coral_on_beige('Hello world'))

with colorful.with_true_colors() as c:
print(c.italic_coral_on_beige('Hello world'))

Color palette
~~~~~~~~~~~~~

**colorful**'s Python API is based on *color names* like in
``colorful.bold_white_on_black('Hello')``. During runtime these *color
names* are translated into proper `ANSI escape
code <https://en.wikipedia.org/wiki/ANSI_escape_code>`__ sequences
supported by the *color mode* in use. However, all *color names* are
registered in a **color palette** which is basically a mapping between
the *color names* and it's corresponding RGB value. Very much like this:

.. code:: python

color_palette_example = {
'black': '#000000',
'white': '#FFFFFF',
}

*Note: Depending on the color mode which is used the RGB value will be
reduced to fit in the value domain of the color mode.*

The default color palette is the `X11
rgb.txt <https://en.wikipedia.org/wiki/X11_color_names>`__ palette -
it's shipped with *colorful*, thus, you don't have to provide your own.

**colorful** supports to update or replace the default color palette
with custom colors. The colors have to be specified as RGB hex or
channel values:

.. code:: python

# corporate identity colors
ci_colors = {
'mint': '#c5e8c8', # RGB hex value
'darkRed': '#c11b55', # RGB hex value
'lightBlue': (15, 138, 191) # RGB channel triplet
}

# replace the default palette with my custom one
colorful.use_palette(ci_colors)
# update the default palette with my custom one
colorful.update_palette(ci_colors)

# we can use these colors
print(colorful.italic_mint_on_darkRed('My company'))

Styles
~~~~~~

**colorful** supports some famous color palettes using what's called
*styles* in colorful:

.. code:: python

colorful.use_style('solarized')

# print the official solarized colors
print(colorful.yellow('yellow'), colorful.orange('orange'),
colorful.red('red'), colorful.magenta('magenta'),
colorful.violet('violet'), colorful.blue('blue'),
colorful.cyan('cyan'), colorful.green('green'))

The following styles are already supported:

* solarized
* monokai

*Note: if you know some awesome color palettes which could be a new
style in colorful, please contribute it!*

Temporarily change colorful settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**colorful** provides a hand full of convenient context managers to
change the colorful settings temporarily:

**(1) change color mode**

Use 8 bit colors:

.. code:: python

with colorful.with_8bit_ansi_colors() as c:
print(c.red('I am red'))

Use 256 colors:

.. code:: python

with colorful.with_256_ansi_colors() as c:
print(c.red('I am red'))

Use true colors:

.. code:: python

with colorful.with_true_colors() as c:
print(c.red('I am red'))

**(2) change color palette**

.. code:: python

# replace the entire color palette
with colorful.with_palette(my_palette) as c:
print(c.customRed('I am custom red'))

# update the color palette
with colorful.with_updated_palette(my_palette) as c:
print(c.customRed('I am custom red'))

**(3) change style**

.. code:: python

with colorful.with_style('solarized') as c:
print(c.red('I am solarized red'))

--------------

\*

.. raw:: html

<p align="center">

This project is published under `MIT <LICENSE>`__.A `Timo
Furrer <https://tuxtimo.me>`__ project.- :tada: -

.. raw:: html

</p>

-

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

colorful-0.3.1.tar.gz (21.5 kB view details)

Uploaded Source

Built Distribution

colorful-0.3.1-py2.py3-none-any.whl (21.9 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file colorful-0.3.1.tar.gz.

File metadata

  • Download URL: colorful-0.3.1.tar.gz
  • Upload date:
  • Size: 21.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for colorful-0.3.1.tar.gz
Algorithm Hash digest
SHA256 cfeeaae229a3bd2af6450609a4c2f1e2c1addc9fa0ff98cb51f297178814fd09
MD5 09218e51dc0c41ee90641f3e0b79ee38
BLAKE2b-256 f0fb70786755e4f3de1f837b4a2fb816b24ccb22e28ed236adae320d82228fa5

See more details on using hashes here.

Provenance

File details

Details for the file colorful-0.3.1-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for colorful-0.3.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 7e1a4021e797cb5bc344be12da935bc389a4a5fe32bf0164367b28296b5ac31f
MD5 438361d2cc446d8935bd71b1c1e8fd36
BLAKE2b-256 3abe88e8b3339cd3647aed54789469f035ec0fee4b93a83cddbe1d4f121cb35d

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page