Update protocols to support Template and fix support for Sync

Author: dgarros

.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

changelog/+docs-tasks.housekeeping.md

@@ -0,0 +1 @@
+Add `invoke lint-doc` command to help run the docs linters locally

changelog/+guide-typing.added.md

@@ -0,0 +1 @@
+Add a Guide related to Python Typing

changelog/+protocol-sync.fixed.md

@@ -0,0 +1 @@
+Fix support for Sync when generating Python Protocols

changelog/329.added.md

@@ -0,0 +1 @@
+Add support for object Template when generating protocols

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

docs/sidebars-python-sdk.ts

@@ -21,6 +21,7 @@ const sidebars: SidebarsConfig = {
             'guides/branches',
             'guides/store',
             'guides/tracking',
+            'guides/python-typing',
             'guides/batch',
             'guides/object-storage',
             'guides/resource-manager',

infrahub_sdk/ctl/cli_commands.py

@@ -20,7 +20,6 @@
 
 from .. import __version__ as sdk_version
 from ..async_typer import AsyncTyper
-from ..code_generator import CodeGenerator
 from ..ctl import config
 from ..ctl.branch import app as branch_app
 from ..ctl.check import run as run_check
@@ -42,6 +41,7 @@
 )
 from ..ctl.validate import app as validate_app
 from ..exceptions import GraphQLError, ModuleImportError
+from ..protocols_generator.generator import CodeGenerator
 from ..schema import MainSchemaTypesAll, SchemaRoot
 from ..template import Jinja2Template
 from ..template.exceptions import JinjaTemplateError