Feature/first tools (#2)

* feat: add initial clevertools project structure

* feat: introduce configurable core utilities and reorganize docs

Expand clevertools into a more structured utility package with a configurable public API for masking, plain text file IO, and logger setup.

Add global runtime configuration support, including shared error handling modes and logger default overrides, to make package behavior easier to customize across projects.

Introduce dedicated modules for configuration, logger bootstrapping, logger retrieval, plain text read/write helpers, static defaults, and centralized error handling policy.

Refine the masking implementation with stronger input validation, customizable visible prefix and suffix lengths, and support for custom mask characters.

Rework the package exports so the main API exposes configure, configure_logger, get_logger, read, write, and mask from clear top-level entry points.

Restructure the documentation into dedicated getting-started and reference sections, add concept pages for logging and error handling, and update the root README to reflect the expanded toolset.

Refresh the test suite layout and add coverage for logger configuration, default file IO helpers, and mask behavior.

Also clean up repository metadata and supporting files, including .gitignore, requirements, and legacy modules replaced by the new structure.

* feat: remove unused dependencies in the requirements.txt file

---------

Signed-off-by: b7binw13 <[email protected]>

Author: b7binw13

.gitignore

@@ -1,6 +1,10 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python,visualstudiocode,pythonvanilla
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,visualstudiocode,pythonvanilla
+
+### Python ###
 # Byte-compiled / optimized / DLL files
 __pycache__/
-*.py[codz]
+*.py[cod]
 *$py.class
 
 # C extensions
@@ -46,7 +50,7 @@ htmlcov/
 nosetests.xml
 coverage.xml
 *.cover
-*.py.cover
+*.py,cover
 .hypothesis/
 .pytest_cache/
 cover/
@@ -94,35 +98,20 @@ ipython_config.py
 #   install all needed dependencies.
 #Pipfile.lock
 
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#uv.lock
-
 # poetry
 #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
 #   This is especially recommended for binary packages to ensure reproducibility, and is more
 #   commonly ignored for libraries.
 #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
 #poetry.lock
-#poetry.toml
 
 # pdm
 #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
-#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
 #pdm.lock
-#pdm.toml
-.pdm-python
-.pdm-build/
-
-# pixi
-#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
-#pixi.lock
-#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
-#   in the .venv directory. It is recommended not to include this directory in version control.
-.pixi
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
 
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
 __pypackages__/
@@ -136,7 +125,6 @@ celerybeat.pid
 
 # Environments
 .env
-.envrc
 .venv
 env/
 venv/
@@ -175,33 +163,61 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
-# Abstra
-# Abstra is an AI-powered process automation framework.
-# Ignore directories containing user credentials, local state, and settings.
-# Learn more at https://abstra.io/docs
-.abstra/
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
 
-# Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
-#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
-#  you could uncomment the following to ignore the entire vscode folder
-# .vscode/
-
-# Ruff stuff:
+# ruff
 .ruff_cache/
 
-# PyPI configuration file
-.pypirc
+# LSP config files
+pyrightconfig.json
+
+### PythonVanilla ###
+# Byte-compiled / optimized / DLL files
+
+# C extensions
+
+# Distribution / packaging
+
+# Installer logs
+
+# Unit test / coverage reports
+
+# Translations
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+
+
+### VisualStudioCode ###
+.vscode/*
+.vscode/
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
 
-# Cursor
-#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
-#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
-#  refer to https://docs.cursor.com/context/ignore-files
-.cursorignore
-.cursorindexingignore
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
 
-# Marimo
-marimo/_static/
-marimo/_lsp/
-__marimo__/
+# End of https://www.toptal.com/developers/gitignore/api/python,visualstudiocode,pythonvanilla

README.md

@@ -1,35 +1,36 @@
 # clevertools
 
-`clevertools` is a Python utility library for everyday filesystem and runtime tasks.
-
-It provides:
-- file and directory creation
-- IO helpers
-- cleanup helpers
-- structured logging with console and file handlers
-- runtime helpers and file bootstrapping
-- a typed exception/validation model
-
-## Start Working with it
-
-1. Clone the repository (ssh recommended):
-```bash
-git clone [email protected]:The-Binary-Labs-TBL/clevertools.git
-cd clevertools
-```
+`clevertools` is a utility library providing practical tools for common
+workflows.
+
+## Public Tools
+
+- plain-text file helpers
+- masking for sensitive values
+- global runtime configuration
+- simple console and file logger setup
+
+## Example
 
-2. Install all dependecies:
+```python
+from clevertools import mask, read
 
-Linux:
-```bash
-python -m venv .venv
-source .venv/bin/activate
-pip install --upgrade pip
-pip install -r requirements.txt
+secret = mask("sk-example-secret-token", 3, 4)
+content = read("example.txt")
 ```
 
-Project metadata is defined in `pyproject.toml`.
+## Project Goal
+
+`clevertools` is intentionally compact. It focuses on practical helpers for
+everyday workflows without introducing a large framework or unnecessary
+abstraction.
+
+## Documentation
+
+- Start here: [docs/README.md](./docs/README.md)
+- Getting started: [docs/getting-started/README.md](./docs/getting-started/README.md)
+- Reference: [docs/reference/README.md](./docs/reference/README.md)
 
-## Python version
+## Requirements
 
-- Required: `>=3.10`
+- Python `>=3.10`

docs/README.md

@@ -1,5 +1,30 @@
 # Documentation
 
-This project documentation has two levels:
-- guided chapters for understanding and onboarding
-- deep API docs with one page per implementation module file
+This folder contains the documentation for `clevertools`, a utility library
+providing practical tools for common workflows.
+
+## Direction
+
+The documentation is split into two main parts:
+
+- [Getting Started](./getting-started/README.md) for installation, setup, and
+  the first steps with the library
+- [Reference](./reference/README.md) for detailed documentation of tools,
+  concepts, and important behavior
+
+## Documentation Structure
+
+This layout keeps the project easy to navigate:
+
+- `README.md` in the project root introduces the package
+- `docs/README.md` explains how the documentation is organized
+- `docs/getting-started/` contains onboarding and first-use pages
+- `docs/reference/` contains structured reference documentation
+- `docs/reference/tools/` documents one public tool per file
+- `docs/reference/concepts/` explains shared behavior such as error handling
+  and logging
+
+## Start Here
+
+- [Getting Started](./getting-started/README.md)
+- [Reference](./reference/README.md)

docs/getting-started/README.md

@@ -0,0 +1,14 @@
+# Getting Started
+
+This section helps you install `clevertools`, verify the package import, and
+build a first small example.
+
+## Pages
+
+- [Installation](./installation.md)
+- [First Steps](./first-steps.md)
+
+## Recommended Order
+
+1. Start with [Installation](./installation.md)
+2. Continue with [First Steps](./first-steps.md)

docs/getting-started/first-steps.md

@@ -0,0 +1,29 @@
+# First Steps
+
+This page shows a small first workflow with `clevertools`.
+
+## First Import
+
+```python
+from clevertools import configure, configure_logger, mask, read, write
+```
+
+## Example
+
+```python
+from clevertools import configure, configure_logger, mask, read, write
+
+configure(error_mode="log")
+
+logger = configure_logger(name="example", level="INFO")
+
+write("demo.txt", f"api_key={mask('sk-demo-123456789', 4, 3)}")
+content = read("demo.txt")
+
+logger.info("Loaded content: %s", content)
+```
+
+## Continue
+
+- [Reference overview](../reference/README.md)
+- [Tool reference](../reference/tools/README.md)

docs/getting-started/installation.md

@@ -0,0 +1,49 @@
+# Installation
+
+This page shows how to install `clevertools` locally on Linux, macOS, and
+Windows.
+
+## Requirements
+
+- Python `>=3.10`
+- dependencies from `requirements.txt`
+
+## Linux
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+pip install -e .
+```
+
+## macOS
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+python3 -m pip install -r requirements.txt
+python3 -m pip install -e .
+```
+
+## Windows PowerShell
+
+```powershell
+py -m venv .venv
+.venv\Scripts\Activate.ps1
+py -m pip install --upgrade pip
+py -m pip install -r requirements.txt
+py -m pip install -e .
+```
+
+## Windows Command Prompt
+
+```bat
+py -m venv .venv
+.venv\Scripts\activate.bat
+py -m pip install --upgrade pip
+py -m pip install -r requirements.txt
+py -m pip install -e .
+```

docs/reference/README.md

@@ -0,0 +1,14 @@
+# Reference
+
+This section contains the structured reference documentation for `clevertools`.
+
+## Sections
+
+- [Tools](./tools/README.md)
+- [Concepts](./concepts/README.md)
+
+## Use This Section For
+
+- detailed descriptions of public helpers
+- shared behavior and design decisions
+- examples for specific tools and workflows

docs/reference/concepts/README.md

@@ -0,0 +1,8 @@
+# Concepts
+
+This section explains shared behavior used across multiple tools.
+
+## Pages
+
+- [Error Handling](./error-handling.md)
+- [Logging](./logging.md)