add docs

Author: dgarros

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

@@ -0,0 +1,76 @@
+---
+title: Strict Typing in Python
+---
+
+# 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.
+
+:::
+
+## 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.
+
+```shell
+# Generate protocols for your schema
+infrahubctl protocols --schemas schemas/tag.schema.yml --out lib/protocols.py
+```
+
+After generation, you can import and use your custom protocols:
+
+```python
+from lib.protocols import MyOwnObject
+
+# Use your custom protocol
+my_object = client.get(MyOwnObject, name__value="example")
+```

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',