geniespec 0.1.1.dev7__tar.gz → 0.1.1.dev8__tar.gz

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geniespec
-Version: 0.1.1.dev7
+Version: 0.1.1.dev8
 Summary: Generate API code from an api.yaml spec
 License-Expression: MIT
 Requires-Dist: jinja2>=3.1.6
@@ -27,7 +27,7 @@ geniespec watch --spec api.yaml --target <python-server | typescript-client> [--
 - `watch` builds, then rebuilds whenever the spec changes. If the spec is invalid it logs the error and keeps the previous output. Given a command after `--`, it runs it once the first build is done, keeps rebuilding while it runs, exits with its exit code and stops it when watch itself is stopped, e.g. `geniespec watch --spec api.yaml --target python-server -- uvicorn app:app --reload`.
 - The bundled templates are examples of a kibalabs-style target.
 
-## Enums and files
+## Enums, oneOfs and files
 
 Enums are string values limited to a list. Name them at the top level to reuse them, or give a field its own:
 
@@ -50,6 +50,24 @@ resources:
 
 `type: File` request fields upload a file. They are only allowed on POST transitions, and the transition's other fields must be single primitive or enum values, as the request is sent as a multipart form. Internal methods receive kiba-core's `UploadedFile` (`filename`, `contentType`, `content`); clients pass a `File`.
 
+A oneOf is a value that is one of several resources, told apart by a discriminator attribute. Each member resource needs that attribute as a non-nullable enum with a single value:
+
+```yaml
+oneOfs:
+  - name: ViewContent
+    discriminator: kind
+    types: [ChartContent, TableContent]
+resources:
+  - singleName: ChartContent
+    collectionName: ChartContents
+    attributes:
+      - name: kind
+        type: Enum
+        enumValues: [chart]
+```
+
+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).
+
 # Development
 
 ```
@@ -70,8 +88,6 @@ Merges to `main` publish a dev version to PyPI. To release, bump `version` in `p
 
 ## Typing of params and fields in general
 
-OneOf not supported yet
-
 I think we need to create an object for Type. what would it look like?
 
 

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/README.md

@@ -13,7 +13,7 @@ geniespec watch --spec api.yaml --target <python-server | typescript-client> [--
 - `watch` builds, then rebuilds whenever the spec changes. If the spec is invalid it logs the error and keeps the previous output. Given a command after `--`, it runs it once the first build is done, keeps rebuilding while it runs, exits with its exit code and stops it when watch itself is stopped, e.g. `geniespec watch --spec api.yaml --target python-server -- uvicorn app:app --reload`.
 - The bundled templates are examples of a kibalabs-style target.
 
-## Enums and files
+## Enums, oneOfs and files
 
 Enums are string values limited to a list. Name them at the top level to reuse them, or give a field its own:
 
@@ -36,6 +36,24 @@ resources:
 
 `type: File` request fields upload a file. They are only allowed on POST transitions, and the transition's other fields must be single primitive or enum values, as the request is sent as a multipart form. Internal methods receive kiba-core's `UploadedFile` (`filename`, `contentType`, `content`); clients pass a `File`.
 
+A oneOf is a value that is one of several resources, told apart by a discriminator attribute. Each member resource needs that attribute as a non-nullable enum with a single value:
+
+```yaml
+oneOfs:
+  - name: ViewContent
+    discriminator: kind
+    types: [ChartContent, TableContent]
+resources:
+  - singleName: ChartContent
+    collectionName: ChartContents
+    attributes:
+      - name: kind
+        type: Enum
+        enumValues: [chart]
+```
+
+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).
+
 # Development
 
 ```
@@ -56,8 +74,6 @@ Merges to `main` publish a dev version to PyPI. To release, bump `version` in `p
 
 ## Typing of params and fields in general
 
-OneOf not supported yet
-
 I think we need to create an object for Type. what would it look like?
 
 

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/pyproject.toml

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

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/pyproject.toml.orig

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

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/src/geniespec/api_schema.yaml

@@ -36,6 +36,10 @@ properties:
     type: array
     items:
       $ref: '#/definitions/Enum'
+  oneOfs:
+    type: array
+    items:
+      $ref: '#/definitions/OneOf'
   imports:
     type: array
     items:
@@ -65,6 +69,27 @@ definitions:
         pattern: '^[A-Z][A-Za-z]*$'
       values:
         $ref: '#/definitions/EnumValues'
