v1.4.2 Official Release

Release Description

CleverTools 1.4.1 expands the library with new filesystem preparation helpers, improved runtime logging workflows, stronger logger behavior, and a broad documentation and test refresh.

This release introduces ensure_file() and ensure_dir() to simplify file and directory preparation before later writes, exports start_file_logger() and stop_file_logger() for early bootstrap logging, and improves logger behavior so startup records can be buffered and replayed once final handlers are configured. It also refines formatter behavior by using the actual handler stream for color detection and improves logger setup integration around bootstrap buffering.

Beyond the runtime and helper updates, the release significantly improves project packaging and developer ergonomics. Metadata in pyproject.toml has been expanded, runtime and development dependencies are separated more clearly, pytest configuration has been added to the project metadata, and the test suite has been reworked toward more isolated tmp-path-based fixtures with reset logic for shared configuration and logger state.

The documentation has also been extensively refreshed. The README now gives a more complete overview of practical CleverTools workflows, the logging and error-handling concepts are more explicit, and new tool pages document ensure_file(), ensure_dir(), start_file_logger(), and stop_file_logger() alongside updates to the existing helper references.

Highlights in this release include:

• new ensure_file() and ensure_dir() helpers
• new bootstrap logging support with start_file_logger() and stop_file_logger()
• improved logger buffering and startup replay behavior
• stream-aware color detection in the formatter
• expanded package exports and updated project metadata
• cleaner test isolation and broader automated coverage
• large documentation refresh across the project

Verification attempted:

• pytest -q

Current status in this environment:

• Verification is currently blocked because PyYAML is not installed locally, which causes import failure before the test suite can run.

Notes:

• Package version was updated to 1.4.1.
• This release does not include UI changes.

v1.3.1 Official Release

Release Summary

CleverTools 1.3.1 extends the library’s file and configuration capabilities with native YAML support and a more powerful configuration loading workflow.

This release introduces dedicated YAML read and write helpers and expands load_config() so it can combine multiple configuration files across TOML, JSON, YAML, and YML into one merged configuration object. Nested mappings are merged recursively, later files override earlier values when keys overlap, and the final configuration can be accessed conveniently through attributes, dictionary-style access, or dot-path lookups.

Alongside these functional changes, the release also updates the public API surface, improves dependency handling for TOML writing through lazy imports, adds focused documentation for the new workflows, and broadens automated test coverage around YAML handling and multi-source configuration loading.

Highlights

• Added read_yaml() and write_yaml() as first-class YAML file helpers
• Extended load_config() to support .toml, .json, .yaml, and .yml
• Enabled recursive merging of configuration data across mixed file formats
• Added top-level exports for the new YAML and configuration helpers
• Added dedicated documentation for YAML file handling and mixed-format config loading
• Improved TOML writing behavior by importing tomli_w only when needed
• Expanded automated coverage for YAML parsing, writing, and config merging scenarios

Why This Release Matters

Many real-world projects do not keep configuration in a single file or even in a single format. Different parts of a system may generate or own TOML, JSON, or YAML configuration independently, which often leaves application code responsible for reading, validating, and merging those sources manually.

CleverTools 1.3.1 reduces that overhead by providing one consistent built-in workflow for loading and combining structured configuration from multiple sources. This makes it easier to support layered configuration setups, shared defaults, environment overrides, and mixed tooling ecosystems without repeating merge logic across projects.

Testing

This release adds or expands automated coverage for:

• YAML read and write roundtrips
• invalid YAML handling
• mixed-format configuration loading across TOML, JSON, and YAML
• recursive merge behavior for overlapping nested sections
• attribute-based and dot-path-based access to merged configuration values
• validation for unsupported config structures and non-mapping roots

Verification attempted:

• pytest -q

Current status in this environment:

• Test collection fails because the yaml dependency is not installed locally.
• Because clevertools.__init__ now exposes the YAML-backed configuration loader, this missing dependency also affects imports in other tests during collection.

Notes

• pyyaml is now required for YAML support.
• The package version was updated to 1.3.1.
• This release does not include any UI changes.

v1.2.1 Official Release

v1.2.1 – Major Expansion & Core System Refinement

Overview

This release represents a major step forward in the evolution of clevertools.
The library has grown from a compact utility collection into a more structured, extensible, and production-ready toolkit.

