geniespec 0.1.1.dev2__tar.gz

geniespec-0.1.1.dev2/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: geniespec
+Version: 0.1.1.dev2
+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. The output is a package you install, not code you commit.
+
+```
+uvx geniespec build --spec api.yaml [--output .genie]
+uvx geniespec watch --spec api.yaml [--output .genie]
+```
+
+- `build` writes `<output>/python`: a project with `pyproject.toml` and `src/<service>_api/v<major>/` (`api`, `endpoints`, `resources`, `internal`, `exceptions`). Only changed files are rewritten and files it no longer generates are removed.
+- `watch` rebuilds whenever the spec changes. If the spec is invalid it logs the error and keeps the previous output.
+- Consumers depend on the output as an editable path dependency, e.g. `my-service-api = { path = ".genie/python", editable = true }` in `[tool.uv.sources]`, and import it as `my_service_api.v1`.
+- Generated code needs `kiba-core` (`core.api`, `core.util.typing_util`), `pydantic` and `starlette` from the consumer.
+
+# Development
+
+```
+make install
+make lint-check type-check test
+```
+
+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
+
+Enum and 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]
+
+```

geniespec-0.1.1.dev2/README.md

@@ -0,0 +1,63 @@
+# Genie
+
+Genie (`geniespec` on PyPI) generates API code from an `api.yaml` spec. The output is a package you install, not code you commit.
+
+```
+uvx geniespec build --spec api.yaml [--output .genie]
+uvx geniespec watch --spec api.yaml [--output .genie]
+```
+
+- `build` writes `<output>/python`: a project with `pyproject.toml` and `src/<service>_api/v<major>/` (`api`, `endpoints`, `resources`, `internal`, `exceptions`). Only changed files are rewritten and files it no longer generates are removed.
+- `watch` rebuilds whenever the spec changes. If the spec is invalid it logs the error and keeps the previous output.
+- Consumers depend on the output as an editable path dependency, e.g. `my-service-api = { path = ".genie/python", editable = true }` in `[tool.uv.sources]`, and import it as `my_service_api.v1`.
+- Generated code needs `kiba-core` (`core.api`, `core.util.typing_util`), `pydantic` and `starlette` from the consumer.
+
+# Development
+
+```
+make install
+make lint-check type-check test
+```
+
+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
+
+Enum and 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]
+
+```

geniespec-0.1.1.dev2/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "geniespec"
+version = "0.1.1.dev2"
+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.dev81,<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.dev2/pyproject.toml.orig

@@ -0,0 +1,38 @@
+[project]
+name = "geniespec"
+version = "0.1.1.dev2"
+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.dev81,<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.dev2/src/geniespec/api_schema.yaml

@@ -0,0 +1,318 @@
+$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'
+  imports:
+    type: array
+    items:
+      type: string
+  defaultAuthentication:
+    type:
+      - "null"
+      - string
+    pattern: '^[a-z][a-z0-9-]*$'
+definitions:
+  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-\[\]_, ]*$'
+  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-\[\]_, ]*$'
+      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-\[\]_, ]*$'
+      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

geniespec-0.1.1.dev2/src/geniespec/cli.py

@@ -0,0 +1,85 @@
+import argparse
+import pathlib
+import tempfile
+import time
+
+import yaml  # type: ignore[import-untyped]
+from core import logging
+
+from geniespec.genie import Renderer
+from geniespec.genie import SyntacticApiValidator
+from geniespec.types import KibaApi
+
+WATCH_INTERVAL_SECONDS = 0.5
+
+
+def _sync_directory(sourceDirectoryPath: pathlib.Path, targetDirectoryPath: pathlib.Path) -> list[pathlib.Path]:
+    changedPaths: list[pathlib.Path] = []
+    sourceRelativePaths = {path.relative_to(sourceDirectoryPath) for path in sourceDirectoryPath.rglob('*') if path.is_file()}
+    for relativePath in sorted(sourceRelativePaths):
+        content = (sourceDirectoryPath / relativePath).read_bytes()
+        targetPath = targetDirectoryPath / relativePath
+        if targetPath.is_file() and targetPath.read_bytes() == content:
+            continue
+        targetPath.parent.mkdir(parents=True, exist_ok=True)
+        temporaryPath = targetPath.with_name(f'.{targetPath.name}.tmp')
+        temporaryPath.write_bytes(content)
+        temporaryPath.replace(targetPath)
+        changedPaths.append(targetPath)
+    stalePaths = [path for path in targetDirectoryPath.rglob('*') if path.is_file() and '__pycache__' not in path.parts and path.relative_to(targetDirectoryPath) not in sourceRelativePaths]
+    for stalePath in stalePaths:
+        stalePath.unlink()
+    return changedPaths + stalePaths
+
+
+def build(specPath: pathlib.Path, outputDirectoryPath: pathlib.Path) -> list[pathlib.Path]:
+    with open(specPath) as specFile:
+        apiYaml = yaml.safe_load(specFile)
+    SyntacticApiValidator().validate(apiYaml)
+    api = KibaApi(**apiYaml)
+    with tempfile.TemporaryDirectory() as renderDirectory:
+        Renderer().render_directory(api=api, outputDirectoryPath=renderDirectory)
+        return _sync_directory(sourceDirectoryPath=pathlib.Path(renderDirectory), targetDirectoryPath=outputDirectoryPath / 'python')
+
+
+def _build_and_log(specPath: pathlib.Path, outputDirectoryPath: pathlib.Path) -> None:
+    changedPaths = build(specPath=specPath, outputDirectoryPath=outputDirectoryPath)
+    logging.info(f'geniespec: built {specPath} into {outputDirectoryPath} ({len(changedPaths)} files changed)')
+
+
+def watch(specPath: pathlib.Path, outputDirectoryPath: pathlib.Path) -> None:
+    lastModifiedTime: int | None = None
+    while True:
+        try:
+            modifiedTime: int | None = specPath.stat().st_mtime_ns
+        except FileNotFoundError:
+            modifiedTime = lastModifiedTime
+        if modifiedTime != lastModifiedTime:
+            lastModifiedTime = modifiedTime
+            try:
+                _build_and_log(specPath=specPath, outputDirectoryPath=outputDirectoryPath)
+            except Exception as exception:  # noqa: BLE001
+                logging.error(f'geniespec: failed to build {specPath}, keeping the previous output: {exception}')
+        time.sleep(WATCH_INTERVAL_SECONDS)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog='geniespec')
+    subparsers = parser.add_subparsers(dest='command', required=True)
+    for command in ('build', 'watch'):
+        subparser = subparsers.add_parser(command)
+        subparser.add_argument('--spec', type=pathlib.Path, required=True)
+        subparser.add_argument('--output', type=pathlib.Path, default=pathlib.Path('.genie'))
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO)
+    if args.command == 'build':
+        _build_and_log(specPath=args.spec, outputDirectoryPath=args.output)
+        return
+    try:
+        watch(specPath=args.spec, outputDirectoryPath=args.output)
+    except KeyboardInterrupt:
+        return
+
+
+if __name__ == '__main__':
+    main()