Skip to main content

Tatuagem, the boastful code signature suite

coverage

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 '@'

alt text

Wallpaper: Pattern-Argument Syntax Example

Using a pattern string for the background.

tatuagem "Tatuagem" --pattern '`':,:''

alt text

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

.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 named file.txt
  • Wildcards: *.log - ignores all files ending with .log
  • Directory patterns: node_modules/ - ignores all files in node_modules directory
  • Recursive patterns: build/** - ignores all files in build and 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

  1. Create a .tatignore file in the directory you want to tattoo (or copy .tatignore.example from this repository)
  2. Add patterns for files/directories to exclude
  3. Run tatuagem with --recurse-path as usual
# This will respect patterns in .tatignore
tatuagem "MyProject" --recurse-path ./my-project/

Development

pip install -e ".[dev]"
pytest
ruff check .

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.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tatuagem 0.1.15
File Size Uploaded Provenance Actions
tatuagem-0.1.15.tar.gz 15.3 MB With provenance Details for tatuagem-0.1.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tatuagem 0.1.15
File Interpreter ABI Platform Actions
tatuagem-0.1.15-py3-none-any.whl Python 3 none any Details for tatuagem-0.1.15-py3-none-any.whl

Total release size: 30.5 MB

Release files / tatuagem-0.1.15.tar.gz

Download URL tatuagem-0.1.15.tar.gz
Size 15.3 MB
Tags Source
SHA-256 checksum
How to use checksums
2f46ced7d235d2a12990c501e83ac96a11851bb8105414ee37c74e6f084f8d26
BLAKE2b-256 checksum
How to use checksums
42c602e615c30a378865eb229212531e99eb039af6957b392225b870bf2dbf0d
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 log

Release files / tatuagem-0.1.15-py3-none-any.whl

Download URL tatuagem-0.1.15-py3-none-any.whl
Size 15.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
4d7bb660aea191f0aa61b469f9e4870667028a7d35172a969de0f518282a0162
BLAKE2b-256 checksum
How to use checksums
851fa51eb6cbece8d45da6e847d9fafa6e6d96c4c7a0d655bf759549a66f4dc7
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 log

Security for tatuagem 0.1.15

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.

Select from 2 files

Attestation for tatuagem-0.1.15.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page