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 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:

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.

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

OneOf not supported yet

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]