geniespec 0.1.2.dev4__tar.gz → 0.1.2.dev6__tar.gz

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geniespec
-Version: 0.1.2.dev4
+Version: 0.1.2.dev6
 Summary: Generate API code from an api.yaml spec
 License-Expression: MIT
 Requires-Dist: jinja2>=3.1.6
@@ -68,6 +68,8 @@ resources:
 
 Fields use it like any other type (`type: ViewContent`, also inside `List` and `Mapping`). `python-server` generates a `ViewContentV1` pydantic discriminated union in `resources`; `typescript-client` generates a `ViewContentV1` union type and a `viewContentV1FromObject` function that builds the member class named by the discriminator (and throws for unknown values).
 
+`type: Uuid` is a string that must be a valid UUID. It works anywhere `String` does, including as a primary attribute in paths. `python-server` types it as `uuid.UUID`, so pydantic rejects other strings with a 400, internal methods get `uuid.UUID` objects and responses write them in the standard lowercase hyphenated form; `typescript-client` types it as `string`.
+
 ## Rate limits
 
 Name rate limits at the top level, then pick one per transition with `rateLimit`. `defaultRateLimit` applies to every transition that doesn't set one, and `rateLimit: none` turns it off for a transition, the same way `defaultAuthentication` and `authentication` work:
@@ -91,6 +93,30 @@ transitions:
 
 A rate limit needs at least one of `perMinute`, `perFiveMinutes`, `perHour` and `perDay`. `keyBy` is `user` (the default) or `ip`. Requests over any window are rejected with a 429. Limits keyed by `user` count per authenticated user, so a transition using one needs `authentication`. `python-server` writes each rate limit as a `RATE_LIMIT_<NAME>` kiba-core `RateLimitConfig` and passes it to `route`; keying by `ip` needs kiba-core's `OriginIpMiddleware`. `typescript-client` ignores rate limits.
 
+## API docs
+
+Transitions can set `operationId`, `summary`, `description`, `tags` and `extensions`, and attributes, request fields and response fields can set a `description`:
+
+```yaml
+resources:
+  - singleName: Member
+    collectionName: Members
+    attributes:
+      - name: member-id
+        type: Uuid
+        isPrimary: true
+        description: The member's id.
+    transitions:
+      - action: GET
+        operationId: getMember
+        summary: Get a member
+        description: Returns one member.
+        tags: [Members]
+        extensions: {deprecated: true}
+```
+
+`python-server` passes the transition fields to kiba-core's `route`, whose `OpenApiSchemaGenerator` documents every route with an `operationId` (and skips the rest); `extensions` reach `OpenApiExtension`s as `metadata['extensions']`. Field descriptions become pydantic `Field(description=...)`, so they show up in the request and response schemas. Each `operationId` must be unique, so a transition that generates more than one route (for example `GET` on a resource with unique attributes) can't set one. `typescript-client` ignores these fields.
+
 # Development
 
 ```

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/README.md

@@ -54,6 +54,8 @@ resources:
 
 Fields use it like any other type (`type: ViewContent`, also inside `List` and `Mapping`). `python-server` generates a `ViewContentV1` pydantic discriminated union in `resources`; `typescript-client` generates a `ViewContentV1` union type and a `viewContentV1FromObject` function that builds the member class named by the discriminator (and throws for unknown values).
 
+`type: Uuid` is a string that must be a valid UUID. It works anywhere `String` does, including as a primary attribute in paths. `python-server` types it as `uuid.UUID`, so pydantic rejects other strings with a 400, internal methods get `uuid.UUID` objects and responses write them in the standard lowercase hyphenated form; `typescript-client` types it as `string`.
+
 ## Rate limits
 
 Name rate limits at the top level, then pick one per transition with `rateLimit`. `defaultRateLimit` applies to every transition that doesn't set one, and `rateLimit: none` turns it off for a transition, the same way `defaultAuthentication` and `authentication` work:
@@ -77,6 +79,30 @@ transitions:
 
 A rate limit needs at least one of `perMinute`, `perFiveMinutes`, `perHour` and `perDay`. `keyBy` is `user` (the default) or `ip`. Requests over any window are rejected with a 429. Limits keyed by `user` count per authenticated user, so a transition using one needs `authentication`. `python-server` writes each rate limit as a `RATE_LIMIT_<NAME>` kiba-core `RateLimitConfig` and passes it to `route`; keying by `ip` needs kiba-core's `OriginIpMiddleware`. `typescript-client` ignores rate limits.
 
+## API docs
+
+Transitions can set `operationId`, `summary`, `description`, `tags` and `extensions`, and attributes, request fields and response fields can set a `description`:
+
+```yaml
+resources:
+  - singleName: Member
+    collectionName: Members
+    attributes:
+      - name: member-id
+        type: Uuid
+        isPrimary: true
+        description: The member's id.
+    transitions:
+      - action: GET
+        operationId: getMember
+        summary: Get a member
+        description: Returns one member.
+        tags: [Members]
+        extensions: {deprecated: true}
+```
+
+`python-server` passes the transition fields to kiba-core's `route`, whose `OpenApiSchemaGenerator` documents every route with an `operationId` (and skips the rest); `extensions` reach `OpenApiExtension`s as `metadata['extensions']`. Field descriptions become pydantic `Field(description=...)`, so they show up in the request and response schemas. Each `operationId` must be unique, so a transition that generates more than one route (for example `GET` on a resource with unique attributes) can't set one. `typescript-client` ignores these fields.
+
 # Development
 
 ```

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "geniespec"
-version = "0.1.2.dev4"
+version = "0.1.2.dev6"
 description = "Generate API code from an api.yaml spec"
 readme = "README.md"
 license = "MIT"

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "geniespec"
-version = "0.1.2.dev4"
+version = "0.1.2.dev6"
 description = "Generate API code from an api.yaml spec"
 readme = "README.md"
 license = "MIT"

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/api_schema.yaml

