Release 1.11

.github/workflows/ci.yml

@@ -166,7 +166,7 @@ jobs:
           python-version: "3.12"
       - name: "Setup Python environment"
         run: |
-          pipx install poetry==1.8.5
+          pipx install poetry==2.1
           poetry config virtualenvs.create true --local
           poetry env use 3.12
       - name: "Install dependencies"
@@ -230,7 +230,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: "Setup environment"
         run: |
-          pipx install poetry==1.8.5 --python python${{ matrix.python-version }}
+          pipx install poetry==2.1 --python python${{ matrix.python-version }}
           poetry config virtualenvs.create true --local
           pip install invoke toml codecov
       - name: "Install Package"
@@ -283,14 +283,11 @@ jobs:
           echo "PYTEST_DEBUG_TEMPROOT=/var/lib/github/${RUNNER_NAME}/_temp" >> $GITHUB_ENV
       - name: "Setup environment"
         run: |
-          pipx install poetry==1.8.5
+          pipx install poetry==2.1
           poetry config virtualenvs.create true --local
           pip install invoke toml codecov
       - name: "Install Package"
         run: "poetry install --all-extras"
-      - name: "Set environment variables for python_testcontainers"
-        run: |
-          echo INFRAHUB_TESTING_IMAGE_VER=latest >> $GITHUB_ENV
       - name: "Integration Tests"
         run: |
           poetry run pytest --cov infrahub_sdk tests/integration/
@@ -359,7 +356,7 @@ jobs:
 
   #     - name: "Setup environment"
   #       run: |
-  #         pipx install poetry==1.8.5
+  #         pipx install poetry==2.1
   #         poetry config virtualenvs.create true --local
   #         pip install invoke toml codecov
 

.gitignore

@@ -27,4 +27,5 @@ dist/*
 **/*.csv
 
 # Generated files
-generated/
+generated/
+sandbox/

.vale/styles/Infrahub/branded-terms-case-swap.yml

@@ -6,9 +6,31 @@ ignorecase: false
 action:
   name: replace
 swap:
