Add Pydantic models and uv support to the Python SDK

src/SDK/Language/Python.php

@@ -135,6 +135,11 @@ public function getFiles(): array
                 'destination' => 'requirements.txt',
                 'template' => 'python/requirements.txt.twig',
             ],
+            [
+                'scope' => 'default',
+                'destination' => 'pyproject.toml',
+                'template' => 'python/pyproject.toml.twig',
+            ],
             [
                 'scope' => 'default',
                 'destination' => '{{ spec.title | caseSnake}}/__init__.py',
@@ -195,6 +200,16 @@ public function getFiles(): array
                 'destination' => '{{ spec.title | caseSnake}}/service.py',
                 'template' => 'python/package/service.py.twig',
             ],
+            [
+                'scope' => 'default',
+                'destination' => '{{ spec.title | caseSnake}}/models/__init__.py',
+                'template' => 'python/package/models/__init__.py.twig',
+            ],
+            [
+                'scope' => 'default',
+                'destination' => '{{ spec.title | caseSnake}}/models/base_model.py',
+                'template' => 'python/package/models/base_model.py.twig',
+            ],
             [
                 'scope' => 'default',
                 'destination' => '{{ spec.title | caseSnake}}/services/__init__.py',
@@ -250,6 +265,11 @@ public function getFiles(): array
                 'destination' => '{{ spec.title | caseSnake}}/models/{{ requestModel.name | caseSnake }}.py',
                 'template' => 'python/package/models/request_model.py.twig',
             ],
+            [
+                'scope' => 'definition',
+                'destination' => '{{ spec.title | caseSnake}}/models/{{ definition.name | caseSnake }}.py',
+                'template' => 'python/package/models/model.py.twig',
+            ],
         ];
     }
 
@@ -303,7 +323,7 @@ public function getTypeName(array $parameter, array $spec = []): string
                     }
                     break;
                 case self::TYPE_OBJECT:
-                    $typeName = 'dict';
+                    $typeName = 'Dict[str, Any]';
                     break;
                 default:
                     $typeName = $parameter['type'];
@@ -410,6 +430,137 @@ public function getParamExample(array $param, string $lang = ''): string
         };
     }
 
