Tatuagem, the boastful code signature suite
Tatuagem is a tool to generate ASCII art signatures (tattoos) and apply them to your code files recursively.
Install
pip install tatuagem
Usage
tatuagem [text_input] [options]
Arguments
| Argument | Description | Default |
|---|---|---|
text_input |
The string you want to convert into a tattoo. Required if --file is not provided. |
None |
--text |
The character used to draw the text pixels. | 1 |
--backsplash |
The character used to fill the background. | 0 |
--font |
A bundled font (unicode-arial.ttf, Poppins-Medium.ttf) or a path to any .ttf/.otf file. |
unicode-arial.ttf |
--pattern |
A repeating string pattern to use for the background. Overrides --backsplash. |
None |
--margin |
Number of empty lines (margin) to add above and below the text. | 3 |
--recurse-path |
Path to a directory. Tatuagem will walk through this directory and prepend the tattoo to every file found. | None |
--file, -f |
Path to a file containing text. • Standard Mode: The content of the file is converted into the tattoo art. • Recurse Mode (with --recurse-path): The content of the file is used as-is for the tattoo (useful for pre-generated art). |
None |
--overwrite |
When using --recurse-path, this flag allows overwriting existing tattoos in files. Without this flag, files that are already tattooed will be skipped. |
False |
--dry-run |
With --recurse-path: list the files that would be tattooed without writing anything. |
False |
--check |
With --recurse-path: like --dry-run, but exit with status 1 if any file is missing its tattoo. Handy in CI. |
False |
--verbose, -v |
Print the settings in use to stderr. | False |
Examples
Basic Example
Generate a simple tattoo.
tatuagem "tatuagem"
Defaults: '1' for text, '0' for background, unicode-arial.ttf for font
Elaborate Syntax Example
Customizing the text and background characters.
tatuagem "L'appel du vide" --font 'unicode-arial.ttf' --backsplash '!' --text '@'
Wallpaper: Pattern-Argument Syntax Example
Using a pattern string for the background.
tatuagem "Tatuagem" --pattern '`':,:''
Recurse your project
Apply the generated tattoo to all files in test_tattoo/.
tatuagem "Tatuagem" --pattern '`':,:'' --recurse-path test_tattoo/
Recurse your project with a text file
Apply the contents of tests/aeaea.inc as a header to all files in test_tattoo/.
tatuagem --file tests/aeaea.inc --recurse-path test_tattoo/
Preview, or enforce in CI
tatuagem "Tatuagem" --recurse-path test_tattoo/ --dry-run # show what would change
tatuagem --file test_input.txt --recurse-path . --check # fail if anything is untattooed
Replace existing tattoos with --overwrite
Update existing tattoos in files that were already tattooed. Without this flag, already-tattooed files will be skipped.
tatuagem "New Tattoo" --recurse-path test_tattoo/ --overwrite
Features
✓ Shebang detection and preservation - files with #!/... shebangs keep them at the top
✓ Safe for npm projects - tattooed npm projects continue to work after tattooing
✓ Idempotent - Tattoos won't repeat on themselves if run multiple times
✓ .tatignore support - Exclude specific files and directories from tattooing
✓ Any character, any font - glyphs are rendered in memory, so accents, symbols and your own .ttf files all work
✓ Skips hidden directories - .git, .venv and friends are never touched
✓ Hundreds of languages, safely - block comments where the tattoo can't break out of them, line comments otherwise; files are skipped rather than corrupted. <?php, <?xml ?>, shebangs, encoding cookies and Dockerfile directives stay on top. Shared extensions (.pl, .m, .pro) are told apart by content, and extensionless scripts by their shebang
.tatignore
Using the same matching rules as .gitignore, you can create a .tatignore file in the root of the directory you want to tattoo to specify patterns of files and directories to exclude from tattooing.
.tatignore Syntax
The .tatignore file supports the following patterns:
- Simple filenames:
file.txt- ignores any file namedfile.txt - Wildcards:
*.log- ignores all files ending with.log - Directory patterns:
node_modules/- ignores all files innode_modulesdirectory - Recursive patterns:
build/**- ignores all files inbuildand its subdirectories - Comments: Lines starting with
#are treated as comments - Empty lines: Empty lines are ignored
.tatignore Example
# Ignore log files
*.log
# Ignore build artifacts
build/
dist/
# Ignore dependencies
node_modules/
# Ignore specific files
secrets.py
config.local.json
# Ignore test directories
tests/**
Usage with .tatignore
- Create a
.tatignorefile in the directory you want to tattoo (or copy.tatignore.examplefrom this repository) - Add patterns for files/directories to exclude
- Run tatuagem with
--recurse-pathas usual
# This will respect patterns in .tatignore
tatuagem "MyProject" --recurse-path ./my-project/
Development
pip install -e ".[dev]"
pytest
ruff check .
Coverage
- Languages —
python scripts/lang_coverage.pytattoos every folder of thetests/hello_worldscorpus and counts the languages that get a comment valid in that language. Languages that can't hold a comment at all (Brainfuck, Piet, JSON…) are listed in the report but left out of the figure. CI fails if it drops below 90%. - Tests —
pytest --cov.
Both badges are computed by the Coverage badges
workflow on every push to main and published to the badges branch.
This repo dogfoods itself: every source file carries a tattoo, and CI runs
tatuagem --file test_input.txt --recurse-path . --check to keep it that way.
New files can be tattooed with the same command minus --check.
Releases: python publish.py 0.1.16 runs the tests and the dogfood check, bumps the version,
tags, and pushes; the tag triggers the PyPI publish workflow.
Metadata
Release files for tatuagem 0.1.16
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tatuagem-0.1.16.tar.gz | 15.3 MB | With provenance | Details for tatuagem-0.1.16.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tatuagem-0.1.16-py3-none-any.whl | Python 3 | none | any | Details for tatuagem-0.1.16-py3-none-any.whl |
Total release size: 30.6 MB
Release files / tatuagem-0.1.16.tar.gz
| Download URL | tatuagem-0.1.16.tar.gz |
|---|---|
| Size | 15.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1a15da54d962c12fc7462c2afc68637d7e048b223335397fc5e3ff676164b482
|
|
BLAKE2b-256 checksum How to use checksums |
9d3209605c3d3790f860e3601b3f6c4d1c1eb9cb13e3018d641b98f6e60be45b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / tatuagem-0.1.16-py3-none-any.whl
| Download URL | tatuagem-0.1.16-py3-none-any.whl |
|---|---|
| Size | 15.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a192b4eb7bc518a5fed6b04a60e0bcd0c641d65bc33e687403c6eab1bd09e01e
|
|
BLAKE2b-256 checksum How to use checksums |
dd894f93d560a51db075ba0df0adf75ff2582b8fcf5a1fefa9a59278bbf5159e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logSecurity for tatuagem 0.1.16
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tatuagem-0.1.16.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.