chore: scaffolder - add pre-commit, bandit, unpinned dev deps, README docs and venv handling

Author: Magic-Man-us

.clinerules/workflows/scaffolding-guide.md

@@ -0,0 +1,131 @@
+
+# Scaffold Python Package – Create & Launch New Project
+
+## 🎯 Purpose  
+Implement a scaffolding project that allows you to launch new Python packages with full setup: `uv` venv management, `pyproject.toml`, `pytest + coverage`, `Sphinx` docs, Git repo, CI config.
+
+## ✅ Inputs  
+- `package_name` — Package name (PEP 8 valid, e.g. `my_cool_pkg`)  
+- `target_dir` — Absolute path to parent directory where the project folder will be created  
+
+## ✅ Sequence of Tasks  
+
+### 1. Validate inputs  
+- [ ] Run shell script to check `package_name` matches `[a-zA-Z_][a-zA-Z0-9_]*`  
+- [ ] Ensure `target_dir` is an absolute path  
+```bash
+set -e
+PKG="${package_name}"
+DIR="${target_dir}"
+python3 - <<'PY'
+import re, sys, os
+pkg=sys.argv[1]; dir_=sys.argv[2]
+if not re.fullmatch(r'[a-zA-Z_][a-zA-Z0-9_]*', pkg):
+    print(f"Invalid package_name: {pkg}"); sys.exit(1)
+if not os.path.isabs(dir_):
+    print(f"target_dir must be absolute: {dir_}"); sys.exit(1)
+print("Inputs OK.")
+PY "$PKG" "$DIR"
+````
+
+### 2. Prepare template workspace
+
+* [ ] Create a temporary workspace `.cline_tmp_pkg_template`
+* [ ] Within it, create directory structure for TEMPLATE:
+
+  * `TEMPLATE/{{PKG}}/`
+  * `TEMPLATE/tests/`
+  * `TEMPLATE/docs/`
+  * `TEMPLATE/.github/workflows/`
+* [ ] Add the following files in TEMPLATE (with placeholder `{{PKG}}` inside):
+
+  * `pyproject.toml`
+  * `README.md`
+  * `LICENSE`
+  * `.gitignore`
+  * `.github/workflows/ci.yaml`
+  * `{{PKG}}/__init__.py`, `{{PKG}}/hello.py`
+  * `tests/test_hello.py`
+  * `docs/conf.py`, `docs/index.rst`
+  * `requirements-dev.txt`
+  * `Makefile`
+  * Optional `setup.cfg` or patch file for dev-extras
+
+### 3. Materialize project & substitute placeholders
+
+* [ ] Compute `DEST="${target_dir}/${package_name}"`
+* [ ] Fail if `DEST` already exists
+* [ ] Copy all files from workspace TEMPLATE to `${DEST}`
+* [ ] Recursively replace placeholder `{{PKG}}` with actual `package_name` in all files
+* [ ] Print “Project created at: ${DEST}”
+
+### 4. Initialize git repository
+
+* [ ] `cd` into `${DEST}`
+* [ ] `git init`
+* [ ] `git add .`
+* [ ] `git commit -m "chore: initial scaffold"`
+* [ ] Print “Git repo initialized.”
+
+### 5. Setup `uv` environment & install dev extras
+
+* [ ] `cd "${DEST}"`
+* [ ] `uv venv`
+* [ ] `uv pip install -e ".[dev]"`
+* [ ] Print “Environment ready.”
+
+### 6. Run tests & coverage
+
+* [ ] `cd "${DEST}"`
+* [ ] `uv run pytest --cov="${package_name}" --cov-report=term-missing`
+
+### 7. Build Sphinx documentation
+
+* [ ] `cd "${DEST}"`
+* [ ] `uv run sphinx-build -b html docs docs/_build/html`
+* [ ] Print “Docs built at: docs/_build/html”
+
+### 8. Output summary
+
+* [ ] Print “Scaffold complete.”
+* [ ] Print project path: `${DEST}`
+* [ ] Print next steps:
+
+  ```text
+  cd "${DEST}"
+  source .venv/bin/activate  # (or use uv run)
+  uv run python -c "import ${package_name}; print(${package_name}.hello())"
+  ```
+
+## 📁 Generated Structure
+
+```
+${package_name}/
+  .github/workflows/ci.yaml
+  docs/
+    conf.py
+    index.rst
+    _build/           (after docs build)
+  tests/
+    test_hello.py
+  ${package_name}/
+    __init__.py
+    hello.py
+  .gitignore
+  LICENSE
+  Makefile
+  README.md
+  pyproject.toml
+  requirements-dev.txt
+  setup.cfg
+```
+
+## 📝 Notes
+
+* Uses `uv` for virtualenv management.
+* Configured for `pytest + pytest-cov`.
+* Sphinx docs with theme `furo` (can edit in `docs/conf.py`).
+* Dev extras via `pyproject.toml` optional-deps.
+* CI workflow provided in `.github/workflows/ci.yaml`.
+
+```

