Merge develop into infrahub-develop

changelog/+idempotent-file-ops.added.md

@@ -0,0 +1,7 @@
+Added SHA-1 idempotency primitives for `CoreFileObject` nodes:
+
+- `InfrahubNode.matches_local_checksum(source)` / sync variant — compare a local `bytes | Path | BinaryIO` source against the node's server-stored checksum without invoking a transfer.
+- `InfrahubNode.upload_if_changed(source, name=None)` / sync variant — stage + save only when the local source differs from the server, returning an `UploadResult(was_uploaded, checksum)` dataclass.
+- `download_file(..., skip_if_unchanged=True)` — short-circuit the download when `dest` already exists on disk with a matching SHA-1. Returns `0` bytes written when skipped.
+
+A shared `sha1_of_source` helper (streaming, 64 KiB chunks) centralises the hashing convention in `infrahub_sdk.file_handler`.

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`