+  OneOf:
+    type: object
+    additionalProperties: false
+    required:
+      - name
+      - discriminator
+      - types
+    properties:
+      name:
+        type: string
+        pattern: '^[A-Z][A-Za-z]*$'
+      discriminator:
+        type: string
+        pattern: '^[a-z][A-Za-z0-9-]*$'
+      types:
+        type: array
+        minItems: 2
+        uniqueItems: true
+        items:
+          type: string
+          pattern: '^[A-Z][A-Za-z-]*$'
   Attribute:
     type: object
     additionalProperties: false

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/src/geniespec/genie.py

@@ -28,6 +28,8 @@ from geniespec.renderable_types import RenderableEnum
 from geniespec.renderable_types import RenderableException
 from geniespec.renderable_types import RenderableField
 from geniespec.renderable_types import RenderableMethod
+from geniespec.renderable_types import RenderableOneOf
+from geniespec.renderable_types import RenderableOneOfMember
 from geniespec.renderable_types import RenderableOperation
 from geniespec.renderable_types import RenderableParameter
 from geniespec.renderable_types import RenderableRawTypes
@@ -36,6 +38,8 @@ from geniespec.renderable_types import RenderableString
 from geniespec.renderable_types import RenderableType
 from geniespec.renderable_types import ResourceEndpointComponent
 from geniespec.renderable_types import SingleResourceEndpointComponent
+from geniespec.types import ApiEnum
+from geniespec.types import ApiOneOf
 from geniespec.types import Attribute
 from geniespec.types import BaseTransition
 from geniespec.types import ComplexTypes
@@ -378,13 +382,44 @@ class Renderer:
         errors += [f'Field {field.name.snakeCaseString} of {exception.name.pascalCaseString} cannot be a File' for exception in exceptions for field in exception.fields if field.fieldType.rawType == RenderableRawTypes.FILE]
         return errors
 
+    @staticmethod
+    def _one_of_members(oneOf: ApiOneOf, resourcesByName: dict[str, Resource], enumsByName: dict[str, ApiEnum]) -> tuple[list[RenderableOneOfMember], list[str]]:
+        members: list[RenderableOneOfMember] = []
+        errors: list[str] = []
+        for typeName in oneOf.types:
+            resource = resourcesByName.get(typeName)
+            if resource is None:
+                errors.append(f'Unknown resource {typeName} in {oneOf.name}')
+                continue
+            attribute = next((attribute for attribute in resource.attributes if attribute.name == oneOf.discriminator), None)
+            if attribute is None:
+                errors.append(f'{typeName} needs a {oneOf.discriminator} attribute to be part of {oneOf.name}')
+                continue
+            values = attribute.enumValues if attribute.fieldType == SpecialTypes.ENUM else enumsByName[attribute.fieldType].values if attribute.fieldType in enumsByName else []
+            if len(values) != 1 or attribute.isNullable:
+                errors.append(f'{oneOf.discriminator} of {typeName} must be a non-nullable Enum with one value to be part of {oneOf.name}')
+                continue
+            members.append(RenderableOneOfMember(className=RenderableString.from_pascal_case_string(string=typeName), value=values[0]))
+        errors += [f'{oneOf.name} has more than one {oneOf.discriminator} {value}' for value, count in collections.Counter(member.value for member in members).items() if count > 1]
+        return members, errors
+
     def build_renderable_api(self, api: KibaApi) -> RenderableApi:
         fullResourceNames = [self._resource_full_name(resource=resource, name=resource.singleName) for resource in api.resources]
         enumNames = [enum.name for enum in api.enums]
-        knownTypeNames = {**dict.fromkeys(fullResourceNames, RenderableRawTypes.CLASS), **dict.fromkeys(enumNames, RenderableRawTypes.ENUM)}
-        resourceErrors = [f'Duplicate type name: {name}' for name, count in collections.Counter(fullResourceNames + enumNames).items() if count > 1]
+        oneOfNames = [oneOf.name for oneOf in api.oneOfs]
+        knownTypeNames = {
+            **dict.fromkeys(fullResourceNames, RenderableRawTypes.CLASS),
+            **dict.fromkeys(enumNames, RenderableRawTypes.ENUM),
+            **dict.fromkeys(oneOfNames, RenderableRawTypes.ONE_OF),
+        }
+        resourceErrors = [f'Duplicate type name: {name}' for name, count in collections.Counter(fullResourceNames + enumNames + oneOfNames).items() if count > 1]
         resourceErrors += [f'Unknown parent resource {resource.parentResource} for {resource.singleName}' for resource in api.resources if resource.parentResource is not None and resource.parentResource not in fullResourceNames]
         resourcesByName = dict(zip(fullResourceNames, api.resources, strict=False))
