Tinta, the a magical console output tool.
Project description
Tinta
Tinta is a magical console output tool for modern Python with support for printing in beautiful colors and with rich formatting, like bold and underline. It's so pretty, it's almost like a unicorn!
Features and Tinta Basics
Tinta takes a statically typed approach to handling rich-color console output.
In the past you might have fiddled with ANSI colors codes, or passed strings to a generic class, only to discover you typo'd one of them! (Yes, we've all been there).
But with Tinta, you can create your own colors.yaml
file, which dynamically generates builder pattern methods for Tinta
. If you add a color for wine
to your colors file, you can then use:
from tinta import Tinta
Tinta.load_colors('colors.yaml')
Tinta().wine('sip')
You can make a really simple drop-in print()
replacement:
Tinta('Our neural pathways have become accustomed '\
'to your sensory input patterns.').print()
Or you can create a variable to make things easier to read (or use control flows):
from tinta import Tinta
children = True
t = Tinta().mint('Fate.')
t.dark_gray('It protects')
t.underline().red('fools')
if chilren:
t.normal().pink('little children')
else:
t.normal().yellow('spotted cats')
t.dark_gray(', and ships named')
t.mint("Enterprise.").print()
OK, neat, so how is that like unicorns?
Glad you asked! Here are some pretty pictures:
Installation and Getting Started
Install Tinta:
pip install tinta
Add Tinta to your project, and optionally configure a path to your colors.yaml
file. This path can be relative, or absolute; the best way to make a path is using pathlib.Path()
.
from tinta import Tinta
# or to specify your custom colors,
# relative to your project's cwd:
from pathlib import Path
from tinta import Tinta
Tinta.load_colors(Path().cwd() / 'config/colors.yaml')
To discover what colors are available on your console:
Tinta.discover()
An example colors.yaml
file might look like:
# A list of ansi colors for your console.
green: 35
red: 1
blue: 32
yellow: 214
API Reference
Tinta (+ color methods)
Dynamic methods
These methods are loaded dynamically from your colors.yaml
file:
Tinta().green()
Tinta().red()
Tinta().blue()
Tinta().wine()
Tinta().my_color()
# etc.
Args
Each color method (and Tinta
) supports the following args. A copy if itself is then returned for method chaining:
*s (str)
– A sequence of one or more text strings, to be joined together.sep (str)
– Used to join segment strings. Defaults to' '
.
For example:
Tinta('A set', 'of strings', 'joined', 'with', 'semicolons', sep=';').print()
~ » A set;of strings;joined;with;semicolons
Attributes
All Tinta
and dynamic color methods will make available the following attributes:
color (str)
— A color string or ansi color code (int), e.g. 'white' or 42.style (str)
— A style string, e.g. 'bold', 'dim', 'underline'. Multiple styles are joined with a +.parts (list)
— A list of richly styled text segments.parts_plaintext (list)
— A list of unstyled text segments.
Built-in Methods
print()
– Prints to the console. See below for supported args.text(sep=' ') -> str
– Returns a compiled rich text stringplaintext(sep=' ') -> str
– Returns a compiled plaintext stringadd() -> self
– Adds segments using any previously defined styles.line() -> self
– Appends the contents preceded by a newline char (\n
).bold() -> self
– Sets segments to bold.underline() -> self
– Sets segments to underline.dim() -> self
– Sets segments to a darker, dimmed color.code() -> self
– Adds segments using the specified ansi code.normal() -> self
– Resets the style to default.reset() -> self
– Resets both style and color to default.
All style methods support the same arguments as Tinta
and dynamic color methods:
Tinta().underline('Underlined', 'text').print()
Tinta().bold('Bold', 'text', sep='+').print()
Tinta().dim('Dimmed', 'text', sep='_').print()
print()
Prints to the console. Probably the most important method, because if you don't print, you don't see anything at all!
A good first step in troubleshooting is checking that you remembered to print()
(ask me how I know...)
This supports all the built-in Python 3 print()
methods, too (sep
, end
, file
, flush
), as well as:
plaintext (bool)
– Prints in plaintext if set to Trueforce (bool)
– Forcibily prints to the console, even if'env::TINTA_STEALTH'
is set.
# Prints in plaintext
Tinta().purple('A bird').print(plaintext=True)
# Always prints, even if 'env::TINTA_STEALTH' is set)
Tinta().green('A plane').print(force=True)
It's also important to note that print()
doesn't make a variable unusable, it just resets and clears itself when called. This means you can do:
tint = Tinta()
tint.blue('A cloud').print()
tint.green('A tree').print()
add()
Sometimes you want the convenience of readability without changing styles, or you might want to use control flow to set a variable. For these, you can use add()
:
tint = Tinta().gray('I am a bear')
if you_love_bears:
tint.pink('and I love bears!')
else:
tint.add('but I am sad.')
tint.print()
For example:
Tinta('A set', 'of strings', 'joined', 'with', 'semicolons', sep=';').print()
~ » A set;of strings;joined;with;semicolons
line()
Adds your same text, but preceded by a newline.
Tinta('A cat').line('scratches').print()
# A cat
# scratches
code()
Sometimes you might want to use a color that wasn't defined in your colors.yaml
. For that, you can use .code()
.
Just set the code
arg to specify an ANSI color code:
Tinta().code('A bear', code=42).print()
This is useful for adding colors on the fly if they aren't defined in colors.yaml
.
Environment Variables
Sometimes it's useful to globally configure Tinta
on a system where you might want it to behave differently, without changing your source code. If these Environment variables are present on the system, they will be considered True.
TINTA_STEALTH
– Disables console output globally
TINTA_PLAINTEXT
– Disables rich console output, only printing plain text.
TINTA_SEPARATOR
– Changes the default separator (' '
) to this value.
Running Tests
To run tests, run the following command:
pip install -r requirements-text.txt
then simply:
python -m pytest -xv
Contributing
Contributions are welcome! Please send in a PR with a clear explanation of what you're adding and why, and where applicable, add tests to validate. Please read our code of conduct before contributing.
Acknowledgements
Special thanks to @katherinecodes for readme.so, @jessicaspacekat for rikeripsum.com, and ansicolors.
License
Tinta is licensed under both the MIT License and the Hippocratic License. Were a conflict or dispute to arise between these two licenses, the Hippocratic License license shall take precedence. Under its principles of Do No Harm, no portion of this software may be used to (or be a part of software that can be used to) cause, infer, encourage, incite, or otherwise lead to physical or verbal harm for any person or people, especially marginalized and underrepresented people.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for tinta-0.1.0a1.post3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 237be662ccb5635afd6919f5633d8a3eceb06d786965e9491f4bd43bcc230d25 |
|
MD5 | 1e81272b3d7b81f7f56fb8a91d1086e0 |
|
BLAKE2b-256 | ab3306a8cb6b989fbb5e9459c151e21e88a36e177f24a9733fa3ce0d002cad7f |