# Tinty
Tinty is a tiny Python library for terminal text colorization and highlighting, inspired by the Ruby colorize gem. Now with a modern, production-safe API featuring Pathlib-inspired operator chaining!
[](https://codecov.io/gh/jim-my/colorize)
[](https://badge.fury.io/py/tinty)
[](https://pypi.org/project/tinty)
## ✨ Features
- **🔒 Production Safe**: No monkey patching or global state pollution
- **🎯 Multiple APIs**: Choose your preferred style - fluent, functional, or global
- **🔗 Pathlib-inspired**: Elegant operator chaining with `|` and `>>` operators
- **🌈 Comprehensive**: Support for all ANSI colors, backgrounds, and text styles
- **⚡ High Performance**: Efficient implementation with minimal overhead
- **🧪 Well Tested**: Comprehensive test suite with 100+ tests
- **📦 Zero Dependencies**: Pure Python implementation
- **🖥️ Cross Platform**: Works on Linux, macOS, and Windows
- **🛠️ CLI Tool**: Command-line interface for colorizing text
## 🚀 Installation
```bash
pip install tinty
```
## 🖼️ See It In Action
**Simple API, beautiful results:**
```python
print(colored("Success") | GREEN | BOLD)
print(colored("Warning") | YELLOW)
print(colored("Error") | RED | BOLD)
print(colored("Info") | BLUE)
```
**CLI pattern highlighting:**
```bash
echo "hello world" | tinty "l.*" yellow
echo "hello world" | tinty "(ll).*(ld)" red,bg_blue blue,bg_red
```
**Complex styling made easy:**
```python
print(colored("SYSTEM ALERT") | RED | BOLD | BG_WHITE)
print(str(colored("DEBUG") | DIM) + " - Application started")
print(str(colored("INFO") | BLUE) + " - User logged in")
print(str(colored("WARNING") | YELLOW | BOLD) + " - Memory usage high")
print(str(colored("ERROR") | RED | BOLD) + " - Database connection failed")
```
**Regex pattern highlighting:**
```python
text = "The quick brown fox jumps over the lazy dog"
highlighted = colored(text).highlight(r"(quick)|(fox)|(lazy)", ["red", "blue", "green"])
print(highlighted)
```
## 🎨 Quick Start
### Modern Enhanced API (Recommended)
```python
from tinty import colored, C, txt, RED, GREEN, BLUE, YELLOW, BOLD, BG_WHITE, UNDERLINE
# Type-safe constants with operator chaining (RECOMMENDED)
print(colored("Success") | GREEN | BOLD)
print(txt("Warning") | YELLOW)
print(colored("Error") | RED | BOLD | BG_WHITE)
print(txt("Info") >> BLUE >> UNDERLINE)
# Global convenience object with constants
print(C("✓ Tests passing") | GREEN)
print(C("✗ Build failed") | RED)
print(C("Processing...") | BLUE | BOLD)
# Legacy method chaining (still works but uses internal string literals)
print(colored("Success").green().bold())
print(txt("Warning").yellow())
```
### Real-World Examples
```python
from tinty import (
colored, C, txt, ColorString,
RED, GREEN, BLUE, YELLOW, BOLD, DIM, BG_WHITE, BLINK
)
# Log levels with type-safe constants
print(C("DEBUG") | DIM + " - Application started")
print(colored("INFO") | BLUE + " - User logged in")
print(txt("WARNING") | YELLOW | BOLD + " - Memory usage high")
print(ColorString("ERROR") | RED | BOLD + " - Database connection failed")
# CLI status indicators (direct color methods still work)
print(f"{C.green('✓')} File saved successfully")
print(f"{C.yellow('⚠')} Configuration outdated")
print(f"{C.red('✗')} Permission denied")
# Complex chaining with constants
alert = (colored("SYSTEM ALERT")
| RED
| BOLD
| BG_WHITE
| BLINK)
print(alert)
```
### Pattern Highlighting
```python
from tinty import colored
# Highlight search terms
text = "The quick brown fox jumps over the lazy dog"
highlighted = colored(text).highlight(r"(quick)|(fox)|(lazy)", ["red", "blue", "green"])
print(highlighted)
# Syntax highlighting
code = "def hello_world():"
result = colored(code).highlight(r"\b(def)\b", ["blue"])
print(result)
```
## 📋 Available Colors and Styles
### Foreground Colors
`red`, `green`, `blue`, `yellow`, `magenta`, `cyan`, `white`, `black`, `lightred`, `lightgreen`, `lightblue`, `lightyellow`, `lightmagenta`, `lightcyan`, `lightgray`, `darkgray`
### Background Colors
`bg_red`, `bg_green`, `bg_blue`, `bg_yellow`, `bg_magenta`, `bg_cyan`, `bg_white`, `bg_black`, `bg_lightred`, `bg_lightgreen`, `bg_lightblue`, `bg_lightyellow`, `bg_lightmagenta`, `bg_lightcyan`, `bg_lightgray`, `bg_darkgray`
### Text Styles
`bright`/`bold`, `dim`, `underline`, `blink`, `invert`/`swapcolor`, `hidden`, `strikethrough`
## 🔒 Type-Safe Color Constants (New!)
Use constants instead of error-prone string literals:
```python
from tinty import colored, RED, GREEN, BLUE, YELLOW, BOLD, BG_WHITE
# ✅ Type-safe with IDE autocompletion and error checking
error_msg = colored("CRITICAL") | RED | BOLD | BG_WHITE
success_msg = colored("SUCCESS") | GREEN | BOLD
warning_msg = colored("WARNING") | YELLOW
# ❌ Error-prone string literals
error_msg = colored("CRITICAL") | "red" | "typo" # Runtime error!
```
**Benefits:**
- 🔍 **IDE Autocompletion**: Get suggestions for valid colors
- 🛡️ **Type Checking**: Catch typos at development time
- 📝 **Self-Documenting**: Clear, readable code
- 🔄 **Refactoring Safe**: Rename constants across codebase
- ⚡ **No Runtime Errors**: Invalid colors caught early
**Available Constants:**
- **Colors**: `RED`, `GREEN`, `BLUE`, `YELLOW`, `MAGENTA`, `CYAN`, `WHITE`, `BLACK`
- **Light Colors**: `LIGHTRED`, `LIGHTGREEN`, `LIGHTBLUE`, etc.
- **Backgrounds**: `BG_RED`, `BG_GREEN`, `BG_BLUE`, etc.
- **Styles**: `BOLD`, `BRIGHT`, `DIM`, `UNDERLINE`, `BLINK`, `INVERT`
## 🎭 API Styles
Choose the style that fits your needs:
### 1. Type-Safe Constants (Recommended)
```python
from tinty import colored, txt, RED, BLUE, BOLD, UNDERLINE
colored("hello") | RED | BOLD
txt("world") | BLUE | UNDERLINE
```
### 2. Global Object with Constants
```python
from tinty import C, RED, BOLD
C.red("hello") # Direct color method
C("hello") | RED | BOLD # Factory with type-safe constants
C("hello", "red") # Direct colorization (legacy)
```
### 3. Enhanced ColorString with Constants
```python
from tinty import ColorString, RED, BOLD, BG_YELLOW
ColorString("hello") | RED | BOLD | BG_YELLOW
```
### 4. Legacy Method Chaining (Still Supported)
```python
from tinty import colored, txt
# Method chaining (uses internal string literals)
colored("hello").red().bold()
txt("world").blue().underline()
# Mixed with operators (not recommended - inconsistent)
colored("Mixed").red() | "bright"
```
## 🛠️ Command Line Interface
```bash
# Basic usage
echo "hello world" | tinty 'l' red
# Pattern highlighting with groups
echo "hello world" | tinty '(h.*o).*(w.*d)' red blue
# List available colors
tinty --list-colors
# Case sensitive matching
echo "Hello World" | tinty --case-sensitive 'Hello' green
```
## 🔄 Legacy API (Still Supported)
The original API remains fully supported for backward compatibility:
```python
from tinty import Colorize, ColorizedString
# Original Colorize class
colorizer = Colorize()
print(colorizer.colorize("hello", "red"))
# Original ColorizedString
cs = ColorizedString("hello")
print(cs.colorize("blue"))
```
## 🧪 Development
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=tinty
# Run specific test file
pytest tests/test_enhanced.py
```
### Code Quality
```bash
# Format and lint
ruff format --preview .
ruff check --preview .
# Type checking
mypy src/
# Run pre-commit hooks
pre-commit run --all-files
```
## 📖 Examples
See the `examples/` directory for more comprehensive examples:
- `examples/quickstart.py` - Basic usage patterns
- `examples/enhanced_demo.py` - Full enhanced API demonstration
## Version Management
This project uses automated versioning via git tags:
- Versions are managed by `setuptools-scm` based on git tags
- `poetry-dynamic-versioning` integrates this with Poetry builds
- To release: `git tag v1.2.3 && git push --tags`
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:
1. Run the pre-commit hooks: `pre-commit run --all-files`
2. Add tests for new features
3. Update documentation as needed
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Inspired by the Ruby [colorize](https://github.com/fazibear/colorize) gem
- Built with modern Python best practices
- Designed for production safety and developer experience
Raw data
{
"_id": null,
"home_page": "https://github.com/jim-my/tinty",
"name": "tinty",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "color, terminal, ansi, highlighting, text, cli",
"author": "Jimmy",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/79/a8/0c02dc3d0cdbe6b38d82b8be9dfe504995961695ca65d6043c00c6e1d451/tinty-0.1.10.tar.gz",
"platform": null,
"description": "# Tinty\n\nTinty is a tiny Python library for terminal text colorization and highlighting, inspired by the Ruby colorize gem. Now with a modern, production-safe API featuring Pathlib-inspired operator chaining!\n\n\n[](https://codecov.io/gh/jim-my/colorize)\n[](https://badge.fury.io/py/tinty)\n[](https://pypi.org/project/tinty)\n\n## \u2728 Features\n\n- **\ud83d\udd12 Production Safe**: No monkey patching or global state pollution\n- **\ud83c\udfaf Multiple APIs**: Choose your preferred style - fluent, functional, or global\n- **\ud83d\udd17 Pathlib-inspired**: Elegant operator chaining with `|` and `>>` operators\n- **\ud83c\udf08 Comprehensive**: Support for all ANSI colors, backgrounds, and text styles\n- **\u26a1 High Performance**: Efficient implementation with minimal overhead\n- **\ud83e\uddea Well Tested**: Comprehensive test suite with 100+ tests\n- **\ud83d\udce6 Zero Dependencies**: Pure Python implementation\n- **\ud83d\udda5\ufe0f Cross Platform**: Works on Linux, macOS, and Windows\n- **\ud83d\udee0\ufe0f CLI Tool**: Command-line interface for colorizing text\n\n## \ud83d\ude80 Installation\n\n```bash\npip install tinty\n```\n\n## \ud83d\uddbc\ufe0f See It In Action\n\n**Simple API, beautiful results:**\n\n```python\nprint(colored(\"Success\") | GREEN | BOLD)\nprint(colored(\"Warning\") | YELLOW)\nprint(colored(\"Error\") | RED | BOLD)\nprint(colored(\"Info\") | BLUE)\n```\n\n\n**CLI pattern highlighting:**\n\n```bash\necho \"hello world\" | tinty \"l.*\" yellow\necho \"hello world\" | tinty \"(ll).*(ld)\" red,bg_blue blue,bg_red\n```\n\n\n**Complex styling made easy:**\n\n```python\nprint(colored(\"SYSTEM ALERT\") | RED | BOLD | BG_WHITE)\nprint(str(colored(\"DEBUG\") | DIM) + \" - Application started\")\nprint(str(colored(\"INFO\") | BLUE) + \" - User logged in\")\nprint(str(colored(\"WARNING\") | YELLOW | BOLD) + \" - Memory usage high\")\nprint(str(colored(\"ERROR\") | RED | BOLD) + \" - Database connection failed\")\n```\n\n\n**Regex pattern highlighting:**\n\n```python\ntext = \"The quick brown fox jumps over the lazy dog\"\nhighlighted = colored(text).highlight(r\"(quick)|(fox)|(lazy)\", [\"red\", \"blue\", \"green\"])\nprint(highlighted)\n```\n\n\n## \ud83c\udfa8 Quick Start\n\n### Modern Enhanced API (Recommended)\n\n```python\nfrom tinty import colored, C, txt, RED, GREEN, BLUE, YELLOW, BOLD, BG_WHITE, UNDERLINE\n\n# Type-safe constants with operator chaining (RECOMMENDED)\nprint(colored(\"Success\") | GREEN | BOLD)\nprint(txt(\"Warning\") | YELLOW)\nprint(colored(\"Error\") | RED | BOLD | BG_WHITE)\nprint(txt(\"Info\") >> BLUE >> UNDERLINE)\n\n# Global convenience object with constants\nprint(C(\"\u2713 Tests passing\") | GREEN)\nprint(C(\"\u2717 Build failed\") | RED)\nprint(C(\"Processing...\") | BLUE | BOLD)\n\n# Legacy method chaining (still works but uses internal string literals)\nprint(colored(\"Success\").green().bold())\nprint(txt(\"Warning\").yellow())\n```\n\n### Real-World Examples\n\n```python\nfrom tinty import (\n colored, C, txt, ColorString,\n RED, GREEN, BLUE, YELLOW, BOLD, DIM, BG_WHITE, BLINK\n)\n\n# Log levels with type-safe constants\nprint(C(\"DEBUG\") | DIM + \" - Application started\")\nprint(colored(\"INFO\") | BLUE + \" - User logged in\")\nprint(txt(\"WARNING\") | YELLOW | BOLD + \" - Memory usage high\")\nprint(ColorString(\"ERROR\") | RED | BOLD + \" - Database connection failed\")\n\n# CLI status indicators (direct color methods still work)\nprint(f\"{C.green('\u2713')} File saved successfully\")\nprint(f\"{C.yellow('\u26a0')} Configuration outdated\")\nprint(f\"{C.red('\u2717')} Permission denied\")\n\n# Complex chaining with constants\nalert = (colored(\"SYSTEM ALERT\")\n | RED\n | BOLD\n | BG_WHITE\n | BLINK)\nprint(alert)\n```\n\n### Pattern Highlighting\n\n```python\nfrom tinty import colored\n\n# Highlight search terms\ntext = \"The quick brown fox jumps over the lazy dog\"\nhighlighted = colored(text).highlight(r\"(quick)|(fox)|(lazy)\", [\"red\", \"blue\", \"green\"])\nprint(highlighted)\n\n# Syntax highlighting\ncode = \"def hello_world():\"\nresult = colored(code).highlight(r\"\\b(def)\\b\", [\"blue\"])\nprint(result)\n```\n\n## \ud83d\udccb Available Colors and Styles\n\n### Foreground Colors\n`red`, `green`, `blue`, `yellow`, `magenta`, `cyan`, `white`, `black`, `lightred`, `lightgreen`, `lightblue`, `lightyellow`, `lightmagenta`, `lightcyan`, `lightgray`, `darkgray`\n\n### Background Colors\n`bg_red`, `bg_green`, `bg_blue`, `bg_yellow`, `bg_magenta`, `bg_cyan`, `bg_white`, `bg_black`, `bg_lightred`, `bg_lightgreen`, `bg_lightblue`, `bg_lightyellow`, `bg_lightmagenta`, `bg_lightcyan`, `bg_lightgray`, `bg_darkgray`\n\n### Text Styles\n`bright`/`bold`, `dim`, `underline`, `blink`, `invert`/`swapcolor`, `hidden`, `strikethrough`\n\n## \ud83d\udd12 Type-Safe Color Constants (New!)\n\nUse constants instead of error-prone string literals:\n\n```python\nfrom tinty import colored, RED, GREEN, BLUE, YELLOW, BOLD, BG_WHITE\n\n# \u2705 Type-safe with IDE autocompletion and error checking\nerror_msg = colored(\"CRITICAL\") | RED | BOLD | BG_WHITE\nsuccess_msg = colored(\"SUCCESS\") | GREEN | BOLD\nwarning_msg = colored(\"WARNING\") | YELLOW\n\n# \u274c Error-prone string literals\nerror_msg = colored(\"CRITICAL\") | \"red\" | \"typo\" # Runtime error!\n```\n\n**Benefits:**\n- \ud83d\udd0d **IDE Autocompletion**: Get suggestions for valid colors\n- \ud83d\udee1\ufe0f **Type Checking**: Catch typos at development time\n- \ud83d\udcdd **Self-Documenting**: Clear, readable code\n- \ud83d\udd04 **Refactoring Safe**: Rename constants across codebase\n- \u26a1 **No Runtime Errors**: Invalid colors caught early\n\n**Available Constants:**\n- **Colors**: `RED`, `GREEN`, `BLUE`, `YELLOW`, `MAGENTA`, `CYAN`, `WHITE`, `BLACK`\n- **Light Colors**: `LIGHTRED`, `LIGHTGREEN`, `LIGHTBLUE`, etc.\n- **Backgrounds**: `BG_RED`, `BG_GREEN`, `BG_BLUE`, etc.\n- **Styles**: `BOLD`, `BRIGHT`, `DIM`, `UNDERLINE`, `BLINK`, `INVERT`\n\n## \ud83c\udfad API Styles\n\nChoose the style that fits your needs:\n\n### 1. Type-Safe Constants (Recommended)\n```python\nfrom tinty import colored, txt, RED, BLUE, BOLD, UNDERLINE\n\ncolored(\"hello\") | RED | BOLD\ntxt(\"world\") | BLUE | UNDERLINE\n```\n\n### 2. Global Object with Constants\n```python\nfrom tinty import C, RED, BOLD\n\nC.red(\"hello\") # Direct color method\nC(\"hello\") | RED | BOLD # Factory with type-safe constants\nC(\"hello\", \"red\") # Direct colorization (legacy)\n```\n\n### 3. Enhanced ColorString with Constants\n```python\nfrom tinty import ColorString, RED, BOLD, BG_YELLOW\n\nColorString(\"hello\") | RED | BOLD | BG_YELLOW\n```\n\n### 4. Legacy Method Chaining (Still Supported)\n```python\nfrom tinty import colored, txt\n\n# Method chaining (uses internal string literals)\ncolored(\"hello\").red().bold()\ntxt(\"world\").blue().underline()\n\n# Mixed with operators (not recommended - inconsistent)\ncolored(\"Mixed\").red() | \"bright\"\n```\n\n## \ud83d\udee0\ufe0f Command Line Interface\n\n```bash\n# Basic usage\necho \"hello world\" | tinty 'l' red\n\n# Pattern highlighting with groups\necho \"hello world\" | tinty '(h.*o).*(w.*d)' red blue\n\n# List available colors\ntinty --list-colors\n\n# Case sensitive matching\necho \"Hello World\" | tinty --case-sensitive 'Hello' green\n```\n\n\n## \ud83d\udd04 Legacy API (Still Supported)\n\nThe original API remains fully supported for backward compatibility:\n\n```python\nfrom tinty import Colorize, ColorizedString\n\n# Original Colorize class\ncolorizer = Colorize()\nprint(colorizer.colorize(\"hello\", \"red\"))\n\n# Original ColorizedString\ncs = ColorizedString(\"hello\")\nprint(cs.colorize(\"blue\"))\n```\n\n## \ud83e\uddea Development\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=tinty\n\n# Run specific test file\npytest tests/test_enhanced.py\n```\n\n### Code Quality\n\n```bash\n# Format and lint\nruff format --preview .\nruff check --preview .\n\n# Type checking\nmypy src/\n\n# Run pre-commit hooks\npre-commit run --all-files\n```\n\n## \ud83d\udcd6 Examples\n\nSee the `examples/` directory for more comprehensive examples:\n\n- `examples/quickstart.py` - Basic usage patterns\n- `examples/enhanced_demo.py` - Full enhanced API demonstration\n\n## Version Management\n\nThis project uses automated versioning via git tags:\n\n- Versions are managed by `setuptools-scm` based on git tags\n- `poetry-dynamic-versioning` integrates this with Poetry builds\n- To release: `git tag v1.2.3 && git push --tags`\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. Make sure to:\n\n1. Run the pre-commit hooks: `pre-commit run --all-files`\n2. Add tests for new features\n3. Update documentation as needed\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Inspired by the Ruby [colorize](https://github.com/fazibear/colorize) gem\n- Built with modern Python best practices\n- Designed for production safety and developer experience\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for terminal text colorization and highlighting",
"version": "0.1.10",
"project_urls": {
"Documentation": "https://github.com/jim-my/tinty",
"Homepage": "https://github.com/jim-my/tinty",
"Repository": "https://github.com/jim-my/tinty"
},
"split_keywords": [
"color",
" terminal",
" ansi",
" highlighting",
" text",
" cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9442809f41ecc5def738e8737766226518d9576592f41ca77125becfb5230479",
"md5": "62e9015f2079bdf0b835bbcc45f58349",
"sha256": "d2b1d3b064bcd16a85ec2e1a472b31f57b2114a375885957e9a7cf04f92dfb63"
},
"downloads": -1,
"filename": "tinty-0.1.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62e9015f2079bdf0b835bbcc45f58349",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 15121,
"upload_time": "2025-07-26T06:50:56",
"upload_time_iso_8601": "2025-07-26T06:50:56.592931Z",
"url": "https://files.pythonhosted.org/packages/94/42/809f41ecc5def738e8737766226518d9576592f41ca77125becfb5230479/tinty-0.1.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "79a80c02dc3d0cdbe6b38d82b8be9dfe504995961695ca65d6043c00c6e1d451",
"md5": "9795a4cd379021f01d685f1c9b95f5a7",
"sha256": "7b079bf0e9b44f4415926c078ef9ae0e0e3b9f58326ad1b280f2ec97ac978c21"
},
"downloads": -1,
"filename": "tinty-0.1.10.tar.gz",
"has_sig": false,
"md5_digest": "9795a4cd379021f01d685f1c9b95f5a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 17691,
"upload_time": "2025-07-26T06:50:58",
"upload_time_iso_8601": "2025-07-26T06:50:58.003233Z",
"url": "https://files.pythonhosted.org/packages/79/a8/0c02dc3d0cdbe6b38d82b8be9dfe504995961695ca65d6043c00c6e1d451/tinty-0.1.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 06:50:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jim-my",
"github_project": "tinty",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tinty"
}
JSON