+        renderableOneOfs: list[RenderableOneOf] = []
+        for oneOf in api.oneOfs:
+            members, oneOfErrors = self._one_of_members(oneOf=oneOf, resourcesByName=resourcesByName, enumsByName={enum.name: enum for enum in api.enums})
+            resourceErrors += oneOfErrors
+            renderableOneOfs.append(RenderableOneOf(name=RenderableString.from_pascal_case_string(string=oneOf.name), discriminator=RenderableString.from_kebab_case_string(string=oneOf.discriminator), members=members))
         for resource, fullName in zip(api.resources, fullResourceNames, strict=True):
             ancestorNames: list[str] = []
             ancestor = resourcesByName.get(resource.parentResource) if resource.parentResource is not None else None
@@ -439,6 +474,7 @@ class Renderer:
             operations=renderableOperations,
             exceptions=renderableExceptions,
             enums=[RenderableEnum(name=RenderableString.from_pascal_case_string(string=enum.name), values=enum.values) for enum in api.enums],
+            oneOfs=renderableOneOfs,
         )
         renderableResources: list[RenderableResource] = [self._resource_to_renderable_resource(resource=resource, knownTypeNames=knownTypeNames) for resource in api.resources]
         uncoveredTransitions: list[str] = []

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/src/geniespec/languages.py

@@ -12,6 +12,7 @@ from geniespec.renderable_types import RenderableEndpointComponent
 from geniespec.renderable_types import RenderableEnum
 from geniespec.renderable_types import RenderableException
 from geniespec.renderable_types import RenderableField
+from geniespec.renderable_types import RenderableOneOf
 from geniespec.renderable_types import RenderableOperation
 from geniespec.renderable_types import RenderableParameter
 from geniespec.renderable_types import RenderableRawTypes
@@ -68,9 +69,6 @@ class BaseLanguageDefinition:
     def object_type(self, isNullable: bool, className: RenderableString, apiVersion: Version, isLocalReference: bool) -> str:
         raise NotImplementedError
 
-    def one_of_type(self, isNullable: bool, subTypes: list[str]) -> str:
-        raise NotImplementedError
-
     def string_type(self, isNullable: bool) -> str:
         raise NotImplementedError
 
@@ -92,10 +90,6 @@ class BaseLanguageDefinition:
     def is_valid_name(self, name: str) -> bool:
         raise NotImplementedError
 
-    def _render_one_of_type_string(self, oneOfTypeString: str, isNullable: bool, apiVersion: Version) -> list[str]:
-        oneOfTypes = ''.join(oneOfTypeString.replace('OneOf[', '', 1).rsplit(']', 1)).split(', ')
-        return [self.render_type(renderableType=RenderableType(rawType=oneOfType, isNullable=isNullable), apiVersion=apiVersion) for oneOfType in oneOfTypes]
-
     def _render_list_type_string(self, listTypeString: str, apiVersion: Version) -> str:
         listItemType = ''.join(listTypeString.replace('List[', '', 1).rsplit(']', 1))
         return self.render_type(renderableType=RenderableType(rawType=listItemType, isNullable=False), apiVersion=apiVersion)
@@ -131,7 +125,7 @@ class BaseLanguageDefinition:
             keyType = self.render_type(renderableType=renderableType.keyType, apiVersion=apiVersion, isLocalReference=isLocalReference)
             valueType = self.render_type(renderableType=renderableType.valueType, apiVersion=apiVersion, isLocalReference=isLocalReference)
             return self.mapping_type(isNullable=isNullable, keyType=keyType, valueType=valueType)
-        if yamlType == 'class' and isinstance(renderableType, RenderableType) and renderableType.className is not None:
+        if yamlType in (RenderableRawTypes.CLASS, RenderableRawTypes.ONE_OF) and renderableType.className is not None:
             return self.object_type(isNullable=isNullable, className=renderableType.className, apiVersion=apiVersion, isLocalReference=isLocalReference)
         raise KibaException(f'Failed to render: {type(renderableType)} {renderableType}')
 
@@ -175,6 +169,12 @@ class BaseLanguageDefinition:
     def enum_class_name(self, enum: RenderableEnum, apiVersion: Version) -> str:
         return f'{self.pascal_name(name=enum.name)}V{apiVersion.major}'
 
+    def one_of_class_name(self, oneOf: RenderableOneOf, apiVersion: Version) -> str:
+        return f'{self.pascal_name(name=oneOf.name)}V{apiVersion.major}'
+
+    def one_of_member_class_names(self, oneOf: RenderableOneOf, apiVersion: Version) -> list[str]:
+        return [f'{self.pascal_name(name=member.className)}V{apiVersion.major}' for member in oneOf.members]
+
     @staticmethod
     def is_inline_enum(renderableType: RenderableType) -> bool:
         return renderableType.rawType == RenderableRawTypes.ENUM and renderableType.className is None
