updated docs strings and added README.md

openapi_first/errors.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Exceptions for OpenAPI-first FastAPI applications.
 
----
-
-## Summary
-
 This module defines a small hierarchy of explicit, intention-revealing
 exceptions used to signal contract violations between an OpenAPI
 specification and its Python implementation.
@@ -12,10 +10,10 @@ specification and its Python implementation.
 Notes:
     **Design Principles:**
 
-        - Errors represent programmer mistakes, not runtime conditions
-        - All errors are raised during application startup
-        - Messages are actionable and suitable for CI/CD output
-        - Exceptions are explicit rather than reused from generic built-ins
+        - Errors represent programmer mistakes, not runtime conditions.
+        - All errors are raised during application startup.
+        - Messages are actionable and suitable for CI/CD output.
+        - Exceptions are explicit rather than reused from generic built-ins.
 
     These errors should normally cause immediate application failure.
 """
@@ -27,8 +25,11 @@ class OpenAPIFirstError(Exception):
     Notes:
         **Responsibilities:**
 
-            - This exception exists to allow callers, test suites, and CI pipelines to catch and distinguish OpenAPI contract violations from unrelated runtime errors
-            - All exceptions raised by the OpenAPI-first core should inherit from this type
+            - This exception exists to allow callers, test suites, and CI
+              pipelines to catch and distinguish OpenAPI contract violations
+              from unrelated runtime errors.
+            - All exceptions raised by the OpenAPI-first core should inherit
+              from this type.
     """
     pass
 
@@ -40,12 +41,15 @@ class MissingOperationHandler(OpenAPIFirstError):
     Notes:
         **Scenarios:**
 
-            - An OpenAPI operation does not define an operationId
-            - An operationId is defined but no matching function exists in the provided routes module
+            - An OpenAPI operation does not define an `operationId`.
+            - An `operationId` is defined but no matching function exists in
+              the provided routes module.
 
         **Guarantees:**
 
-            - This represents a violation of the OpenAPI-first contract and indicates that the specification and implementation are out of sync
+            - This represents a violation of the OpenAPI-first contract and
+              indicates that the specification and implementation are out of
+              sync.
     """
 
     def __init__(self, *, path: str, method: str, operation_id: str | None = None):