geniespec 0.1.1__tar.gz

geniespec-0.1.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: geniespec
+Version: 0.1.1
+Summary: Generate API code from an api.yaml spec
+License-Expression: MIT
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: kiba-core>=0.5.3.dev81,<0.5.4
+Requires-Python: >=3.13, <4
+Project-URL: repository, https://github.com/kibalabs/genie
+Description-Content-Type: text/markdown
+
+# Genie
+
+Genie (`geniespec` on PyPI) generates API code from an `api.yaml` spec. Install it like any other tool and run it from your build scripts; the generated code is gitignored, not committed.
+
+```
+geniespec build --spec api.yaml --target <python-server | typescript-client> [--output .]
+geniespec watch --spec api.yaml --target <python-server | typescript-client> [--output .] [-- <command>]
+```
+
+- `build` writes the target's package into the output directory. Only files in that package are touched: changed files are rewritten and files it no longer generates are removed.
+  - `python-server`: `./<service>_api/v<major>/` (`api`, `endpoints`, `resources`, `internal`, `exceptions`). Code run from the output directory imports it directly, e.g. `from my_service_api.v1 import api`. Needs `kiba-core` (`core.api`, `core.util.typing_util`; 0.5.3.dev87 or later for `File` fields), `pydantic` and `starlette`.
+  - `typescript-client`: `./<service>-api/v<major>/` (`client`, `endpoints`, `resources`, `index`) with a `<Service>ApiV<major>Client` that extends `@kibalabs/core`'s `ServiceClient`. Construct it with the url the API version is mounted at, e.g. `new MyServiceApiV1Client(requester, 'https://api.example.com/v1')`. Methods take path parameters, then a params object for the request fields, and return the response field; stream transitions take a callback for each item; transitions with `File` fields send a multipart form. Transitions with `responseType: redirect` or a `query-parameters` field are left out, as browsers open redirects directly and query-parameters fields receive third-party callbacks. Needs `@kibalabs/core`.
+- `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, 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:
+
+```yaml
+enums:
+  - name: ViewKind
+    values: [member, cycle-start]
+resources:
+  - singleName: View
+    collectionName: Views
+    attributes:
+      - name: kind
+        type: ViewKind
+      - name: size
+        type: Enum
+        enumValues: [small, large]
+```
+
+`python-server` types them as `typing.Literal[...]` (named ones as `ViewKindV1` in `resources`) and rejects requests with other values; `typescript-client` types them as `'member' | 'cycle-start'` (named ones as an exported `ViewKindV1`).
+
+`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
+
+```
+make install
+make lint-check type-check test
+```
+
+`tests/python_server` covers the core and the `python-server` target (the core tests generate through it) and runs in `Dockerfile`. `tests/typescript_client` covers the `typescript-client` target; it needs node and runs in `typescript-client.Dockerfile`:
+
+```
+make install-typescript-client
+make test-typescript-client
+```
+
+Merges to `main` publish a dev version to PyPI. To release, bump `version` in `pyproject.toml` in a PR, then run the Release workflow on `main` (Actions → Release → Run workflow). It tags `vX.Y.Z` and the Publish workflow publishes it. Only the release workflow can push version tags.
+
+# Things that need work
+
+## Typing of params and fields in general
+
+I think we need to create an object for Type. what would it look like?
+
+
+```
+class BaseFieldType:
+    isNullable: bool
+
+
+class RawFieldType(BaseFieldType):
+    name: str
+
+
+class ClassFieldType(BaseFieldType):
+    fieldType: RawFieldType
+
+
+class ListFieldType:(BaseFieldType)
+    fieldType: RawFieldType
+    isNullable: bool
+
+
+class MappingFieldType(BaseFieldType):
+    keyFieldType: RawFieldType
+    valueFieldType: RawFieldType
+
+
+class OneOfFieldType(BaseFieldType):
+    fieldTypes: list[RawFieldType]
+
+
+class EnumFieldType(BaseFieldType):
+    values: list[str]
+
+```

geniespec-0.1.1/README.md