@@ -339,10 +339,6 @@ class PythonLanguageDefinition(BaseLanguageDefinition):
         typeName = f'{className.pascalCaseString}V{apiVersion.major}' if isLocalReference else f'resources.{className.pascalCaseString}V{apiVersion.major}'
         return f'{typeName} | None' if isNullable else typeName
 
-    def one_of_type(self, isNullable: bool, subTypes: list[str]) -> str:
-        fieldTypes = ' | '.join(subTypes)
-        return f'{fieldTypes} | None' if isNullable else f'Union[{fieldTypes} | None'
-
     def string_type(self, isNullable: bool) -> str:
         return 'str | None' if isNullable else 'str'
 
@@ -416,7 +412,10 @@ class PythonLanguageDefinition(BaseLanguageDefinition):
         return any(self._contains_json(renderableType=attribute.fieldType) for resource in api.resources for attribute in resource.attributes)
 
     def resources_require_typing(self, api: RenderableApi) -> bool:
-        return len(api.enums) > 0 or any(self.is_inline_enum(renderableType=attribute.fieldType) for resource in api.resources for attribute in resource.attributes)
+        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)
+
+    def one_of_alias(self, oneOf: RenderableOneOf, apiVersion: Version) -> str:
+        return f'typing.Annotated[{" | ".join(self.one_of_member_class_names(oneOf=oneOf, apiVersion=apiVersion))}, pydantic.Field(discriminator={self.identifier(name=oneOf.discriminator)!r})]'
 
     def operations_require_typing(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 []]
@@ -612,7 +611,10 @@ class TypeScriptLanguageDefinition(BaseLanguageDefinition):
 
     def references_resources(self, renderableTypes: list[RenderableType]) -> bool:
         valueTypes = [self._value_type(renderableType=renderableType) for renderableType in renderableTypes]
-        return any(valueType.rawType in ('class', PrimitiveTypes.JSON) or (valueType.rawType == RenderableRawTypes.ENUM and valueType.className is not None) for valueType in valueTypes)
+        return any(valueType.rawType in ('class', PrimitiveTypes.JSON, RenderableRawTypes.ONE_OF) or (valueType.rawType == RenderableRawTypes.ENUM and valueType.className is not None) for valueType in valueTypes)
+
+    def one_of_parser_name(self, name: RenderableString, apiVersion: Version) -> str:
+        return f'{self._normalized_name(name=name).camelCaseString}V{apiVersion.major}FromObject'
 
     def _value_type(self, renderableType: RenderableType) -> RenderableType:
         return self._value_type(renderableType=renderableType.valueType) if isinstance(renderableType, MappingRenderableType) else renderableType
@@ -658,6 +660,9 @@ class TypeScriptLanguageDefinition(BaseLanguageDefinition):
             valueTypeName = self.type(renderableType=renderableType.valueType, apiVersion=apiVersion, isLocalReference=isLocalReference)
             convertedEntry = self.from_object(renderableType=renderableType.valueType, value='entry', apiVersion=apiVersion, isLocalReference=isLocalReference)
             return f'Object.fromEntries(Object.entries({value} as RawObject).map(([key, entry]: [string, unknown]): [string, {valueTypeName}] => [key, {convertedEntry}]))'
+        if renderableType.rawType == RenderableRawTypes.ONE_OF and renderableType.className is not None:
+            parserName = self.one_of_parser_name(name=renderableType.className, apiVersion=apiVersion)
+            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:
@@ -677,7 +682,7 @@ class TypeScriptLanguageDefinition(BaseLanguageDefinition):
     def _is_serialized_as_is(self, renderableType: RenderableType) -> bool:
         if isinstance(renderableType, MappingRenderableType):
             return self._is_serialized_as_is(renderableType=renderableType.valueType)
-        return renderableType.rawType not in ('class', PrimitiveTypes.DATE, PrimitiveTypes.DATETIME)
+        return renderableType.rawType not in ('class', RenderableRawTypes.ONE_OF, PrimitiveTypes.DATE, PrimitiveTypes.DATETIME)
 
     def to_object(self, renderableType: RenderableType, value: str, apiVersion: Version, isOptional: bool = False, isLocalReference: bool = False) -> str:
         if self._is_serialized_as_is(renderableType=renderableType):
