feat: add initial clevertools project structure (#1)

b7binw13 · web-flow · commit 52f30171fedd · 2026-03-14T00:08:16.000+01:00
approved [x]
diff --git a/.gitignore b/.gitignore
@@ -204,4 +204,4 @@ cython_debug/
 # Marimo
 marimo/_static/
 marimo/_lsp/
-__marimo__/
+__marimo__/
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -0,0 +1 @@
+b7binw13
diff --git a/CONTRIBUTORS b/CONTRIBUTORS
@@ -0,0 +1,7 @@
+CONTRIBUTORS
+
+Original Author:
+- b7binw13
+
+Contributors:
+- b7binw13
diff --git a/LICENSE b/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 b7binw13 and The Binary Labs (TBL)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.
diff --git a/NOTICE b/NOTICE
@@ -0,0 +1,7 @@
+NOTICE
+
+This product includes software developed by:
+- b7binw13 (original author)
+
+Contributors:
+- b7binw13
diff --git a/README.md b/README.md
@@ -1,2 +1,35 @@
 # clevertools
-clevertools is a python tools utility, that provides usefull tools for logging, file handling, error handling and so much more!
+
+`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 git@github.com:The-Binary-Labs-TBL/clevertools.git
+cd clevertools
+```
+
+2. Install all dependecies:
+
+Linux:
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+Project metadata is defined in `pyproject.toml`.
+
+## Python version
+
+- Required: `>=3.10`
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,5 @@
+# Documentation
+
+This project documentation has two levels:
+- guided chapters for understanding and onboarding
+- deep API docs with one page per implementation module file
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,6 @@
+# Getting Started
+
+## Prerequisites
+
+- Python `>=3.10`
+- dependencies installed from `requirements.txt`
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clevertools"
+version = "0.1.0"
+description = "Clevertools is a utility library providing practical tools for common workflows."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE", "CONTRIBUTORS"]
+authors = [{ name = "b7binw13" }]
+dynamic = ["dependencies"]
+
+[tool.setuptools.dynamic]
+dependencies = { file = "requirements.txt" }
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/The-Binary-Labs-TBL/clevertools"
+Repository = "https://github.com/The-Binary-Labs-TBL/clevertools.git"
+Issues = "https://github.com/The-Binary-Labs-TBL/clevertools/issues"
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,7 @@
+PyYAML
+tomli-w
+twine
+faker
+python-dotenv
+logging
+pymongo
diff --git a/src/clevertools/__init__.py b/src/clevertools/__init__.py
@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from errors.exceptions import (
+    AppError,
+    ValidationError,
+    FatalError,
+    RecoverableError,
+    ParseError
+)
+from system.mask_handler import mask
+
+__all__ = [
+    "mask",
+    "AppError",
+    "ValidationError",
+    "FatalError",
+    "RecoverableError",
+    "ParseError"
+]
diff --git a/src/clevertools/errors/exceptions.py b/src/clevertools/errors/exceptions.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+class AppError(Exception):
+    """Base class for all domain-specific errors in clevertools."""
+
+class RecoverableError(AppError):
+    """Error indicating the current operation can be skipped safely."""
+
+class FatalError(AppError):
+    """Error indicating execution should stop immediately."""
+
+class ValidationError(RecoverableError):
+    """Raised when input values fail semantic or structural validation."""
+
+class ParseError(ValidationError):
+    """Raised when a value or payload cannot be parsed into the expected format."""
diff --git a/src/clevertools/system/mask_handler.py b/src/clevertools/system/mask_handler.py
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Optional
+
+def mask(value: str, show_start_characters: Optional[int] = None, show_end_characters: Optional[int] = None) -> str:
+    if value is None:
+        return ""
+
+    start: int = 8
+    end: int = 2
+
+    if show_start_characters is not None:
+        if show_start_characters < 0:
+            raise ValueError("show_start_characters must be more than 0!")
+        if show_start_characters > 0:
+            start = show_start_characters
+
+    if show_end_characters is not None:
+        if show_end_characters < 0:
+            raise ValueError("show_end_characters must be more than 0!")
+        if show_end_characters > 0:
+            end = show_end_characters
+
+    try:
+        visible_start = value[: start]
+        visible_end = value[-end:]
+        masked_middle = "*" * (len(value) - start - end)
+
+        return f"{visible_start}{masked_middle}{visible_end}"
+    except ValueError as exc:
+        raise ValueError(f"Failed to mask: {exc}") from exc
diff --git a/tests/start.py b/tests/start.py
@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import sys
+
+def main() -> int:
+    try:
+        return 0
+    except Exception as exc:
+        raise Exception(f"Failed to run main") from exc
+
+if __name__ == "__main__":
+    raise SystemError(sys.exit(main()))

-Original file line number
+Diff line change
@@ @@ -0,0 +1,7 @@ @@
 +PyYAML
 +tomli-w
 +twine
 +faker
 +python-dotenv
 +logging
 +pymongo