This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

A python module for using terminal colors in linux. 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

Modules

There are no dependencies required for importing this library on Linux, however:

Installation:

Colr is listed on PyPi, and can be installed using pip:

pip install colr

Or you can clone the repo on GitHub and install it from the command line:

git clone https://github.com/welbornprod/colr.git
cd colr
python3 setup.py install

Examples:

Simple:

from colr import color
print(color('Hello world.', fore='red', style='bright'))

Chainable:

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:

from colr import color
# Invalid color names/numbers raise a ValueError.
print(color('Hello world', fore=125, back=80))

Chainable:

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:

from colr import color
print(color('Hello there.', fore=(255, 0, 0), back=(0, 0, 0)))

Chainable:

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.'))

Other methods:

The Colr object has several helper methods. The color() method returns a str, but the rest return a Colr instance so they can be chained. A chainable version of color() does exist (chained()), but it’s not really needed outside of the colr module itself.

Colr.center

Like str.center, except it ignores escape codes.

Colr('Hello', fore='green').center(40)

# This also ignores escape codes:
'{:^40}'.format(Colr('Hello', fore='green'))

Colr.format

Like str.format, except it operates on Colr.data.

Colr('Hello').blue(' {}').red(' {}').format('my', 'friend').center(40)

Colr.gradient

Like rainbow(), except a known name can be passed to choose the color (same names as the basic fore colors).

(Colr('Wow man, ').gradient(name='red')
.gradient('what a neat feature that is.', name='blue'))

Colr.gradient_black

Builds a black and white gradient. The default starting color is black, but white will be used if reverse=True is passed. Like the other gradient/rainbow functions, if you pass a fore color, the background will be gradient.

(C('Why does it have to be black or white?').gradient_black(step=3)
.gradient_black(' ' * 10, fore='reset', reverse=True))

Colr.gradient_rgb

Uses true color (rgb codes) to build a gradient from one rgb value to another. Just like the other gradient/rainbow methods, passing a fore color means the background is gradient.

When using linemode=True (where each line is a separate gradient), you can “shift” the gradient left or right for each line using movefactor=N. N can be positive or negative to change the direction of the shift, or None / 0 to not shift at all (the default is None).

C('This is pretty fancy.').gradient_rgb((0, 0, 255), (255, 0, 0), step=5)

Colr.join

Joins Colr instances or other types together. If anything except a Colr is passed, str(thing) is called before joining. join accepts multiple args, and any list-like arguments are flattened at least once (simulating str.join args).

Colr('alert', 'red').join('[', ']').yellow(' This is neat.')

Colr.ljust

Like str.ljust, except it ignores escape codes.

Colr('Hello', 'blue').ljust(40)

# This also ignores escape codes:
'{:<40}'.format(Colr('Hello', 'blue'))

Colr.rainbow

Beautiful rainbow gradients in the same style as lolcat. This method is incapable of doing black and white gradients. That’s what gradient_black() is for.

Colr('This is really pretty.').rainbow(freq=.5)

If your terminal supports it, you can use true color (rgb codes) by using rgb_mode=True:

Colr('This is even prettier.').rainbow(rgb_mode=True)

Colr.rgb

This will set the fore color using true color (rgb codes). It accepts the same args as the other chained methods, except the r, g, and b values should be the first arguments.

Colr().rgb(255, 55, 55).bgwhite('Test')

It has a background version called b_rgb.

Colr().b_rgb(255, 255, 255).rgb(255, 55, 55, 'Test')

Colr.rjust

Like str.rjust, except it ignores escape codes.

Colr('Hello', 'blue').rjust(40)

# This also ignores escape codes:
'{:>40}'.format(Colr('Hello', 'blue'))

Colr.str

The same as calling str() on a Colr instance.

Colr('test', 'blue').str() == str(Colr('test', 'blue'))

Colr.stripped

The same as calling strip_codes(Colr().data).

data = 'Testing this.'
colored = Colr(data, fore='red')
data == colored.stripped()

Colr.__add__

Strings can be added to a Colr and the other way around. Both return a Colr instance.

Colr('test', 'blue') + 'this' == Colr('').join(Colr('test', 'blue'), 'this')
'test' + Colr('this', 'blue') == Colr('').join('test', Colr(' this', 'blue'))

Colr.__bytes__