The focus of this version lies on expanding the public API, improving internal consistency, strengthening core systems such as file I/O and logging, and significantly increasing test coverage and documentation quality.

---

What's New

Expanded Core Utilities

• Introduction of structured file helpers for JSON and TOML
• Extended default file I/O to support both text and binary workflows
• Improved validation for unsupported modes and invalid data inputs
• Consistent handling of missing files, directories, and edge cases

Logging System Overhaul

• Refactored logging into modular building blocks
• Introduction of:
  • CleverToolsFormatter
  • Console and file handler builders
  • Centralized logger option resolver
• Clean handler reset logic to prevent duplicate logs
• Built-in format presets and improved configurability
• Shared global logger instance (log) exposed via package root

Public API Expansion

• Significantly broader top-level API exposure
• Direct access to:
  • Configuration helpers
  • Logging utilities
  • Structured file handlers (JSON/TOML)
  • Formatter and handler tools
  • Extended exception hierarchy
• Reduced need for deep internal imports

---

File Handling Improvements

• Unified raw I/O layer with clearer behavior definitions
• Explicit support for:
  • Binary reads/writes
  • Safer type handling
• New structured helpers:
  • read_json, write_json
  • read_toml, write_toml
• Features include:
  • Automatic file creation
  • Parse validation
  • Configurable fallback behavior

---

Error Handling Expansion

• Massive extension of the exception hierarchy
• New categorized error domains, including:
  • Validation & parsing
  • Filesystem & storage
  • Runtime & setup
  • API & integration
  • Worker, scheduler, metrics, tracing
• More expressive and scalable error modeling

---

Internal Model Cleanup

• static.py renamed to models.py
• Consolidation of:
  • Defaults and literals
  • Logger presets and configurations
  • Write modes and internal mappings
• Improved internal structure and maintainability

---

Masking Enhancements

• Improved validation of invalid inputs
• Integration into shared error policy system
• More predictable fallback behavior
• Safer handling of:
  • Empty values
  • Invalid visibility configurations
  • Incorrect mask characters

---

Documentation Overhaul

• Complete restructuring of documentation
• New sections introduced:
  • Concepts
  • Tools
  • Quickstart
  • Installation
• Expanded README and improved accessibility
• Dedicated pages for new utilities, including:
  • Logging system components
  • JSON/TOML helpers
  • Formatter and handler tools

---

Packaging & Requirements

• Version upgrade to v1.2.1
• Minimum Python version raised to 3.11
• Updated dependencies and tooling:
  • ruff
  • mypy
  • faker
  • tomli_w
• Improved packaging metadata and project configuration

---

Testing & Quality

• Significant increase in automated test coverage
• New tests for:
  • Configuration handling
  • Structured file I/O (JSON/TOML)
  • Logging behavior and formatting
  • Edge cases in default I/O
  • Masking logic
• Addition of debug utilities and structured test runners

---

Public API (Highlights)

• mask
• read, write
• read_json, write_json
• read_toml, write_toml
• configure
• configure_logger
• get_logger
• log
• build_console_handler
• build_file_handler
• reset_handlers
• CleverToolsFormatter
• resolve_logger_options

---

Release Notes

This release transforms clevertools from a simple helper library into a more complete and scalable utility framework.

The system is now more modular, better structured, and easier to integrate into real-world projects.
At the same time, stronger validation, improved error handling, and expanded test coverage ensure more predictable and reliable behavior.

Note: Running the test suite may require additional dependencies such as faker and tomli_w.

v0.1.1 - First Official Release

Initial Release

Welcome to the first official release of clevertools.

clevertools is a compact Python utility library that provides practical helpers for everyday workflows, with a focus on simplicity, readability, and useful defaults.

What's Included

Core Utilities

• Plain-text file helpers for reading and writing UTF-8 files
• Sensitive value masking with configurable visible sections
• Global runtime configuration for shared defaults
• Simple logger setup for console and file output

Logging and Error Handling

• Configurable logger creation via configure_logger()
• Named logger access via get_logger()
• Optional colored terminal output
• Shared error handling modes: raise, log, and silent

Project Foundation

• Initial package structure and release configuration
• Getting started guides and reference documentation
• Automated tests for masking, logging, and file I/O
• Build and dependency updates for the first release

Public API

• mask
• read
• write
• configure
• configure_logger
• get_logger

Release Notes

This version establishes the initial foundation of the project and marks the first public release of clevertools.