<div align="center">
# FastAPI Environment Banner
<img src="public/logo.svg" alt="FastAPI Environment Banner Logo" width="400">
[](https://badge.fury.io/py/fastapi-env-banner)
[](https://pypi.org/project/fastapi-env-banner/)
[](https://opensource.org/licenses/MIT)
[](https://pinnlabs.github.io/fastapi-env-banner/)
</div>
<p align="center">
A lightweight and simple library for adding visual environment banners to FastAPI applications.<br>
Inspired by <code>django-env-notice</code>, but specifically designed for FastAPI with a focus on simplicity and ease of integration.
</p>
---
<div align="center">
### See it in action
<img src="public/demo.png" alt="FastAPI Environment Banner Demo" width="800">
*Visual environment indicators help prevent mistakes by clearly showing which environment you're working in*
</div>
---
## Features
- **Simple and Lightweight**: Just a few lines of code to integrate
- **Visual and Intuitive**: Colorful banners that clearly differentiate environments
- **Highly Configurable**: Customize colors, texts, and positions
- **Swagger UI Support**: Banner also appears in API documentation
- **Zero Configuration**: Works out-of-the-box with sensible defaults
- **Secure**: Banner disabled in production by default
## Documentation
Full documentation is available at **[pinnlabs.github.io/fastapi-env-banner](https://pinnlabs.github.io/fastapi-env-banner/)**
## Installation
```bash
pip install fastapi-env-banner
```
or if you are using `uv`:
```bash
uv add fastapi-env-banner
```
### Basic Setup
```python
from fastapi import FastAPI
from fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware, setup_swagger_ui
# Create FastAPI application
app = FastAPI(title="My API")
# Configure banner (auto-detects from ENVIRONMENT variable)
config = EnvBannerConfig.from_env()
# Add middleware
app.add_middleware(EnvBannerMiddleware, config=config)
# Setup Swagger UI with banner
setup_swagger_ui(app, config)
@app.get("/")
async def root():
return {"message": "Hello World"}
```
### Manual Configuration
```python
from fastapi_env_banner import Environment, EnvBannerConfig
# Custom configuration
config = EnvBannerConfig(
environment=Environment.STAGING,
enabled=True,
custom_text="STAGING ENVIRONMENT",
custom_color="#FF6B6B",
position="top", # or "bottom"
show_in_swagger=True
)
```
## Supported Environments
The library supports the following environments with pre-defined colors:
| Environment | Default Color | Default Text |
|----------|------------|-------------|
| **LOCAL** | Green (`#4CAF50`) | LOCAL ENVIRONMENT |
| **DEVELOPMENT** | Blue (`#2196F3`) | DEVELOPMENT ENVIRONMENT |
| **STAGING** | Orange (`#FF9800`) | STAGING ENVIRONMENT |
| **PRODUCTION** | Red (`#F44336`) | PRODUCTION ENVIRONMENT |
| **TESTING** | Purple (`#9C27B0`) | TESTING ENVIRONMENT |
## Detailed Configuration
### Using Environment Variables
Set the `ENVIRONMENT` variable (or another of your choice):
```bash
export ENVIRONMENT=staging
```
Accepted values:
- `local`
- `dev`, `development`
- `stage`, `staging`
- `prod`, `production`
- `test`, `testing`
### Configuration Parameters
```python
EnvBannerConfig(
environment: Environment = Environment.LOCAL,
enabled: bool = True,
custom_text: Optional[str] = None,
custom_color: Optional[str] = None,
position: str = "top", # "top" or "bottom"
show_in_swagger: bool = True
)
```
## Examples
### Example 1: Minimal Configuration
```python
from fastapi import FastAPI
from fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware
app = FastAPI()
app.add_middleware(EnvBannerMiddleware, config=EnvBannerConfig.from_env())
```
### Example 2: Full Customization
```python
from fastapi import FastAPI
from fastapi_env_banner import (
Environment,
EnvBannerConfig,
EnvBannerMiddleware,
setup_swagger_ui
)
app = FastAPI(title="Production API")
config = EnvBannerConfig(
environment=Environment.STAGING,
custom_text="⚠️ TEST ENVIRONMENT - DO NOT USE IN PRODUCTION ⚠️",
custom_color="#E91E63",
position="bottom",
show_in_swagger=True
)
app.add_middleware(EnvBannerMiddleware, config=config)
setup_swagger_ui(app, config)
```
### Example 3: Disable in Production
```python
import os
from fastapi import FastAPI
from fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware
app = FastAPI()
# Completely disable in production
is_production = os.getenv("ENVIRONMENT") == "production"
config = EnvBannerConfig.from_env()
config.enabled = not is_production
app.add_middleware(EnvBannerMiddleware, config=config)
```
## Security
By default, the banner **is NOT displayed in production environment** as a security measure. This prevents environment information from being accidentally exposed.
To force display in production (not recommended):
```python
config = EnvBannerConfig(
environment=Environment.PRODUCTION,
enabled=True # Force display
)
```
## How It Works
1. **Middleware**: Intercepts HTML responses and automatically injects the banner
2. **Templates**: Clean, pythonic HTML generation using string templates
3. **Swagger UI**: Customizes the documentation page to include the banner
4. **Zero Impact**: Does not affect JSON APIs or other non-HTML responses
5. **Performance**: Minimal overhead, only processes HTML responses
## Contributing
Contributions are welcome! Feel free to:
1. Fork the project
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Inspired by [django-env-notice](https://github.com/dizballanze/django-admin-env-notice)
- Built with [FastAPI](https://fastapi.tiangolo.com/)
- Developed by [PinnLabs](https://github.com/pinnlabs)
## Support
If you encounter any issues or have suggestions, please [open an issue](https://github.com/pinnlabs/fastapi-env-banner/issues).
---
Made with ❤️ by PinnLabs
Raw data
{
"_id": null,
"home_page": null,
"name": "fastapi-env-banner",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "banner, development, environment, fastapi, production, staging",
"author": null,
"author_email": "PinnLabs <hi@pinnlabs.online>",
"download_url": "https://files.pythonhosted.org/packages/a3/49/2ab14d6ae9b74cea94919209b328d79c4df32bcf858a4c674b458d4b2214/fastapi_env_banner-0.1.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# FastAPI Environment Banner\n\n<img src=\"public/logo.svg\" alt=\"FastAPI Environment Banner Logo\" width=\"400\">\n\n[](https://badge.fury.io/py/fastapi-env-banner)\n[](https://pypi.org/project/fastapi-env-banner/)\n[](https://opensource.org/licenses/MIT)\n[](https://pinnlabs.github.io/fastapi-env-banner/)\n\n</div>\n\n<p align=\"center\">\nA lightweight and simple library for adding visual environment banners to FastAPI applications.<br>\nInspired by <code>django-env-notice</code>, but specifically designed for FastAPI with a focus on simplicity and ease of integration.\n</p>\n\n---\n\n<div align=\"center\">\n\n### See it in action\n\n<img src=\"public/demo.png\" alt=\"FastAPI Environment Banner Demo\" width=\"800\">\n\n*Visual environment indicators help prevent mistakes by clearly showing which environment you're working in*\n\n</div>\n\n---\n\n## Features\n\n- **Simple and Lightweight**: Just a few lines of code to integrate\n- **Visual and Intuitive**: Colorful banners that clearly differentiate environments\n- **Highly Configurable**: Customize colors, texts, and positions\n- **Swagger UI Support**: Banner also appears in API documentation\n- **Zero Configuration**: Works out-of-the-box with sensible defaults\n- **Secure**: Banner disabled in production by default\n\n## Documentation\n\nFull documentation is available at **[pinnlabs.github.io/fastapi-env-banner](https://pinnlabs.github.io/fastapi-env-banner/)**\n\n## Installation\n\n```bash\npip install fastapi-env-banner\n```\n\nor if you are using `uv`:\n\n```bash\nuv add fastapi-env-banner\n```\n\n### Basic Setup\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware, setup_swagger_ui\n\n# Create FastAPI application\napp = FastAPI(title=\"My API\")\n\n# Configure banner (auto-detects from ENVIRONMENT variable)\nconfig = EnvBannerConfig.from_env()\n\n# Add middleware\napp.add_middleware(EnvBannerMiddleware, config=config)\n\n# Setup Swagger UI with banner\nsetup_swagger_ui(app, config)\n\n@app.get(\"/\")\nasync def root():\n return {\"message\": \"Hello World\"}\n```\n\n### Manual Configuration\n\n```python\nfrom fastapi_env_banner import Environment, EnvBannerConfig\n\n# Custom configuration\nconfig = EnvBannerConfig(\n environment=Environment.STAGING,\n enabled=True,\n custom_text=\"STAGING ENVIRONMENT\",\n custom_color=\"#FF6B6B\",\n position=\"top\", # or \"bottom\"\n show_in_swagger=True\n)\n```\n\n## Supported Environments\n\nThe library supports the following environments with pre-defined colors:\n\n| Environment | Default Color | Default Text |\n|----------|------------|-------------|\n| **LOCAL** | Green (`#4CAF50`) | LOCAL ENVIRONMENT |\n| **DEVELOPMENT** | Blue (`#2196F3`) | DEVELOPMENT ENVIRONMENT |\n| **STAGING** | Orange (`#FF9800`) | STAGING ENVIRONMENT |\n| **PRODUCTION** | Red (`#F44336`) | PRODUCTION ENVIRONMENT |\n| **TESTING** | Purple (`#9C27B0`) | TESTING ENVIRONMENT |\n\n## Detailed Configuration\n\n### Using Environment Variables\n\nSet the `ENVIRONMENT` variable (or another of your choice):\n\n```bash\nexport ENVIRONMENT=staging\n```\n\nAccepted values:\n- `local`\n- `dev`, `development`\n- `stage`, `staging`\n- `prod`, `production`\n- `test`, `testing`\n\n### Configuration Parameters\n\n```python\nEnvBannerConfig(\n environment: Environment = Environment.LOCAL,\n enabled: bool = True,\n custom_text: Optional[str] = None,\n custom_color: Optional[str] = None,\n position: str = \"top\", # \"top\" or \"bottom\"\n show_in_swagger: bool = True\n)\n```\n\n## Examples\n\n### Example 1: Minimal Configuration\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware\n\napp = FastAPI()\napp.add_middleware(EnvBannerMiddleware, config=EnvBannerConfig.from_env())\n```\n\n### Example 2: Full Customization\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_env_banner import (\n Environment,\n EnvBannerConfig,\n EnvBannerMiddleware,\n setup_swagger_ui\n)\n\napp = FastAPI(title=\"Production API\")\n\nconfig = EnvBannerConfig(\n environment=Environment.STAGING,\n custom_text=\"\u26a0\ufe0f TEST ENVIRONMENT - DO NOT USE IN PRODUCTION \u26a0\ufe0f\",\n custom_color=\"#E91E63\",\n position=\"bottom\",\n show_in_swagger=True\n)\n\napp.add_middleware(EnvBannerMiddleware, config=config)\nsetup_swagger_ui(app, config)\n```\n\n### Example 3: Disable in Production\n\n```python\nimport os\nfrom fastapi import FastAPI\nfrom fastapi_env_banner import EnvBannerConfig, EnvBannerMiddleware\n\napp = FastAPI()\n\n# Completely disable in production\nis_production = os.getenv(\"ENVIRONMENT\") == \"production\"\n\nconfig = EnvBannerConfig.from_env()\nconfig.enabled = not is_production\n\napp.add_middleware(EnvBannerMiddleware, config=config)\n```\n\n## Security\n\nBy default, the banner **is NOT displayed in production environment** as a security measure. This prevents environment information from being accidentally exposed.\n\nTo force display in production (not recommended):\n\n```python\nconfig = EnvBannerConfig(\n environment=Environment.PRODUCTION,\n enabled=True # Force display\n)\n```\n\n## How It Works\n\n1. **Middleware**: Intercepts HTML responses and automatically injects the banner\n2. **Templates**: Clean, pythonic HTML generation using string templates\n3. **Swagger UI**: Customizes the documentation page to include the banner\n4. **Zero Impact**: Does not affect JSON APIs or other non-HTML responses\n5. **Performance**: Minimal overhead, only processes HTML responses\n\n## Contributing\n\nContributions are welcome! Feel free to:\n\n1. Fork the project\n2. Create a feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by [django-env-notice](https://github.com/dizballanze/django-admin-env-notice)\n- Built with [FastAPI](https://fastapi.tiangolo.com/)\n- Developed by [PinnLabs](https://github.com/pinnlabs)\n\n## Support\n\nIf you encounter any issues or have suggestions, please [open an issue](https://github.com/pinnlabs/fastapi-env-banner/issues).\n\n---\n\nMade with \u2764\ufe0f by PinnLabs\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight and simple library for adding visual environment banners to FastAPI applications",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/pinnlabs/fastapi-env-banner",
"Issues": "https://github.com/pinnlabs/fastapi-env-banner/issues",
"Repository": "https://github.com/pinnlabs/fastapi-env-banner"
},
"split_keywords": [
"banner",
" development",
" environment",
" fastapi",
" production",
" staging"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7ea86ef262e2fd04037f92887ee41b781dbd7c284b8b8380c2a30e95491bcac7",
"md5": "53ebdca44e95196d5d273dd908dd1366",
"sha256": "2eaf582dbf3d0725e4bd5342c17608391e5eea4941cbfbf77910747ce65aea3d"
},
"downloads": -1,
"filename": "fastapi_env_banner-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53ebdca44e95196d5d273dd908dd1366",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 9018,
"upload_time": "2025-10-20T14:22:54",
"upload_time_iso_8601": "2025-10-20T14:22:54.007976Z",
"url": "https://files.pythonhosted.org/packages/7e/a8/6ef262e2fd04037f92887ee41b781dbd7c284b8b8380c2a30e95491bcac7/fastapi_env_banner-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a3492ab14d6ae9b74cea94919209b328d79c4df32bcf858a4c674b458d4b2214",
"md5": "b150785911392e1b2b84d89764ed2698",
"sha256": "c90fd969c93a66178bc9550c9cc02800635d9c0458ea0af470a185148c52e9d6"
},
"downloads": -1,
"filename": "fastapi_env_banner-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "b150785911392e1b2b84d89764ed2698",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 566081,
"upload_time": "2025-10-20T14:22:55",
"upload_time_iso_8601": "2025-10-20T14:22:55.634639Z",
"url": "https://files.pythonhosted.org/packages/a3/49/2ab14d6ae9b74cea94919209b328d79c4df32bcf858a4c674b458d4b2214/fastapi_env_banner-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 14:22:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pinnlabs",
"github_project": "fastapi-env-banner",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "fastapi-env-banner"
}
JSON
