1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
.. The colorzero color library
..
.. Copyright (c) 2016-2019 Dave Jones <dave@waveform.org.uk>
..
.. SPDX-License-Identifier: BSD-3-Clause
.. _api_color:
===
API
===
.. currentmodule:: colorzero
The colorzero library includes a comprehensive :class:`Color` class which
is capable of converting between numerous color representations and calculating
color differences. Various ancillary classes can be used to manipulate aspects
of a color.
Color Class
===========
This the primary class in the package, and often the only class you'll need or
want to interact with. It has an extremely flexible constructor, along with
numerous explicit constructors, and attributes for conversion to other color
systems.
.. autoclass:: Color
.. _format:
Format Strings
==============
Instances of :class:`Color` can be used in format strings to output various
representations of a color, including HTML sequences and ANSI escape sequences
to color terminal output. Format specifications can be used to modify the
output to support different terminal types. For example:
.. code-block:: pycon
>>> red = Color('red')
>>> green = Color('green')
>>> blue = Color('#47b')
>>> print("{red:html}".format(red=red))
#ff0000
>>> print(repr("{red}Red{red:0} Alert!".format(red=red)))
'\\x1b[1;31mRed\\x1b[0m Alert!'
>>> print(repr("The grass is {green:16m}greener{green:0}.".format(
... green=green)))
'The grass is \\x1b[38;2;0;128;0mgreener\\x1b[0m.'
>>> print(repr("{blue:b16m}Blue skies{blue:0}".format(blue=blue)))
'\\x1b[48;2;68;119;187mBlue skies\\x1b[0m'
The format specification is one of:
* "html" - the color will be output as the common 7-character HTML represention
of #RRGGBB where RR, GG, and BB are the red, green and blue components
expressed as a single hexidecimal byte
* "css" or "cssrgb" - the color will be output in CSS' functional notation
rgb(*r*, *g*, *b*) where *r*, *g*, and *b* are decimal representations of the
red, green, and blue components in the range 0 to 255
* "csshsl" - the color will be output in CSS' function notation hue(*h*\deg,
*s*\%, *l*\%) where *h*, *s*, and *l* are the hue (expressed in degrees),
saturation, and lightness (expressed as percentages)
* One of the ANSI format specifications which consist of an optional foreground
/ background specifier (the letters "f" or "b") followed by an optional
terminal type identifer, which is one of:
- "8" - the default, indicating only the original 8 DOS colors are supported
(technically, 16 foreground colors are supported via use of the "bold"
style for "intense" colors)
- "256" - indicates the terminal supports 256 colors via `8-bit color ANSI
codes`_
- "16m" - indicating the terminal supports ~16 million colors via `24-bit
color ANSI codes`_
Alternately, "0" can be specified indicating that the style should be
reset. If specified with the optional foreground / background specifier,
"0" resets only the foreground / background color. If specified alone it
resets all styles. More formally:
.. code-block:: bnf
<term_fore_back> ::= "" | "f" | "b"
<term_type> ::= "" | "0" | "8" | "256" | "16m"
<term> ::= <term_fore_back> <term_type>
<html> ::= "html"
<css> ::= "css" ("rgb" | "hsl")?
<format_spec> ::= <html> | <css> | <term>
.. versionadded:: 1.1
The ability to output ANSI codes via format strings, and the
customization of :func:`repr` output.
.. versionadded:: 1.2
The ability to output HTML and CSS representations via format strings
.. _8-bit color ANSI codes: https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
.. _24-bit color ANSI codes: https://en.wikipedia.org/wiki/ANSI_escape_code#24-bit
Manipulation Classes
====================
These manipulation classes are used in conjunction with the standard arithmetic
addition, subtraction, and multiplication operators to calculate new
:class:`Color` instances.
.. autoclass:: Red
.. autoclass:: Green
.. autoclass:: Blue
.. autoclass:: Hue
.. autoclass:: Saturation
.. autoclass:: Lightness
.. autoclass:: Luma
Difference Functions
====================
.. autofunction:: euclid
.. autofunction:: cie1976
.. autofunction:: cie1994g
.. autofunction:: cie1994t
.. autofunction:: ciede2000
Easing Functions
================
These functions can be used with the :meth:`Color.gradient` method to control
the progression of the fade between the two colors.
.. autofunction:: linear
.. autofunction:: ease_in
.. autofunction:: ease_out
.. autofunction:: ease_in_out
|
