{"id":29229449,"url":"https://github.com/seapagan/response-codes","last_synced_at":"2026-04-01T23:33:39.755Z","repository":{"id":282672886,"uuid":"918756191","full_name":"seapagan/response-codes","owner":"seapagan","description":"A comprehensive Python library providing HTTP status code constants and exceptions","archived":false,"fork":false,"pushed_at":"2026-03-27T02:05:59.000Z","size":293,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-27T14:56:09.615Z","etag":null,"topics":["http-exceptions","http-status-codes","python","python3","status-codes"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seapagan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-18T19:15:59.000Z","updated_at":"2026-03-22T12:00:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"bbce0207-59e7-46d0-97b7-959629d5a926","html_url":"https://github.com/seapagan/response-codes","commit_stats":null,"previous_names":["seapagan/response-codes"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/seapagan/response-codes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Fresponse-codes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Fresponse-codes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Fresponse-codes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Fresponse-codes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seapagan","download_url":"https://codeload.github.com/seapagan/response-codes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seapagan%2Fresponse-codes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http-exceptions","http-status-codes","python","python3","status-codes"],"created_at":"2025-07-03T12:11:07.821Z","updated_at":"2026-04-01T23:33:39.734Z","avatar_url":"https://github.com/seapagan.png","language":"Python","readme":"# HTTP Response Codes\n\nA comprehensive Python library providing HTTP status code constants and exceptions.\n\n[![PyPI version](https://badge.fury.io/py/http-response-codes.svg)](https://badge.fury.io/py/http-response-codes)\n[![Python Support](https://img.shields.io/pypi/pyversions/http-response-codes.svg)](https://pypi.org/project/http-response-codes/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Overview\n\n`http-response-codes` is a Python library that provides a comprehensive set of\nHTTP status codes as exception classes. Each status code is represented by a\nclass that inherits from `HTTPStatus`, containing the numeric code, message, and\ndescription.\n\nThe module covers all standard HTTP status codes in the following categories:\n\n- 1xx: Informational responses (100-103)\n- 2xx: Success responses (200-208, 226)\n- 3xx: Redirection responses (300-308)\n- 4xx: Client error responses (400-431, 451)\n- 5xx: Server error responses (500-511)\n\n## Installation\n\n```bash\npip install http-response-codes\n```\n\nOr using `uv`:\n\n```bash\nuv add http-response-codes\n```\n\n## Features\n\n- Complete coverage of HTTP status codes\n- Each status code is a proper Python exception class\n- **Class-level comparisons** without instantiation required\n- Rich comparison operators (`==`, `\u003c`, `\u003c=`, `\u003e`, `\u003e=`)\n- Compare with both integers and strings\n- Type conversion support (`int()`, `str()`)\n- Hashable - use as dictionary keys or in sets\n- Type hints included\n- Predefined groups of related status codes\n- Category predicate helpers (`is_success`, `is_client_error`, `is_server_error`, etc.)\n- Detailed descriptions for each status code\n- Zero dependencies\n\n## Usage\n\n### Basic Usage\n\n```python\nfrom response_codes import HTTP_404_NOT_FOUND\n\n# Raise as an exception\nraise HTTP_404_NOT_FOUND()\n\n# Access status code properties (no instantiation needed!)\nprint(HTTP_404_NOT_FOUND.status_code)  # 404\nprint(HTTP_404_NOT_FOUND.message)      # \"Not Found\"\nprint(HTTP_404_NOT_FOUND.description)  # Detailed description\n\n# Compare directly with integers (class-level magic!)\nassert HTTP_404_NOT_FOUND == 404\nassert HTTP_404_NOT_FOUND == \"Not Found\"\n```\n\n\u003e [!NOTE]\n\u003e Thanks to metaclass magic, you can compare status codes and access their\n\u003e properties directly on the class - no need to instantiate!\n\n### Using Status Code Groups\n\n```python\nfrom response_codes import (\n    HTTP_INFORMATIONAL,\n    HTTP_SUCCESS,\n    HTTP_REDIRECTION,\n    HTTP_CLIENT_ERRORS,\n    HTTP_SERVER_ERRORS,\n)\n\n# Check if a status code is in a group\nstatus_code = 404\nif status_code in HTTP_CLIENT_ERRORS:\n    print(\"This is a client error!\")\n```\n\n\u003e [!NOTE]\n\u003e Built-in status groups are exported as read-only mappings. You can look up\n\u003e and iterate values normally, but mutation operations are not supported.\n\n### Status Category Helpers\n\nCategory predicate helpers: `is_informational`, `is_success`, `is_redirection`,\n`is_client_error`, `is_server_error`.\nThey accept an `int`, a status class, or a status instance; unsupported types\nraise `TypeError`.\n\nPractical example:\n\n```python\nfrom response_codes import HTTP_202_ACCEPTED, HTTP_429_TOO_MANY_REQUESTS, is_success, is_client_error\nis_success(202)  # True\nis_success(HTTP_202_ACCEPTED)  # True\nis_success(HTTP_202_ACCEPTED())  # True\nis_success(302)  # False\nis_client_error(HTTP_429_TOO_MANY_REQUESTS)  # True\nis_client_error(404)  # True\nis_client_error(3.14)  # TypeError: value must be int or HTTPStatus\nis_client_error(None)  # TypeError: value must be int or HTTPStatus\n```\n\n### Advanced Comparison Features\n\nThe library uses a metaclass to enable powerful comparison operations\ndirectly on the status code classes (no instantiation required):\n\n#### Compare with Integers or Strings\n\n```python\nfrom response_codes import HTTP_404_NOT_FOUND, HTTP_200_OK\n\n# Integer comparison\nif HTTP_404_NOT_FOUND == 404:\n    print(\"It's a 404!\")\n\n# String comparison\nif HTTP_200_OK == \"OK\":\n    print(\"Request succeeded\")\n\n# Rich comparisons for range checking\nif 400 \u003c= HTTP_404_NOT_FOUND \u003c 500:\n    print(\"Client error\")\n\nif HTTP_500_INTERNAL_SERVER_ERROR \u003e= 500:\n    print(\"Server error\")\n```\n\n#### Type Conversions\n\n```python\nfrom response_codes import HTTP_404_NOT_FOUND\n\n# Convert to integer\nstatus_code = int(HTTP_404_NOT_FOUND)  # 404\n\n# Convert to string\nstatus_msg = str(HTTP_404_NOT_FOUND)   # \"Not Found\"\n```\n\n#### Use in Collections\n\nStatus codes are hashable and can be used as dictionary keys or in sets:\n\n```python\nfrom response_codes import (\n    HTTP_200_OK,\n    HTTP_404_NOT_FOUND,\n    HTTP_500_INTERNAL_SERVER_ERROR,\n)\n\n# As dictionary keys\nhandlers = {\n    HTTP_200_OK: handle_success,\n    HTTP_404_NOT_FOUND: handle_not_found,\n    HTTP_500_INTERNAL_SERVER_ERROR: handle_error,\n}\n\n# In sets\ncritical_errors = {\n    HTTP_500_INTERNAL_SERVER_ERROR,\n    HTTP_503_SERVICE_UNAVAILABLE,\n}\n```\n\n### Real-World Examples\n\n#### Flask/FastAPI Response Handling\n\n```python\nfrom flask import jsonify\nfrom response_codes import (\n    HTTP_200_OK,\n    HTTP_404_NOT_FOUND,\n    HTTP_400_BAD_REQUEST,\n)\n\n@app.route('/api/user/\u003cint:user_id\u003e')\ndef get_user(user_id):\n    user = db.get_user(user_id)\n\n    if not user:\n        return (\n            jsonify({\"error\": str(HTTP_404_NOT_FOUND)}),\n            int(HTTP_404_NOT_FOUND)\n        )\n\n    return jsonify(user), int(HTTP_200_OK)\n```\n\n#### Exception Handling with Detailed Information\n\n```python\nfrom response_codes import HTTP_404_NOT_FOUND, HTTPStatus\n\ntry:\n    resource = fetch_resource(resource_id)\n    if not resource:\n        raise HTTP_404_NOT_FOUND()\nexcept HTTP_404_NOT_FOUND as e:\n    logger.error(f\"{e.status_code} - {e.message}: {e.description}\")\n    return {\"error\": e.message}, e.status_code\nexcept HTTPStatus as e:\n    # Catch any HTTP status exception\n    logger.error(f\"HTTP Error {e.status_code}: {e.message}\")\n    return {\"error\": e.message}, e.status_code\n```\n\n#### Status Code Validation and Range Checking\n\n```python\nfrom response_codes import HTTP_CLIENT_ERRORS\n\ndef handle_api_response(status_code):\n    # Check if status code is in client error range\n    if status_code in HTTP_CLIENT_ERRORS:\n        retry_request()\n\n    # Check status code ranges using comparisons\n    if 200 \u003c= status_code \u003c 300:\n        return \"Success\"\n    elif 300 \u003c= status_code \u003c 400:\n        return \"Redirection\"\n    elif 400 \u003c= status_code \u003c 500:\n        return \"Client Error\"\n    elif 500 \u003c= status_code \u003c 600:\n        return \"Server Error\"\n```\n\n#### Custom Error Groups\n\n```python\nfrom response_codes import (\n    create_status_group,\n    HTTP_401_UNAUTHORIZED,\n    HTTP_403_FORBIDDEN,\n)\n\n# Create custom groups for your application\nAUTH_ERRORS = create_status_group(\n    HTTP_401_UNAUTHORIZED,\n    HTTP_403_FORBIDDEN,\n)\n\ndef requires_auth(status_code):\n    return status_code in AUTH_ERRORS\n```\n\n## Development\n\nThis project uses modern Python tooling:\n\n- `uv` for dependency management\n- `ruff` for linting and formatting\n- `mypy` for type checking\n- `pytest` for testing\n- `pre-commit` for git hooks\n\n### Setup Development Environment\n\nClone the repository:\n\n```bash\ngit clone https://github.com/seapagan/response-codes.git\ncd response-codes\n```\n\nInstall development dependencies:\n\n```bash\nuv sync\n```\n\nInstall pre-commit hooks:\n\n```bash\nprek install\n```\n\n### Running Tests\n\n```bash\npoe test # or simply run 'pytest'\n```\n\nOr in watch mode:\n\n```bash\npoe test:watch\n```\n\n### Code Quality Checks\n\n```bash\n# Run all pre-commit checks\npoe pre\n\n# Run mypy type checking\npoe mypy\n\n# Run ruff linting\npoe ruff\n\n# Run ruff formatting\npoe format\n```\n\n## Contributing\n\nContributions 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.\n\nPlease make sure to update tests as appropriate and adhere to the existing coding style.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Author\n\nCreated and maintained by [Grant Ramsay](https://github.com/seapagan)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseapagan%2Fresponse-codes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseapagan%2Fresponse-codes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseapagan%2Fresponse-codes/lists"}