django-deploy-probes 0.1.0__tar.gz

django_deploy_probes-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+.coverage
+.DS_Store
+.idea/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+htmlcov/
+*.egg-info/
+.agents/*

django_deploy_probes-0.1.0/CHANGELOG.md

@@ -0,0 +1,183 @@
+# Changelog
+
+## v0.1.0 - Initial Release
+
+`django-deploy-probes` provides lightweight deployment probe endpoints for Django applications.
+
+This release is focused on deployment validation workflows such as blue/green deployments, rolling deployments, Kubernetes probes, Docker health checks, Nginx upstream switching, and CI/CD verification.
+
+### Highlights
+
+- Add `healthz` endpoint for process liveness checks.
+- Add `readyz` endpoint for traffic readiness checks.
+- Add `startupz` endpoint for startup/bootstrap checks.
+- Add `version` endpoint for deployed application metadata.
+- Support both include-style and import-style Django URL configuration.
+- Support optional readiness checks for Django databases, Redis, Celery, migrations, and custom checks.
+- Add optional package extras for Redis and Celery integrations.
+- Add basic probe access controls for internal IP and header token validation.
+- Add configurable internal IP networks, secret-safe custom check messages, and optional safe
+  failure reasons.
+- Add GitHub Actions CI and Trusted Publishing release workflow.
+
+### Installation
+
+Install the base package:
+
+```bash
+pip install django-deploy-probes
+```
+
+Install optional Redis and Celery readiness check dependencies:
+
+```bash
+pip install "django-deploy-probes[redis]"
+pip install "django-deploy-probes[celery]"
+pip install "django-deploy-probes[all]"
+```
+
+### Quick Start
+
+Include all probe URLs:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("", include("django_deploy_probes.urls")),
+]
+```
+
+This exposes:
+
+- `GET /healthz`
+- `GET /readyz`
+- `GET /startupz`
+- `GET /version`
+
+Alternatively, import the views directly:
+
+```python
+from django.urls import path
+from django_deploy_probes.views import healthz, readyz, startupz, version
+
+urlpatterns = [
+    path("healthz/", healthz),
+    path("readyz/", readyz),
+    path("startupz/", startupz),
+    path("version/", version),
+]
+```
+
+Configure deployment metadata and readiness checks in Django settings:
+
+```python
+DEPLOY_PROBES = {
+    "SERVICE_NAME": "my-django-app",
+    "ENVIRONMENT": "prod",
+    "VERSION": "1.2.0",
+    "COMMIT": "a1b2c3d",
+    "BRANCH": "main",
+    "BUILD_TIME": "2026-05-13T10:00:00+09:00",
+    "SLOT": "green",
+    "READY_CHECKS": [
+        "database",
+        "redis",
+        "celery",
+    ],
+    "DATABASES": [
+        "default",
+    ],
+    "REDIS": {
+        "default": {
+            "LOCATION": "redis://localhost:6379/0",
+            "TIMEOUT": 1.0,
+        },
+    },
+    "CELERY": {
+        "BROKER": True,
+        "WORKERS": False,
+        "RESULT_BACKEND": False,
+        "TIMEOUT": 1.0,
+    },
+    "DETAIL_LEVEL": "none",
+    "EXPOSE_CHECK_MESSAGES": False,
+}
+```
+
+### Endpoint Behavior
+
+`GET /healthz` returns `200` when the Django process is alive:
+
+```json
+{
+  "status": "ok"
+}
+```
+
+`GET /readyz` returns `200` when all enabled readiness checks pass:
+
+```json
+{
+  "status": "ready",
+  "checks": {
+    "database.default": "ok",
+    "redis.default": "ok",
+    "celery.broker": "ok"
+  }
+}
+```
+
+`GET /readyz` returns `503` when any enabled readiness check fails:
+
+```json
+{
+  "status": "not_ready",
+  "checks": {
+    "database.default": "ok",
+    "redis.default": "fail",
+    "celery.broker": "ok"
+  }
+}
+```
+
+`GET /version` returns configured deployment metadata:
+
+```json
+{
+  "service": "my-django-app",
+  "environment": "prod",
+  "version": "1.2.0",
+  "commit": "a1b2c3d",
+  "branch": "main",
+  "build_time": "2026-05-13T10:00:00+09:00",
+  "slot": "green"
+}
+```
+
+### Supported Versions
+
+- Python: 3.9+
+- Django: 4.2+
+- Redis extra: `redis>=4.5`
+- Celery extra: `celery>=5.3`
+
+Package classifiers include Python 3.9 through 3.14 and Django 4.2 / 5.x.
+
+### Known Limitations
+
+- `healthz` is intentionally minimal and does not check databases, cache, Redis, Celery, migrations, or external services.
+- `readyz` only checks dependencies that are explicitly enabled in `DEPLOY_PROBES["READY_CHECKS"]`.
+- Redis and Celery checks require installing the corresponding optional extras.
+- Security checks use `REMOTE_ADDR` by default and do not trust `X-Forwarded-For`; configure trusted proxy handling separately at the application or infrastructure layer.
+- Custom readiness check messages are hidden by default; do not include secrets or sensitive values
+  if `EXPOSE_CHECK_MESSAGES=True`.
+- This package is not a metrics, tracing, APM, or full monitoring system.
+
+### Next Version Plans
+
+- Expand documentation for production deployment patterns.
+- Add more examples for Kubernetes, Docker, Nginx, and CI/CD validation.
+- Add more examples for custom readiness checks.
+- Consider richer readiness check result details while keeping secret-safe defaults.
+- Continue compatibility testing across supported Python and Django versions.

django_deploy_probes-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,20 @@
+# Code of Conduct
+
+## Our Pledge
+
+We want `django-deploy-probes` to be a respectful and useful project for maintainers, contributors, and users.
+
+Participants are expected to communicate clearly, assume good intent, and focus technical discussions on the work.
+
+## Unacceptable Behavior
+
+- Harassment, threats, or personal attacks.
+- Publicly sharing private information without permission.
+- Sustained disruption of project discussions.
+- Dismissive or hostile behavior toward new contributors.
+
+## Enforcement
+
+Report conduct concerns privately to the maintainer listed in `pyproject.toml`.
+
+Maintainers may remove comments, close issues, block accounts, or take other reasonable action to protect the project.

django_deploy_probes-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+Thanks for helping improve `django-deploy-probes`.
+
+## Local setup
+
+```bash
+uv sync --dev
+uv run pytest -q
+uv run ruff check .
+uv build
+```
+
+## Development guidelines
+
+- Keep `/healthz` lightweight. It must not touch databases, caches, Redis, Celery, or external services.
+- Keep readiness failures secret-safe by default.
+- Add or update tests for behavior changes.
+- Update README or docs when public settings, endpoints, or response shapes change.
+
+## Release checklist
+
+1. Update the version in `django_deploy_probes/__init__.py`.
+2. Update `CHANGELOG.md`.
+3. Run tests, lint, and build locally.
+4. Create a GitHub release. The publish workflow uses PyPI Trusted Publishing.

django_deploy_probes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 django-deploy-probes contributors
+
+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.

django_deploy_probes-0.1.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: django-deploy-probes
+Version: 0.1.0
+Summary: Deployment probe endpoints for Django applications.
+Project-URL: Homepage, https://github.com/emfpdlzj/django-deploy-probes
+Project-URL: Repository, https://github.com/emfpdlzj/django-deploy-probes
+Project-URL: Issues, https://github.com/emfpdlzj/django-deploy-probes/issues
+Project-URL: Documentation, https://github.com/emfpdlzj/django-deploy-probes#readme
+Project-URL: Changelog, https://github.com/emfpdlzj/django-deploy-probes/blob/main/CHANGELOG.md
+Author-email: emfpdlzj <redryan@ajou.ac.kr>
+Maintainer-email: emfpdlzj <redryan@ajou.ac.kr>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deployment,django,healthcheck,kubernetes,probe,readiness
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: django>=4.2
+Provides-Extra: all
+Requires-Dist: celery>=5.3; extra == 'all'
+Requires-Dist: djangorestframework>=3.14; extra == 'all'
+Requires-Dist: drf-spectacular>=0.27; extra == 'all'
+Requires-Dist: redis>=4.5; extra == 'all'
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == 'celery'
+Provides-Extra: openapi
+Requires-Dist: djangorestframework>=3.14; extra == 'openapi'
+Requires-Dist: drf-spectacular>=0.27; extra == 'openapi'
+Provides-Extra: redis
+Requires-Dist: redis>=4.5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# django-deploy-probes
+
+Production-ready HTTP deployment probe endpoints for Django applications. Unlike `django-probes`, this package does not provide management commands; it exposes lightweight `/healthz`, `/readyz`, `/startupz`, and `/version` views for runtime deployment checks.
+
+Use these endpoints for CI/CD, Docker, Kubernetes, and blue-green deployments.
+
+[![PyPI](https://img.shields.io/pypi/v/django-deploy-probes.svg?label=PyPI)](https://pypi.org/project/django-deploy-probes/)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.9-3776AB.svg)](https://www.python.org/)
+[![Django](https://img.shields.io/badge/django-%3E%3D4.2-0C4B33.svg)](https://www.djangoproject.com/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![uv](https://img.shields.io/badge/package%20manager-uv-5C3EE8.svg)](https://docs.astral.sh/uv/)
+
+## Features
+
+- Lightweight `healthz` endpoint for liveness checks.
+- Dependency-aware `readyz` endpoint for deployment readiness checks.
+- `startupz` endpoint for startup/bootstrap checks such as pending migrations.
+- `version` endpoint for validating service metadata, with optional build details when explicitly enabled.
+- Optional Redis, Celery, migration, and custom readiness checks for production deployments.
+- Secret-safe response defaults, with optional safe failure reasons and check durations for CI/CD debugging.
+
+## Quick Start
+
+- [Install the package](#installation)
+- [Configure Django URLs](#include-style-url-configuration)
+
+## Installation
+
+```bash
+pip install django-deploy-probes
+```
+
+Optional Redis and Celery readiness checks are available as extras:
+
+```bash
+pip install "django-deploy-probes[redis]"
+pip install "django-deploy-probes[celery]"
+pip install "django-deploy-probes[all]"
+```
+
+Optional Swagger/OpenAPI documentation support is available as a separate extra:
+
+```bash
+pip install "django-deploy-probes[openapi]"
+```
+
+### Include-style URL configuration
+
+Add the app so Django system checks can validate your probe settings:
+
+```python
+INSTALLED_APPS = [
+    "django_deploy_probes",
+]
+```
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    path("", include("django_deploy_probes.urls")),
+]
+```
+
+### Import-style URL configuration
+
+```python
+from django.urls import path
+from django_deploy_probes.views import healthz, readyz, startupz, version
+
+urlpatterns = [
+    path("healthz", healthz),
+    path("readyz", readyz),
+    path("startupz", startupz),
+    path("version", version),
+]
+```
+
+Custom check messages are hidden by default. If you enable `EXPOSE_CHECK_MESSAGES=True`, do not include secrets or sensitive values in those messages.
+
+Security checks use `REMOTE_ADDR` by default and do not trust `X-Forwarded-For`; configure your reverse proxy separately when probes are accessed through a proxy.
+
+### Common settings
+
+```python
+DEPLOY_PROBES = {
+    "SERVICE_NAME": "my-django-app",
+    "ENVIRONMENT": "prod",
+    "VERSION": "1.2.0",
+    "READY_CHECKS": ["database", "redis", "celery"],
+    "STARTUP_CHECKS": ["migrations"],
+    "READY_CUSTOM_CHECKS": [],
+    "STARTUP_CUSTOM_CHECKS": [],
+    "DATABASES": ["default"],
+    "REDIS": {
+        "default": {
+            "LOCATION": "redis://localhost:6379/0",
+            "TIMEOUT": 1.0,
+        },
+    },
+    "CELERY": {
+        "BROKER": True,
+        "WORKERS": False,
+        "RESULT_BACKEND": False,
+        "TIMEOUT": 1.0,
+    },
+    "DETAIL_LEVEL": "none",
+    "INCLUDE_CHECK_DURATIONS": False,
+    "REQUIRE_READY_CHECKS": False,
+    "REQUIRE_STARTUP_CHECKS": False,
+    "EXPOSE_CHECK_MESSAGES": False,
+    "INTERNAL_IP_ONLY": False,
+    "INTERNAL_IP_NETWORKS": [
+        "127.0.0.1/32",
+        "::1/128",
+        "10.0.0.0/8",
+        "172.16.0.0/12",
+        "192.168.0.0/16",
+    ],
+}
+```
+
+Set `DETAIL_LEVEL="safe"` to include stable failure reasons such as
+`redis_package_missing` or `unapplied_migrations`.
+
+Set `INCLUDE_CHECK_DURATIONS=True` to wrap each check result with a `status` and
+`duration_ms` value. This is useful in CI/CD diagnostics, but keep it disabled if
+you want the smallest possible response body.
+
+## Optional Swagger/OpenAPI
+
+Probe endpoints are not added to Swagger/OpenAPI documentation by default. They are operational endpoints and should normally stay internal or be protected with the package security options documented in [Security options](docs/security.md).
+
+To document `/healthz`, `/readyz`, `/startupz`, and `/version` with drf-spectacular, install the OpenAPI extra:
+
+```bash
+pip install "django-deploy-probes[openapi]"
+```
+
+Enable probe documentation explicitly in `settings.py`:
+
+```python
+INSTALLED_APPS = [
+    "django_deploy_probes",
+    "rest_framework",
+    "drf_spectacular",
+]
+
+REST_FRAMEWORK = {
+    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
+}
+
+DEPLOY_PROBES = {
+    "ENABLE_OPENAPI": True,
+    "OPENAPI_TAG": "Deployment Probes",
+}
+```
+
+Add drf-spectacular schema and Swagger UI URLs in your project `urls.py`:
+
+```python
+from django.urls import include, path
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
+
+urlpatterns = [
+    path("", include("django_deploy_probes.urls")),
+    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
+    path(
+        "api/docs/",
+        SpectacularSwaggerView.as_view(url_name="schema"),
+        name="swagger-ui",
+    ),
+]
+```
+
+If `ENABLE_OPENAPI=True` but drf-spectacular is not installed, the probe views continue to work without schema metadata. drf-yasg is not implemented in this phase and is reserved for future compatibility work.
+
+## Tutorials
+
+- [Tutorial index](docs/tutorial.md)
+- [Basic setup](docs/basic.md)
+- [Docker integration](docs/docker.md)
+- [Docker Compose integration](docs/docker-compose.md)
+- [Kubernetes probes](docs/kubernetes.md)
+- [API reference](docs/api.md)
+- [Security options](docs/security.md)
+- [Comparison with django-probes](docs/comparison.md)
+- [GitHub Actions deployment validation](docs/recipes/github-actions.md)
+- [Nginx blue-green switching](docs/recipes/nginx-blue-green.md)
+- [AWS ECS/ALB health checks](docs/recipes/aws-ecs-alb.md)
+
+## Runnable Examples
+
+- [Basic example](examples/basic)
+- [Docker example](examples/docker)
+- [Docker Compose example](examples/docker-compose)
+- [Kubernetes example](examples/kubernetes)
+- [Security example](examples/security)
+
+## Build and Publish
+
+### Build
+
+```bash
+uv build
+```
+
+Generated distributions are written to `dist/`.
+
+Generated files:
+
+- `dist/django_deploy_probes-0.1.0.tar.gz`
+- `dist/django_deploy_probes-0.1.0-py3-none-any.whl`
+
+### Installation Test
+
+After building, install the wheel in a clean environment:
+
+```bash
+python -m venv /tmp/django-deploy-probes-install-test
+source /tmp/django-deploy-probes-install-test/bin/activate
+pip install dist/django_deploy_probes-0.1.0-py3-none-any.whl
+python -c "import django_deploy_probes; print(django_deploy_probes.__version__)"
+```
+
+### PyPI Publish
+
+Publishing is handled by `.github/workflows/publish.yml` when a GitHub release is published.
+Configure PyPI Trusted Publishing for the repository before the first release.