pyforge-init 0.1.0__tar.gz

pyforge_init-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Publish Release to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    name: Run Test Suite
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run Tests
+        run: |
+          python -m pytest -v
+
+  publish:
+    name: Build and Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for trusted publishing (OIDC)
+      contents: read
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Build CLI
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build Source and Binary Distributions
+        run: |
+          python -m build
+
+      - name: Publish Package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pyforge_init-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python cache files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Build and distribution
+build/
+dist/
+*.egg-info/
+
+# Environments
+.venv/
+env/
+venv/
+ENV/
+.env
+
+# IDEs
+.idea/
+.vscode/

pyforge_init-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: pyforge-init
+Version: 0.1.0
+Summary: A CLI tool to scaffold new Python projects, similar to create-react-app.
+Author-email: Your Name <your.email@example.com>
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyforge
+
+`pyforge` is a lightweight, interactive command-line interface (CLI) tool designed to scaffold production-ready Python projects in seconds. Inspired by standard scaffolding tools, `pyforge` automates project initialization, environment setup, testing configuration, linting, formatting, and dependency management.
+
+---
+
+## Key Features
+
+* **Interactive TUI**: Driven by `questionary` for guided project configuration (supports non-interactive overrides).
+* **Multiple Built-in Templates**: Native templates for `basic` packages, `cli` tools, `fastapi` microservices, and `flask` applications.
+* **Remote Templates**: Pull custom project layouts directly from public GitHub repositories using the `gh:owner/repo` syntax.
+* **Configurable Defaults**: Save persistent author, license, and tool choices in a `~/.newpythonrc` configuration file.
+* **Standards-Compliant**: Generates PEP 621-compliant `pyproject.toml` using `hatchling` as the build backend.
+* **Tooling Configuration**: Preconfigured integration with `pytest`, `ruff` (linter and formatter), and `pre-commit` hooks.
+* **Task Automation**: Automated creation of a local virtual environment, Git repository initialization, and generation of a template-aware `Makefile` or `Justfile`.
+
+---
+
+## Installation
+
+Install `pyforge-init` globally via PyPI:
+
+```bash
+pip install pyforge-init
+```
+
+Or install it in an isolated environment using `pipx`:
+
+```bash
+pipx install pyforge-init
+```
+
+---
+
+## Quick Start
+
+Initialize a new project by running:
+
+```bash
+newpython myproject
+```
+
+The CLI will start the interactive configuration wizard:
+
+```
+? Project description: A new Python project
+? Author name: Jane Doe
+? License: MIT
+? Initialize a virtual environment (.venv)? Yes
+? Initialize a git repository? Yes
+```
+
+Once the wizard completes, your project directory is created and populated. Execute the following commands to begin development:
+
+```bash
+cd myproject
+source .venv/bin/activate    # On Windows use: .venv\Scripts\activate
+make install                 # Installs the package and all dev dependencies
+make run                     # Runs the application (varies by template)
+```
+
+---
+
+## CLI Reference
+
+```
+Usage: newpython [OPTIONS] PROJECT_NAME
+
+  Scaffold a new Python project.
+
+Arguments:
+  PROJECT_NAME  Name of the project (must be a valid Python identifier)
+
+Options:
+  --template TEXT      Built-in template (basic, cli, fastapi, flask)
+                       or a remote GitHub repo (gh:owner/repo[@ref]) [default: basic]
+  --no-pre-commit      Skip generating .pre-commit-config.yaml
+  --justfile           Generate a Justfile instead of a Makefile
+  -y, --yes            Skip interactive prompts and accept defaults
+  --help               Show this message and exit.
+```
+
+---
+
+## Project Structure (Basic Template)
+
+The default template (`basic`) generates the following directory structure:
+
+```
+myproject/
+├── src/
+│   └── myproject/
+│       └── __init__.py          # Package initialization
+├── tests/
+│   └── test_main.py             # Starter unit test
+├── .env.example                 # Example environment variables
+├── .gitignore                   # Standard Python git ignore rules
+├── .pre-commit-config.yaml      # Pre-configured linting/formatting hooks
+├── Makefile                     # Task runner
+├── README.md                    # Generated project documentation
+├── pyproject.toml               # Metadata, dependencies, and tool settings
+└── requirements.txt             # Project dependencies
+```
+
+---
+
+## Templates
+
+### Built-in Templates
+
+| Template | Primary Stack | Generated Entry Point | Run Command |
+|---|---|---|---|
+| `basic` | Pure Python | `src/package/__init__.py` | `python -m package` |
+| `cli` | `click` | `src/package/cli.py` & `__main__.py` | Registered console script |
+| `fastapi` | `fastapi`, `uvicorn`, `httpx` | `src/package/main.py` | `uvicorn src.package.main:app` |
+| `flask` | `flask` (Factory pattern) | `src/package/app.py` | `flask run` |
+
+### Remote Templates
+
+You can import any public GitHub repository to use as a project template:
+
+```bash
+# Uses the main/master branch
+newpython myproject --template gh:username/repo-name
+
+# Pin to a specific branch, tag, or commit hash
+newpython myproject --template gh:username/repo-name@v1.0.0
+```
+
+#### Remote Repository Requirements
+Remote templates are fetched and copied as-is (no Jinja template rendering is performed on remote files). 
+* If the remote repository has a top-level `template/` directory, only the contents of that folder are copied to the destination.
+* If no `template/` directory is present, the entire contents of the repository root will be copied.
+
+---
+
+## Configuration File (`~/.newpythonrc`)
+
+You can persist configuration defaults in a `~/.newpythonrc` (TOML format) file to pre-fill prompt values and skip entering them on every run.
+
+```toml
+# ~/.newpythonrc
+author = "Jane Doe"
+license = "MIT"
+template = "basic"
+pre_commit = true
+justfile = false
+```
+
+### Precedence Order
+When resolving configurations, `pyforge` applies overrides in the following order (highest to lowest):
+1. **CLI Flags** (e.g. `--template`, `--justfile`)
+2. **Configuration file** (`~/.newpythonrc`)
+3. **Interactive Prompt Defaults**
+
+To override the default config location, set the `NEWPYTHON_CONFIG` environment variable:
+```bash
+export NEWPYTHON_CONFIG="/path/to/custom/config.toml"
+```
+
+---
+
+## Automated Task Runner
+
+The generated `Makefile` (or `Justfile` if `--justfile` is passed) exposes standard commands for project maintenance:
+
+* `make install`: Installs the project locally in editable mode alongside all development dependencies (`pip install -e ".[dev]"`).
+* `make test`: Executes the test suite using `pytest`.
+* `make lint`: Performs static analysis checking with `ruff`.
+* `make format`: Auto-formats code styles using `ruff format`.
+* `make run`: Starts the application server or CLI script (template-aware).
+* `make clean`: Recursively cleans local cache directories (`__pycache__`, `.pytest_cache`, `.ruff_cache`, `build`, `dist`).
+
+---
+
+## Publishing to PyPI
+
+Projects generated by `pyforge` use `hatchling` as the build system and are ready to be built and uploaded to PyPI:
+
+1. Install build and publication dependencies:
+   ```bash
+   pip install build twine
+   ```
+2. Build the project distribution packages (source archive and wheel):
+   ```bash
+   python -m build
+   ```
+3. Upload to PyPI (or TestPyPI first):
+   ```bash
+   python -m twine upload dist/*
+   ```
+
+---
+
+## Contributing
+
+Contributions to `pyforge` are welcome. To set up a local development environment:
+
+```bash
+git clone https://github.com/your-name/pyforge.git
+cd pyforge
+pip install -e ".[dev]"
+python -m pytest -v
+```

