updated docs strings and added README.md

openapi_first/loader.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 OpenAPI specification loading and validation utilities.
 
----
-
-## Summary
-
 This module is responsible for loading an OpenAPI 3.x specification
 from disk and validating it before it is used by the application.
 
@@ -14,14 +12,18 @@ must never reach the routing or runtime layers.
 Notes:
     **Design Principles:**
 
-        - OpenAPI is treated as an authoritative contract
-        - Invalid specifications fail fast at application startup
-        - Supported formats are JSON and YAML
-        - Validation errors are surfaced clearly and early
+        - OpenAPI is treated as an authoritative contract.
+        - Invalid specifications fail fast at application startup.
+        - Supported formats are JSON and YAML.
+        - Validation errors are surfaced clearly and early.
 
     **Constraints:**
 
-        - This module intentionally does NOT: Modify the OpenAPI document, infer missing fields, generate models or code, or perform request/response validation at runtime.
+        - This module intentionally does NOT:
+            - Modify the OpenAPI document.
+            - Infer missing fields.
+            - Generate models or code.
+            - Perform request/response validation at runtime.
 """
 
 import json
@@ -41,7 +43,8 @@ class OpenAPISpecLoadError(OpenAPIFirstError):
     Notes:
         **Guarantees:**
 
-            - This error indicates that the OpenAPI document is unreadable, malformed, or violates the OpenAPI 3.x specification
+            - This error indicates that the OpenAPI document is unreadable,
+              malformed, or violates the OpenAPI 3.x specification.
     """
     pass
 
@@ -52,7 +55,8 @@ def load_openapi(path: str | Path) -> dict[str, Any]:
 
     Args:
         path (str | Path):
-            Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.
+            Filesystem path to an OpenAPI specification file. Supported
+            extensions: `.json`, `.yaml`, `.yml`.
 
     Returns:
         dict[str, Any]:
@@ -60,13 +64,16 @@ def load_openapi(path: str | Path) -> dict[str, Any]:
 
     Raises:
         OpenAPISpecLoadError:
-            If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.
+            If the file does not exist, cannot be parsed, or fails OpenAPI
+            schema validation.
 
     Notes:
         **Guarantees:**
 
-            - The specification is parsed based on file extension and validated using a strict OpenAPI schema validator
-            - Any error results in an immediate exception, preventing application startup
+            - The specification is parsed based on file extension and validated
+              using a strict OpenAPI schema validator.
+            - Any error results in an immediate exception, preventing
+              application startup.
     """
     spec_path = Path(path)