@@ -693,7 +698,7 @@ class TypeScriptLanguageDefinition(BaseLanguageDefinition):
             valueTypeName = self.type(renderableType=renderableType.valueType, apiVersion=apiVersion, isLocalReference=isLocalReference)
             convertedEntry = self.to_object(renderableType=renderableType.valueType, value='entry', apiVersion=apiVersion, isLocalReference=isLocalReference)
             return f'Object.fromEntries(Object.entries({value}).map(([key, entry]: [string, {valueTypeName}]): [string, unknown] => [key, {convertedEntry}]))'
-        if renderableType.rawType == 'class':
+        if renderableType.rawType in ('class', RenderableRawTypes.ONE_OF):
             return f'{value}.toObject()'
         if renderableType.rawType == PrimitiveTypes.DATETIME:
             return f'dateToString({value})'

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/src/geniespec/renderable_types.py

@@ -91,6 +91,7 @@ class RenderableRawTypes:
     CLASS = 'class'
     ENUM = 'enum'
     FILE = 'file'
+    ONE_OF = 'oneOf'
 
 
 class RenderableType(BaseModel):
@@ -106,6 +107,17 @@ class RenderableEnum(BaseModel):
     values: list[str]
 
 
+class RenderableOneOfMember(BaseModel):
+    className: RenderableString
+    value: str
+
+
+class RenderableOneOf(BaseModel):
+    name: RenderableString
+    discriminator: RenderableString
+    members: list[RenderableOneOfMember]
+
+
 class MappingRenderableType(RenderableType):
     keyType: RenderableType
     valueType: RenderableType
@@ -238,6 +250,7 @@ class RenderableApi(BaseModel):
     operations: list[RenderableOperation]
     exceptions: list[RenderableException]
     enums: list[RenderableEnum] = []
+    oneOfs: list[RenderableOneOf] = []
 
 
 class ProcessableResource(BaseModel):

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/src/geniespec/templates/python-server/{service}/v{version}/resources.py.j2

@@ -7,7 +7,7 @@ import datetime
 import typing
 {% endif %}
 
-{% if target.resources_require_json(api=api) %}
+{% if target.resources_require_json(api=api) or api.oneOfs %}
 import pydantic
 {% endif %}
 from pydantic import BaseModel
@@ -29,3 +29,9 @@ class {{ target.resource_class_name(resource=resource, apiVersion=api.version) }
 {% endfor %}
 
 {% endfor %}
+{% for oneOf in api.oneOfs %}
+{% if loop.first %}
+
+{% endif %}
+{{ target.one_of_class_name(oneOf=oneOf, apiVersion=api.version) }} = {{ target.one_of_alias(oneOf=oneOf, apiVersion=api.version) }}
+{% endfor %}

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/src/geniespec/templates/typescript-client/{service}/v{version}/resources.ts.j2

@@ -47,3 +47,20 @@ export class {{ className }} {
 {% endif %}
 }
 {% endfor %}
+{% for oneOf in api.oneOfs %}
+{% set typeName = target.one_of_class_name(oneOf=oneOf, apiVersion=api.version) %}
+{% set discriminator = target.identifier(name=oneOf.discriminator) %}
+
+export type {{ typeName }} = {{ target.one_of_member_class_names(oneOf=oneOf, apiVersion=api.version) | join(' | ') }};
+
+export const {{ target.one_of_parser_name(name=oneOf.name, apiVersion=api.version) }} = (obj: RawObject): {{ typeName }} => {
+  switch (obj.{{ discriminator }}) {
+{% for member in oneOf.members %}
+    case '{{ member.value }}':
+      return {{ target.one_of_member_class_names(oneOf=oneOf, apiVersion=api.version)[loop.index0] }}.fromObject(obj);
+{% endfor %}
+    default:
+      throw new Error(`Unknown {{ typeName }} {{ discriminator }}: ${String(obj.{{ discriminator }})}`);
+  }
+};
+{% endfor %}

{geniespec-0.1.1.dev7 → geniespec-0.1.1.dev8}/src/geniespec/types.py

@@ -47,6 +47,12 @@ class ApiEnum(BaseModel):
     values: list[str]
 
 
+class ApiOneOf(BaseModel):
+    name: str
+    discriminator: str
+    types: list[str]
+
+
 class Attribute(BaseModel):
     name: str
     fieldType: str = pydantic.Field(alias='type')
@@ -155,6 +161,7 @@ class KibaApi(BaseModel):
     transitions: list[RootTransition] = []
     exceptions: list[ApiException] = []
     enums: list[ApiEnum] = []
+    oneOfs: list[ApiOneOf] = []
     defaultAuthentication: str | None = None
 
     @property