https://github.com/seapagan/response-codes
A comprehensive Python library providing HTTP status code constants and exceptions
https://github.com/seapagan/response-codes
http-exceptions http-status-codes python python3 status-codes
Last synced: 25 days ago
JSON representation
A comprehensive Python library providing HTTP status code constants and exceptions
- Host: GitHub
- URL: https://github.com/seapagan/response-codes
- Owner: seapagan
- License: mit
- Created: 2025-01-18T19:15:59.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-27T02:05:59.000Z (about 1 month ago)
- Last Synced: 2026-03-27T14:56:09.615Z (about 1 month ago)
- Topics: http-exceptions, http-status-codes, python, python3, status-codes
- Language: Python
- Homepage:
- Size: 286 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# HTTP Response Codes
A comprehensive Python library providing HTTP status code constants and exceptions.
[](https://badge.fury.io/py/http-response-codes)
[](https://pypi.org/project/http-response-codes/)
[](https://opensource.org/licenses/MIT)
## Overview
`http-response-codes` is a Python library that provides a comprehensive set of
HTTP status codes as exception classes. Each status code is represented by a
class that inherits from `HTTPStatus`, containing the numeric code, message, and
description.
The module covers all standard HTTP status codes in the following categories:
- 1xx: Informational responses (100-103)
- 2xx: Success responses (200-208, 226)
- 3xx: Redirection responses (300-308)
- 4xx: Client error responses (400-431, 451)
- 5xx: Server error responses (500-511)
## Installation
```bash
pip install http-response-codes
```
Or using `uv`:
```bash
uv add http-response-codes
```
## Features
- Complete coverage of HTTP status codes
- Each status code is a proper Python exception class
- **Class-level comparisons** without instantiation required
- Rich comparison operators (`==`, `<`, `<=`, `>`, `>=`)
- Compare with both integers and strings
- Type conversion support (`int()`, `str()`)
- Hashable - use as dictionary keys or in sets
- Type hints included
- Predefined groups of related status codes
- Category predicate helpers (`is_success`, `is_client_error`, `is_server_error`, etc.)
- Detailed descriptions for each status code
- Zero dependencies
## Usage
### Basic Usage
```python
from response_codes import HTTP_404_NOT_FOUND
# Raise as an exception
raise HTTP_404_NOT_FOUND()
# Access status code properties (no instantiation needed!)
print(HTTP_404_NOT_FOUND.status_code) # 404
print(HTTP_404_NOT_FOUND.message) # "Not Found"
print(HTTP_404_NOT_FOUND.description) # Detailed description
# Compare directly with integers (class-level magic!)
assert HTTP_404_NOT_FOUND == 404
assert HTTP_404_NOT_FOUND == "Not Found"
```
> [!NOTE]
> Thanks to metaclass magic, you can compare status codes and access their
> properties directly on the class - no need to instantiate!
### Using Status Code Groups
```python
from response_codes import (
HTTP_INFORMATIONAL,
HTTP_SUCCESS,
HTTP_REDIRECTION,
HTTP_CLIENT_ERRORS,
HTTP_SERVER_ERRORS,
)
# Check if a status code is in a group
status_code = 404
if status_code in HTTP_CLIENT_ERRORS:
print("This is a client error!")
```
> [!NOTE]
> Built-in status groups are exported as read-only mappings. You can look up
> and iterate values normally, but mutation operations are not supported.
### Status Category Helpers
Category predicate helpers: `is_informational`, `is_success`, `is_redirection`,
`is_client_error`, `is_server_error`.
They accept an `int`, a status class, or a status instance; unsupported types
raise `TypeError`.
Practical example:
```python
from response_codes import HTTP_202_ACCEPTED, HTTP_429_TOO_MANY_REQUESTS, is_success, is_client_error
is_success(202) # True
is_success(HTTP_202_ACCEPTED) # True
is_success(HTTP_202_ACCEPTED()) # True
is_success(302) # False
is_client_error(HTTP_429_TOO_MANY_REQUESTS) # True
is_client_error(404) # True
is_client_error(3.14) # TypeError: value must be int or HTTPStatus
is_client_error(None) # TypeError: value must be int or HTTPStatus
```
### Advanced Comparison Features
The library uses a metaclass to enable powerful comparison operations
directly on the status code classes (no instantiation required):
#### Compare with Integers or Strings
```python
from response_codes import HTTP_404_NOT_FOUND, HTTP_200_OK
# Integer comparison
if HTTP_404_NOT_FOUND == 404:
print("It's a 404!")
# String comparison
if HTTP_200_OK == "OK":
print("Request succeeded")
# Rich comparisons for range checking
if 400 <= HTTP_404_NOT_FOUND < 500:
print("Client error")
if HTTP_500_INTERNAL_SERVER_ERROR >= 500:
print("Server error")
```
#### Type Conversions
```python
from response_codes import HTTP_404_NOT_FOUND
# Convert to integer
status_code = int(HTTP_404_NOT_FOUND) # 404
# Convert to string
status_msg = str(HTTP_404_NOT_FOUND) # "Not Found"
```
#### Use in Collections
Status codes are hashable and can be used as dictionary keys or in sets:
```python
from response_codes import (
HTTP_200_OK,
HTTP_404_NOT_FOUND,
HTTP_500_INTERNAL_SERVER_ERROR,
)
# As dictionary keys
handlers = {
HTTP_200_OK: handle_success,
HTTP_404_NOT_FOUND: handle_not_found,
HTTP_500_INTERNAL_SERVER_ERROR: handle_error,
}
# In sets
critical_errors = {
HTTP_500_INTERNAL_SERVER_ERROR,
HTTP_503_SERVICE_UNAVAILABLE,
}
```
### Real-World Examples
#### Flask/FastAPI Response Handling
```python
from flask import jsonify
from response_codes import (
HTTP_200_OK,
HTTP_404_NOT_FOUND,
HTTP_400_BAD_REQUEST,
)
@app.route('/api/user/')
def get_user(user_id):
user = db.get_user(user_id)
if not user:
return (
jsonify({"error": str(HTTP_404_NOT_FOUND)}),
int(HTTP_404_NOT_FOUND)
)
return jsonify(user), int(HTTP_200_OK)
```
#### Exception Handling with Detailed Information
```python
from response_codes import HTTP_404_NOT_FOUND, HTTPStatus
try:
resource = fetch_resource(resource_id)
if not resource:
raise HTTP_404_NOT_FOUND()
except HTTP_404_NOT_FOUND as e:
logger.error(f"{e.status_code} - {e.message}: {e.description}")
return {"error": e.message}, e.status_code
except HTTPStatus as e:
# Catch any HTTP status exception
logger.error(f"HTTP Error {e.status_code}: {e.message}")
return {"error": e.message}, e.status_code
```
#### Status Code Validation and Range Checking
```python
from response_codes import HTTP_CLIENT_ERRORS
def handle_api_response(status_code):
# Check if status code is in client error range
if status_code in HTTP_CLIENT_ERRORS:
retry_request()
# Check status code ranges using comparisons
if 200 <= status_code < 300:
return "Success"
elif 300 <= status_code < 400:
return "Redirection"
elif 400 <= status_code < 500:
return "Client Error"
elif 500 <= status_code < 600:
return "Server Error"
```
#### Custom Error Groups
```python
from response_codes import (
create_status_group,
HTTP_401_UNAUTHORIZED,
HTTP_403_FORBIDDEN,
)
# Create custom groups for your application
AUTH_ERRORS = create_status_group(
HTTP_401_UNAUTHORIZED,
HTTP_403_FORBIDDEN,
)
def requires_auth(status_code):
return status_code in AUTH_ERRORS
```
## Development
This project uses modern Python tooling:
- `uv` for dependency management
- `ruff` for linting and formatting
- `mypy` for type checking
- `pytest` for testing
- `pre-commit` for git hooks
### Setup Development Environment
Clone the repository:
```bash
git clone https://github.com/seapagan/response-codes.git
cd response-codes
```
Install development dependencies:
```bash
uv sync
```
Install pre-commit hooks:
```bash
prek install
```
### Running Tests
```bash
poe test # or simply run 'pytest'
```
Or in watch mode:
```bash
poe test:watch
```
### Code Quality Checks
```bash
# Run all pre-commit checks
poe pre
# Run mypy type checking
poe mypy
# Run ruff linting
poe ruff
# Run ruff formatting
poe format
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate and adhere to the existing coding style.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Author
Created and maintained by [Grant Ramsay](https://github.com/seapagan)