clevertools
clevertools is a practical Python helper library for everyday application code. It focuses on the boring but important parts that show up in many projects: reading and writing files, handling JSON/TOML/YAML, masking sensitive values, loading split configuration, and setting up logging without repetitive boilerplate.
The package is intentionally small, but it still gives you enough structure that a new teammate can open the project and understand how configuration, file access, and logging are supposed to work.
What clevertools is for
Use clevertools when you want:
- a consistent way to read and write text, bytes, JSON, TOML, and YAML
- one shared error-handling model across helpers
- simple masking for API keys, tokens, emails, IDs, and similar values
- merged configuration from multiple files with dot access
- fast logger setup for console and file logging
- lower-level logging primitives when you need custom control
What is included
Core helpers
configure() stores package-wide defaults such as error handling and logger overrides
log is the shared default logger
mask() partially hides sensitive strings before you log or display them
File helpers
read() and write() handle plain text and raw bytes
ensure_file() and ensure_dir() make sure file and directory paths exist
read_json() and write_json() handle JSON files
read_toml() and write_toml() handle TOML files
read_yaml() and write_yaml() handle YAML files
load_config() merges multiple config files into one object
Logging helpers
configure_logger() creates or refreshes a logger with console and file handlers
start_file_logger() captures early startup output before final logger setup is ready
stop_file_logger() restores captured stdout and stderr
get_logger() returns a named logger without modifying it
CleverToolsFormatter adds structured time fields and optional colors
build_console_handler() and build_file_handler() expose the low-level handler builders
reset_handlers() safely clears existing handlers
resolve_logger_options() shows the final logger settings after overrides are applied
Quick example
from clevertools import (
configure,
configure_logger,
load_config,
mask,
read_json,
write_json,
)
configure(
error_mode="raise",
logger_overrides={
"level": "INFO",
"format_preset": "datetime",
"console_enabled": True,
},
)
logger = configure_logger(name="billing", use_colors=False)
payload = {
"service": "billing",
"token": mask("sk-demo-123456789", 4, 3),
"retries": 3,
}
write_json("tmp/config.json", payload, indent=2, ensure_ascii=False)
loaded = read_json("tmp/config.json")
logger.info("Loaded config: %s", loaded)
config = load_config("config/base.toml", "config/local.yaml")
logger.info("Feature enabled: %s", config.get("features.billing.enabled"))
Typical workflows
1. Read and write structured files
from clevertools import read_toml, write_yaml
settings = read_toml("settings.toml", on_error="raise")
write_yaml("build/settings.yaml", settings, sort_keys=False)
2. Hide secrets before logging
from clevertools import mask, log
token = "sk-prod-abcdef1234567890"
log.info("Using token %s", mask(token, 5, 4))
3. Merge config from multiple sources
from clevertools import load_config
config = load_config(
"config/defaults.toml",
"config/team.json",
"config/local.yaml",
)
print(config.database.host)
print(config.get("features.search.enabled", False))
4. Set up application logging
from clevertools import configure_logger
logger = configure_logger(
name="worker",
level="INFO",
format_preset="datetime",
console_enabled=True,
file_logging_enabled=True,
file_log_path="logs/worker.log",
file_write_mode="buffered",
use_colors=False,
)
logger.info("worker started")
Error handling model
Most helpers support on_error. If you do not pass it, the package-wide default from configure() is used.
"raise" raises the original exception
"log" logs the error and returns the helper's fallback value
"silent" suppresses the error and returns the helper's fallback value
Example:
from clevertools import configure, read_json
configure(error_mode="silent")
payload = read_json("missing.json")
print(payload) # None
Documentation map
If this is your first time in the repository, read the docs in this order:
- docs/README.md
- docs/installation.md
- docs/quickstart.md
- docs/tools/README.md
- docs/concepts/README.md
Important reference pages:
Repository layout
src/clevertools/ contains the library code
tests/ contains the automated test suite
docs/ contains the user-facing documentation
README.md is the first overview for new users
Installation
pip install -e .
For a full local setup including virtual environments and dependencies, see docs/installation.md.
Requirements