hamidrezam 0.1.0__tar.gz

hamidrezam-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamidreza Moghaddam Kohi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hamidrezam-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: hamidrezam
+Version: 0.1.0
+Summary: Hamidrezam — safe, intelligent software-project backup tool (library + CLI)
+Author-email: Hamidreza Moghaddam Kohi <info@hamidrezamoghaddam.ir>
+Maintainer-email: Hamidreza Moghaddam Kohi <info@hamidrezamoghaddam.ir>
+License-Expression: MIT
+Project-URL: Homepage, https://hamidrezamoghaddam.ir/
+Keywords: backup,archive,project,cli,developer-tools,zip
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# Hamidrezam — Safe, Intelligent Software-Project Backups
+
+Hamidrezam (`pip install hamidrezam`) is a professional Python library + CLI that creates **clean, optimized project archives** while guaranteeing one non-negotiable invariant:
+
+> **Hamidrezam NEVER modifies the source project.**
+
+Excluded files (`node_modules`, `.venv`, caches, build artifacts, …) are excluded **only from the archive**. They are never deleted, moved, renamed, or touched on disk. Hamidrezam streams selected files **directly into the ZIP** — no temporary cleaned copies.
+
+```bash
+pip install hamidrezam
+hamidrezam backup ./my-project
+# -> ./backups/my-project_2026-09-20_10-50-00.zip
+```
+
+Expected output:
+
+```text
+✓ Project scanned
+✓ Exclusions applied
+✓ Archive created
+✓ Manifest generated
+✓ Archive verified
+```
+
+## Why Hamidrezam?
+
+Developer machines accumulate gigabytes of reproducible data: virtualenvs, `node_modules`, `__pycache__`, `.next/`, `.tox/`, ML runs, logs. Copying all of it for a backup is slow and wasteful — but hand-deleting it is dangerous. Hamidrezam automates the safe middle ground:
+
+- **Safe** — read-only scan; source hashes unchanged (covered by a dedicated integrity test).
+- **Predictable** — every decision has a reason (`hamidrezam explain`).
+- **Transparent** — exclusion report + in-archive manifest with SHA-256 per file.
+- **Fast** — single-pass streaming, chunked hashing, no temp copies.
+- **Cross-platform** — `pathlib` throughout; Windows/Linux/macOS.
+- **Configurable** — CLI > `.hamidrezam.toml` > global config > defaults.
+- **Scriptable & extensible** — typed Python API + `BackupWriter` abstraction (ZIP today, `tar.gz` reserved).
+
+## Features
+
+- Auto-detection of Python, Node.js/npm/pnpm/Yarn, React, Next.js, Vue, Nuxt, PHP, Laravel, Docker, AI/ML, generic/mixed projects.
+- Sensible default exclusions (dependencies, venvs, caches, artifacts, temp, ML outputs) with opt-in knobs for `dist/`/`build/`, IDE dirs, ML outputs.
+- Secrets (`.env*`, `secrets.json`, …) and large-file policies: `include` / `exclude` / `warn` (default `warn` = include + warning).
+- `--dry-run` planning, `explain` auditing, `verify` integrity checks, safe `restore` with traversal protection.
+- Output-inside-source self-inclusion guard; never-silently-overwrite naming.
+- Zero runtime dependencies (stdlib only; `tomli` backport on Python < 3.11).
+
+## Installation
+
+```bash
+pip install hamidrezam
+```
+
+Requires Python ≥ 3.9. Verify:
+
+```bash
+hamidrezam version
+python -m hamidrezam version
+```
+
+## Quick start
+
+```bash
+hamidrezam backup ./my-project
+hamidrezam backup ./my-project --dry-run
+hamidrezam backup ./my-project --include-git
+hamidrezam backup ./my-project --format zip
+hamidrezam backup . --exclude "*.log" --exclude "data/tmp/"
+hamidrezam verify ./backups/my-project_2026-09-20_10-50-00.zip
+hamidrezam restore ./backups/my-project_2026-09-20_10-50-00.zip ./restored --overwrite
+hamidrezam explain ./my-project
+hamidrezam list ./backups/my-project_2026-09-20_10-50-00.zip
+```
+
+## CLI usage
+
+```text
+hamidrezam backup <source> [--output ./backups] [--name NAME] [--format zip]
+                     [--dry-run] [--include-git]
+                     [--exclude GLOB]... [--include GLOB]...
+                     [--secret-mode warn|include|exclude]
+                     [--large-mode warn|include|exclude] [--max-size 2GB]
+                     [--symlink-mode preserve|skip|follow] [--no-compression]
+hamidrezam restore <backup.zip> <destination> [--overwrite]
+hamidrezam verify <backup.zip> [--check-hashes]
+hamidrezam explain <source>
+hamidrezam list <backup.zip>
+hamidrezam version
+python -m hamidrezam <same as above>
+```
+
+Include/exclude precedence: **output-safety > `--include` > protected source-of-truth files > `--exclude` > secrets/large policies > default rules > include**. In short: explicit `--include` wins over default excludes; explicit `--exclude` still wins over protected files (your explicit choice); the archive can never include itself.
+
+## Python API
+
+```python
+from hamidrezam import BackupManager, BackupConfig
+
+manager = BackupManager()
+result = manager.backup(source="./my-project", output="./backups")
+print(result.archive_path, result.verified)
+
+config = BackupConfig(include_git=False, secret_mode="warn", max_size="2GB")
+manager = BackupManager(config=config)
+dry = manager.backup("./project", dry_run=True)
+print(dry.files_included, dry.files_excluded)
+```
+
+Typed results: `BackupResult`, `ScanResult`, `VerificationResult`, `RestoreResult`, `BackupStatistics` (with `archive_path`, `files_included/excluded`, `bytes_included/excluded`, `duration`, `sha256`, `warnings`, …).
+
+## Supported project types
+
+No manual `--type` flag needed. Signals include `pyproject.toml`/`requirements.txt`/`Pipfile` → Python; `package.json` → Node.js (+ `package-lock.json` → npm, `pnpm-lock.yaml` → pnpm, `yarn.lock` → Yarn; `react`/`next`/`vue`/`nuxt` deps → frameworks); `composer.json` → PHP, `artisan` → Laravel; `Dockerfile`/`docker-compose.yml`/`compose.yml` → Docker; notebooks/`wandb`/`.mlflow` → AI/ML. Multiple labels can apply at once.
+
+## Default exclusions
+
+| Area | Excluded (from archive only) |
+|---|---|
+| Python | `.venv/`, `venv/`, `env/`, `ENV/`, `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `.tox/`, `.nox/`, `.coverage`, `htmlcov/`, `*.pyc/pyo/pyd`, `*.egg-info/` |
+| Node/frontend | `node_modules/`, `.npm/`, `.yarn/`, `.pnpm-store/`, `.next/`, `.nuxt/`, `.parcel-cache/`, `.turbo/`, `.cache/`, `coverage/` |
+| AI/ML | `.ipynb_checkpoints/`, `.mlflow/`, `wandb/`, `runs/`, `logs/`, `.cache/` (+ `outputs/`, `checkpoints/` unless `include_outputs=true`) |
+| General | `.cache/`, `tmp/`, `temp/`, `*.tmp`, `*.temp`, `.DS_Store`, `Thumbs.db`, `*.swp/swo` |
+| Build | `dist/`, `build/` unless `include_dist_build=true` |
+| IDE | `.idea/`, `.vscode/` only when `include=false` (default `true` = preserved) |
+| Git | `.git/` unless `--include-git` / `[git] include=true` |
+
+Never excluded by default: `README.md`, `LICENSE`, `.gitignore`, `.gitattributes`, `Dockerfile`, compose files, `package.json`, lock files (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `poetry.lock`, `uv.lock`, `Pipfile.lock`, `composer.lock`), `requirements.txt`, `pyproject.toml`, `composer.json`. Model weights (`*.pt/.pth/.onnx/.safetensors/.ckpt/.bin`) are never auto-excluded for being large — they trigger `warn`.
+
+## Configuration (`.hamidrezam.toml`)
+
+Place in the project root; see `examples/.hamidrezam.toml`:
+
+```toml
+[backup]
+format = "zip"
+compression = true
+output = "./backups"
+
+[git]
+include = false
+
+[secrets]
+mode = "warn"
+
+[large_files]
+mode = "warn"
+max_size = "2GB"
+
+[symlinks]
+mode = "preserve"
+
+[ide]
+include = true
+
+[build]
+include_dist_build = false
+
+[ml]
+include_outputs = false
+
+[custom]
+exclude = ["*.log"]
+include = []
+```
+
+Priority: **CLI args > `.hamidrezam.toml` > global config (`~/.config/hamidrezam/config.toml` or `~/.hamidrezam.toml`) > defaults**.
+
+## Secrets policy
+
+`.env`, `.env.local/.production/.development/.staging`, `secrets.json`, `credentials.json` (plus generic `.env.*`; `.env.example` is treated as a safe template). Default `warn`: included + listed as a warning. Use `exclude` to drop, `include` to silence the warning.
+
+## Large files
+
+Any file over `max_size` (default `2GB`; accepts `500MB`, `1024`, …) follows `large_files.mode` (default `warn`). Never silently dropped.
+
+## Git handling
+
+`.git/` excluded by default (`include_git=false`). Enable per-run (`--include-git`) or per-project (`[git] include=true`). `.gitignore`/`.gitattributes` are always preserved.
+
+## Restore
+
+```bash
+hamidrezam restore backup.zip ./restored-project --overwrite
+```
+
+Validates the archive, rejects `../` and absolute entries, confines writes to the destination, preserves structure, skips existing files unless `--overwrite`, restores symlinks best-effort (falls back to regular files on Windows without privilege).
+
+## Verification
+
+Every backup auto-verifies (ZIP integrity + manifest schema). Re-check later:
+
+```bash
+hamidrezam verify backup.zip
+hamidrezam verify backup.zip --check-hashes   # re-hash contents vs manifest
+```
+
+Each archive embeds `.hamidrezam/manifest.json` with `tool`, `version`, `created_at`, `project_name`, `profiles`, `statistics`, `warnings`, and per-file `path/size/sha256/modified_time` (relative paths only).
+
+## Security
+
+- No blind extraction; all member names validated.
+- Symlinks never followed outside the project; loops detected via `(st_dev, st_ino)`.
+- Broken links, special files (sockets/FIFOs/devices), permission errors → skipped with warnings, never fatal.
+- Secrets/large files surface as warnings, never silently leaked/dropped.
+
+## Examples
+
+- `examples/.hamidrezam.toml` — annotated config.
+- `examples/basic_backup.py` — `python examples/basic_backup.py` after install.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+## Testing
+
+```bash
+pytest            # full suite
+pytest tests/unit
+pytest tests/integration
+```
+
+Covers scanner (nesting/empty/unicode/spaces), exclusions, secrets, large files, ZIP+manifest+hashes, restore/overwrite/traversal, symlinks (broken/outside/skip), CLI exit codes, and the mandatory **source-integrity** test (hashes + paths + mtimes identical before/after backup).
+
+## Roadmap
+
+- `tar.gz` writer (`TarGzBackupWriter` via the existing `BackupWriter` interface).
+- Opt-in `.gitignore`-aware mode, negation (`!`) support.
+- Progress bars, JSON output (`--json`), exclusion-size report table.
+- `hamidrezam init` config generator.
+
+## Known limitations (0.1.0)
+
+- Only `zip` format (`--format tar.gz` fails with a clear future-reserved message).
+- `.gitignore` patterns are parsed by `GitIgnoreRule` for API use but not auto-applied to backups (avoids surprising drops of `.env`-style files).
+- `runs/`, `logs/`, `tmp/`, `temp/`, `outputs/`, `checkpoints/` directory names are excluded wherever they appear; rename intentional source dirs or use `--include` to keep them.
+- Symlink restore on Windows may fall back to regular files without Developer Mode/admin.
+
+## License
+
+MIT — see `LICENSE`.
+
+## Author
+
+**Hamidreza Moghaddam Kohi** — Full Stack Developer · AI · Automation
+Website: <https://hamidrezamoghaddam.ir/> · Email: <info@hamidrezamoghaddam.ir>

hamidrezam-0.1.0/README.md

@@ -0,0 +1,249 @@
+# Hamidrezam — Safe, Intelligent Software-Project Backups
+
+Hamidrezam (`pip install hamidrezam`) is a professional Python library + CLI that creates **clean, optimized project archives** while guaranteeing one non-negotiable invariant:
+
+> **Hamidrezam NEVER modifies the source project.**
+
+Excluded files (`node_modules`, `.venv`, caches, build artifacts, …) are excluded **only from the archive**. They are never deleted, moved, renamed, or touched on disk. Hamidrezam streams selected files **directly into the ZIP** — no temporary cleaned copies.
+
+```bash
+pip install hamidrezam
+hamidrezam backup ./my-project
+# -> ./backups/my-project_2026-09-20_10-50-00.zip
+```
+
+Expected output:
+
+```text
+✓ Project scanned
+✓ Exclusions applied
+✓ Archive created
+✓ Manifest generated
+✓ Archive verified
+```
+
+## Why Hamidrezam?
+
+Developer machines accumulate gigabytes of reproducible data: virtualenvs, `node_modules`, `__pycache__`, `.next/`, `.tox/`, ML runs, logs. Copying all of it for a backup is slow and wasteful — but hand-deleting it is dangerous. Hamidrezam automates the safe middle ground:
+
+- **Safe** — read-only scan; source hashes unchanged (covered by a dedicated integrity test).
+- **Predictable** — every decision has a reason (`hamidrezam explain`).
+- **Transparent** — exclusion report + in-archive manifest with SHA-256 per file.
+- **Fast** — single-pass streaming, chunked hashing, no temp copies.
+- **Cross-platform** — `pathlib` throughout; Windows/Linux/macOS.
+- **Configurable** — CLI > `.hamidrezam.toml` > global config > defaults.
+- **Scriptable & extensible** — typed Python API + `BackupWriter` abstraction (ZIP today, `tar.gz` reserved).
+
+## Features
+
+- Auto-detection of Python, Node.js/npm/pnpm/Yarn, React, Next.js, Vue, Nuxt, PHP, Laravel, Docker, AI/ML, generic/mixed projects.
+- Sensible default exclusions (dependencies, venvs, caches, artifacts, temp, ML outputs) with opt-in knobs for `dist/`/`build/`, IDE dirs, ML outputs.
+- Secrets (`.env*`, `secrets.json`, …) and large-file policies: `include` / `exclude` / `warn` (default `warn` = include + warning).
+- `--dry-run` planning, `explain` auditing, `verify` integrity checks, safe `restore` with traversal protection.
+- Output-inside-source self-inclusion guard; never-silently-overwrite naming.
+- Zero runtime dependencies (stdlib only; `tomli` backport on Python < 3.11).
+
+## Installation
+
+```bash
+pip install hamidrezam
+```
+
+Requires Python ≥ 3.9. Verify:
+
+```bash
+hamidrezam version
+python -m hamidrezam version
+```
+
+## Quick start
+
+```bash
+hamidrezam backup ./my-project
+hamidrezam backup ./my-project --dry-run
+hamidrezam backup ./my-project --include-git
+hamidrezam backup ./my-project --format zip
+hamidrezam backup . --exclude "*.log" --exclude "data/tmp/"
+hamidrezam verify ./backups/my-project_2026-09-20_10-50-00.zip
+hamidrezam restore ./backups/my-project_2026-09-20_10-50-00.zip ./restored --overwrite
+hamidrezam explain ./my-project
+hamidrezam list ./backups/my-project_2026-09-20_10-50-00.zip
+```
+
+## CLI usage
+
+```text
+hamidrezam backup <source> [--output ./backups] [--name NAME] [--format zip]
+                     [--dry-run] [--include-git]
+                     [--exclude GLOB]... [--include GLOB]...
+                     [--secret-mode warn|include|exclude]
+                     [--large-mode warn|include|exclude] [--max-size 2GB]
+                     [--symlink-mode preserve|skip|follow] [--no-compression]
+hamidrezam restore <backup.zip> <destination> [--overwrite]
+hamidrezam verify <backup.zip> [--check-hashes]
+hamidrezam explain <source>
+hamidrezam list <backup.zip>
+hamidrezam version
+python -m hamidrezam <same as above>
+```
+
+Include/exclude precedence: **output-safety > `--include` > protected source-of-truth files > `--exclude` > secrets/large policies > default rules > include**. In short: explicit `--include` wins over default excludes; explicit `--exclude` still wins over protected files (your explicit choice); the archive can never include itself.
+
+## Python API
+
+```python
+from hamidrezam import BackupManager, BackupConfig
+
+manager = BackupManager()
+result = manager.backup(source="./my-project", output="./backups")
+print(result.archive_path, result.verified)
+
+config = BackupConfig(include_git=False, secret_mode="warn", max_size="2GB")
+manager = BackupManager(config=config)
+dry = manager.backup("./project", dry_run=True)
+print(dry.files_included, dry.files_excluded)
+```
+
+Typed results: `BackupResult`, `ScanResult`, `VerificationResult`, `RestoreResult`, `BackupStatistics` (with `archive_path`, `files_included/excluded`, `bytes_included/excluded`, `duration`, `sha256`, `warnings`, …).
+
+## Supported project types
+
+No manual `--type` flag needed. Signals include `pyproject.toml`/`requirements.txt`/`Pipfile` → Python; `package.json` → Node.js (+ `package-lock.json` → npm, `pnpm-lock.yaml` → pnpm, `yarn.lock` → Yarn; `react`/`next`/`vue`/`nuxt` deps → frameworks); `composer.json` → PHP, `artisan` → Laravel; `Dockerfile`/`docker-compose.yml`/`compose.yml` → Docker; notebooks/`wandb`/`.mlflow` → AI/ML. Multiple labels can apply at once.
+
+## Default exclusions
+
+| Area | Excluded (from archive only) |
+|---|---|
+| Python | `.venv/`, `venv/`, `env/`, `ENV/`, `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `.tox/`, `.nox/`, `.coverage`, `htmlcov/`, `*.pyc/pyo/pyd`, `*.egg-info/` |
+| Node/frontend | `node_modules/`, `.npm/`, `.yarn/`, `.pnpm-store/`, `.next/`, `.nuxt/`, `.parcel-cache/`, `.turbo/`, `.cache/`, `coverage/` |
+| AI/ML | `.ipynb_checkpoints/`, `.mlflow/`, `wandb/`, `runs/`, `logs/`, `.cache/` (+ `outputs/`, `checkpoints/` unless `include_outputs=true`) |
+| General | `.cache/`, `tmp/`, `temp/`, `*.tmp`, `*.temp`, `.DS_Store`, `Thumbs.db`, `*.swp/swo` |
+| Build | `dist/`, `build/` unless `include_dist_build=true` |
+| IDE | `.idea/`, `.vscode/` only when `include=false` (default `true` = preserved) |
+| Git | `.git/` unless `--include-git` / `[git] include=true` |
+
+Never excluded by default: `README.md`, `LICENSE`, `.gitignore`, `.gitattributes`, `Dockerfile`, compose files, `package.json`, lock files (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `poetry.lock`, `uv.lock`, `Pipfile.lock`, `composer.lock`), `requirements.txt`, `pyproject.toml`, `composer.json`. Model weights (`*.pt/.pth/.onnx/.safetensors/.ckpt/.bin`) are never auto-excluded for being large — they trigger `warn`.
+
+## Configuration (`.hamidrezam.toml`)
+
+Place in the project root; see `examples/.hamidrezam.toml`:
+
+```toml
+[backup]
+format = "zip"
+compression = true
+output = "./backups"
+
+[git]
+include = false
+
+[secrets]
+mode = "warn"
+
+[large_files]
+mode = "warn"
+max_size = "2GB"
+
+[symlinks]
+mode = "preserve"
+
+[ide]
+include = true
+
+[build]
+include_dist_build = false
+
+[ml]
+include_outputs = false
+
+[custom]
+exclude = ["*.log"]
+include = []
+```
+
+Priority: **CLI args > `.hamidrezam.toml` > global config (`~/.config/hamidrezam/config.toml` or `~/.hamidrezam.toml`) > defaults**.
+
+## Secrets policy
+
+`.env`, `.env.local/.production/.development/.staging`, `secrets.json`, `credentials.json` (plus generic `.env.*`; `.env.example` is treated as a safe template). Default `warn`: included + listed as a warning. Use `exclude` to drop, `include` to silence the warning.
+
+## Large files
+
+Any file over `max_size` (default `2GB`; accepts `500MB`, `1024`, …) follows `large_files.mode` (default `warn`). Never silently dropped.
+
+## Git handling
+
+`.git/` excluded by default (`include_git=false`). Enable per-run (`--include-git`) or per-project (`[git] include=true`). `.gitignore`/`.gitattributes` are always preserved.
+
+## Restore
+
+```bash
+hamidrezam restore backup.zip ./restored-project --overwrite
+```
+
+Validates the archive, rejects `../` and absolute entries, confines writes to the destination, preserves structure, skips existing files unless `--overwrite`, restores symlinks best-effort (falls back to regular files on Windows without privilege).
+
+## Verification
+
+Every backup auto-verifies (ZIP integrity + manifest schema). Re-check later:
+
+```bash
+hamidrezam verify backup.zip
+hamidrezam verify backup.zip --check-hashes   # re-hash contents vs manifest
+```
+
+Each archive embeds `.hamidrezam/manifest.json` with `tool`, `version`, `created_at`, `project_name`, `profiles`, `statistics`, `warnings`, and per-file `path/size/sha256/modified_time` (relative paths only).
+
+## Security
+
+- No blind extraction; all member names validated.
+- Symlinks never followed outside the project; loops detected via `(st_dev, st_ino)`.
+- Broken links, special files (sockets/FIFOs/devices), permission errors → skipped with warnings, never fatal.
+- Secrets/large files surface as warnings, never silently leaked/dropped.
+
+## Examples
+
+- `examples/.hamidrezam.toml` — annotated config.
+- `examples/basic_backup.py` — `python examples/basic_backup.py` after install.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+python -m build
+```
+
+## Testing
+
+```bash
+pytest            # full suite
+pytest tests/unit
+pytest tests/integration
+```
+
+Covers scanner (nesting/empty/unicode/spaces), exclusions, secrets, large files, ZIP+manifest+hashes, restore/overwrite/traversal, symlinks (broken/outside/skip), CLI exit codes, and the mandatory **source-integrity** test (hashes + paths + mtimes identical before/after backup).
+
+## Roadmap
+
+- `tar.gz` writer (`TarGzBackupWriter` via the existing `BackupWriter` interface).
+- Opt-in `.gitignore`-aware mode, negation (`!`) support.
+- Progress bars, JSON output (`--json`), exclusion-size report table.
+- `hamidrezam init` config generator.
+
+## Known limitations (0.1.0)
+
+- Only `zip` format (`--format tar.gz` fails with a clear future-reserved message).
+- `.gitignore` patterns are parsed by `GitIgnoreRule` for API use but not auto-applied to backups (avoids surprising drops of `.env`-style files).
+- `runs/`, `logs/`, `tmp/`, `temp/`, `outputs/`, `checkpoints/` directory names are excluded wherever they appear; rename intentional source dirs or use `--include` to keep them.
+- Symlink restore on Windows may fall back to regular files without Developer Mode/admin.
+
+## License
+
+MIT — see `LICENSE`.
+
+## Author
+
+**Hamidreza Moghaddam Kohi** — Full Stack Developer · AI · Automation
+Website: <https://hamidrezamoghaddam.ir/> · Email: <info@hamidrezamoghaddam.ir>

hamidrezam-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=77", "wheel", "build"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hamidrezam"
+version = "0.1.0"
+description = "Hamidrezam — safe, intelligent software-project backup tool (library + CLI)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Hamidreza Moghaddam Kohi", email = "info@hamidrezamoghaddam.ir" }
+]
+maintainers = [
+    { name = "Hamidreza Moghaddam Kohi", email = "info@hamidrezamoghaddam.ir" }
+]
+keywords = ["backup", "archive", "project", "cli", "developer-tools", "zip"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Archiving :: Backup",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "tomli>=2; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "build>=1",
+]
+test = [
+    "pytest>=7",
+]
+
+[project.urls]
+Homepage = "https://hamidrezamoghaddam.ir/"
+
+[project.scripts]
+hamidrezam = "hamidrezam.cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hamidrezam = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+target-version = "py39"

hamidrezam-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hamidrezam-0.1.0/src/hamidrezam/__init__.py

@@ -0,0 +1,48 @@
+"""Public Python API for hamidrezam.
+
+Example:
+    from hamidrezam import BackupManager, BackupConfig
+
+    manager = BackupManager()
+    result = manager.backup(source="./my-project", output="./backups")
+    print(result.archive_path)
+"""
+
+from __future__ import annotations
+
+from hamidrezam.version import __version__
+from hamidrezam.exceptions import (
+    HamidrezamError,
+    ConfigurationError,
+    SourceNotFoundError,
+    BackupError,
+    RestoreError,
+    VerificationError,
+    UnsafeArchiveError,
+)
+from hamidrezam.config.models import BackupConfig
+from hamidrezam.core.backup import BackupManager, BackupResult
+from hamidrezam.core.scanner import ScanResult, FileEntry, ExcludedEntry
+from hamidrezam.core.restore import RestoreResult
+from hamidrezam.core.verifier import VerificationResult
+from hamidrezam.core.statistics import BackupStatistics
+
+__all__ = [
+    "__version__",
+    "HamidrezamError",
+    "ConfigurationError",
+    "SourceNotFoundError",
+    "BackupError",
+    "RestoreError",
+    "VerificationError",
+    "UnsafeArchiveError",
+    "BackupConfig",
+    "BackupManager",
+    "BackupResult",
+    "ScanResult",
+    "FileEntry",
+    "ExcludedEntry",
+    "RestoreResult",
+    "VerificationResult",
+    "BackupStatistics",
+]

hamidrezam-0.1.0/src/hamidrezam/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m hamidrezam`` (forwards to the CLI)."""
+
+from __future__ import annotations
+
+import sys
+
+from hamidrezam.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())