| Name | twilkit JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Lightweight Python toolkit: validators, colors, decorators, and FlexVar |
| upload_time | 2025-09-08 01:44:47 |
| maintainer | None |
| docs_url | None |
| author | Avi Twil |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2025 Avi Twil
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
validation
decorators
colors
ansi
toolkit
utilities
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# twilkit
A lightweight toolkit for everyday Python work:
* **Validators** – clean, reusable descriptors for attribute validation
* **Colors** – simple ANSI color formatting for terminal output
* **Decorators** – exception handling and per-function logging
* **FlexVar** – a flexible, chainable dict-like container with a pretty `__str__`
---
## Table of Contents
* [Installation](#installation)
* [Quick Start](#quick-start)
* [API](#api)
* [Validators](#validators)
* [Colors](#colors)
* [Decorators](#decorators)
* [FlexVar](#flexvar)
* [Mini Project: “User Registry” CLI](#mini-project-user-registry-cli)
* [Contributing](#contributing)
* [License](#license)
---
## Installation
```bash
pip install twilkit
```
> Supports Python 3.10+
---
## Quick Start
```python
from twilkit import validators, color, FlexVar, catch_exceptions, log_function
class User:
name = validators.StartWith("Mr ", "Ms ", "Dr ")
email = validators.EndsWith("@example.com", "@corp.local")
age = validators.InBetween(0, 130)
@catch_exceptions
@log_function
def create_profile(name, email, age):
u = User()
u.name = name
u.email = email
u.age = age
profile = FlexVar("Profile").add("name", name).add("email", email).add("age", age)
print(color("User created").green)
print(profile)
return profile
create_profile("Dr Jane Doe", "jane@example.com", 34)
```
---
## API
### Validators
Reusable data descriptors that enforce constraints on attributes when you set them.
Import them via the grouped namespace or directly:
```python
from twilkit import validators
# or:
from twilkit import StartWith, EndsWith, MoreThan, LessThan, InBetween
```
#### `StartWith(*prefixes: str)`
Validate that a string starts with any of the provided prefixes.
```python
class Person:
title = validators.StartWith("Mr ", "Ms ", "Dr ")
p = Person()
p.title = "Dr Alice" # OK
# p.title = "Alice" # raises ValidationError
```
#### `EndsWith(*suffixes: str)`
Validate that a string ends with any of the provided suffixes.
```python
class Account:
email = validators.EndsWith("@example.com", "@corp.local")
a = Account()
a.email = "dev@corp.local" # OK
# a.email = "dev@gmail.com" # raises ValidationError
```
#### `MoreThan(value: int | float)`
Validate that a number is strictly greater than `value`.
```python
class Metrics:
height_cm = validators.MoreThan(0)
m = Metrics()
m.height_cm = 172 # OK
# m.height_cm = 0 # raises ValidationError
```
#### `LessThan(value: int | float)`
Validate that a number is strictly less than `value`.
```python
class Bio:
age = validators.LessThan(150)
b = Bio()
b.age = 42 # OK
# b.age = 200 # raises ValidationError
```
#### `InBetween(minv: int | float, maxv: int | float)`
Validate that `minv <= value <= maxv`.
```python
class Exam:
score = validators.InBetween(0, 100)
e = Exam()
e.score = 88 # OK
# e.score = -5 # raises ValidationError
```
> All validators raise `twilkit.ValidationError` with a clear, colored message on failure.
---
### Colors
Minimal ANSI color helpers for terminals.
* `color(value)` → wraps the value and provides properties:
* `.red`, `.light_green`, `.green`, `.yellow`, `.blue`, `.light_blue`, `.magenta`, `.cyan`, `.black`, `.purple`, `.orange`
* `Colors` enum → raw escape codes
* `Cprint` class → underlying helper
```python
from twilkit import color, Colors
print(color("Success").green)
print(color("Warning").yellow)
print(f"{Colors.RED.value}Error{Colors.RESET.value}")
```
---
### Decorators
#### `@catch_exceptions`
Catch any exception, print a colored error (`<func> <error>`), return `None`.
```python
from twilkit import catch_exceptions, color
@catch_exceptions
def risky_div(a, b):
return a / b
print(color("Result:").blue, risky_div(6, 3)) # 2.0
risky_div(1, 0) # Prints colored error, returns None
```
#### `@log_function`
Log function start, arguments, return values, and exceptions to `<func_name>.log`.
```python
from twilkit import log_function
@log_function
def compute_total(prices):
return sum(prices)
compute_total([10, 20, 30]) # Logs to compute_total.log
```
---
### FlexVar
A small, chainable dict-like container with a pretty string output.
```python
from twilkit import FlexVar
cfg = (
FlexVar("Server Config")
.add("host", "localhost")
.add("port", 8080)
.update("port", 9090)
)
print(cfg["host"]) # "localhost"
print(cfg.port) # "9090"
print(cfg) # Pretty formatted block
"host" in cfg # True
del cfg["port"] # Remove key
for key, val in cfg:
print(key, val)
```
Error behavior:
* `.add(name, _)` → `KeyError` if attribute exists
* `.update(name, _)` / `.remove(name)` → `KeyError` if missing
* `.__getattr__(name)` → `AttributeError` if missing
* `.__getitem__` / `.__delitem__` → `KeyError` if missing
---
## Mini Project: User Registry CLI
Combining validators, colors, decorators, and FlexVar.
```python
# file: user_registry.py
from twilkit import validators, color, log_function, catch_exceptions, FlexVar
class User:
name = validators.StartWith("Mr ", "Ms ", "Dr ")
email = validators.EndsWith("@example.com", "@corp.local")
age = validators.InBetween(0, 130)
def __init__(self, name: str, email: str, age: int):
self.name = name
self.email = email
self.age = age
class Registry:
def __init__(self):
self._db = []
@log_function
@catch_exceptions
def add_user(self, name: str, email: str, age: int):
user = User(name, email, age)
entry = (
FlexVar("User")
.add("name", user.name)
.add("email", user.email)
.add("age", user.age)
)
self._db.append(entry)
print(color("User added").green)
print(entry)
return entry
@log_function
def list_users(self):
if not self._db:
print(color("No users found").yellow)
return []
print(color(f"Total users: {len(self._db)}").cyan)
for i, entry in enumerate(self._db, start=1):
print(color(f"[{i}]").purple)
print(entry)
return list(self._db)
@log_function
@catch_exceptions
def update_email(self, index: int, new_email: str):
entry = self._db[index]
tmp = User(entry.name, new_email, entry.age) # re-validation
entry["email"] = tmp.email
print(color("Email updated").light_green)
print(entry)
return entry
if __name__ == "__main__":
reg = Registry()
reg.add_user("Dr Alice", "alice@example.com", 34)
reg.add_user("Ms Eve", "eve@gmail.com", 29) # invalid -> ValidationError
reg.list_users()
reg.update_email(0, "alice@corp.local")
reg.list_users()
```
This demonstrates:
* **Validation**: descriptors enforce constraints
* **Colors**: feedback messages
* **Logging**: each method logs to its own file
* **FlexVar**: flexible, human-readable data storage
---
## Contributing
* Issues and PRs are welcome.
* Keep scope small, API tidy, docs clear.
* Include tests for new features .
---
## License
This project is licensed under the terms of the [MIT License](LICENSE).
---
Raw data
{
"_id": null,
"home_page": null,
"name": "twilkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "validation, decorators, colors, ansi, toolkit, utilities",
"author": "Avi Twil",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/af/9a/e8a39ae1b5700d9a2c4abbbc33f004b316eed988580628681168468e44a2/twilkit-1.0.0.tar.gz",
"platform": null,
"description": "\r\n# twilkit\r\n\r\nA lightweight toolkit for everyday Python work:\r\n\r\n* **Validators** \u2013 clean, reusable descriptors for attribute validation\r\n* **Colors** \u2013 simple ANSI color formatting for terminal output\r\n* **Decorators** \u2013 exception handling and per-function logging\r\n* **FlexVar** \u2013 a flexible, chainable dict-like container with a pretty `__str__`\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n* [Installation](#installation)\r\n* [Quick Start](#quick-start)\r\n* [API](#api)\r\n\r\n * [Validators](#validators)\r\n * [Colors](#colors)\r\n * [Decorators](#decorators)\r\n * [FlexVar](#flexvar)\r\n* [Mini Project: \u201cUser Registry\u201d CLI](#mini-project-user-registry-cli)\r\n* [Contributing](#contributing)\r\n* [License](#license)\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\npip install twilkit\r\n```\r\n\r\n> Supports Python 3.10+\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom twilkit import validators, color, FlexVar, catch_exceptions, log_function\r\n\r\nclass User:\r\n name = validators.StartWith(\"Mr \", \"Ms \", \"Dr \")\r\n email = validators.EndsWith(\"@example.com\", \"@corp.local\")\r\n age = validators.InBetween(0, 130)\r\n\r\n@catch_exceptions\r\n@log_function\r\ndef create_profile(name, email, age):\r\n u = User()\r\n u.name = name\r\n u.email = email\r\n u.age = age\r\n profile = FlexVar(\"Profile\").add(\"name\", name).add(\"email\", email).add(\"age\", age)\r\n print(color(\"User created\").green)\r\n print(profile)\r\n return profile\r\n\r\ncreate_profile(\"Dr Jane Doe\", \"jane@example.com\", 34)\r\n```\r\n\r\n---\r\n\r\n## API\r\n\r\n### Validators\r\n\r\nReusable data descriptors that enforce constraints on attributes when you set them.\r\nImport them via the grouped namespace or directly:\r\n\r\n```python\r\nfrom twilkit import validators\r\n# or:\r\nfrom twilkit import StartWith, EndsWith, MoreThan, LessThan, InBetween\r\n```\r\n\r\n#### `StartWith(*prefixes: str)`\r\n\r\nValidate that a string starts with any of the provided prefixes.\r\n\r\n```python\r\nclass Person:\r\n title = validators.StartWith(\"Mr \", \"Ms \", \"Dr \")\r\n\r\np = Person()\r\np.title = \"Dr Alice\" # OK\r\n# p.title = \"Alice\" # raises ValidationError\r\n```\r\n\r\n#### `EndsWith(*suffixes: str)`\r\n\r\nValidate that a string ends with any of the provided suffixes.\r\n\r\n```python\r\nclass Account:\r\n email = validators.EndsWith(\"@example.com\", \"@corp.local\")\r\n\r\na = Account()\r\na.email = \"dev@corp.local\" # OK\r\n# a.email = \"dev@gmail.com\" # raises ValidationError\r\n```\r\n\r\n#### `MoreThan(value: int | float)`\r\n\r\nValidate that a number is strictly greater than `value`.\r\n\r\n```python\r\nclass Metrics:\r\n height_cm = validators.MoreThan(0)\r\n\r\nm = Metrics()\r\nm.height_cm = 172 # OK\r\n# m.height_cm = 0 # raises ValidationError\r\n```\r\n\r\n#### `LessThan(value: int | float)`\r\n\r\nValidate that a number is strictly less than `value`.\r\n\r\n```python\r\nclass Bio:\r\n age = validators.LessThan(150)\r\n\r\nb = Bio()\r\nb.age = 42 # OK\r\n# b.age = 200 # raises ValidationError\r\n```\r\n\r\n#### `InBetween(minv: int | float, maxv: int | float)`\r\n\r\nValidate that `minv <= value <= maxv`.\r\n\r\n```python\r\nclass Exam:\r\n score = validators.InBetween(0, 100)\r\n\r\ne = Exam()\r\ne.score = 88 # OK\r\n# e.score = -5 # raises ValidationError\r\n```\r\n\r\n> All validators raise `twilkit.ValidationError` with a clear, colored message on failure.\r\n\r\n---\r\n\r\n### Colors\r\n\r\nMinimal ANSI color helpers for terminals.\r\n\r\n* `color(value)` \u2192 wraps the value and provides properties:\r\n\r\n * `.red`, `.light_green`, `.green`, `.yellow`, `.blue`, `.light_blue`, `.magenta`, `.cyan`, `.black`, `.purple`, `.orange`\r\n* `Colors` enum \u2192 raw escape codes\r\n* `Cprint` class \u2192 underlying helper\r\n\r\n```python\r\nfrom twilkit import color, Colors\r\n\r\nprint(color(\"Success\").green)\r\nprint(color(\"Warning\").yellow)\r\nprint(f\"{Colors.RED.value}Error{Colors.RESET.value}\")\r\n```\r\n\r\n---\r\n\r\n### Decorators\r\n\r\n#### `@catch_exceptions`\r\n\r\nCatch any exception, print a colored error (`<func> <error>`), return `None`.\r\n\r\n```python\r\nfrom twilkit import catch_exceptions, color\r\n\r\n@catch_exceptions\r\ndef risky_div(a, b):\r\n return a / b\r\n\r\nprint(color(\"Result:\").blue, risky_div(6, 3)) # 2.0\r\nrisky_div(1, 0) # Prints colored error, returns None\r\n```\r\n\r\n#### `@log_function`\r\n\r\nLog function start, arguments, return values, and exceptions to `<func_name>.log`.\r\n\r\n```python\r\nfrom twilkit import log_function\r\n\r\n@log_function\r\ndef compute_total(prices):\r\n return sum(prices)\r\n\r\ncompute_total([10, 20, 30]) # Logs to compute_total.log\r\n```\r\n\r\n---\r\n\r\n### FlexVar\r\n\r\nA small, chainable dict-like container with a pretty string output.\r\n\r\n```python\r\nfrom twilkit import FlexVar\r\n\r\ncfg = (\r\n FlexVar(\"Server Config\")\r\n .add(\"host\", \"localhost\")\r\n .add(\"port\", 8080)\r\n .update(\"port\", 9090)\r\n)\r\n\r\nprint(cfg[\"host\"]) # \"localhost\"\r\nprint(cfg.port) # \"9090\"\r\nprint(cfg) # Pretty formatted block\r\n\r\n\"host\" in cfg # True\r\ndel cfg[\"port\"] # Remove key\r\nfor key, val in cfg:\r\n print(key, val)\r\n```\r\n\r\nError behavior:\r\n\r\n* `.add(name, _)` \u2192 `KeyError` if attribute exists\r\n* `.update(name, _)` / `.remove(name)` \u2192 `KeyError` if missing\r\n* `.__getattr__(name)` \u2192 `AttributeError` if missing\r\n* `.__getitem__` / `.__delitem__` \u2192 `KeyError` if missing\r\n\r\n---\r\n\r\n## Mini Project: User Registry CLI\r\n\r\nCombining validators, colors, decorators, and FlexVar.\r\n\r\n```python\r\n# file: user_registry.py\r\nfrom twilkit import validators, color, log_function, catch_exceptions, FlexVar\r\n\r\nclass User:\r\n name = validators.StartWith(\"Mr \", \"Ms \", \"Dr \")\r\n email = validators.EndsWith(\"@example.com\", \"@corp.local\")\r\n age = validators.InBetween(0, 130)\r\n\r\n def __init__(self, name: str, email: str, age: int):\r\n self.name = name\r\n self.email = email\r\n self.age = age\r\n\r\nclass Registry:\r\n def __init__(self):\r\n self._db = []\r\n\r\n @log_function\r\n @catch_exceptions\r\n def add_user(self, name: str, email: str, age: int):\r\n user = User(name, email, age)\r\n entry = (\r\n FlexVar(\"User\")\r\n .add(\"name\", user.name)\r\n .add(\"email\", user.email)\r\n .add(\"age\", user.age)\r\n )\r\n self._db.append(entry)\r\n print(color(\"User added\").green)\r\n print(entry)\r\n return entry\r\n\r\n @log_function\r\n def list_users(self):\r\n if not self._db:\r\n print(color(\"No users found\").yellow)\r\n return []\r\n print(color(f\"Total users: {len(self._db)}\").cyan)\r\n for i, entry in enumerate(self._db, start=1):\r\n print(color(f\"[{i}]\").purple)\r\n print(entry)\r\n return list(self._db)\r\n\r\n @log_function\r\n @catch_exceptions\r\n def update_email(self, index: int, new_email: str):\r\n entry = self._db[index]\r\n tmp = User(entry.name, new_email, entry.age) # re-validation\r\n entry[\"email\"] = tmp.email\r\n print(color(\"Email updated\").light_green)\r\n print(entry)\r\n return entry\r\n\r\nif __name__ == \"__main__\":\r\n reg = Registry()\r\n reg.add_user(\"Dr Alice\", \"alice@example.com\", 34)\r\n reg.add_user(\"Ms Eve\", \"eve@gmail.com\", 29) # invalid -> ValidationError\r\n reg.list_users()\r\n reg.update_email(0, \"alice@corp.local\")\r\n reg.list_users()\r\n```\r\n\r\nThis demonstrates:\r\n\r\n* **Validation**: descriptors enforce constraints\r\n* **Colors**: feedback messages\r\n* **Logging**: each method logs to its own file\r\n* **FlexVar**: flexible, human-readable data storage\r\n\r\n---\r\n\r\n## Contributing\r\n\r\n* Issues and PRs are welcome.\r\n* Keep scope small, API tidy, docs clear.\r\n* Include tests for new features .\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the terms of the [MIT License](LICENSE).\r\n\r\n---\r\n",
"bugtrack_url": null,
"license": "MIT License\r\n \r\n Copyright (c) 2025 Avi Twil\r\n \r\n Permission is hereby granted, free of charge, to any person obtaining a copy\r\n of this software and associated documentation files (the \"Software\"), to deal\r\n in the Software without restriction, including without limitation the rights\r\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n copies of the Software, and to permit persons to whom the Software is\r\n furnished to do so, subject to the following conditions:\r\n \r\n The above copyright notice and this permission notice shall be included in all\r\n copies or substantial portions of the Software.\r\n \r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n SOFTWARE.\r\n ",
"summary": "Lightweight Python toolkit: validators, colors, decorators, and FlexVar",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/avitwil/twilkit",
"Issues": "https://github.com/avitwil/twilkit/issues",
"Repository": "https://github.com/avitwil/twilkit"
},
"split_keywords": [
"validation",
" decorators",
" colors",
" ansi",
" toolkit",
" utilities"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a26fbadf85ed31a2cd731f9b2ae9f431830dd4a095a21d896b2ad95163c4d689",
"md5": "850d4688aa5b57c8f063bcd3aa719be9",
"sha256": "1ed0a8761ed0533bad06a1cfbc24b11b20d63bdf5530733cc70983b82ab1852e"
},
"downloads": -1,
"filename": "twilkit-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "850d4688aa5b57c8f063bcd3aa719be9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11152,
"upload_time": "2025-09-08T01:44:45",
"upload_time_iso_8601": "2025-09-08T01:44:45.538114Z",
"url": "https://files.pythonhosted.org/packages/a2/6f/badf85ed31a2cd731f9b2ae9f431830dd4a095a21d896b2ad95163c4d689/twilkit-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "af9ae8a39ae1b5700d9a2c4abbbc33f004b316eed988580628681168468e44a2",
"md5": "a158400986fd9ee04420781f17682b27",
"sha256": "03bac2136b270b7e3afb40dc54f3ec642c6eec2d1858674acb9ebd469d7a16f3"
},
"downloads": -1,
"filename": "twilkit-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a158400986fd9ee04420781f17682b27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12541,
"upload_time": "2025-09-08T01:44:47",
"upload_time_iso_8601": "2025-09-08T01:44:47.172180Z",
"url": "https://files.pythonhosted.org/packages/af/9a/e8a39ae1b5700d9a2c4abbbc33f004b316eed988580628681168468e44a2/twilkit-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-08 01:44:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avitwil",
"github_project": "twilkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "twilkit"
}