+    protected function getModelName(string $name): string
+    {
+        return $this->toPascalCase($name);
+    }
+
+    protected function getUnionType(array $types): string
+    {
+        $types = array_values(array_unique(array_filter($types)));
+
+        if (empty($types)) {
+            return 'Any';
+        }
+
+        if (count($types) === 1) {
+            return $types[0];
+        }
+
+        return 'Union[' . implode(', ', $types) . ']';
+    }
+
+    protected function normalizeModelFieldName(string $name): string
+    {
+        $name = ltrim($name, '$');
+        $name = $this->toSnakeCase($name);
+
+        if ($name === '') {
+            $name = 'value';
+        }
+
+        return $this->escapeKeyword($name);
+    }
+
+    protected function getModelFieldName(array $property, array $properties): string
+    {
+        $propertyName = $property['name'] ?? 'value';
+        $baseName = $this->normalizeModelFieldName($propertyName);
+        $index = 0;
+
+        foreach ($properties as $candidate) {
+            if ($this->normalizeModelFieldName($candidate['name'] ?? 'value') !== $baseName) {
+                continue;
+            }
+
+            $index++;
+
+            if (($candidate['name'] ?? null) === $propertyName) {
+                break;
+            }
+        }
+
+        if ($index <= 1) {
+            return $baseName;
+        }
+
+        return $baseName . '_' . $index;
+    }
+
+    protected function getModelPropertyType(array $property, string $ownerName = ''): string
+    {
+        if (!empty($property['sub_schemas'])) {
+            $unionType = $this->getUnionType(array_map(
+                fn($schema) => $this->getModelName($schema),
+                $property['sub_schemas']
+            ));
+
+            return ($property['type'] ?? '') === self::TYPE_ARRAY
+                ? 'List[' . $unionType . ']'
+                : $unionType;
+        }
+
+        if (!empty($property['sub_schema'])) {
+            $modelType = $this->getModelName($property['sub_schema']);
+
+            return ($property['type'] ?? '') === self::TYPE_ARRAY
+                ? 'List[' . $modelType . ']'
+                : $modelType;
+        }
+
+        if (
+            ($property['type'] ?? null) === self::TYPE_ARRAY
+            && !empty($property['items']['enum'])
+        ) {
+            $enumType = $this->getModelName($property['x-enum-name'] ?? (($ownerName ?: 'Model') . ucfirst($property['name'] ?? 'Value')));
+
+            return 'List[' . $enumType . ']';
+        }
+
+        if (!empty($property['enum'])) {
+            $enumType = $this->getModelName($property['enumName'] ?? $property['x-enum-name'] ?? (($ownerName ?: 'Model') . ucfirst($property['name'] ?? 'Value')));
+
+            return ($property['type'] ?? '') === self::TYPE_ARRAY
+                ? 'List[' . $enumType . ']'
+                : $enumType;
+        }
+
+        if (($property['type'] ?? '') === self::TYPE_OBJECT) {
+            return 'Dict[str, Any]';
+        }
+
+        return $this->getTypeName(array_merge($property, [
+            'required' => true,
+            'nullable' => false,
+        ]));
+    }
+
+    protected function getResponseType(array $method): string
+    {
+        if (($method['type'] ?? null) === 'webAuth') {
+            return 'str';
+        }
+
+        if (($method['type'] ?? null) === 'location') {
+            return 'bytes';
+        }
+
+        if (!empty($method['responseModels']) && count($method['responseModels']) > 1) {
+            $types = array_map(fn($model) => $this->getModelName($model), array_filter(
+                $method['responseModels'],
+                fn($model) => !empty($model) && $model !== 'any'
+            ));
+
+            return $this->getUnionType($types);
+        }
+
+        if (!empty($method['responseModel']) && $method['responseModel'] !== 'any') {
+            return $this->getModelName($method['responseModel']);
+        }
+
+        return 'Dict[str, Any]';
+    }
+
     public function getFilters(): array
     {
         return [
@@ -419,6 +570,15 @@ public function getFilters(): array
             new TwigFilter('getPropertyType', function ($value, $method = []) {
                 return $this->getTypeName($value, $method);
             }),
+            new TwigFilter('getModelPropertyType', function (array $value, string $ownerName = '') {
+                return $this->getModelPropertyType($value, $ownerName);
+            }),
+            new TwigFilter('getModelFieldName', function (array $value, array $properties) {
+                return $this->getModelFieldName($value, $properties);
+            }),
+            new TwigFilter('getResponseType', function (array $method) {
+                return $this->getResponseType($method);
+            }),
             new TwigFilter('formatParamValue', function (string $paramName, string $paramType, bool $isMultipartFormData) {
                 if ($isMultipartFormData && $paramType === self::TYPE_BOOLEAN) {
                     return "str({$paramName}).lower() if type({$paramName}) is bool else {$paramName}";

templates/python/README.md.twig

@@ -28,6 +28,12 @@ To install via [PyPI](https://pypi.org/):
 pip install {{ language.params.pipPackage }}
 ```
 
+Or with `uv`:
+
+```bash
+uv add {{ language.params.pipPackage }}
+```
+
 {% if sdk.gettingStarted %}
 
 {{ sdk.gettingStarted|raw }}

templates/python/base/params.twig

@@ -8,15 +8,15 @@
 {% endif %}
 {% endfor %}
 {% for parameter in method.parameters.path %}
-        api_path = api_path.replace('{{ '{' }}{{ parameter.name | caseCamel }}{{ '}' }}', {{ parameter.name | escapeKeyword | caseSnake }})
+        api_path = api_path.replace('{{ '{' }}{{ parameter.name | caseCamel }}{{ '}' }}', str(self._normalize_value({{ parameter.name | escapeKeyword | caseSnake }})))
 {% endfor %}
 
 {% for parameter in method.parameters.query %}
 {% if not parameter.nullable and not parameter.required %}
         if {{ parameter.name | escapeKeyword | caseSnake }} is not None:
-            api_params['{{ parameter.name }}'] = {{ parameter.name | escapeKeyword | caseSnake }}
+            api_params['{{ parameter.name }}'] = self._normalize_value({{ parameter.name | escapeKeyword | caseSnake }})
 {% else %}
-        api_params['{{ parameter.name }}'] = {{ parameter.name | escapeKeyword | caseSnake }}
+        api_params['{{ parameter.name }}'] = self._normalize_value({{ parameter.name | escapeKeyword | caseSnake }})
 {% endif %}
 {% endfor %}
 {% for parameter in method.parameters.body|merge(method.parameters.formData|default([])) %}
@@ -25,9 +25,9 @@
 {% set formattedValue = paramName | formatParamValue(parameter.type, isMultipart) %}
 {% if not parameter.nullable and not parameter.required %}
         if {{ paramName }} is not None:
-            api_params['{{ parameter.name }}'] = {{ formattedValue }}
+            api_params['{{ parameter.name }}'] = self._normalize_value({{ formattedValue }})
 {% else %}
-        api_params['{{ parameter.name }}'] = {{ formattedValue }}
+        api_params['{{ parameter.name }}'] = self._normalize_value({{ formattedValue }})
 {% endif %}
 {% endfor %}
-{% endif %}
+{% endif %}

templates/python/base/requests/api.twig

@@ -1,8 +1,24 @@
-        return self.client.call('{{ method.method | caseLower }}', api_path, {
+        response = self.client.call('{{ method.method | caseLower }}', api_path, {
 {% for parameter in method.parameters.header %}
-            '{{ parameter.name }}': {{ parameter.name | escapeKeyword | caseSnake }},
+            '{{ parameter.name }}': self._normalize_value({{ parameter.name | escapeKeyword | caseSnake }}),
 {% endfor %}
 {% for key, header in method.headers %}
             '{{ key }}': '{{ header }}',
 {% endfor %}
-        }, api_params{% if method.type == 'webAuth' %}, response_type='location'{% endif %})
+        }, api_params{% if method.type == 'webAuth' %}, response_type='location'{% endif %})
+{% if method.responseModels is defined and method.responseModels|length > 1 %}
+{% set validResponseModels = [] %}
+{% for responseModel in method.responseModels %}
+{% if responseModel and responseModel != 'any' %}
+{% set validResponseModels = validResponseModels|merge([responseModel]) %}
+{% endif %}
+{% endfor %}
+
+        return self._parse_response(response, union_models=({% for responseModel in validResponseModels %}{% if (responseModel | caseUcfirst) == (service.name | caseUcfirst) %}{{ responseModel | caseUcfirst }}Model{% else %}{{ responseModel | caseUcfirst }}{% endif %}, {% endfor %}))
+{% elseif method.responseModel and method.responseModel != 'any' %}
+
+        return self._parse_response(response, model={% if (method.responseModel | caseUcfirst) == (service.name | caseUcfirst) %}{{ method.responseModel | caseUcfirst }}Model{% else %}{{ method.responseModel | caseUcfirst }}{% endif %})
+{% else %}
+
+        return response
+{% endif %}

templates/python/base/requests/file.twig

@@ -12,11 +12,27 @@
 {% endif %}
 {% endfor %}
 
-        return self.client.chunked_upload(api_path, {
+        response = self.client.chunked_upload(api_path, {
 {% for parameter in method.parameters.header %}
-            '{{ parameter.name }}': {{ parameter.name | escapeKeyword | caseSnake }},
+            '{{ parameter.name }}': self._normalize_value({{ parameter.name | escapeKeyword | caseSnake }}),
 {% endfor %}
 {% for key, header in method.headers %}
             '{{ key }}': '{{ header }}',
 {% endfor %}
-        }, api_params, param_name, on_progress, upload_id)
+        }, api_params, param_name, on_progress, upload_id)
+{% if method.responseModels is defined and method.responseModels|length > 1 %}
+{% set validResponseModels = [] %}
+{% for responseModel in method.responseModels %}
+{% if responseModel and responseModel != 'any' %}
+{% set validResponseModels = validResponseModels|merge([responseModel]) %}
+{% endif %}
+{% endfor %}
+
+        return self._parse_response(response, union_models=({% for responseModel in validResponseModels %}{% if (responseModel | caseUcfirst) == (service.name | caseUcfirst) %}{{ responseModel | caseUcfirst }}Model{% else %}{{ responseModel | caseUcfirst }}{% endif %}, {% endfor %}))
+{% elseif method.responseModel and method.responseModel != 'any' %}
+
+        return self._parse_response(response, model={% if (method.responseModel | caseUcfirst) == (service.name | caseUcfirst) %}{{ method.responseModel | caseUcfirst }}Model{% else %}{{ method.responseModel | caseUcfirst }}{% endif %})
+{% else %}
+
+        return response
+{% endif %}

templates/python/package/encoders/value_class_encoder.py.twig

@@ -1,13 +1,17 @@
 import json
+from ..models.base_model import AppwriteModel
 {%~ for enum in spec.allEnums %}
 from ..enums.{{ enum.name | caseSnake }} import {{ enum.name | caseUcfirst | overrideIdentifier }}
 {%~ endfor %}
 
 class ValueClassEncoder(json.JSONEncoder):
     def default(self, o):
+        if isinstance(o, AppwriteModel):
+            return o.to_dict()
+
         {%~ for enum in spec.allEnums %}
         if isinstance(o, {{ enum.name | caseUcfirst | overrideIdentifier }}):
             return o.value
 
         {%~ endfor %}
-        return super().default(o)
+        return super().default(o)

templates/python/package/models/__init__.py.twig

@@ -0,0 +1,17 @@
+from .base_model import AppwriteModel
+{% for definition in spec.definitions %}
+from .{{ definition.name | caseSnake }} import {{ definition.name | caseUcfirst }}
+{% endfor %}
+{% for requestModel in spec.requestModels %}
+from .{{ requestModel.name | caseSnake }} import {{ requestModel.name | caseUcfirst }}
+{% endfor %}
+
+__all__ = [
+    'AppwriteModel',
+{% for definition in spec.definitions %}
+    '{{ definition.name | caseUcfirst }}',
+{% endfor %}
+{% for requestModel in spec.requestModels %}
+    '{{ requestModel.name | caseUcfirst }}',
+{% endfor %}
+]

templates/python/package/models/base_model.py.twig

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Type, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+ModelType = TypeVar('ModelType', bound='AppwriteModel')
+
+class AppwriteModel(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra='allow',
+        populate_by_name=True,
+    )
+
+    @classmethod
+    def from_dict(cls: Type[ModelType], data: Optional[Dict[str, Any]]) -> Optional[ModelType]:
+        if data is None:
+            return None
+
+        return cls.model_validate(data)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return self.model_dump(by_alias=True, mode='json')
+
+    def to_json(self) -> str:
+        return self.model_dump_json(by_alias=True)