Modernize packaging, tooling, and docs for ec_tools

.gitignore

@@ -8,4 +8,3 @@ ec_tools.egg-info/
 
 upload.sh
 .*swp
-

.pre-commit-config.yaml

@@ -1,31 +1,25 @@
 repos:
-  # --- isort: import sorter ---
-  - repo: https://github.com/PyCQA/isort
-    rev: 5.13.2
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
     hooks:
       - id: isort
-        args: ["--profile", "black", "--line-length", "120"]
-  # --- autoflake: remove unused imports/vars ---
-  - repo: https://github.com/myint/autoflake
-    rev: v2.3.1
+        args: ["--profile=black"]
+        name: isort (python)
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
     hooks:
-      - id: autoflake
-        args: [
-          "--in-place",
-          "--remove-unused-variables",
-          "--remove-all-unused-imports",
-        ]
-        exclude: "__init__.py"
-  # --- Black: Python code formatter ---
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
   - repo: https://github.com/psf/black
-    rev: 24.8.0   # use a stable release
+    rev: 25.1.0
     hooks:
       - id: black
         language_version: python3
-        args: ["--line-length=120"]
-  # --- YAML lint/format ---
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+        args: [--line-length=120]
+  - repo: https://github.com/myint/autoflake
+    rev: v2.3.1
     hooks:
-      - id: check-yaml
-
+      - id: autoflake
+        args: [ '--remove-all-unused-imports', '--in-place' ]

.pylintrc

@@ -1,3 +1,2 @@
 [MESSAGES CONTROL]
 disable=missing-docstring,broad-exception-caught,too-many-return-statements,too-many-arguments,too-many-positional-arguments
-

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -1 +1,76 @@
 # ec_tools
+
+A lightweight Python toolbox for data modeling, SQLite DAOs, encrypted key-value storage, and small productivity utilities.
+
+## Highlights
+- Data objects with JSON serialization and type-aware formatting.
+- SQLite client + DAO layer with query generation.
+- KV DAO with optional AES-backed encryption.
+- Encryption helpers for bytes, chunks, and files.
+- Utility helpers for IO, hashing, logging, and timing.
+
+## Requirements
+- Python >= 3.12
+
+## Install (from source)
+```bash
+pip install -e .
+```
+
+## Quick start
+### Encrypted KV storage with a KeyManager
+```python
+from ec_tools.database import CipherKvDao, SqliteClient, SqliteKvDao
+from ec_tools.tools.cipher import AesCipherGenerator
+from ec_tools.tools.key_manager import KeyManager
+
+sqlite_client = SqliteClient(":memory:")
+kv_dao = SqliteKvDao(sqlite_client)
+cipher_generator = AesCipherGenerator()
+cipher_kv_dao = CipherKvDao(kv_dao, cipher_generator)
+
+manager = KeyManager(cipher_kv_dao, "my-password")
+manager.refresh_keys(["token", "cookie"])
+print(manager.get_key("token"))
+```
+
+### Build headers from stored secrets
+```python
+from ec_tools.tools.headers_manager import HeadersManager
+
+headers = HeadersManager(manager, ["token"], {"User-Agent": "ec-tools"}).get()
+print(headers)
+```
+
+## Data objects
+Define dataclasses that serialize to/from JSON with helpers for enums, lists, sets, and nested objects.
+```python
+import dataclasses
+from ec_tools.data import DataObject
+
+@dataclasses.dataclass
+class User(DataObject):
+    name: str
+    age: int
+
+user = User.from_json({"name": "Ada", "age": "42"})
+print(user.to_json())
+```
+
+## Encryption helpers
+- `AesCipher` for encrypting/decrypting bytes.
+- Chunked and file-level encryption utilities in `ec_tools.tools.cipher`.
+
+## Project layout
+- `ec_tools/data`: data-object helpers and JSON formatting.
+- `ec_tools/database`: SQLite client, DAO, and KV DAO.
+- `ec_tools/tools`: key/headers managers, cipher tools, thread pool.
+- `ec_tools/utils`: IO, hashing, logging, and timing helpers.
+
+## Development
+```bash
+pytest
+```
+
+## License
+MIT

ec_tools/data/__init__.py

@@ -1,2 +1,9 @@
 from .data_object import CustomizedJsonEncoder, DataObject, Formatter
 from .json_type import JsonType
+
+__all__ = [
+    "CustomizedJsonEncoder",
+    "DataObject",
+    "Formatter",
+    "JsonType",
+]

ec_tools/database/__init__.py

@@ -7,3 +7,16 @@
 from .sqlite_dao.sqlite_dao import SqliteDao
 from .sqlite_dao.sqlite_data_object import SqliteDataObject
 from .sqlite_dao.sqlite_query_generator import SqliteQueryGenerator
+
+__all__ = [
+    "CipherKvDao",
+    "ONE_THOUSAND_YEAR",
+    "KvDao",
+    "KvData",
+    "SqliteKvDao",
+    "SqliteClient",
+    "SqliteQuery",
+    "SqliteDao",
+    "SqliteDataObject",
+    "SqliteQueryGenerator",
+]

ec_tools/tools/__init__.py

@@ -1 +1,5 @@
 from .thread_pool import CustomThreadPoolExecutor
+
+__all__ = [
+    "CustomThreadPoolExecutor",
+]

ec_tools/tools/cipher/__init__.py

@@ -3,3 +3,13 @@
 from .cipher import Cipher, SecrectKey
 from .cipher_generator.aes_cipher_generator import AesCipherGenerator
 from .cipher_generator.cipher_generator import CipherGenerator
+
+__all__ = [
+    "AesCipher",
+    "AesConfig",
+    "AesMode",
+    "Cipher",
+    "SecrectKey",
+    "AesCipherGenerator",
+    "CipherGenerator",
+]

ec_tools/tools/cipher/file_encryption_utils.py

@@ -2,7 +2,10 @@
 
 from ec_tools.tools.cipher.aes_config import AesMode
 from ec_tools.tools.cipher.chunk_config import ChunkConfig
-from ec_tools.tools.cipher.chunk_encryption_utils import decrypt_by_chunk, encrypt_by_chunk
+from ec_tools.tools.cipher.chunk_encryption_utils import (
+    decrypt_by_chunk,
+    encrypt_by_chunk,
+)
 from ec_tools.utils.io_utils import chunk_read_file
 
 

pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = [
+    "setuptools>=61.0",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ec_tools"
+version = "0.3.0"
+description = "A collection of tool for EC."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "colorama==0.4.6",
+    "pycryptodome==3.20.0",
+    "setuptools==69.5.1",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+[project.optional-dependencies]
+dev = ["black"]
+
+[tool.black]
+line-length = 120
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = [
+    "tests/"
+]
+
+[tool.setuptools.packages.find]
+where = ["ec_tools"]

requirements.txt

@@ -1,2 +1,3 @@
+colorama==0.4.6
 pycryptodome==3.20.0
 setuptools==69.5.1

scripts/local.sh

@@ -4,4 +4,3 @@ rm -rf dist/ build/ *.egg-info .pytest_cache/
 find . | grep -E "(/__pycache__$|/\.DS_Store$)" | xargs rm -rf
 python3 -m build
 pip3 install .
-