@@ -0,0 +1,110 @@
+# Genie
+
+Genie (`geniespec` on PyPI) generates API code from an `api.yaml` spec. Install it like any other tool and run it from your build scripts; the generated code is gitignored, not committed.
+
+```
+geniespec build --spec api.yaml --target <python-server | typescript-client> [--output .]
+geniespec watch --spec api.yaml --target <python-server | typescript-client> [--output .] [-- <command>]
+```
+
+- `build` writes the target's package into the output directory. Only files in that package are touched: changed files are rewritten and files it no longer generates are removed.
+  - `python-server`: `./<service>_api/v<major>/` (`api`, `endpoints`, `resources`, `internal`, `exceptions`). Code run from the output directory imports it directly, e.g. `from my_service_api.v1 import api`. Needs `kiba-core` (`core.api`, `core.util.typing_util`; 0.5.3.dev87 or later for `File` fields), `pydantic` and `starlette`.
+  - `typescript-client`: `./<service>-api/v<major>/` (`client`, `endpoints`, `resources`, `index`) with a `<Service>ApiV<major>Client` that extends `@kibalabs/core`'s `ServiceClient`. Construct it with the url the API version is mounted at, e.g. `new MyServiceApiV1Client(requester, 'https://api.example.com/v1')`. Methods take path parameters, then a params object for the request fields, and return the response field; stream transitions take a callback for each item; transitions with `File` fields send a multipart form. Transitions with `responseType: redirect` or a `query-parameters` field are left out, as browsers open redirects directly and query-parameters fields receive third-party callbacks. Needs `@kibalabs/core`.
+- `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, 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:
+
+```yaml
+enums:
+  - name: ViewKind
+    values: [member, cycle-start]
+resources:
+  - singleName: View
+    collectionName: Views
+    attributes:
+      - name: kind
+        type: ViewKind
+      - name: size
+        type: Enum
+        enumValues: [small, large]
+```
+
+`python-server` types them as `typing.Literal[...]` (named ones as `ViewKindV1` in `resources`) and rejects requests with other values; `typescript-client` types them as `'member' | 'cycle-start'` (named ones as an exported `ViewKindV1`).
+
+`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
+
+```
+make install
+make lint-check type-check test
+```
+
+`tests/python_server` covers the core and the `python-server` target (the core tests generate through it) and runs in `Dockerfile`. `tests/typescript_client` covers the `typescript-client` target; it needs node and runs in `typescript-client.Dockerfile`:
+
+```
+make install-typescript-client
+make test-typescript-client
+```
+
+Merges to `main` publish a dev version to PyPI. To release, bump `version` in `pyproject.toml` in a PR, then run the Release workflow on `main` (Actions → Release → Run workflow). It tags `vX.Y.Z` and the Publish workflow publishes it. Only the release workflow can push version tags.
+
+# Things that need work
+
+## Typing of params and fields in general
+
+I think we need to create an object for Type. what would it look like?
+
+
+```
+class BaseFieldType:
+    isNullable: bool
+
+
+class RawFieldType(BaseFieldType):
+    name: str
+
+
+class ClassFieldType(BaseFieldType):
+    fieldType: RawFieldType
+
+
+class ListFieldType:(BaseFieldType)
+    fieldType: RawFieldType
+    isNullable: bool
+
+
+class MappingFieldType(BaseFieldType):
+    keyFieldType: RawFieldType
+    valueFieldType: RawFieldType
+
+
+class OneOfFieldType(BaseFieldType):
+    fieldTypes: list[RawFieldType]
+
+
+class EnumFieldType(BaseFieldType):
+    values: list[str]
+
+```