pyproject.toml

@@ -43,8 +43,8 @@ dev = [
 scaffold-python = "python_project_deployment.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/magicman/python-project-deployment"
-Repository = "https://github.com/magicman/python-project-deployment"
+Homepage = "https://github.com/Magic-Man-us/PythonProjectDeployment"
+Repository = "https://github.com/Magic-Man-us/PythonProjectDeployment"
 
 [tool.hatch.build.targets.wheel]
 packages = ["python_project_deployment"]
@@ -54,12 +54,12 @@ testpaths = ["tests"]
 addopts = "--cov=python_project_deployment --cov-report=term-missing --cov-report=html"
 
 [tool.black]
-line-length = 88
+line-length = 100
 target-version = ['py310']
 
 [tool.isort]
 profile = "black"
-line_length = 88
+line_length = 100
 
 [tool.mypy]
 python_version = "3.10"
@@ -68,6 +68,8 @@ warn_unused_configs = true
 disallow_untyped_defs = true
 
 [tool.ruff]
-line-length = 88
+line-length = 100
 target-version = "py310"
+
+[tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "B", "C4"]

python_project_deployment/__init__.py

@@ -5,4 +5,4 @@
 from python_project_deployment.models import ProjectConfig
 from python_project_deployment.scaffolder import Scaffolder
 
-__all__ = ["Scaffolder", "ProjectConfig", "__version__"]
+__all__ = ["__version__", "ProjectConfig", "Scaffolder"]

python_project_deployment/cli.py

@@ -50,10 +50,10 @@ def main(
     verbose: bool,
 ) -> None:
     """Scaffold a new Python package with best practices.
-    
+
     PACKAGE_NAME: Valid Python package identifier (e.g., my_awesome_pkg)
     TARGET_DIR: Absolute path to parent directory for the project
-    
+
     Example:
         scaffold-python my_package /home/user/projects
     """
@@ -113,7 +113,8 @@ def main(
         click.echo("\n📖 Next steps:")
         click.echo(f"  1. cd {result_path}")
         click.echo("  2. source .venv/bin/activate  # (or use uv run)")
-        click.echo(f"  3. uv run python -c \"import {package_name}; print({package_name}.hello())\"")
+        cmd = f'uv run python -c "import {package_name}; print({package_name}.hello())"'
+        click.echo(f"  3. {cmd}")
 
         click.echo("\n🔍 Available commands:")
         click.echo("  • Run tests: pytest")
@@ -140,6 +141,7 @@ def main(
         click.secho(f"\n❌ Unexpected Error: {e}", fg="red", bold=True)
         if verbose:
             import traceback
+
             click.echo("\n" + traceback.format_exc())
         sys.exit(1)
 

python_project_deployment/models.py

@@ -8,7 +8,7 @@
 
 class ProjectConfig(BaseModel):
     """Configuration model for a Python project to be scaffolded.
-    
+
     Attributes:
         package_name: Valid Python package identifier
         target_dir: Absolute path to parent directory where project will be created
@@ -50,32 +50,33 @@ class ProjectConfig(BaseModel):
     def validate_package_name(cls, v: str) -> str:
         """Validate that package_name is a valid Python identifier."""
         if not re.fullmatch(r"[a-zA-Z_][a-zA-Z0-9_]*", v):
-            raise ValueError(
-                f"Invalid package_name: '{v}'. "
+            msg = (
+                "Invalid package_name: '" + v + "'. "
                 "Must start with letter or underscore, "
                 "followed by letters, numbers, or underscores."
             )
+            raise ValueError(msg)
         return v
 
     @field_validator("target_dir")
     @classmethod
     def validate_target_dir(cls, v: Path) -> Path:
         """Validate that target_dir is an absolute path."""
         if not v.is_absolute():
-            raise ValueError(
-                f"target_dir must be an absolute path, got: {v}"
-            )
+            msg = "target_dir must be an absolute path, got: " + str(v)
+            raise ValueError(msg)
         return v
 
     @model_validator(mode="after")
     def validate_destination_not_exists(self) -> "ProjectConfig":
         """Validate that destination directory doesn't already exist."""
         destination = self.target_dir / self.package_name
         if destination.exists():
-            raise ValueError(
-                f"Destination already exists: {destination}. "
+            msg = (
+                "Destination already exists: " + str(destination) + ". "
                 "Please choose a different package_name or target_dir."
             )
+            raise ValueError(msg)
         return self
 
     @property