Metadata-Version: 2.4
Name: connectionsphere-fastapi-cli
Version: 0.3.3
Summary: CLI to scaffold production-ready FastAPI projects with UV, Docker, and GitHub Actions
Author-email: Martin Hewing <martinhewing777@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ConnectSphere/connectionsphere-fastapi-cli
Project-URL: Repository, https://github.com/ConnectSphere/connectionsphere-fastapi-cli
Project-URL: Issues, https://github.com/ConnectSphere/connectionsphere-fastapi-cli/issues
Keywords: fastapi,cli,scaffold,boilerplate,generator,uv,docker,github-actions,modern-python
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: inflect>=7.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# connectionsphere-fastapi-cli

A command-line tool for scaffolding production-ready FastAPI projects. Generates a complete project structure with UV dependency management, GitHub Actions CI/CD, Docker, pre-commit hooks, Ruff, and MyPy — ready to run on first install.

---

## Installation

```bash
pip install connectionsphere-fastapi-cli
```

Requires Python 3.10 or later.

---

## Commands

### `fastapi-scaffold`

Scaffold a production-ready FastAPI project.

```bash
fastapi-cli fastapi-scaffold <project-name> [OPTIONS]
```

**Options**

| Flag | Description |
|---|---|
| `--postgres` | Add PostgreSQL integration (SQLModel, Alembic, psycopg2) |
| `--redis` | Add Redis integration |

**Examples**

```bash
# Minimal project
fastapi-cli fastapi-scaffold my-api

# With Postgres and Redis
fastapi-cli fastapi-scaffold my-api --postgres --redis
```

**Generated structure**

```
my-api/
├── app/
│   ├── api/
│   │   └── v1/
│   │       └── endpoints.py
│   ├── core/
│   │   ├── config.py          # Pydantic Settings, injected via Depends
│   │   └── security.py        # JWT + bcrypt, env-validated secret key
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── main.py                # App factory + lifespan context manager
├── tests/
│   ├── conftest.py            # TestClient fixture, function scope
│   └── test_main.py
├── .github/
│   └── workflows/
│       └── ci.yml             # uv, Ruff, MyPy, pytest
├── alembic/                   # If --postgres
├── docker-compose.yml
├── pyproject.toml             # uv-compatible, Ruff + MyPy configured
└── .env                       # Placeholder values, gitignored
```

---

### `init`

Initialise a plain UV Python project with a virtual environment, core dependencies, pre-commit hooks, and a GitHub Actions workflow.

```bash
fastapi-cli init <project-name>
```

Requires `uv` to be installed. Install with:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

---

### `create-github`

Create a GitHub repository from a local project directory and push all files.

```bash
fastapi-cli create-github <project-dir> [OPTIONS]
```

**Options**

| Flag | Description |
|---|---|
| `--repo-name TEXT` | Repository name (defaults to directory name) |
| `--private` | Create a private repository (default: public) |

Requires the [GitHub CLI](https://cli.github.com) (`gh`) to be installed and authenticated.

---

### Reference guides

Built-in terminal reference guides — no internet connection required.

| Command | Description |
|---|---|
| `fastapi-cli git-cheat-sheet` | Git commands reference |
| `fastapi-cli git-refactor-workflow` | Git workflow for refactoring legacy projects |
| `fastapi-cli pseudocode-guide` | Pseudocode conventions for DSA problems |

---

## What the scaffold enforces

**Security** — `SECRET_KEY` is loaded from the environment. The application raises `RuntimeError` at startup if the variable is unset or holds the default placeholder. No secrets are hardcoded in generated source files.

**Settings** — `pydantic-settings` with `BaseSettings`. Settings are injected via `Depends(get_settings)`, never imported as a module-level singleton. The `@lru_cache` factory ensures one `Settings` instance per process; tests call `get_settings.cache_clear()` and use `dependency_overrides`.

**App factory** — `main.py` uses a `create_app()` factory and a `lifespan` context manager rather than a bare module-level `FastAPI()` instance. Startup and shutdown logic has a defined home.

**Testing** — `conftest.py` uses `scope="function"` for the `TestClient` fixture. Mutable state is never shared across tests. The fixture includes a commented scaffold for SQLite in-memory `dependency_overrides` for integration tests.

**CI** — GitHub Actions workflow uses `uv` throughout. Steps: install, Ruff lint, Ruff format check, MyPy type check, pytest. Postgres and Redis service containers are included automatically when the corresponding flags were passed at scaffold time.

**Tooling** — Ruff handles both linting and formatting. MyPy runs in strict mode. Black is not included; Ruff's formatter covers the same ground without the dependency.

---

## Requirements

| Tool | Required | Purpose |
|---|---|---|
| Python | 3.10+ | Runtime |
| uv | Optional | Used by `init` command and generated projects |
| gh (GitHub CLI) | Optional | Used by `create-github` command |

---

## Development

```bash
git clone https://github.com/ConnectSphere/connectionsphere-fastapi-cli
cd connectionsphere-fastapi-cli
uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy src/
```

---

## Changelog

### 0.3.0
- First release of the real implementation
- `fastapi-scaffold` command with Jinja2 template engine
- `--postgres` and `--redis` flags
- App factory pattern, lifespan context manager
- Environment-validated secret key, no hardcoded credentials
- `init` and `create-github` commands
- Built-in terminal reference guides

---

## License

MIT
