Merge pull request #1009 from opsmill/pog-doc501

Add raises section to existing docstrings

Author: ogenstad

docs/docs/python-sdk/sdk_ref/infrahub_sdk/client.mdx

@@ -241,6 +241,10 @@ If retry_on_failure is True, the query will retry until the server becomes reach
 **Raises:**
 
 - `GraphQLError`: When the GraphQL response contains errors.
+- `ServerNotReachableError`: If the server is not reachable after exhausting retries.
+- `AuthenticationError`: If the server returns a 401 or 403 response.
+- `URLNotFoundError`: If the server returns a 404 response.
+- `Error`: If the response is unexpectedly missing.
 
 **Returns:**
 
@@ -286,6 +290,10 @@ Get complete diff tree with metadata and nodes.
 
 Returns None if no diff exists.
 
+**Raises:**
+
+- `ValueError`: If ``from_time`` is later than ``to_time``.
+
 #### `allocate_next_ip_address`
 
 ```python
@@ -324,6 +332,10 @@ Allocate a new IP address by using the provided resource pool.
 
 - Node corresponding to the allocated resource.
 
+**Raises:**
+
+- `ValueError`: If ``resource_pool`` is not a ``CoreIPAddressPool``.
+
 </details>
 #### `allocate_next_ip_prefix`
 
@@ -364,6 +376,10 @@ Allocate a new IP prefix by using the provided resource pool.
 
 - Node corresponding to the allocated resource.
 
+**Raises:**
+
+- `ValueError`: If ``resource_pool`` is not a ``CoreIPPrefixPool``.
+
 </details>
 #### `create_batch`
 
@@ -524,6 +540,10 @@ If retry_on_failure is True, the query will retry until the server becomes reach
 **Raises:**
 
 - `GraphQLError`: When the GraphQL response contains errors.
+- `ServerNotReachableError`: If the server is not reachable after exhausting retries.
+- `AuthenticationError`: If the server returns a 401 or 403 response.
+- `URLNotFoundError`: If the server returns a 404 response.
+- `Error`: If the response is unexpectedly missing.
 
 **Returns:**
 
@@ -676,6 +696,10 @@ Get complete diff tree with metadata and nodes.
 
 Returns None if no diff exists.
 
+**Raises:**
+
+- `ValueError`: If ``from_time`` is later than ``to_time``.
+
 #### `allocate_next_ip_address`
 
 ```python
@@ -714,6 +738,10 @@ Allocate a new IP address by using the provided resource pool.
 
 - Node corresponding to the allocated resource.
 
+**Raises:**
+
+- `ValueError`: If ``resource_pool`` is not a ``CoreIPAddressPool``.
+
 </details>
 #### `allocate_next_ip_prefix`
 
@@ -754,6 +782,10 @@ Allocate a new IP prefix by using the provided resource pool.
 
 - Node corresponding to the allocated resource.
 
+**Raises:**
+
+- `ValueError`: If ``resource_pool`` is not a ``CoreIPPrefixPool``.
+
 </details>
 #### `repository_update_commit`
 

docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/node.mdx

@@ -259,6 +259,10 @@ Fetch all nodes that were allocated for the pool and a given resource.
 
 - list\[InfrahubNode]: The allocated nodes.
 
+**Raises:**
+
+- `ValueError`: If the node is not a resource pool.
+
 #### `get_pool_resources_utilization`
 
 ```python
@@ -271,19 +275,28 @@ Fetch the utilization of each resource for the pool.
 
 - list\[dict\[str, Any]]: A list containing the allocation numbers for each resource of the pool.
 
+**Raises:**
+
+- `ValueError`: If the node is not a resource pool.
+
 #### `get_flat_value`
 
 ```python
 get_flat_value(self, key: str, separator: str = '__') -> Any
 ```
 
-Query recursively a value defined in a flat notation (string), on a hierarchy of objects
+Query recursively a value defined in a flat notation (string), on a hierarchy of objects.
 
 **Examples:**
 
 name__value
 module.object.value
 
+**Raises:**
+
+- `ValueError`: If ``key`` references an unknown attribute or relationship,
+or if a referenced relationship is not of cardinality ``ONE``.
+
 #### `extract`
 
 ```python
@@ -544,6 +557,10 @@ Fetch all nodes that were allocated for the pool and a given resource.
 
 - list\[InfrahubNodeSync]: The allocated nodes.
 
+**Raises:**
+
+- `ValueError`: If the node is not a resource pool.
+
 #### `get_pool_resources_utilization`
 
 ```python
@@ -556,19 +573,28 @@ Fetch the utilization of each resource for the pool.
 
 - list\[dict\[str, Any]]: A list containing the allocation numbers for each resource of the pool.
 
+**Raises:**
+
+- `ValueError`: If the node is not a resource pool.
+
 #### `get_flat_value`
 
 ```python
 get_flat_value(self, key: str, separator: str = '__') -> Any
 ```
 
-Query recursively a value defined in a flat notation (string), on a hierarchy of objects
+Query recursively a value defined in a flat notation (string), on a hierarchy of objects.
 
 **Examples:**
 
 name__value
 module.object.value
 
+**Raises:**
+
+- `ValueError`: If ``key`` references an unknown attribute or relationship,
+or if a referenced relationship is not of cardinality ``ONE``.
+
 #### `extract`
 
 ```python

docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/parsers.mdx

@@ -14,3 +14,7 @@ parse_human_friendly_id(hfid: str | list[str]) -> tuple[str | None, list[str]]
 ```
 
 Parse a human-friendly ID into a kind and an identifier.
+
+**Raises:**
+
+- `ValueError`: If ``hfid`` is neither a string nor a list of strings.

docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/relationship.mdx

@@ -65,6 +65,10 @@ add(self, data: str | RelatedNode | dict) -> None
 
 Add a new peer to this relationship.
 
+**Raises:**
+
+- `UninitializedError`: If ``fetch()`` has not been called on the manager yet.
+
 #### `extend`
 
 ```python
@@ -99,6 +103,10 @@ add(self, data: str | RelatedNodeSync | dict) -> None
 
 Add a new peer to this relationship.
 
+**Raises:**
+
+- `UninitializedError`: If ``fetch()`` has not been called on the manager yet.
+
 #### `extend`
 
 ```python

docs/docs_generation/content_gen_methods/mdx/mdx_collapsed_overload_section.py

@@ -48,6 +48,10 @@ def from_overloads(cls, sections: list[MdxSection]) -> CollapsedOverloadSection:
 
         Selects the overload with the most parameters as *primary*.
         On ties, the first in source order wins.
+
+        Raises:
+            ValueError: If ``sections`` is empty.
+
         """
         if not sections:
             raise ValueError("Cannot create CollapsedOverloadSection from an empty list")

infrahub_sdk/_importer.py

@@ -21,6 +21,9 @@ def import_module(module_path: Path, import_root: str | None = None, relative_pa
         import_root (Optional[str]): Absolute string path to the current repository.
         relative_path (Optional[str]): Relative string path between module_path and import_root.
 
+    Raises:
+        ModuleImportError: If the module cannot be found or contains a syntax error.
+
     """
     import_root = import_root or str(module_path.parent)