-  (?i:[^/]Github): GitHub
-  (?i:gitpod): GitPod
-  (?i:[^/]Graphql): GraphQL
+  (?:ansible): Ansible
+  (?:[^"]docker): Docker
+  (?:[Dd]ockerhub): DockerHub
+  (?:[^/][Gg]ithub): GitHub
+  (?:[Gg]itlab): GitLab
+  (?:gitpod): GitPod
+  (?:grafana): Grafana
+  (?:[^/][Gg]raphql): GraphQL
+  (?:[Ii]nflux[Dd]b): InfluxDB
   infrahub(?:\s|$): Infrahub
-  (?i:Openconfig): OpenConfig
+  (?:jinja2): Jinja2
+  (?:k3s): K3s
+  (?:k8s): K8s
+  (?:kubernetes): Kubernetes
+  (?:[^/][Mm]y[Ss]ql): MySQL
+  (?:neo4j): Neo4j
+  (?:[^/][Nn]ginx): NGINX
+  (?:[Nn]odejs): Node.js
+  (?:[^/][Oo]penapi): OpenAPI
+  (?:Openconfig): OpenConfig
   opsmill(?:\s|$): OpsMill
+  (?:[Pp]ostgre[Ss]ql): PostgreSQL
+  (?:[^/]prometheus): Prometheus
+  (?:[^/-]python): Python
+  (?:[Rr]abbitmq): RabbitMQ
+  (?:[^/]terraform): Terraform
+  (?:ubuntu): Ubuntu
+  (?:[Vv]s\W?[Cc]ode): VS Code

.yamllint.yml

@@ -5,6 +5,9 @@ ignore: |
   /.venv
   /examples
   tests/unit/sdk/test_data/schema_encoding_error.yml
+  /**/node_modules/**
+  tests/unit/sdk/test_data/multiple_files_valid_not_valid.yml
+  tests/fixtures/menus/invalid_yaml.yml
 
 rules:
   new-lines: disable

CHANGELOG.md

@@ -11,6 +11,31 @@ This project uses [*towncrier*](https://towncrier.readthedocs.io/) and the chang
 
 <!-- towncrier release notes start -->
 
+## [1.11.0](https://github.com/opsmill/infrahub-sdk-python/tree/v1.11.0) - 2025-04-17
+
+### Deprecated
+
+- The 'timeout' parameter while creating a node or fetching the schema has been deprecated. the default_timeout will be used instead.
+
+### Added
+
+- Add support for object Template when generating protocols ([#329](https://github.com/opsmill/infrahub-sdk-python/issues/329))
+- Add a Guide related to Python Typing
+- Add method `client.schema.set_cache()` to populate the cache manually (primarily for unit testing)
+- By default, schema.fetch will now populate the cache (this behavior can be changed with `populate_cache`)
+- Add `menu validate` command to validate the format of menu files.
+
+### Fixed
+
+- Raise a proper branch not found error when requesting a node or schema for a branch that doesn't exist. ([#286](https://github.com/opsmill/infrahub-sdk-python/issues/286))
+- Fix support for Sync when generating Python Protocols
+
+### Housekeeping
+
+- Add `invoke lint-doc` command to help run the docs linters locally
+- Add a fixture to always reset some environment variables before running tests
+- Update Pytest-httpx and set all responses as reusable
+
 ## [1.10.2](https://github.com/opsmill/infrahub-sdk-python/tree/v1.10.2) - 2025-04-11
 
 ### Fixed

docs/docs/infrahubctl/infrahubctl-menu.mdx

@@ -17,6 +17,7 @@ $ infrahubctl menu [OPTIONS] COMMAND [ARGS]...
 **Commands**:
 
 * `load`: Load one or multiple menu files into...
+* `validate`: Validate one or multiple menu files.
 
 ## `infrahubctl menu load`
 
@@ -38,3 +39,24 @@ $ infrahubctl menu load [OPTIONS] MENUS...
 * `--branch TEXT`: Branch on which to load the menu.
 * `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
 * `--help`: Show this message and exit.
+
+## `infrahubctl menu validate`
+
+Validate one or multiple menu files.
+
+**Usage**:
+
+```console
+$ infrahubctl menu validate [OPTIONS] PATHS...
+```
+
+**Arguments**:
+
+* `PATHS...`: [required]
+
+**Options**:
+
+* `--debug / --no-debug`: [default: no-debug]
+* `--branch TEXT`: Branch on which to validate the objects.
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--help`: Show this message and exit.

docs/docs/infrahubctl/infrahubctl-object.mdx

@@ -17,6 +17,7 @@ $ infrahubctl object [OPTIONS] COMMAND [ARGS]...
 **Commands**:
 
 * `load`: Load one or multiple objects files into...
+* `validate`: Validate one or multiple objects files.
 
 ## `infrahubctl object load`
 
@@ -38,3 +39,24 @@ $ infrahubctl object load [OPTIONS] PATHS...
 * `--branch TEXT`: Branch on which to load the objects.
 * `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
 * `--help`: Show this message and exit.
+
+## `infrahubctl object validate`
+
+Validate one or multiple objects files.
+
+**Usage**:
+
+```console
+$ infrahubctl object validate [OPTIONS] PATHS...
+```
+
+**Arguments**:
+
+* `PATHS...`: [required]
+
+**Options**:
+
+* `--debug / --no-debug`: [default: no-debug]
+* `--branch TEXT`: Branch on which to validate the objects.
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--help`: Show this message and exit.

docs/docs/python-sdk/guides/python-typing.mdx

@@ -0,0 +1,103 @@
+---
+title: Strict Typing in Python
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Overview
+
+This guide explains how to use Python's type system effectively with the Infrahub SDK, focusing on the use of Protocols for type-safe development.
+
+:::note What is Python Typing
+
+Python typing allows you to specify the expected data types of variables, function arguments, and return values to improve code clarity and catch bugs early.
+
+```python
+# Basic type hints
+def percentage(num1: int, num2: int) -> float:
+    return (num1 / num2) * 100
+```
+
+:::
+
+## Leveraging Python protocols
+
+The Python SDK for Infrahub has been designed to automatically work with any schemas loaded into Infrahub.
+Internally, the Python SDK generates dynamic Python representations of your schemas.
+
+While this approach improves code readability, it presents challenges with type checking because each object has a different signature based on your schema.
+
+### Without protocols
+
+In the example below, type checkers like Mypy will typically complain about `blue_tag.description.value` because `description` is a dynamic parameter generated by the SDK.
+
+```python
+# Type checker cannot verify the existence of 'description'
+blue_tag = client.get("BuiltinTag", name__value="blue")  # blue_tag is of type InfrahubNode or InfrahubNodeSync
+blue_tag.description.value = "The blue tag"  # Mypy: error: "InfrahubNode" has no attribute "description"
+blue_tag.save()
+```
+
+### With protocols
+
+To provide strict type checking while maintaining platform extensibility, the Python SDK integrates with Python Protocols.
+
+For all core and internal models, the protocols are included in the SDK under `infrahub_sdk.protocols`.
+Whenever you need to specify the kind of object you're working with as a string, you can use the corresponding protocol instead.
+
+```python
+from infrahub_sdk.protocols import BuiltinTag
+
+# Type checker can now verify all attributes
+blue_tag = client.get(BuiltinTag, name__value="blue")  # blue_tag is of type BuiltinTag
+blue_tag.description.value = "The blue tag"  # No type errors
+blue_tag.save()
+```
+
+:::note Python Protocols
+
+Python Protocols, introduced in PEP 544, define a set of method and property signatures that a class must implement to be considered a match, enabling structural subtyping (also known as "duck typing" with static checks). They allow you to specify behavior without requiring inheritance, making code more flexible and type-safe.
+
+More information about Python Protocols can be found [here](https://typing.python.org/en/latest/spec/protocol.html)
+
+:::
+
+## Generating custom protocols based on your schema
+
+You can generate Python Protocols for your own models using the `infrahubctl protocols` command. This supports both synchronous and asynchronous Python code.
+
+It's possible to provide the schema from a local directory or from an existing Infrahub Instance.
+
+<Tabs groupId="local-remote">
+  <TabItem value="Existing Infrahub Instance" default>
+
+  ```shell
+  export INFRAHUB_ADDRESS=https://infrahub.example.com
+  infrahubctl protocols --out lib/protocols.py --sync
+  ```
+
+  </TabItem>
+  <TabItem value="Local Directory" default>
+
+  ```shell
+  infrahubctl protocols --schemas schemas/tag.schema.yml --out lib/protocols.py
+  ```
+
+  </TabItem>
+</Tabs>
+
+> When using a local directory, Protocols for Profiles and Object Templates won't be generated.
+
+## Using custom protocols
+
+After generation, you can import and use your custom protocols as describe below.
+
+```python
+from lib.protocols import MyOwnObject
+
+# Use your custom protocol
+my_object = client.get(MyOwnObject, name__value="example")
+```
+
+> if you don't have your own Python module, it's possible to use relative path by having the `procotols.py` in the same directory as your script/transform/generator