Calling bytes() on a Colr is like calling Colr().data.encode(). For custom encodings, you can use str(Colr()).encode(my_encoding).

bytes(Colr('test')) = 'test'.encode()

Colr.__call__

Colr instances are callable themselves. Calling a Colr will append text to it, with the same arguments as color().

Colr('One', 'blue')(' formatted', 'red')(' string.', 'blue')

Colr.__eq__, __ne__

Colr instances can also be compared with other Colr instances. They are equal if self.data is equal to other.data.

Colr('test', 'blue') == Colr('test', 'blue')
Colr('test', 'blue') != Colr('test', 'red')

Colr.__lt__, __gt__, __le__, __ge__

Escape codes are stripped for less-than/greater-than comparisons.

Colr('test', 'blue') < Colr('testing', 'blue')

Colr.__getitem__

Escape codes are stripped when subscripting/indexing.

Colr('test', 'blue')[2] == Colr('s')
Colr('test', 'blue')[1:3] == Colr('es')

Colr.__hash__

Hashing a Colr just means hashing Colr().data, but this works:

hash(Colr('test', 'blue')) == hash(Colr('test', 'blue'))

Colr.__mul__

Colr instances can be multiplied by an int to build color strings. These are all equal:

Colr('*', 'blue') * 2
Colr('*', 'blue') + Colr('*', 'blue')
Colr('').join(Colr('*', 'blue'), Colr('*', 'blue'))

Color Translation:

The colr module also includes several tools for converting from one color value to another:

ColorCode

A class that automatically converts hex, rgb, or terminal codes to the other types. They can be accessed through the attributes code, hexval, and rgb.

from colr import ColorCode
print(ColorCode(30))
# Terminal:  30, Hex: 008787, RGB:   0, 135, 135

print(ColorCode('de00fa'))
# Terminal: 165, Hex: de00fa, RGB: 222,   0, 250

print(ColorCode((75, 50, 178)))
# Terminal:  61, Hex: 4b32b2, RGB:  75,  50, 178

Printing ColorCode(45).example() will show the actual color in the terminal.

hex2rgb

Converts a hex color (#000000) to RGB (0, 0, 0).

hex2term

Converts a hex color to terminal code number.

from colr import color, hex2term
print(color('Testing', hex2term('#FF0000')))

hex2termhex

Converts a hex color to it’s closest terminal color in hex.

from colr import hex2termhex
hex2termhex('005500') == '005f00'

rgb2hex

Converts an RGB value (0, 0, 0) to it’s hex value (000000).

rgb2term

Converts an RGB value to terminal code number.

from colr import color, rgb2term
print(color('Testing', rgb2term(0, 255, 0)))

rgb2termhex

Converts an RGB value to it’s closest terminal color in hex.

from colr import rgb2termhex
rgb2termhex(0, 55, 0) == '005f00'

term2hex

Converts a terminal code number to it’s hex value.

from colr import term2hex
term2hex(30) == '008787'

term2rgb

Converts a terminal code number to it’s RGB value.

from colr import term2rgb
term2rgb(30) == (0, 135, 135)

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.

colr --help

Basic usage involves passing text, or piping stdin data and setting the colors by position or flag.

# 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:

colr "Test" -s "bright"

Extended and True colors are supported:

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 emulation:

fortune | colr --rainbow

The colr tool does not read files, but it’s not a problem:

cat myfile.txt | colr --gradient red

Also see ccat.

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.

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 or a pull request.


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

Basic colors are supported on Windows through the colorama library. It is only imported if platform.system() == 'Windows'. It provides a wrapper around stdout and stderr to make basic ansi codes work. If the import fails, then all color codes are disabled (as if colr.disable() was called). I booted into Windows 8 for the first time in months to make this little feature happen, only to discover that the color situation for CMD and PowerShell really sucks. If you think you can help improve the colr package for windows, please see the contributing section.

Misc.

This library may be a little too flexible:

from colr import Colr as C
warnmsg = lambda s: C('warning', 'red').join('[', ']')(' ').green(s)
print(warnmsg('The roof is on fire again.'))

The possibilities are endless.

Release History

Release History

0.7.5

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.6.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.5.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.5.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.5.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.3.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.1-1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.7-2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.3-1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.0.2-2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
Colr-0.7.5.tar.gz (57.7 kB) Copy SHA256 Checksum SHA256 Source Feb 23, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting