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,247 @@ public function getParamExample(array $param, string $lang = ''): string
         };
     }
 
+    protected function getRequestModelDefinition(string $modelName, array $spec): ?array
+    {
+        foreach (($spec['requestModels'] ?? []) as $requestModel) {
+            if (($requestModel['name'] ?? '') === $modelName) {
+                return $requestModel;
+            }
+        }
+
+        return null;
+    }
+
+    protected function getDocsModelTypeName(string $modelName, string $serviceName = ''): string
+    {
+        $modelType = $this->getModelName($modelName);
+
+        if ($serviceName !== '' && $modelType === $this->getModelName($serviceName)) {
+            return $modelType . 'Model';
+        }
+
+        return $modelType;
+    }
+
+    protected function getRequestModelPropertyExample(array $property, array $spec, string $serviceName = ''): string
+    {
+        if (!empty($property['sub_schema'])) {
+            $example = $this->getRequestModelInstanceExample($property['sub_schema'], $spec, $serviceName);
+
+            return ($property['type'] ?? '') === self::TYPE_ARRAY ? '[' . $example . ']' : $example;
+        }
+
+        if (!empty($property['sub_schemas'])) {
+            $example = $this->getRequestModelInstanceExample($property['sub_schemas'][0], $spec, $serviceName);
+
+            return ($property['type'] ?? '') === self::TYPE_ARRAY ? '[' . $example . ']' : $example;
+        }
+
+        return $this->getParamExample($property);
+    }
+
+    protected function getRequestModelInstanceExample(string $modelName, array $spec, string $serviceName = ''): string
+    {
+        $requestModel = $this->getRequestModelDefinition($modelName, $spec);
+
+        if ($requestModel === null) {
+            return $this->getDocsModelTypeName($modelName, $serviceName) . '()';
+        }
+
+        $arguments = [];
+
+        foreach (($requestModel['properties'] ?? []) as $property) {
+            $arguments[] = $this->getModelFieldName($property, $requestModel['properties']) . ' = ' . $this->getRequestModelPropertyExample($property, $spec, $serviceName);
+        }
+
+        return $this->getDocsModelTypeName($modelName, $serviceName) . '(' . implode(', ', $arguments) . ')';
+    }
+
+    protected function getRequestModelExample(array $parameter, array $spec, string $serviceName = ''): string
+    {
+        $modelName = $parameter['model'] ?? (($parameter['array'] ?? [])['model'] ?? null);
+
+        if (empty($modelName)) {
+            return $this->getParamExample($parameter);
+        }
+
+        $example = $this->getRequestModelInstanceExample($modelName, $spec, $serviceName);
+
+        if (($parameter['type'] ?? '') === self::TYPE_ARRAY) {
+            return '[' . $example . ']';
+        }
+
+        return $example;
+    }
+
+    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
+    {
+        $wrapNullable = function (string $type) use ($property): string {
+            if ($property['nullable'] ?? false) {
+                return 'Optional[' . $type . ']';
+            }
+
+            return $type;
+        };
+
+        if (!empty($property['sub_schemas'])) {
+            $unionType = $this->getUnionType(array_map(
+                fn($schema) => $this->getModelName($schema),
+                $property['sub_schemas']
+            ));
+
+            return $wrapNullable(($property['type'] ?? '') === self::TYPE_ARRAY
+                ? 'List[' . $unionType . ']'
+                : $unionType);
+        }
+
+        if (!empty($property['sub_schema'])) {
+            $modelType = $this->getModelName($property['sub_schema']);
+
+            return $wrapNullable(($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 $wrapNullable('List[' . $enumType . ']');
+        }
+
+        if (!empty($property['enum'])) {
+            $enumType = $this->getModelName($property['enumName'] ?? $property['x-enum-name'] ?? (($ownerName ?: 'Model') . ucfirst($property['name'] ?? 'Value')));
+
+            return $wrapNullable(($property['type'] ?? '') === self::TYPE_ARRAY
+                ? 'List[' . $enumType . ']'
+                : $enumType);
+        }
+
+        if (($property['type'] ?? '') === self::TYPE_OBJECT) {
+            return $wrapNullable('Dict[str, Any]');
+        }
+
+        return $this->getTypeName(array_merge($property, [
+            'required' => true,
+            'nullable' => $property['nullable'] ?? false,
+        ]));
+    }
+
+    protected function getServiceModelTypeName(string $modelName, string $serviceName): string
+    {
+        $modelType = $this->getModelName($modelName);
+
+        if ($modelType === $this->getModelName($serviceName)) {
+            return $modelType . 'Model';
+        }
+
+        return $modelType;
+    }
+
+    protected function getServicePropertyType(array $parameter, string $serviceName): string
+    {
+        if (!empty($parameter['array']['model'])) {
+            $typeName = 'List[' . $this->getServiceModelTypeName($parameter['array']['model'], $serviceName) . ']';
+        } elseif (!empty($parameter['model'])) {
+            $modelType = $this->getServiceModelTypeName($parameter['model'], $serviceName);
+            $typeName = ($parameter['type'] ?? '') === self::TYPE_ARRAY ? 'List[' . $modelType . ']' : $modelType;
+        } else {
+            return $this->getTypeName($parameter);
+        }
+
+        if (!($parameter['required'] ?? true) || ($parameter['nullable'] ?? false)) {
+            return 'Optional[' . $typeName . ']';
+        }
+
+        return $typeName;
+    }
+
+    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 +680,18 @@ public function getFilters(): array
             new TwigFilter('getPropertyType', function ($value, $method = []) {
                 return $this->getTypeName($value, $method);
             }),
+            new TwigFilter('getServicePropertyType', function (array $value, string $serviceName) {
+                return $this->getServicePropertyType($value, $serviceName);
+            }),
+            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}";
@@ -473,6 +746,9 @@ public function getFilters(): array
                 $value = ($example !== null && $example !== '') ? $example : $enumValues[0];
                 return $enumName . '.' . $resolveKey($value);
             }),
+            new TwigFilter('requestModelExample', function (array $parameter, array $spec, string $serviceName = '') {
+                return $this->getRequestModelExample($parameter, $spec, $serviceName);
+            }),
         ];
     }
 }

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 %}