From f543aa8315aa5e5ce469c86c9c26944a562cc6c6 Mon Sep 17 00:00:00 2001 From: mohit-tanwar-dev <275454979+mohit-tanwar-dev@users.noreply.github.com> Date: Wed, 5 Aug 2026 07:42:55 +0000 Subject: [PATCH] docs: strip emojis and tighten README, CONTRIBUTING, SECURITY, CHANGELOG, templates --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yml | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 16 +- CHANGELOG.md | 16 +- CONTRIBUTING.md | 40 ++--- README.md | 196 +++++---------------- SECURITY.md | 13 +- 8 files changed, 85 insertions(+), 202 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 0f6cf87..64ea3bd 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,4 +1,4 @@ -name: ๐Ÿ› Bug report +name: Bug report description: Report something that's broken labels: ["bug", "needs-triage"] body: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 5ef6d56..553ee47 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,5 @@ blank_issues_enabled: false contact_links: - - name: ๐Ÿ’ฌ Ask a question + - name: Ask a question url: https://github.com/mohit-tanwar-dev/python-backend/discussions about: Ask questions and discuss ideas in Discussions. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index a99bdb0..36eef25 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,4 +1,4 @@ -name: โœจ Feature request +name: Feature request description: Suggest a new feature or improvement labels: ["enhancement", "needs-triage"] body: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7c9d5b6..83da2b0 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,17 +4,17 @@ ## Type of change -- [ ] ๐Ÿ› Bug fix (non-breaking change that fixes an issue) -- [ ] โœจ New feature (non-breaking change that adds functionality) -- [ ] ๐Ÿ’ฅ Breaking change (would cause existing functionality to not work as expected) -- [ ] ๐Ÿ“ Documentation update -- [ ] โ™ป๏ธ Refactor (no functional changes) -- [ ] ๐Ÿงช Test additions / improvements -- [ ] ๐Ÿ”ง CI / build / tooling +- [ ] Bug fix (non-breaking change that fixes an issue) +- [ ] New feature (non-breaking change that adds functionality) +- [ ] Breaking change (would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Refactor (no functional changes) +- [ ] Test additions / improvements +- [ ] CI / build / tooling ## Checklist -- [ ] My code follows the [style guide](../ruff.toml) (`ruff check .` passes) +- [ ] My code follows the style guide (`ruff check .` passes) - [ ] I ran `ruff format .` and the code is formatted - [ ] I added / updated tests for my changes - [ ] `pytest -v` passes locally diff --git a/CHANGELOG.md b/CHANGELOG.md index 4523930..62d156d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,14 +11,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - FastAPI application scaffold with `lifespan` event hooks. -- `/health` and `/api/v1/health` endpoints returning service status, version, and uptime. -- Root `/` endpoint returning basic service info. -- Pydantic-settings based configuration with sensible defaults. -- Structured logging via stdlib `logging`. -- `pytest` test suite covering all endpoints. -- `ruff` lint + format configuration targeting Python 3.12. -- `mypy` for static type checking. -- `.env.example` documenting all supported environment variables. +- `/health` and `/api/v1/health` endpoints. +- Root `/` endpoint. +- Pydantic-settings configuration with defaults. +- Structured logging. +- pytest test suite covering all endpoints. +- Ruff lint + format configuration targeting Python 3.12. +- mypy for static type checking. +- `.env.example`. - MIT License. [Unreleased]: https://github.com/mohit-tanwar-dev/python-backend/compare/v0.1.0...HEAD diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b87dbf8..577ad3e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,40 +1,25 @@ # Contributing to python-backend -Thanks for taking the time to contribute! ๐ŸŽ‰ - -This document describes how to set up your environment and submit changes. - -## ๐Ÿ› ๏ธ Development setup +## Development setup ```bash -# 1. Fork & clone git clone https://github.com//python-backend.git cd python-backend - -# 2. Create a virtual environment python -m venv .venv source .venv/bin/activate # Linux / macOS # .venv\Scripts\activate # Windows - -# 3. Install dev dependencies pip install -r requirements-dev.txt - -# 4. Copy env file (optional โ€” defaults work out of the box) cp .env.example .env - -# 5. Run the server uvicorn app.main:app --reload - -# 6. Run tests / lint pytest -v ruff check . ruff format --check . mypy app tests ``` -## ๐ŸŒฟ Branch & commit conventions +## Branch and commit conventions -- Branch from `main`: `feat/my-feature`, `fix/my-bugfix`, `docs/my-change` +- Branch from `main`: `feat/...`, `fix/...`, `docs/...` - Use [Conventional Commits](https://www.conventionalcommits.org/): - `feat: add /ready endpoint` - `fix: handle missing env var gracefully` @@ -43,20 +28,19 @@ mypy app tests - `test: add tests for /api/v1/health` - `chore: bump ruff to 0.8.5` -## ๐Ÿšฆ Pull request flow +## Pull request flow 1. Open a PR against `main`. -2. CI must pass (ruff + pytest on Python 3.11 & 3.12). -3. Request a review. -4. Squash-and-merge once approved. +2. CI must pass (ruff + pytest on Python 3.11 and 3.12). +3. Squash-and-merge once approved. -## โœ… Code style +## Code style -- Python 3.12+ syntax is fine (PEP 695 type hints, etc.) -- Line length: 100 chars (configured in `ruff.toml`) -- All functions / modules have docstrings -- Tests live in `tests/` and are named `test_*.py` +- Python 3.12+ syntax (PEP 695 type hints) +- Line length: 100 chars (`ruff.toml`) +- All functions and modules have docstrings +- Tests live in `tests/` named `test_*.py` -## ๐Ÿ“œ Code of conduct +## Code of conduct Be kind. Be patient. Be helpful. diff --git a/README.md b/README.md index 91680f3..f2534a0 100644 --- a/README.md +++ b/README.md @@ -7,64 +7,31 @@ [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230?style=flat-square)](https://docs.astral.sh/ruff/) [![GitHub release](https://img.shields.io/github/v/release/mohit-tanwar-dev/python-backend?style=flat-square)](https://github.com/mohit-tanwar-dev/python-backend/releases) -> A production-ready **FastAPI** scaffold with health checks, structured logging, configurable settings, and CI/CD out of the box. -> Use this as the starting point for any new Python backend service. +FastAPI scaffold with health endpoint, structured logging, env-driven config, pytest suite, ruff/mypy, and GitHub Actions CI. ---- +## Stack -## โœจ Features +- Python 3.12 (3.11 supported) +- FastAPI 0.115, Uvicorn +- Pydantic v2 + pydantic-settings +- pytest + httpx +- Ruff (lint + format), mypy +- GitHub Actions CI, Dependabot +- Multi-stage Dockerfile (non-root user, healthcheck) -- ๐Ÿš€ **FastAPI** async web framework with auto-generated OpenAPI docs (`/docs`, `/redoc`) -- โš™๏ธ **Pydantic v2 + pydantic-settings** for type-safe, environment-driven configuration -- ๐Ÿ“‹ **Health-check endpoint** at `/health` and `/api/v1/health` โ€” perfect for Kubernetes probes and load balancers -- ๐Ÿชต **Structured logging** with consistent timestamps and log levels -- ๐Ÿงช **pytest** test suite with `httpx` + `TestClient` covering every endpoint -- ๐Ÿงน **Ruff** for linting and formatting (replaces black + isort + flake8) -- ๐Ÿ” **mypy** for static type checking -- ๐Ÿค– **GitHub Actions CI** running on every push & PR (Python 3.11 + 3.12 matrix) -- ๐Ÿ“ฆ **Dependabot** for automated dependency updates -- ๐Ÿณ **Docker-ready** with multi-stage Dockerfile (optional) -- ๐Ÿ“š **Issue & PR templates**, **CONTRIBUTING.md**, **CODE_OF_CONDUCT.md**, **SECURITY.md** - ---- - -## ๐Ÿ› ๏ธ Tech stack - -| Layer | Tool | -| ------------ | ----------------------------------- | -| Framework | [FastAPI](https://fastapi.tiangolo.com/) 0.115 | -| Server | [Uvicorn](https://www.uvicorn.org/) 0.34 | -| Validation | [Pydantic](https://pydantic.dev/) 2.10 + `pydantic-settings` | -| Testing | [pytest](https://pytest.org/) 8.3 + `pytest-asyncio` | -| HTTP client | [httpx](https://www.python-httpx.org/) 0.28 | -| Lint/format | [Ruff](https://docs.astral.sh/ruff/) 0.8 | -| Type check | [mypy](https://mypy-lang.org/) 1.14 | -| Python | 3.12+ (3.11 supported) | - ---- - -## ๐Ÿ“ Project structure +## Project structure ``` python-backend/ โ”œโ”€โ”€ app/ -โ”‚ โ”œโ”€โ”€ __init__.py -โ”‚ โ”œโ”€โ”€ main.py # FastAPI app entrypoint +โ”‚ โ”œโ”€โ”€ main.py โ”‚ โ”œโ”€โ”€ core/ -โ”‚ โ”‚ โ”œโ”€โ”€ __init__.py -โ”‚ โ”‚ โ”œโ”€โ”€ config.py # Pydantic settings -โ”‚ โ”‚ โ””โ”€โ”€ logging.py # Structured logging -โ”‚ โ””โ”€โ”€ api/ -โ”‚ โ”œโ”€โ”€ __init__.py -โ”‚ โ””โ”€โ”€ v1/ -โ”‚ โ”œโ”€โ”€ __init__.py -โ”‚ โ”œโ”€โ”€ router.py # Aggregates route modules -โ”‚ โ””โ”€โ”€ endpoints/ -โ”‚ โ”œโ”€โ”€ __init__.py -โ”‚ โ””โ”€โ”€ health.py # Health-check endpoint -โ”œโ”€โ”€ tests/ -โ”‚ โ”œโ”€โ”€ __init__.py -โ”‚ โ””โ”€โ”€ test_health.py +โ”‚ โ”‚ โ”œโ”€โ”€ config.py +โ”‚ โ”‚ โ””โ”€โ”€ logging.py +โ”‚ โ””โ”€โ”€ api/v1/ +โ”‚ โ”œโ”€โ”€ router.py +โ”‚ โ””โ”€โ”€ endpoints/health.py +โ”œโ”€โ”€ tests/test_health.py โ”œโ”€โ”€ .github/ โ”‚ โ”œโ”€โ”€ workflows/ci.yml โ”‚ โ”œโ”€โ”€ ISSUE_TEMPLATE/ @@ -76,143 +43,74 @@ python-backend/ โ”œโ”€โ”€ ruff.toml โ”œโ”€โ”€ .env.example โ”œโ”€โ”€ Dockerfile -โ”œโ”€โ”€ LICENSE โ”œโ”€โ”€ CHANGELOG.md โ”œโ”€โ”€ CONTRIBUTING.md โ”œโ”€โ”€ CODE_OF_CONDUCT.md -โ”œโ”€โ”€ SECURITY.md -โ””โ”€โ”€ README.md +โ””โ”€โ”€ SECURITY.md ``` ---- - -## ๐Ÿš€ Quick start - -### Option A โ€” Local development +## Quick start ```bash -# 1. Clone git clone https://github.com/mohit-tanwar-dev/python-backend.git cd python-backend - -# 2. Create a virtual environment -python -m venv .venv -source .venv/bin/activate # Linux / macOS -# .venv\Scripts\activate # Windows - -# 3. Install dependencies -pip install -r requirements-dev.txt # includes dev / test extras - -# 4. (optional) configure env -cp .env.example .env - -# 5. Run the server -uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 +python -m venv .venv && source .venv/bin/activate +pip install -r requirements-dev.txt +cp .env.example .env # optional โ€” defaults work +uvicorn app.main:app --reload ``` -Open in your browser: -- ๐Ÿฉบ Health โ€” http://localhost:8000/health -- ๐Ÿ“š Swagger UI โ€” http://localhost:8000/docs -- ๐Ÿ“˜ ReDoc โ€” http://localhost:8000/redoc -- ๐Ÿ“‹ OpenAPI JSON โ€” http://localhost:8000/openapi.json +Endpoints: + +- `GET /` โ€” service info +- `GET /health` โ€” health check +- `GET /api/v1/health` โ€” versioned health check +- `GET /docs` โ€” Swagger UI +- `GET /redoc` โ€” ReDoc -### Option B โ€” Docker +Docker: ```bash docker build -t python-backend:latest . docker run --rm -p 8000:8000 --env-file .env python-backend:latest ``` ---- +## Configuration -## ๐Ÿ”Œ API endpoints - -| Method | Path | Description | -| ------ | ----------------- | ---------------------------------------------- | -| `GET` | `/` | Root โ€” basic service info & docs link | -| `GET` | `/health` | Public health check (no API prefix) | -| `GET` | `/api/v1/health` | Versioned health check under `/api/v1` prefix | - -### Example response (`GET /health`) - -```json -{ - "status": "ok", - "app": "python-backend", - "version": "0.1.0", - "env": "local", - "uptime_seconds": 12.345 -} -``` - ---- - -## โš™๏ธ Configuration - -All settings are loaded from environment variables (or a local `.env` file). -Every setting has a sensible default, so the service runs out-of-the-box. +Settings loaded from environment variables or `.env`. All have defaults. | Variable | Default | Description | | --------------- | ---------------- | ---------------------------------------- | -| `APP_NAME` | `python-backend` | Human-readable app name | -| `APP_ENV` | `local` | Environment: `local` / `dev` / `prod` | -| `APP_DEBUG` | `true` | Enable verbose logging & error details | +| `APP_NAME` | `python-backend` | Service name | +| `APP_ENV` | `local` | `local` / `dev` / `prod` | +| `APP_DEBUG` | `true` | Verbose logs and error details | | `APP_HOST` | `0.0.0.0` | Bind host | | `APP_PORT` | `8000` | Bind port | -| `APP_LOG_LEVEL` | `INFO` | Log level: DEBUG/INFO/WARNING/ERROR | - -Copy `.env.example` to `.env` and edit as needed. +| `APP_LOG_LEVEL` | `INFO` | DEBUG / INFO / WARNING / ERROR | ---- - -## ๐Ÿงช Testing & quality checks +## Tests ```bash -# Run tests pytest -v - -# Lint ruff check . - -# Format check (without writing) ruff format --check . - -# Format (write) -ruff format . - -# Type check mypy app tests ``` -CI runs all of the above on every push and pull request, on Python 3.11 **and** 3.12. - ---- - -## ๐Ÿค Contributing - -Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, branch conventions, and PR guidelines. - -1. Fork the repo -2. Create a feature branch: `git checkout -b feat/my-feature` -3. Commit using [Conventional Commits](https://www.conventionalcommits.org/) -4. Open a PR against `main` - -Please follow the [Code of Conduct](CODE_OF_CONDUCT.md) in all interactions. - ---- +CI runs all of the above on Python 3.11 and 3.12. -## ๐Ÿ“œ Changelog +## Contributing -See [CHANGELOG.md](CHANGELOG.md) for release history. +See [CONTRIBUTING.md](CONTRIBUTING.md). Fork, branch from `main`, open a PR. ---- +## Changelog -## ๐Ÿ” Security +See [CHANGELOG.md](CHANGELOG.md). -To report a vulnerability, see [SECURITY.md](SECURITY.md). +## Security ---- +See [SECURITY.md](SECURITY.md). -## ๐Ÿ“„ License +## License -[MIT](LICENSE) ยฉ Mohit Tanwar +MIT โ€” see [LICENSE](LICENSE). diff --git a/SECURITY.md b/SECURITY.md index b0fd639..f0344f8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,16 +2,17 @@ ## Supported versions -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | โœ… Security fixes | -| < 0.1 | โŒ Not supported | +| Version | Supported | +| ------- | -------------- | +| 0.1.x | Security fixes | +| < 0.1 | Not supported | ## Reporting a vulnerability -Please **do not** open a public GitHub issue for security vulnerabilities. +Do not open a public GitHub issue for security vulnerabilities. + +Email **mohitsinghtanwar000@gmail.com** with: -Instead, email **mohitsinghtanwar000@gmail.com** with: - A description of the issue - Steps to reproduce - Affected versions / commits