pyforge_init-0.1.0/README.md

@@ -0,0 +1,204 @@
+# pyforge
+
+`pyforge` is a lightweight, interactive command-line interface (CLI) tool designed to scaffold production-ready Python projects in seconds. Inspired by standard scaffolding tools, `pyforge` automates project initialization, environment setup, testing configuration, linting, formatting, and dependency management.
+
+---
+
+## Key Features
+
+* **Interactive TUI**: Driven by `questionary` for guided project configuration (supports non-interactive overrides).
+* **Multiple Built-in Templates**: Native templates for `basic` packages, `cli` tools, `fastapi` microservices, and `flask` applications.
+* **Remote Templates**: Pull custom project layouts directly from public GitHub repositories using the `gh:owner/repo` syntax.
+* **Configurable Defaults**: Save persistent author, license, and tool choices in a `~/.newpythonrc` configuration file.
+* **Standards-Compliant**: Generates PEP 621-compliant `pyproject.toml` using `hatchling` as the build backend.
+* **Tooling Configuration**: Preconfigured integration with `pytest`, `ruff` (linter and formatter), and `pre-commit` hooks.
+* **Task Automation**: Automated creation of a local virtual environment, Git repository initialization, and generation of a template-aware `Makefile` or `Justfile`.
+
+---
+
+## Installation
+
+Install `pyforge-init` globally via PyPI:
+
+```bash
+pip install pyforge-init
+```
+
+Or install it in an isolated environment using `pipx`:
+
+```bash
+pipx install pyforge-init
+```
+
+---
+
+## Quick Start
+
+Initialize a new project by running:
+
+```bash
+newpython myproject
+```
+
+The CLI will start the interactive configuration wizard:
+
+```
+? Project description: A new Python project
+? Author name: Jane Doe
+? License: MIT
+? Initialize a virtual environment (.venv)? Yes
+? Initialize a git repository? Yes
+```
+
+Once the wizard completes, your project directory is created and populated. Execute the following commands to begin development:
+
+```bash
+cd myproject
+source .venv/bin/activate    # On Windows use: .venv\Scripts\activate
+make install                 # Installs the package and all dev dependencies
+make run                     # Runs the application (varies by template)
+```
+
+---
+
+## CLI Reference
+
+```
+Usage: newpython [OPTIONS] PROJECT_NAME
+
+  Scaffold a new Python project.
+
+Arguments:
+  PROJECT_NAME  Name of the project (must be a valid Python identifier)
+
+Options:
+  --template TEXT      Built-in template (basic, cli, fastapi, flask)
+                       or a remote GitHub repo (gh:owner/repo[@ref]) [default: basic]
+  --no-pre-commit      Skip generating .pre-commit-config.yaml
+  --justfile           Generate a Justfile instead of a Makefile
+  -y, --yes            Skip interactive prompts and accept defaults
+  --help               Show this message and exit.
+```
+
+---
+
+## Project Structure (Basic Template)
+
+The default template (`basic`) generates the following directory structure:
+
+```
+myproject/
+├── src/
+│   └── myproject/
+│       └── __init__.py          # Package initialization
+├── tests/
+│   └── test_main.py             # Starter unit test
+├── .env.example                 # Example environment variables
+├── .gitignore                   # Standard Python git ignore rules
+├── .pre-commit-config.yaml      # Pre-configured linting/formatting hooks
+├── Makefile                     # Task runner
+├── README.md                    # Generated project documentation
+├── pyproject.toml               # Metadata, dependencies, and tool settings
+└── requirements.txt             # Project dependencies
+```
+
+---
+
+## Templates
+
+### Built-in Templates
+
+| Template | Primary Stack | Generated Entry Point | Run Command |
+|---|---|---|---|
+| `basic` | Pure Python | `src/package/__init__.py` | `python -m package` |
+| `cli` | `click` | `src/package/cli.py` & `__main__.py` | Registered console script |
+| `fastapi` | `fastapi`, `uvicorn`, `httpx` | `src/package/main.py` | `uvicorn src.package.main:app` |
+| `flask` | `flask` (Factory pattern) | `src/package/app.py` | `flask run` |
+
+### Remote Templates
+
+You can import any public GitHub repository to use as a project template:
+
+```bash
+# Uses the main/master branch
+newpython myproject --template gh:username/repo-name
+
+# Pin to a specific branch, tag, or commit hash
+newpython myproject --template gh:username/repo-name@v1.0.0
+```
+
+#### Remote Repository Requirements
+Remote templates are fetched and copied as-is (no Jinja template rendering is performed on remote files). 
+* If the remote repository has a top-level `template/` directory, only the contents of that folder are copied to the destination.
+* If no `template/` directory is present, the entire contents of the repository root will be copied.
+
+---
+
+## Configuration File (`~/.newpythonrc`)
+
+You can persist configuration defaults in a `~/.newpythonrc` (TOML format) file to pre-fill prompt values and skip entering them on every run.
+
+```toml
+# ~/.newpythonrc
+author = "Jane Doe"
+license = "MIT"
+template = "basic"
+pre_commit = true
+justfile = false
+```
+
+### Precedence Order
+When resolving configurations, `pyforge` applies overrides in the following order (highest to lowest):
+1. **CLI Flags** (e.g. `--template`, `--justfile`)
+2. **Configuration file** (`~/.newpythonrc`)
+3. **Interactive Prompt Defaults**
+
+To override the default config location, set the `NEWPYTHON_CONFIG` environment variable:
+```bash
+export NEWPYTHON_CONFIG="/path/to/custom/config.toml"
+```
+
+---
+
+## Automated Task Runner
+
+The generated `Makefile` (or `Justfile` if `--justfile` is passed) exposes standard commands for project maintenance:
+
+* `make install`: Installs the project locally in editable mode alongside all development dependencies (`pip install -e ".[dev]"`).
+* `make test`: Executes the test suite using `pytest`.
+* `make lint`: Performs static analysis checking with `ruff`.
+* `make format`: Auto-formats code styles using `ruff format`.
+* `make run`: Starts the application server or CLI script (template-aware).
+* `make clean`: Recursively cleans local cache directories (`__pycache__`, `.pytest_cache`, `.ruff_cache`, `build`, `dist`).
+
+---
+
+## Publishing to PyPI
+
+Projects generated by `pyforge` use `hatchling` as the build system and are ready to be built and uploaded to PyPI:
+
+1. Install build and publication dependencies:
+   ```bash
+   pip install build twine
+   ```
+2. Build the project distribution packages (source archive and wheel):
+   ```bash
+   python -m build
+   ```
+3. Upload to PyPI (or TestPyPI first):
+   ```bash
+   python -m twine upload dist/*
+   ```
+
+---
+
+## Contributing
+
+Contributions to `pyforge` are welcome. To set up a local development environment:
+
+```bash
+git clone https://github.com/your-name/pyforge.git
+cd pyforge
+pip install -e ".[dev]"
+python -m pytest -v
+```

pyforge_init-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyforge-init"
+version = "0.1.0"
+description = "A CLI tool to scaffold new Python projects, similar to create-react-app."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Your Name", email = "your.email@example.com" }
+]
+dependencies = [
+    "click>=8.0.0",
+    "jinja2>=3.0.0",
+    "rich>=13.0.0",
+    "questionary>=2.0.0",
+    "httpx>=0.27.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+]
+
+[project.scripts]
+newpython = "pyforge.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-mock>=3.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyforge"]

pyforge_init-0.1.0/src/pyforge/__init__.py

@@ -0,0 +1,4 @@
+"""
+pyforge - Python Project Generator
+"""
+__version__ = "0.1.0"