@@ -48,7 +48,7 @@ properties:
     type:
       - "null"
       - string
-    pattern: '^[a-z][a-z0-9-]*$'
+    pattern: '^[a-z][a-z0-9_-]*$'
   rateLimits:
     type: array
     items:
@@ -158,6 +158,8 @@ definitions:
         type: boolean
       isDeprecated:
         type: boolean
+      description:
+        type: string
       defaultValue:
         type:
           - string
@@ -230,7 +232,7 @@ definitions:
         type:
           - "null"
           - string
-        pattern: '^[a-z][a-z0-9-]*$'
+        pattern: '^[a-z][a-z0-9_-]*$'
       rateLimit:
         type:
           - "null"
@@ -242,6 +244,19 @@ definitions:
           - json
           - stream
           - redirect
+      operationId:
+        type: string
+        pattern: '^[A-Za-z][A-Za-z0-9_]*$'
+      summary:
+        type: string
+      description:
+        type: string
+      tags:
+        type: array
+        items:
+          type: string
+      extensions:
+        type: object
   Transition:
     type: object
     additionalProperties: false
@@ -266,7 +281,7 @@ definitions:
         type:
           - "null"
           - string
-        pattern: '^[a-z][a-z0-9-]*$'
+        pattern: '^[a-z][a-z0-9_-]*$'
       rateLimit:
         type:
           - "null"
@@ -285,6 +300,19 @@ definitions:
           - collection
       isIndirectAction:
         type: boolean
+      operationId:
+        type: string
+        pattern: '^[A-Za-z][A-Za-z0-9_]*$'
+      summary:
+        type: string
+      description:
+        type: string
+      tags:
+        type: array
+        items:
+          type: string
+      extensions:
+        type: object
   RootTransition:
     type: object
     allOf:
@@ -328,6 +356,8 @@ definitions:
           - 'null'
       isDeprecated:
         type: boolean
+      description:
+        type: string
       maxValue:
         type:
           - string
@@ -374,6 +404,8 @@ definitions:
         type: boolean
       isList:
         type: boolean
+      description:
+        type: string
   Exception:
     type: object
     additionalProperties: false

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/genie.py

@@ -199,6 +199,7 @@ class Renderer:
             isRequired=requestField.isRequired,
             isDeprecated=requestField.isDeprecated,
             source=requestField.source,
+            description=requestField.description,
         )
 
     def _response_field_to_renderable_field(self, responseField: ResponseField, knownTypeNames: dict[str, str]) -> RenderableField:
@@ -214,6 +215,7 @@ class Renderer:
                 mappingValueTypes=responseField.mappingValueTypes,
                 enumValues=responseField.enumValues,
             ),
+            description=responseField.description,
         )
 
     def _attribute_to_renderable_attribute(self, attribute: Attribute, knownTypeNames: dict[str, str], isNullable: bool | None = None) -> RenderableAttribute:
@@ -236,6 +238,7 @@ class Renderer:
             isAccessibleIndependently=attribute.isAccessibleIndependently,
             isSettable=attribute.isSettable,
             isNullable=attribute.isNullable,
+            description=attribute.description,
         )
 
     def _attribute_to_renderable_parameter(self, attribute: Attribute, isRequired: bool, knownTypeNames: dict[str, str], shouldUseDefault: bool = True) -> RenderableParameter:
@@ -254,8 +257,13 @@ class Renderer:
             defaultValue=attribute.defaultValue if shouldUseDefault else None,
             isRequired=isRequired,
             isDeprecated=attribute.isDeprecated,
+            description=attribute.description,
         )
 
+    @staticmethod
+    def _operation_documentation(transition: BaseTransition) -> dict[str, object]:
+        return {'operationId': transition.operationId, 'summary': transition.summary, 'description': transition.description, 'tags': transition.tags, 'extensions': transition.extensions}
+
     @staticmethod
     def _resource_full_name(resource: Resource, name: str) -> str:
         return f'{resource.parentResource or ""}{name}'
@@ -458,7 +466,7 @@ class Renderer:
                 knownTypeNames=knownTypeNames,
                 defaultAuthentication=api.defaultAuthentication,
                 defaultRateLimit=api.defaultRateLimit,
