@voxgig/sdkgen 0.35.2 → 0.37.0

package/project/.sdk/src/cmp/py/Main_py.ts

@@ -0,0 +1,156 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp, each, names, cmap,
+  List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+} from '@voxgig/sdkgen'
+
+
+import type {
+  ModelEntity
+} from '@voxgig/apidef'
+
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
+
+import { Package } from './Package_py'
+import { Config } from './Config_py'
+import { MainEntity } from './MainEntity_py'
+
+
+const Main = cmp(async function Main(props: any) {
+
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  Package({ target })
+
+  // Copy tm/py files with replacements
+  Copy({
+    from: 'tm/' + target.name,
+    exclude: [/src\//],
+    replace: {
+      ...props.ctx$.stdrep,
+    }
+  })
+
+  // Generate main SDK file
+  File({ name: model.name + '_sdk.' + target.ext }, () => {
+
+    Fragment(
+      {
+        from: Path.normalize(__dirname + '/../../../src/cmp/py/fragment/Main.fragment.py'),
+        replace: {
+          ...props.ctx$.stdrep,
+
+          '#BuildFeatures': ({ indent }: any) => {
+            each(feature, (feat: any) => {
+              const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+              Content({ indent }, `  # feature: ${feat.name}
+`)
+            })
+          },
+
+          '#Feature-Hook': ({ name, indent }: any) => Content({ indent }, `
+self._utility.feature_hook(self._rootctx, "${name}")
+`),
+
+        }
+      },
+
+      // Entities - injected at SLOT
+      () => {
+        each(entity, (entity: ModelEntity) => {
+          const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
+          const entprops = { target, entity, entitySDK }
+          MainEntity(entprops)
+        })
+      })
+  })
+
+  // Generate config module
+  Folder({ name: '.' }, () => {
+    Config({ target })
+  })
+
+  // Generate feature factory module
+  File({ name: 'features.' + target.ext }, () => {
+    Content(`# ${model.const.Name} SDK feature factory
+
+from feature.base_feature import ${model.const.Name}BaseFeature
+`)
+
+    each(feature, (feat: any) => {
+      if (feat.name !== 'base') {
+        const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+        Content(`from feature.${feat.name}_feature import ${model.const.Name}${fname}Feature
+`)
+      }
+    })
+
+    Content(`
+
+def _make_feature(name):
+    features = {
+        "base": lambda: ${model.const.Name}BaseFeature(),
+`)
+
+    each(feature, (feat: any) => {
+      if (feat.name !== 'base') {
+        const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+        Content(`        "${feat.name}": lambda: ${model.const.Name}${fname}Feature(),
+`)
+      }
+    })
+
+    Content(`    }
+    factory = features.get(name)
+    if factory is not None:
+        return factory()
+    return features["base"]()
+`)
+  })
+
+  // Generate __init__.py files for packages
+  File({ name: '__init__.' + target.ext }, () => {
+    Content(``)
+  })
+
+  Folder({ name: 'core' }, () => {
+    File({ name: '__init__.' + target.ext }, () => {
+      Content(``)
+    })
+  })
+
+  Folder({ name: 'entity' }, () => {
+    File({ name: '__init__.' + target.ext }, () => {
+      Content(``)
+    })
+  })
+
+  Folder({ name: 'feature' }, () => {
+    File({ name: '__init__.' + target.ext }, () => {
+      Content(``)
+    })
+  })
+
+  Folder({ name: 'utility' }, () => {
+    File({ name: '__init__.' + target.ext }, () => {
+      Content(``)
+    })
+  })
+
+})
+
+
+export {
+  Main
+}

package/project/.sdk/src/cmp/py/Package_py.ts

@@ -0,0 +1,75 @@
+
+import {
+  Content,
+  File,
+  cmp,
+  each,
+} from '@voxgig/sdkgen'
+
+
+import {
+  KIT,
+  Model,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const Package = cmp(async function Package(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  File({ name: 'pyproject.toml' }, () => {
+    Content(`[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.backends._legacy:_Backend"
+
+[project]
+name = "${model.name}-sdk"
+version = "0.0.1"
+description = "${model.const.Name} SDK for Python"
+license = "MIT"
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.28",
+`)
+
+    // Collect dependencies from features
+    each(feature, (f: any) => {
+      const pyDeps = f.deps?.py
+      if (pyDeps) {
+        each(pyDeps, (dep: any) => {
+          if (dep.active) {
+            Content(`    "${dep.key$}>=${dep.version}",
+`)
+          }
+        })
+      }
+    })
+
+    // Add target-level deps
+    const targetDeps = target.deps
+    if (targetDeps) {
+      each(targetDeps, (dep: any) => {
+        if (dep.active !== false) {
+          Content(`    "${dep.key$}>=${dep.version || '0.0'}",
+`)
+        }
+      })
+    }
+
+    Content(`]
+
+[project.urls]
+Homepage = "https://github.com/voxgig/${model.name}-sdk"
+`)
+  })
+})
+
+
+export {
+  Package
+}

package/project/.sdk/src/cmp/py/ReadmeExplanation_py.ts

@@ -0,0 +1,41 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as dicts
+
+The Python SDK uses plain dicts throughout rather than typed
+objects. This mirrors the dynamic nature of the API and keeps the
+SDK flexible — no code generation is needed when the API schema
+changes.
+
+Use \`helpers.to_map()\` to safely validate that a value is a dict.
+
+### Module structure
+
+\`\`\`
+py/
+├── ${model.name}_sdk.py         -- Main SDK module
+├── config.py                    -- Configuration
+├── features.py                  -- Feature factory
+├── core/                        -- Core types and context
+├── entity/                      -- Entity implementations
+├── feature/                     -- Built-in features (Base, Test, Log)
+├── utility/                     -- Utility functions and struct library
+└── test/                        -- Test suites
+\`\`\`
+
+The main module (\`${model.name}_sdk\`) exports the SDK class.
+Import entity or utility modules directly only when needed.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

package/project/.sdk/src/cmp/py/ReadmeHowto_py.ts

@@ -0,0 +1,98 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`python
+result, err = client.direct({
+    "path": "/api/resource/{id}",
+    "method": "GET",
+    "params": {"id": "example"},
+})
+if err:
+    raise Exception(err)
+
+if result["ok"]:
+    print(result["status"])  # 200
+    print(result["data"])    # response body
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`python
+fetchdef, err = client.prepare({
+    "path": "/api/resource/{id}",
+    "method": "DELETE",
+    "params": {"id": "example"},
+})
+if err:
+    raise Exception(err)
+
+print(fetchdef["url"])
+print(fetchdef["method"])
+print(fetchdef["headers"])
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`python
+client = ${model.const.Name}SDK.test(None, None)
+
+result, err = client.${model.const.Name}(None).load(
+    {"id": "test01"}, None
+)
+# result contains mock response data
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own function:
+
+\`\`\`python
+def mock_fetch(url, init):
+    return {
+        "status": 200,
+        "statusText": "OK",
+        "headers": {},
+        "json": lambda: {"id": "mock01"},
+    }, None
+
+client = ${model.const.Name}SDK({
+    "base": "http://localhost:8080",
+    "system": {
+        "fetch": mock_fetch,
+    },
+})
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${model.NAME}_TEST_LIVE=TRUE
+${model.NAME}_APIKEY=<your-key>
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd py && pytest test/
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

package/project/.sdk/src/cmp/py/ReadmeInstall_py.ts

@@ -0,0 +1,25 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  Content(`\`\`\`bash
+pip install ${model.name}-sdk
+\`\`\`
+
+Or install from source:
+
+\`\`\`bash
+pip install -e .
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

package/project/.sdk/src/cmp/py/ReadmeModel_py.ts

@@ -0,0 +1,130 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const ReadmeModel = cmp(function ReadmeModel(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  Content(`### ${model.const.Name}SDK
+
+\`\`\`python
+from ${model.name}_sdk import ${model.const.Name}SDK
+
+client = ${model.const.Name}SDK(options)
+\`\`\`
+
+Creates a new SDK client.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| \`apikey\` | \`str\` | API key for authentication. |
+| \`base\` | \`str\` | Base URL of the API server. |
+| \`prefix\` | \`str\` | URL path prefix prepended to all requests. |
+| \`suffix\` | \`str\` | URL path suffix appended to all requests. |
+| \`feature\` | \`dict\` | Feature activation flags. |
+| \`extend\` | \`list\` | Additional Feature instances to load. |
+| \`system\` | \`dict\` | System overrides (e.g. custom \`fetch\` function). |
+
+### test
+
+\`\`\`python
+client = ${model.const.Name}SDK.test(testopts, sdkopts)
+\`\`\`
+
+Creates a test-mode client with mock transport. Both arguments may be \`None\`.
+
+### ${model.const.Name}SDK methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`options_map\` | \`() -> dict\` | Deep copy of current SDK options. |
+| \`get_utility\` | \`() -> Utility\` | Copy of the SDK utility object. |
+| \`prepare\` | \`(fetchargs) -> (dict, err)\` | Build an HTTP request definition without sending. |
+| \`direct\` | \`(fetchargs) -> (dict, err)\` | Build and send an HTTP request. |
+`)
+
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}\` | \`(data) -> ${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`
+### Entity interface
+
+All entities share the same interface.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`load\` | \`(reqmatch, ctrl) -> (any, err)\` | Load a single entity by match criteria. |
+| \`list\` | \`(reqmatch, ctrl) -> (any, err)\` | List entities matching the criteria. |
+| \`create\` | \`(reqdata, ctrl) -> (any, err)\` | Create a new entity. |
+| \`update\` | \`(reqdata, ctrl) -> (any, err)\` | Update an existing entity. |
+| \`remove\` | \`(reqmatch, ctrl) -> (any, err)\` | Remove an entity. |
+| \`data_get\` | \`() -> dict\` | Get entity data. |
+| \`data_set\` | \`(data)\` | Set entity data. |
+| \`match_get\` | \`() -> dict\` | Get entity match criteria. |
+| \`match_set\` | \`(match)\` | Set entity match criteria. |
+| \`make\` | \`() -> Entity\` | Create a new instance with the same options. |
+| \`get_name\` | \`() -> str\` | Return the entity name. |
+
+### Result shape
+
+Entity operations return \`(any, err)\`. The first value is a
+\`dict\` with these keys:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`ok\` | \`bool\` | \`True\` if the HTTP status is 2xx. |
+| \`status\` | \`int\` | HTTP status code. |
+| \`headers\` | \`dict\` | Response headers. |
+| \`data\` | \`any\` | Parsed JSON response body. |
+
+On error, \`ok\` is \`False\` and \`err\` contains the error value.
+
+`)
+
+  // Entities summary
+  Content(`### Entities
+
+`)
+  each(entityList, (ent: any) => {
+    const fields = ent.fields || []
+    const opnames = Object.keys(ent.op || {})
+    const ops = ent.op || {}
+    const points = each(ops).map((op: any) =>
+      op.points ? each(op.points) : []
+    ).flat()
+    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+
+    Content(`#### ${ent.Name}
+
+| Field | Description |
+| --- | --- |
+`)
+    each(fields, (field: any) => {
+      Content(`| \`${field.name}\` | ${field.short || ''} |
+`)
+    })
+
+    Content(`
+Operations: ${opnames.map((n: string) => n.charAt(0).toUpperCase() + n.slice(1)).join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}

package/project/.sdk/src/cmp/py/ReadmeQuick_py.ts

@@ -0,0 +1,100 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  const nestedEntity = Object.values(entity).find((e: any) =>
+    e.active !== false && e.ancestors && e.ancestors.length > 0
+  ) as any
+
+  Content(`### 1. Create a client
+
+\`\`\`python
+import os
+from ${model.name}_sdk import ${model.const.Name}SDK
+
+client = ${model.const.Name}SDK({
+    "apikey": os.environ.get("${model.NAME}_APIKEY"),
+})
+\`\`\`
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const opnames = Object.keys(exampleEntity.op || {})
+
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${eName.toLowerCase()}s
+
+\`\`\`python
+result, err = client.${eName}(None).list(None, None)
+if err:
+    raise Exception(err)
+
+if isinstance(result, list):
+    for item in result:
+        d = item.data_get()
+        print(d["id"], d["name"])
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('load')) {
+      Content(`### 3. Load a ${eName.toLowerCase()}
+
+\`\`\`python
+result, err = client.${eName}(None).load({"id": "example_id"}, None)
+if err:
+    raise Exception(err)
+print(result)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      Content(`### 4. Create, update, and remove
+
+\`\`\`python
+`)
+      if (opnames.includes('create')) {
+        Content(`# Create
+created, _ = client.${eName}(None).create({"name": "Example"}, None)
+
+`)
+      }
+      if (opnames.includes('update')) {
+        Content(`# Update
+client.${eName}(None).update({"id": created["id"], "name": "Example-Renamed"}, None)
+
+`)
+      }
+      if (opnames.includes('remove')) {
+        Content(`# Remove
+client.${eName}(None).remove({"id": created["id"]}, None)
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  }
+})
+
+
+export {
+  ReadmeQuick
+}

package/project/.sdk/src/cmp/py/ReadmeTopHowto_py.ts

@@ -0,0 +1,24 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**Python:**
+\`\`\`python
+result, err = client.direct({
+    "path": "/api/resource/{id}",
+    "method": "GET",
+    "params": {"id": "example"},
+})
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

package/project/.sdk/src/cmp/py/ReadmeTopQuick_py.ts

@@ -0,0 +1,56 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  Content(`\`\`\`python
+import os
+from ${model.name}_sdk import ${model.const.Name}SDK
+
+client = ${model.const.Name}SDK({
+    "apikey": os.environ.get("${model.NAME}_APIKEY"),
+})
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const opnames = Object.keys(exampleEntity.op || {})
+
+    if (opnames.includes('list')) {
+      Content(`# List all ${eName.toLowerCase()}s
+${eName.toLowerCase()}s, err = client.${eName}(None).list(None, None)
+`)
+    }
+
+    if (opnames.includes('load')) {
+      Content(`
+# Load a specific ${eName.toLowerCase()}
+${eName.toLowerCase()}, err = client.${eName}(None).load(
+    {"id": "example_id"}, None
+)
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}