geniespec-0.1.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "geniespec"
+version = "0.1.1"
+description = "Generate API code from an api.yaml spec"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13, <4"
+dependencies = [
+    "jinja2>=3.1.6",
+    "pyyaml>=6.0.3",
+    "jsonschema>=4.26.0",
+    "pydantic>=2.13.5",
+    "kiba-core>=0.5.3.dev81,<0.5.4",
+]
+
+[project.scripts]
+geniespec = "geniespec.cli:main"
+
+[project.urls]
+repository = "https://github.com/kibalabs/genie"
+
+[dependency-groups]
+dev = [
+    "kiba-build==0.1.11.dev15",
+    "kiba-core[core-api,requester]>=0.5.3.dev87,<0.5.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.bumpversion]
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'

geniespec-0.1.1/pyproject.toml.orig

@@ -0,0 +1,38 @@
+[project]
+name = "geniespec"
+version = "0.1.1"
+description = "Generate API code from an api.yaml spec"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13, <4"
+dependencies = [
+    "jinja2>=3.1.6",
+    "pyyaml>=6.0.3",
+    "jsonschema>=4.26.0",
+    "pydantic>=2.13.5",
+    "kiba-core>=0.5.3.dev81,<0.5.4",
+]
+
+[project.scripts]
+geniespec = "geniespec.cli:main"
+
+[project.urls]
+repository = "https://github.com/kibalabs/genie"
+
+[dependency-groups]
+dev = [
+    "kiba-build==0.1.11.dev15",
+    "kiba-core[core-api,requester]>=0.5.3.dev87,<0.5.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+# NOTE(krishan711): without this, bumping the version also rewrites dependency pins that contain it (e.g. 0.1.1 inside kiba-build==0.1.11.dev15)
+[tool.bumpversion]
+search = "version = \"{current_version}\""
+replace = "version = \"{new_version}\""

geniespec-0.1.1/src/geniespec/api_schema.yaml

@@ -0,0 +1,372 @@
+$schema: 'http://json-schema.org/draft-07/schema#'
+$id: kibaRestApiSchema
+type: object
+additionalProperties: false
+required:
+  - version
+  - serviceName
+  - pythonClientPackageName
+  - typescriptClientPackageName
+properties:
+  version:
+    type: string
+    pattern: '^([0-9]|[1-9][0-9]*)\.([0-9]|[1-9][0-9]*)\.([0-9]|[1-9][0-9]*)$'
+  serviceName:
+    type: string
+    pattern: '^[a-z][a-z-]*$'
+  pythonClientPackageName:
+    type: string
+    pattern: '^[a-z][-a-z]*$'
+  typescriptClientPackageName:
+    type: string
+    pattern: '[@/-a-z]*$'
+  transitions:
+    type: array
+    items:
+      $ref: '#/definitions/RootTransition'
+  resources:
+    type: array
+    items:
+      $ref: '#/definitions/Resource'
+  exceptions:
+    type: array
+    items:
+      $ref: '#/definitions/Exception'
+  enums:
+    type: array
+    items:
+      $ref: '#/definitions/Enum'
+  oneOfs:
+    type: array
+    items:
+      $ref: '#/definitions/OneOf'
+  imports:
+    type: array
+    items:
+      type: string
+  defaultAuthentication:
+    type:
+      - "null"
+      - string
+    pattern: '^[a-z][a-z0-9-]*$'
+definitions:
+  EnumValues:
+    type: array
+    minItems: 1
+    uniqueItems: true
+    items:
+      type: string
+      pattern: '^[A-Za-z0-9][A-Za-z0-9_-]*$'
+  Enum:
+    type: object
+    additionalProperties: false
+    required:
+      - name
+      - values
+    properties:
+      name:
+        type: string
+        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
+    required:
+      - name
+      - type
+    properties:
+      name:
+        type: string
+        pattern: '^[a-z][A-Za-z0-9-]*$'
+      type:
+        type: string
+        pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      listValueTypes:
+        type: array
+        minItems: 1
+        items:
+          type: string
+          pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      isPrimary:
+        type: boolean
+      isUnique:
+        type: boolean
+      shouldDisableGetEndpoint:
+        type: boolean
+      isUnfilterable:
+        type: boolean
+      isUpdatable:
+        type: boolean
+      isNullable:
+        type: boolean
+      isDeprecated:
+        type: boolean
+      defaultValue:
+        type:
+          - string
+          - number
+          - boolean
+          - 'null'
+      isSettable:
+        type: boolean
+      isAccessibleIndependently:
+        type: boolean
+      mappingKeyType:
+        type: string
+        pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      mappingValueTypes:
+        type: array
+        items:
+          type: string
+          pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      enumValues:
+        $ref: '#/definitions/EnumValues'
+  Resource:
+    type: object
+    additionalProperties: false
+    required:
+      - singleName
+      - collectionName
+    properties:
+      singleName:
+        type: string
+        pattern: '^[A-Z][A-Za-z-]*$'
+      collectionName:
+        type: string
+        pattern: '^[A-Z][A-Za-z-]*$'
+      parentResource:
+        type: string
+        pattern: '^[A-Z][A-Za-z-]*$'
+      attributes:
+        type: array
+        items:
+          $ref: '#/definitions/Attribute'
+      transitions:
+        type: array
+        items:
+          $ref: '#/definitions/Transition'
+      accessibleFrom:
+        type: array
+        items:
+          type: string
+  BaseTransition:
+    type: object
+    additionalProperties: false
+    required:
+      - action
+    properties:
+      action:
+        type: string
+        pattern: '^[A-Z][A-Z-]*$'
+      method:
+        type: string
+        enum:
+          - GET
+          - POST
+      requestFields:
+        type: array
+        items:
+          $ref: '#/definitions/RequestField'
+      responseField:
+        $ref: '#/definitions/ResponseField'
+      authentication:
+        type:
+          - "null"
+          - string
+        pattern: '^[a-z][a-z0-9-]*$'
+      responseType:
+        type: string
+        enum:
+          - json
+          - stream
+          - redirect
+  Transition:
+    type: object
+    additionalProperties: false
+    required:
+      - action
+    properties:
+      action:
+        type: string
+        pattern: '^[A-Z][A-Z-]*$'
+      method:
+        type: string
+        enum:
+          - GET
+          - POST
+      requestFields:
+        type: array
+        items:
+          $ref: '#/definitions/RequestField'
+      responseField:
+        $ref: '#/definitions/ResponseField'
+      authentication:
+        type:
+          - "null"
+          - string
+        pattern: '^[a-z][a-z0-9-]*$'
+      responseType:
+        type: string
+        enum:
+          - json
+          - stream
+          - redirect
+      operatesOn:
+        type: string
+        enum:
+          - individual
+          - collection
+      isIndirectAction:
+        type: boolean
+  RootTransition:
+    type: object
+    allOf:
+      - $ref: '#/definitions/BaseTransition'
+  RequestField:
+    type: object
+    additionalProperties: false
+    required:
+      - name
+      - type
+    properties:
+      name:
+        type: string
+        pattern: '^[a-z][A-Za-z0-9-]*$'
+      type:
+        type: string
+        pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      listValueTypes:
+        type: array
+        minItems: 1
+        items:
+          type: string
+          pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      mappingKeyType:
+        type: string
+        pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      mappingValueTypes:
+        type: array
+        items:
+          type: string
+          pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      enumValues:
+        $ref: '#/definitions/EnumValues'
+      isRequired:
+        type: boolean
+      defaultValue:
+        type:
+          - string
+          - number
+          - boolean
+          - 'null'
+      isDeprecated:
+        type: boolean
+      maxValue:
+        type:
+          - string
+          - number
+      minValue:
+        type:
+          - string
+          - number
+      source:
+        type: string
+        enum:
+          - request
+          - query-parameters
+  ResponseField:
+    type: object
+    additionalProperties: false
+    required:
+      - name
+      - type
+    properties:
+      name:
+        type: string
+        pattern: '^[a-z][A-Za-z-]*$'
+      type:
+        type: string
+        pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      listValueTypes:
+        type: array
+        minItems: 1
+        items:
+          type: string
+          pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      mappingKeyType:
+        type: string
+        pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      mappingValueTypes:
+        type: array
+        items:
+          type: string
+          pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      enumValues:
+        $ref: '#/definitions/EnumValues'
+      isNullable:
+        type: boolean
+      isList:
+        type: boolean
+  Exception:
+    type: object
+    additionalProperties: false
+    required:
+      - name
+    properties:
+      name:
+        type: string
+        pattern: '^[A-Z][A-Za-z-]*Exception$'
+      message:
+        type: string
+      extends:
+        type: string
+        pattern: '^([a-z-]+.exceptions.[A-Za-z-]*)|([A-Za-z-]*)'
+      statusCode:
+        type: integer
+      fields:
+        type: array
+        items:
+          $ref: '#/definitions/ExceptionField'
+  ExceptionField:
+    type: object
+    additionalProperties: false
+    required:
+      - name
+      - type
+    properties:
+      name:
+        type: string
+        pattern: '^[a-z][A-Za-z-]*$'
+      type:
+        type: string
+        pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      listValueTypes:
+        type: array
+        minItems: 1
+        items:
+          type: string
+          pattern: '^[A-Z][A-Za-z-\[\]_, ]*$'
+      isRequired:
+        type: boolean