-            )
+            ).model_copy(update=self._operation_documentation(transition=transition))
             for transition in api.transitions
         ]
         renderableExceptions = [
@@ -564,6 +572,7 @@ class Renderer:
                     for endpoint in customEndpoints:
                         customEndpoint = RenderableEndpoint(components=[*endpoint.components, ActionEndpointComponent(actionName=RenderableString.from_separated_string(string=transition.action, separator='-'))])
                         renderableApi.operations.append(self._action_operation(transition=transition, endpoint=customEndpoint, knownTypeNames=knownTypeNames, defaultAuthentication=api.defaultAuthentication, defaultRateLimit=api.defaultRateLimit, isIndirectAction=transition.isIndirectAction))
+                renderableApi.operations[operationCount:] = [operation.model_copy(update=self._operation_documentation(transition=transition)) for operation in renderableApi.operations[operationCount:]]
                 if len(renderableApi.operations) == operationCount:
                     uncoveredTransitions.append(f'{renderableResource.singleName.pascalCaseString} {transition.action}')
         if uncoveredTransitions:
@@ -573,6 +582,8 @@ class Renderer:
         rateLimitsByName = {rateLimit.name.kebabCaseString: rateLimit for rateLimit in renderableApi.rateLimits}
         operationErrors = [error for operation in renderableApi.operations for error in self._operation_errors(operation=operation, rateLimitsByName=rateLimitsByName)]
         operationErrors += self._file_errors(resources=renderableResources, exceptions=renderableExceptions)
+        operationIdCounts = collections.Counter(operation.operationId for operation in renderableApi.operations if operation.operationId is not None)
+        operationErrors += [f'Duplicate operationId: {operationId}' for operationId, count in operationIdCounts.items() if count > 1]
         if operationErrors:
             raise SemanticValidationException(message='\n'.join(operationErrors))
         renderableApi.resources.extend(renderableResources)

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/languages.py

@@ -1,6 +1,7 @@
 import collections
 import keyword
 import re
+import typing
 
 from core.exceptions import KibaException
 
@@ -8,6 +9,7 @@ from geniespec.renderable_types import ActionEndpointComponent
 from geniespec.renderable_types import AttributeEndpointComponent
 from geniespec.renderable_types import MappingRenderableType
 from geniespec.renderable_types import RenderableApi
+from geniespec.renderable_types import RenderableAttribute
 from geniespec.renderable_types import RenderableEndpointComponent
 from geniespec.renderable_types import RenderableEnum
 from geniespec.renderable_types import RenderableException
@@ -73,6 +75,9 @@ class BaseLanguageDefinition:
     def string_type(self, isNullable: bool) -> str:
         raise NotImplementedError
 
+    def uuid_type(self, isNullable: bool) -> str:
+        raise NotImplementedError
+
     def enum_type(self, isNullable: bool, renderableType: RenderableType, apiVersion: Version, isLocalReference: bool) -> str:
         raise NotImplementedError
 
@@ -110,6 +115,8 @@ class BaseLanguageDefinition:
             return self.double_type(isNullable=isNullable)
         if yamlType == PrimitiveTypes.STRING:
             return self.string_type(isNullable=isNullable)
+        if yamlType == PrimitiveTypes.UUID:
+            return self.uuid_type(isNullable=isNullable)
         if yamlType == PrimitiveTypes.BOOLEAN:
             return self.boolean_type(isNullable=isNullable)
         if yamlType == PrimitiveTypes.DATETIME:
@@ -227,9 +234,9 @@ class BaseLanguageDefinition:
                 return output
             if component.attribute.isUnique and not component.attribute.isPrimary:
                 output.append(self.kebab_name(name=component.attribute.name))
-            if component.attribute.fieldType.rawType not in (PrimitiveTypes.INTEGER, PrimitiveTypes.LONG_INTEGER, PrimitiveTypes.STRING):
-                raise KibaException(message=f'ResourceEndpointComponent created with an invalid attribute type of {component.attribute.fieldType}. Valid types are: integer, long integer and string.')
-            output.append(self.path_parameter_segment(parameterName=self.identifier(name=component.attribute.name), isInteger=component.attribute.fieldType.rawType != PrimitiveTypes.STRING))
+            if component.attribute.fieldType.rawType not in (PrimitiveTypes.INTEGER, PrimitiveTypes.LONG_INTEGER, PrimitiveTypes.STRING, PrimitiveTypes.UUID):
+                raise KibaException(message=f'ResourceEndpointComponent created with an invalid attribute type of {component.attribute.fieldType}. Valid types are: integer, long integer, string and uuid.')
+            output.append(self.path_parameter_segment(parameterName=self.identifier(name=component.attribute.name), isInteger=component.attribute.fieldType.rawType in (PrimitiveTypes.INTEGER, PrimitiveTypes.LONG_INTEGER)))
             return output
         raise KibaException(message=f'Unsupported endpoint component: {type(component)}')
 
@@ -343,6 +350,9 @@ class PythonLanguageDefinition(BaseLanguageDefinition):
     def string_type(self, isNullable: bool) -> str:
         return 'str | None' if isNullable else 'str'
 
+    def uuid_type(self, isNullable: bool) -> str:
+        return 'uuid.UUID | None' if isNullable else 'uuid.UUID'
+
     def enum_type(self, isNullable: bool, renderableType: RenderableType, apiVersion: Version, isLocalReference: bool) -> str:
         if renderableType.className is None:
             typeName = self.enum_literal(values=renderableType.enumValues)
@@ -397,6 +407,43 @@ class PythonLanguageDefinition(BaseLanguageDefinition):
     def requires_optional_field_default(self, api: RenderableApi) -> bool:
         return any(not self.is_undefined_parameter(operation=operation, parameter=parameter) and not parameter.isRequired and not parameter.fieldType.isNullable for operation in api.operations for parameter in self.request_parameters(operation=operation))
 
+    def endpoints_require_field(self, api: RenderableApi) -> bool:
+        hasRequestDescriptions = any(parameter.description is not None for operation in api.operations for parameter in self.request_parameters(operation=operation))
+        hasResponseDescriptions = any(field.description is not None for operation in api.operations for field in operation.responseFields or [])
+        return self.requires_optional_field_default(api=api) or hasRequestDescriptions or hasResponseDescriptions
+
+    @staticmethod
+    def resources_require_field(api: RenderableApi) -> bool:
+        return any(attribute.description is not None for resource in api.resources for attribute in resource.attributes)
+
+    @staticmethod
+    def _field_default(default: str | None, description: str | None, fieldFunction: str = 'Field', shouldUseField: bool = False) -> str:
+        if description is None and not shouldUseField:
+            return '' if default is None else f' = {default}'
+        arguments = ([] if default is None else [f'default={default}']) + ([] if description is None else [f'description={description!r}'])
+        return f' = {fieldFunction}({", ".join(arguments)})'
+
+    def request_field_declaration(self, operation: RenderableOperation, parameter: RenderableParameter, apiVersion: Version) -> str:
+        typeName = self.type(renderableType=parameter.fieldType, apiVersion=apiVersion)
+        if self.is_undefined_parameter(operation=operation, parameter=parameter):
+            return f'UpdateValue[{typeName}]{self._field_default(default="UNDEFINED", description=parameter.description)}'
+        if parameter.isRequired:
+            return f'{typeName}{self._field_default(default=None, description=parameter.description)}'
+        if parameter.fieldType.isNullable:
+            return f'{typeName}{self._field_default(default="None", description=parameter.description)}'
+        return f'{typeName}{self._field_default(default=f"typing.cast({typeName}, None)", description=parameter.description, shouldUseField=True)}'
+
+    def response_field_declaration(self, field: RenderableField, apiVersion: Version) -> str:
+        return f'{self.type(renderableType=field.fieldType, apiVersion=apiVersion)}{self._field_default(default=None, description=field.description)}'
+
+    def attribute_declaration(self, attribute: RenderableAttribute, apiVersion: Version) -> str:
+        return f'{self.type(renderableType=attribute.fieldType, apiVersion=apiVersion, isLocalReference=True)}{self._field_default(default=None, description=attribute.description, fieldFunction="pydantic.Field")}'
+
+    @staticmethod
+    def route_documentation_arguments(operation: RenderableOperation) -> str:
+        arguments = {'operationId': operation.operationId, 'summary': operation.summary, 'description': operation.description, 'tags': operation.tags or None, 'extensions': operation.extensions or None}
+        return ''.join(f', {name}={value!r}' for name, value in arguments.items() if value is not None)
+
     def requires_streaming(self, api: RenderableApi) -> bool:
         return any(self.is_streaming(operation=operation) for operation in api.operations)
 
@@ -418,13 +465,32 @@ class PythonLanguageDefinition(BaseLanguageDefinition):
         return parameterName if self.requires_parameter_preprocessing(operation=operation, parameter=parameter) else f'request.data.{parameterName}'
 
     @staticmethod
-    def _contains_json(renderableType: RenderableType) -> bool:
+    def _type_parts(renderableType: RenderableType) -> list[RenderableType]:
         if isinstance(renderableType, MappingRenderableType):
-            return PythonLanguageDefinition._contains_json(renderableType=renderableType.keyType) or PythonLanguageDefinition._contains_json(renderableType=renderableType.valueType)
-        return renderableType.rawType == PrimitiveTypes.JSON
-
-    def resources_require_json(self, api: RenderableApi) -> bool:
-        return any(self._contains_json(renderableType=attribute.fieldType) for resource in api.resources for attribute in resource.attributes)
+            return [renderableType, *PythonLanguageDefinition._type_parts(renderableType=renderableType.keyType), *PythonLanguageDefinition._type_parts(renderableType=renderableType.valueType)]
+        return [renderableType]
+
+    def _module_field_types(self, api: RenderableApi, module: str) -> list[RenderableType]:
+        responseFieldTypes = [field.fieldType for operation in api.operations for field in operation.responseFields or []]
+        if module == 'resources':
+            return [attribute.fieldType for resource in api.resources for attribute in resource.attributes]
+        if module == 'endpoints':
+            return [parameter.fieldType for operation in api.operations for parameter in self.request_parameters(operation=operation)] + responseFieldTypes
+        if module == 'internal':
+            return [parameter.fieldType for operation in api.operations for parameter in operation.parameters] + responseFieldTypes
+        if module == 'exceptions':
+            return [field.fieldType for exception in api.exceptions for field in exception.fields]
+        raise KibaException(message=f'Unknown module: {module}')
+
+    def module_requires(self, api: RenderableApi, module: str, requirement: str) -> bool:
+        predicates: dict[str, typing.Callable[[RenderableType], bool]] = {
+            'collections': lambda part: part.isList or isinstance(part, MappingRenderableType),
+            'datetime': lambda part: part.rawType in (PrimitiveTypes.DATETIME, PrimitiveTypes.DATE),
+            'json': lambda part: part.rawType == PrimitiveTypes.JSON,
+            'resources': lambda part: part.className is not None,
+            'uuid': lambda part: part.rawType == PrimitiveTypes.UUID,
+        }
+        return any(predicates[requirement](part) for fieldType in self._module_field_types(api=api, module=module) for part in self._type_parts(renderableType=fieldType))
 
     def resources_require_typing(self, api: RenderableApi) -> bool:
         return len(api.enums) > 0 or len(api.oneOfs) > 0 or any(self.is_inline_enum(renderableType=attribute.fieldType) for resource in api.resources for attribute in resource.attributes)
@@ -439,13 +505,6 @@ class PythonLanguageDefinition(BaseLanguageDefinition):
     def requires_uploaded_file(self, api: RenderableApi) -> bool:
         return any(self.is_file_operation(operation=operation) for operation in api.operations)
 
-    def operations_require_json(self, api: RenderableApi) -> bool:
-        fieldTypes = [parameter.fieldType for operation in api.operations for parameter in operation.parameters] + [field.fieldType for operation in api.operations for field in operation.responseFields or []]
-        return any(self._contains_json(renderableType=fieldType) for fieldType in fieldTypes)
-
-    def exceptions_require_json(self, api: RenderableApi) -> bool:
-        return any(self._contains_json(renderableType=field.fieldType) for exception in api.exceptions for field in exception.fields)
-
     def route_ordered_operations(self, api: RenderableApi) -> list[RenderableOperation]:
         return sorted(api.operations, key=lambda operation: tuple(segment.startswith('{') for segment in self.endpoint(operation=operation).split('/')))
 
@@ -562,6 +621,9 @@ class TypeScriptLanguageDefinition(BaseLanguageDefinition):
     def string_type(self, isNullable: bool) -> str:
         return self._nullable(typeName='string', isNullable=isNullable)
 
+    def uuid_type(self, isNullable: bool) -> str:
+        return self._nullable(typeName='string', isNullable=isNullable)
+
     def enum_type(self, isNullable: bool, renderableType: RenderableType, apiVersion: Version, isLocalReference: bool) -> str:
         if renderableType.className is None:
             return self._nullable(typeName=f'({self.enum_union(values=renderableType.enumValues)})', isNullable=isNullable)
@@ -649,6 +711,12 @@ class TypeScriptLanguageDefinition(BaseLanguageDefinition):
     def requires_request_data(self, api: RenderableApi) -> bool:
         return any(self.body_parameters(operation=operation) and not self.is_file_operation(operation=operation) for operation in self.client_operations(api=api))
 
+    def requires_rest_method(self, api: RenderableApi) -> bool:
+        return any(not self.is_file_operation(operation=operation) for operation in self.client_operations(api=api))
+
+    def has_endpoint_classes(self, api: RenderableApi) -> bool:
+        return len(self.body_parameter_types(api=api)) > 0 or len(self.response_field_types(api=api)) > 0
+
     def form_value(self, renderableType: RenderableType, value: str) -> str:
         if renderableType.rawType == RenderableRawTypes.FILE:
             return value
@@ -680,7 +748,7 @@ class TypeScriptLanguageDefinition(BaseLanguageDefinition):
             return f'{parserName if isLocalReference else f"Resources.{parserName}"}({value} as RawObject)'
         if renderableType.rawType == 'class' and renderableType.className is not None:
             return f'{self.type(renderableType=renderableType, apiVersion=apiVersion, isLocalReference=isLocalReference)}.fromObject({value} as RawObject)'
-        if renderableType.rawType == PrimitiveTypes.STRING:
+        if renderableType.rawType in (PrimitiveTypes.STRING, PrimitiveTypes.UUID):
             return f'String({value})'
         if renderableType.rawType in (PrimitiveTypes.INTEGER, PrimitiveTypes.LONG_INTEGER, PrimitiveTypes.FLOAT, PrimitiveTypes.DOUBLE):
             return f'Number({value})'

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/renderable_types.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import re
 
+import pydantic
 from core.exceptions import KibaException
 from pydantic import BaseModel
 
@@ -128,6 +129,7 @@ class RenderableField(BaseModel):
     name: RenderableString
     fieldType: RenderableType
     defaultValue: str | int | float | bool | None = None
+    description: str | None = None
 
 
 class RenderableAttribute(RenderableField):
@@ -191,7 +193,7 @@ class RenderableEndpoint(BaseModel):
     @property
     def urlParameters(self) -> list[RenderableParameter]:  # noqa: N802
         return [
-            RenderableParameter(name=component.attribute.name, fieldType=component.attribute.fieldType, isRequired=True, isDeprecated=False)
+            RenderableParameter(name=component.attribute.name, fieldType=component.attribute.fieldType, isRequired=True, isDeprecated=False, description=component.attribute.description)
             for component in self.components
             if isinstance(component, ResourceEndpointComponent) and component.attribute is not None
         ]
@@ -215,6 +217,11 @@ class RenderableOperation(BaseModel):
     rateLimit: str | None = None
     isIndirectAction: bool = False
     responseType: str = ResponseTypes.JSON
+    operationId: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    tags: list[str] = []
+    extensions: dict[str, pydantic.JsonValue] = {}
 
     @property
     def urlParameters(self) -> list[RenderableParameter]:  # noqa: N802

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/python-server/{service}/v{version}/api.py.j2

@@ -2,11 +2,12 @@
 # ruff: noqa: ARG001
 {% if target.requires_streaming(api=api) %}
 import collections.abc
-{% endif %}
-import datetime
 
+{% endif %}
+{% if api.operations %}
 from core.api.api_request import KibaApiRequest
 from core.api.route import route
+{% endif %}
 from core.api.route_auth import RouteAuthResolver
 {% if api.rateLimits %}
 from core.api.route_metadata import RateLimitConfig
@@ -14,10 +15,14 @@ from core.api.route_metadata import RateLimitConfig
 {% if target.requires_redirect(api=api) %}
 from core.exceptions import FoundRedirectException
 {% endif %}
+{% if api.operations %}
 from core.http.rest_method import RestMethod
+{% endif %}
 from starlette.routing import BaseRoute
+{% if api.operations %}
 from starlette.routing import Route
 from . import endpoints
+{% endif %}
 from .internal import {{ target.internal_class_name(api=api) }}
 {% for rateLimit in api.rateLimits %}
 {{ target.rate_limit_constant_name(name=rateLimit.name.kebabCaseString) }}: RateLimitConfig = {{ target.rate_limit_config(rateLimit=rateLimit) }}
@@ -30,7 +35,7 @@ def create_routes(internal: {{ target.internal_class_name(api=api) }}, {% if tar
 {% set rate_limit = target.route_rate_limit(operation=operation) %}
 {% set class_name = target.operation_class_name(operation=operation) %}
 {% set result_name = target.identifier(name=operation.responseFields[0].name) if operation.responseFields else 'result' %}
-    @route(requestType=endpoints.{{ class_name }}Request, responseType=endpoints.{{ class_name }}Response{% if target.is_streaming(operation=operation) %}, isStreaming=True{% endif %}{% if auth is not none %}, authResolver=authResolver, auth='{{ auth }}'{% endif %}{% if rate_limit is not none %}, rateLimit={{ target.rate_limit_constant_name(name=rate_limit) }}{% endif %})
+    @route(requestType=endpoints.{{ class_name }}Request, responseType=endpoints.{{ class_name }}Response{% if target.is_streaming(operation=operation) %}, isStreaming=True{% endif %}{% if auth is not none %}, authResolver=authResolver, auth='{{ auth }}'{% endif %}{% if rate_limit is not none %}, rateLimit={{ target.rate_limit_constant_name(name=rate_limit) }}{% endif %}{{ target.route_documentation_arguments(operation=operation) }})
     async def {{ target.operation_name(operation=operation) }}(request: KibaApiRequest[endpoints.{{ class_name }}Request]) -> {% if target.is_streaming(operation=operation) %}collections.abc.AsyncIterator[endpoints.{{ class_name }}Response]{% else %}endpoints.{{ class_name }}Response{% endif %}:
 {% for parameter in target.request_parameters(operation=operation) %}
 {% set param_name = target.identifier(name=parameter.name) %}

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/python-server/{service}/v{version}/endpoints.py.j2

@@ -1,16 +1,23 @@
 {{ autogenerated_notice }}
+{% if target.module_requires(api=api, module='endpoints', requirement='collections') %}
 import collections.abc
+{% endif %}
+{% if target.module_requires(api=api, module='endpoints', requirement='datetime') %}
 import datetime
+{% endif %}
 {% if target.requires_optional_field_default(api=api) or target.operations_require_typing(api=api) %}
 import typing
 {% endif %}
+{% if target.module_requires(api=api, module='endpoints', requirement='uuid') %}
+import uuid
+{% endif %}
 
-{% if target.operations_require_json(api=api) %}
+{% if target.module_requires(api=api, module='endpoints', requirement='json') %}
 import pydantic
 {% endif %}
-{% if target.requires_optional_field_default(api=api) %}
+{% if target.endpoints_require_field(api=api) %}
 from pydantic import BaseModel, Field
-{% else %}
+{% elif api.operations %}
 from pydantic import BaseModel
 {% endif %}
 {% if target.requires_undefined(api=api) %}
@@ -19,21 +26,23 @@ from core.util.typing_util import UNDEFINED, UpdateValue
 {% if target.requires_uploaded_file(api=api) %}
 from core.api.uploaded_file import UploadedFile
 {% endif %}
+{% if target.module_requires(api=api, module='endpoints', requirement='resources') %}
 
 from . import resources
+{% endif %}
 
 {% for operation in api.operations %}
 
 class {{ target.operation_class_name(operation=operation) }}Request(BaseModel):
 {% for parameter in target.request_parameters(operation=operation) %}
-    {{ target.identifier(name=parameter.name) }}: {% if target.is_undefined_parameter(operation=operation, parameter=parameter) %}UpdateValue[{{ target.type(renderableType=parameter.fieldType, apiVersion=api.version) }}] = UNDEFINED{% else %}{{ target.type(renderableType=parameter.fieldType, apiVersion=api.version) }}{% if not parameter.isRequired %}{% if parameter.fieldType.isNullable %} = None{% else %} = Field(default=typing.cast({{ target.type(renderableType=parameter.fieldType, apiVersion=api.version) }}, None)){% endif %}{% endif %}{% endif +%}
+    {{ target.identifier(name=parameter.name) }}: {{ target.request_field_declaration(operation=operation, parameter=parameter, apiVersion=api.version) }}
 {% else %}
     pass
 {% endfor %}
 
 class {{ target.operation_class_name(operation=operation) }}Response(BaseModel):
 {% if operation.responseFields and operation.responseFields | length > 0 %}
-    {{ target.identifier(name=operation.responseFields[0].name) }}: {{ target.type(renderableType=operation.responseFields[0].fieldType, apiVersion=api.version) }}
+    {{ target.identifier(name=operation.responseFields[0].name) }}: {{ target.response_field_declaration(field=operation.responseFields[0], apiVersion=api.version) }}
 {% else %}
     pass
 {% endif %}

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/python-server/{service}/v{version}/exceptions.py.j2

@@ -1,13 +1,25 @@
 {{ autogenerated_notice }}
 from __future__ import annotations
+{% if target.module_requires(api=api, module='exceptions', requirement='collections') %}
 import collections.abc
+{% endif %}
+{% if target.module_requires(api=api, module='exceptions', requirement='datetime') %}
+import datetime
+{% endif %}
 import typing
-{% if target.exceptions_require_json(api=api) %}
+{% if target.module_requires(api=api, module='exceptions', requirement='uuid') %}
+import uuid
+{% endif %}
+{% if target.module_requires(api=api, module='exceptions', requirement='json') %}
 import pydantic
 {% endif %}
+{% if api.exceptions %}
 from core import exceptions
 from core.util.typing_util import Json
+{% endif %}
+{% if target.module_requires(api=api, module='exceptions', requirement='resources') %}
 from . import resources
+{% endif %}
 
 
 class KibaExceptionTypedDict(typing.TypedDict):

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/python-server/{service}/v{version}/internal.py.j2

@@ -1,16 +1,25 @@
 {{ autogenerated_notice }}
 import abc
-import datetime
+{% if target.module_requires(api=api, module='internal', requirement='collections') or target.requires_streaming(api=api) %}
 import collections.abc
+{% endif %}
+{% if target.module_requires(api=api, module='internal', requirement='datetime') %}
+import datetime
+{% endif %}
 {% if target.operations_require_typing(api=api) %}
 import typing
 {% endif %}
+{% if target.module_requires(api=api, module='internal', requirement='uuid') %}
+import uuid
+{% endif %}
 
-{% if target.operations_require_json(api=api) %}
+{% if target.module_requires(api=api, module='internal', requirement='json') %}
 import pydantic
 
 {% endif %}
+{% if target.module_requires(api=api, module='internal', requirement='resources') %}
 from . import resources
+{% endif %}
 {% if target.requires_undefined(api=api) %}
 from core.util.typing_util import UNDEFINED, UpdateValue
 {% endif %}

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/python-server/{service}/v{version}/resources.py.j2

@@ -1,16 +1,25 @@
 {{ autogenerated_notice }}
 from __future__ import annotations
 
+{% if target.module_requires(api=api, module='resources', requirement='collections') %}
 import collections.abc
+{% endif %}
+{% if target.module_requires(api=api, module='resources', requirement='datetime') %}
 import datetime
+{% endif %}
 {% if target.resources_require_typing(api=api) %}
 import typing
 {% endif %}
+{% if target.module_requires(api=api, module='resources', requirement='uuid') %}
+import uuid
+{% endif %}
 
-{% if target.resources_require_json(api=api) or api.oneOfs %}
+{% if target.module_requires(api=api, module='resources', requirement='json') or api.oneOfs or target.resources_require_field(api=api) %}
 import pydantic
 {% endif %}
+{% if api.resources %}
 from pydantic import BaseModel
+{% endif %}
 
 {% for enum in api.enums %}
 {{ target.enum_class_name(enum=enum, apiVersion=api.version) }} = {{ target.enum_literal(values=enum.values) }}
@@ -25,7 +34,7 @@ class {{ target.resource_class_name(resource=resource, apiVersion=api.version) }
     pass
 {% endif %}
 {% for attribute in resource.attributes %}
-    {{ target.identifier(name=attribute.name) }}: {{ target.type(renderableType=attribute.fieldType, apiVersion=api.version, isLocalReference=True) }}
+    {{ target.identifier(name=attribute.name) }}: {{ target.attribute_declaration(attribute=attribute, apiVersion=api.version) }}
 {% endfor %}
 
 {% endfor %}

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/typescript-client/{service}/v{version}/client.ts.j2

@@ -1,7 +1,13 @@
 {{ autogenerated_notice }}
+{% if target.requires_rest_method(api=api) %}
 import { RestMethod, ServiceClient } from '@kibalabs/core';
+{% else %}
+import { ServiceClient } from '@kibalabs/core';
+{% endif %}
+{% if target.has_endpoint_classes(api=api) %}
 
 import * as Endpoints from './endpoints';
+{% endif %}
 {% if target.references_resources(renderableTypes=target.response_field_types(api=api)) %}
 import * as Resources from './resources';
 {% endif %}

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/typescript-client/{service}/v{version}/endpoints.ts.j2

@@ -4,10 +4,12 @@
 {% set coreImports = [] %}
 {% if target.requires_date_parsing(renderableTypes=responseTypes) %}{% set _ = coreImports.append('dateFromString') %}{% endif %}
 {% if target.requires_date_parsing(renderableTypes=bodyTypes) %}{% set _ = coreImports.append('dateToString') %}{% endif %}
-{% set _ = coreImports.append('RawObject') %}
+{% if target.requires_request_data(api=api) or responseTypes %}{% set _ = coreImports.append('RawObject') %}{% endif %}
 {% if target.requires_request_data(api=api) %}{% set _ = coreImports.append('RequestData') %}{% endif %}
 {% if responseTypes %}{% set _ = coreImports.append('ResponseData') %}{% endif %}
+{% if coreImports %}
 import { {{ coreImports | join(', ') }} } from '@kibalabs/core';
+{% endif %}
 {% if target.references_resources(renderableTypes=responseTypes + bodyTypes) %}
 
 import * as Resources from './resources';

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/typescript-client/{service}/v{version}/index.ts.j2

@@ -1,4 +1,6 @@
 {{ autogenerated_notice }}
 export * from './client';
+{% if target.has_endpoint_classes(api=api) %}
 export * from './endpoints';
+{% endif %}
 export * from './resources';

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/templates/typescript-client/{service}/v{version}/resources.ts.j2

@@ -1,8 +1,9 @@
 {{ autogenerated_notice }}
-{% if target.requires_date_parsing(renderableTypes=target.resource_field_types(api=api)) %}
-import { dateFromString, dateToString, RawObject } from '@kibalabs/core';
-{% else %}
-import { RawObject } from '@kibalabs/core';
+{% set coreImports = [] %}
+{% if target.requires_date_parsing(renderableTypes=target.resource_field_types(api=api)) %}{% set _ = coreImports.extend(['dateFromString', 'dateToString']) %}{% endif %}
+{% if api.resources or api.oneOfs %}{% set _ = coreImports.append('RawObject') %}{% endif %}
+{% if coreImports %}
+import { {{ coreImports | join(', ') }} } from '@kibalabs/core';
 {% endif %}
 
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };

{geniespec-0.1.2.dev4 → geniespec-0.1.2.dev6}/src/geniespec/types.py

@@ -12,11 +12,12 @@ class PrimitiveTypes:
     FLOAT = 'Float'
     DOUBLE = 'Double'
     STRING = 'String'
+    UUID = 'Uuid'
     BOOLEAN = 'Boolean'
     DATETIME = 'Datetime'
     DATE = 'Date'
     JSON = 'Json'
-    ALL: ClassVar[list[str]] = [LONG_INTEGER, INTEGER, FLOAT, DOUBLE, STRING, BOOLEAN, DATETIME, DATE, JSON]
+    ALL: ClassVar[list[str]] = [LONG_INTEGER, INTEGER, FLOAT, DOUBLE, STRING, UUID, BOOLEAN, DATETIME, DATE, JSON]
 
 
 class FieldSources:
@@ -84,6 +85,7 @@ class Attribute(BaseModel):
     isSettable: bool = False
     isAccessibleIndependently: bool = False
     defaultValue: str | int | float | bool | None = None
+    description: str | None = None
 
 
 class ResponseField(BaseModel):
@@ -95,6 +97,7 @@ class ResponseField(BaseModel):
     enumValues: list[str] = []
     isNullable: bool = False
     isList: bool = False
+    description: str | None = None
 
 
 class RequestField(BaseModel):
@@ -110,6 +113,7 @@ class RequestField(BaseModel):
     maxValue: str | int | float | None = None
     minValue: str | int | float | None = None
     source: str = FieldSources.REQUEST
+    description: str | None = None
 
 
 class BaseTransition(BaseModel):
@@ -120,6 +124,11 @@ class BaseTransition(BaseModel):
     authentication: str | None = None
     rateLimit: str | None = None
     responseType: str = ResponseTypes.JSON
+    operationId: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    tags: list[str] = []
+    extensions: dict[str, pydantic.JsonValue] = {}
 
 
 class Transition(BaseTransition):