Install & Compatibility
Where this runs
tested against v0.2.10 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.113s · 17.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.101s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HTTPException
✓ from http_exceptions import HTTPException
BadRequest
✓ from http_exceptions import BadRequest
NotFound
✓ from http_exceptions import NotFound
Forbidden
✓ from http_exceptions import Forbidden
Unauthorized
✓ from http_exceptions import Unauthorized
InternalServerError
✓ from http_exceptions import InternalServerError
This quickstart demonstrates how to define and raise HTTP exceptions within a function and then catch specific exception types to handle different HTTP error scenarios. All custom HTTP exceptions inherit from `HTTPException`.
from http_exceptions import BadRequest, NotFound, HTTPException
def get_user_data(user_id: str):
if not user_id.isdigit():
raise BadRequest(detail="User ID must be a numeric string.")
if user_id == "404":
raise NotFound(detail=f"User with ID '{user_id}' not found.")
if user_id == "500":
raise HTTPException(status_code=500, detail="Internal server error processing user.")
return {"id": user_id, "name": f"User {user_id}"}
# Example usage and error handling
try:
user = get_user_data("abc")
except BadRequest as e:
print(f"Caught error: {e.status_code} - {e.detail}")
try:
user = get_user_data("404")
except NotFound as e:
print(f"Caught error: {e.status_code} - {e.detail}")
try:
user = get_user_data("500")
except HTTPException as e:
print(f"Caught generic HTTP error: {e.status_code} - {e.detail}")
try:
user = get_user_data("123")
print(f"Successfully retrieved user: {user}")
except HTTPException:
pass # Should not happen here
Debug
Known issues
gotchaWhen raising `HTTPException` or any of its subclasses, the `detail` argument is mandatory. Omitting it will result in a `TypeError` as it's not optional.fixAlways provide a `detail` string argument when instantiating any `http-exceptions` exception, e.g., `raise BadRequest(detail="Invalid input.")`.
affects: All versions
gotchaFor Python versions prior to 3.8, `importlib-metadata` is a required dependency. While `pip install http-exceptions` should handle this automatically, issues might arise in constrained environments or older `pip` versions.fixEnsure `importlib-metadata` is installed if you are using Python 3.7 or earlier: `pip install importlib-metadata`.
affects: < 0.2.9 (was missing), >= 0.2.9 (explicitly added)
gotchaThe library name on PyPI (`http-exceptions`) differs slightly from the import path (`http_exceptions`). Be careful with underscores vs. hyphens.fixAlways use `from http_exceptions import ...` for imports and `pip install http-exceptions` for installation.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'http_exceptions'
Incorrect library name used in the import statement, or the package was not installed.
fixVerify the package is installed with `pip install http-exceptions` and that the import uses an underscore: `from http_exceptions import HTTPException`.
TypeError: __init__() missing 1 required positional argument: 'detail'
Attempted to raise an HTTP exception without providing the mandatory `detail` argument.
fixProvide a descriptive string for the `detail` argument: `raise BadRequest(detail='User provided invalid data.')`.
AttributeError: 'HTTPException' object has no attribute 'status_code'
This error is unlikely with `http-exceptions` as `status_code` is always present. More likely, you're catching a generic `Exception` which isn't an `HTTPException` or a subclass.
fixEnsure you are catching `HTTPException` or a specific subclass and not a generic `Exception` if you intend to access `status_code` or `detail` attributes. Example: `except HTTPException as e:`.
Upgrade
Version history
0.2.10latest on PyPI · released Feb 15, 2022
Audit
Dependencies
importlib-metadataoptionalRequired for Python versions older than 3.8 to manage package metadata.