@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -9,6 +9,12 @@ import {
 import { EntityOperation } from './EntityOperation_py'
 
 
+// Op -> generated request-type suffix (keep in sync with EntityTypes_py.ts).
+const OP_SUFFIX: Record<string, 'Match' | 'Data'> = {
+  load: 'Match', list: 'Match', remove: 'Match', create: 'Data', update: 'Data',
+}
+
+
 const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
@@ -19,6 +25,22 @@ const Entity = cmp(function Entity(props: any) {
 
   names(entrep, entity.Name, 'EntityName')
 
+  // Import exactly the typed models this entity references: its data type plus
+  // one request type per ACTIVE op (matches what EntityTypes_py.ts emits).
+  const typeNames = [entity.Name]
+  const opnamesAll = Object.keys(entity.op || {})
+  ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+    if (opnamesAll.includes(opname)) {
+      const suffix = OP_SUFFIX[opname] || 'Match'
+      const cap = opname.charAt(0).toUpperCase() + opname.slice(1)
+      typeNames.push(entity.Name + cap + suffix)
+    }
+  })
+  const typesModule = model.const.Name.toLowerCase() + '_types'
+  const typeImport =
+    'from ' + typesModule + ' import (\n    ' +
+    typeNames.join(',\n    ') + ',\n)'
+
   const ff = Path.normalize(__dirname + '/../../../src/cmp/py/fragment/')
 
   // Entity files go to entity/ folder
@@ -44,6 +66,11 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
+          // Literal-marker slot (jostraca's `#Name` tag pattern is hardcoded to
+          // `//` comments, so Python uses a `# #`-prefixed literal like the op
+          // frag slots) — fills in the typed-model import for this entity.
+          '# #TypeImports': typeImport,
+
           '#Entity-Hook': ({ name, indent }: any) =>
             Content({ indent }, `utility.feature_hook(ctx, "${name}")`),
 

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

@@ -8,7 +8,8 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { model } = props.ctx$
 
   Content(`
-    def ${entity.Name}(self, data=None):
+    def ${entity.Name}(self, data=None) -> "${entity.Name}Entity":
+        """Entity factory: client.${entity.Name}().list() / client.${entity.Name}().load({"id": ...})."""
         from entity.${entity.name}_entity import ${entity.Name}Entity
         return ${entity.Name}Entity(self, data)
 

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

@@ -22,6 +22,7 @@ import { Package } from './Package_py'
 import { Config } from './Config_py'
 import { Gitignore } from './Gitignore_py'
 import { MainEntity } from './MainEntity_py'
+import { EntityTypes } from './EntityTypes_py'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -77,6 +78,35 @@ self._utility.feature_hook(self._rootctx, "${name}")
           MainEntity(entprops)
         })
       })
+
+    // Type-checker-only imports for the entity factory return annotations
+    // (def <Entity>(...) -> "<Entity>Entity"). Guarded by TYPE_CHECKING so
+    // there is no eager runtime import (the factories still import lazily in
+    // their bodies); this lets mypy resolve list()/load() return types on
+    // client.<Entity>() results — e.g. flagging `.data` on a list() result.
+    const entnames = each(entity)
+    if (entnames.length > 0) {
+      Content(`
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+`)
+      each(entity, (ent: any) => {
+        Content(`    from entity.${ent.name}_entity import ${ent.Name}Entity
+`)
+      })
+    }
+  })
+
+  // Generate the typed-model module (<sdk>_types.py) next to the main SDK file.
+  EntityTypes({ target })
+
+  // PEP 561 marker so the inline type hints ship to consumers. Emitted at the
+  // language root (documents intent for the top-level modules) and inside the
+  // entity package (the type-bearing package, included via package-data).
+  File({ name: 'py.typed' }, () => {
+    Content(``)
   })
 
   // Generate config module
@@ -137,6 +167,11 @@ def _make_feature(name):
     File({ name: '__init__.' + target.ext }, () => {
       Content(``)
     })
+    // PEP 561 marker inside the type-bearing package so setuptools package-data
+    // ("*" = ["py.typed"]) bundles it into the wheel.
+    File({ name: 'py.typed' }, () => {
+      Content(``)
+    })
   })
 
   Folder({ name: 'feature' }, () => {

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

@@ -4,6 +4,9 @@ import {
   File,
   cmp,
   collectDeps,
+  pkgDescription,
+  keywords,
+  repoInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -24,6 +27,8 @@ const Package = cmp(async function Package(props: any) {
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const distName = `${ns}-${pkgBase}`
+  const { repoUrl, issuesUrl } = repoInfo(model)
+  const kw = keywords(model).map((k) => `"${k}"`).join(', ')
 
   File({ name: 'pyproject.toml' }, () => {
     Content(`[build-system]
@@ -33,14 +38,18 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "${distName}"
 version = "0.0.1"
-description = "${model.const.Name} SDK for Python"
+description = "${pkgDescription(model, 'py')}"
+readme = "README.md"
 license = "MIT"
 requires-python = ">=3.8"
+keywords = [${kw}]
 dependencies = [
-    "requests>=2.33",
 `)
 
+    const seen = new Set<string>()
     for (const d of collectDeps(model, target.name, target.deps)) {
+      if (seen.has(d.name)) continue
+      seen.add(d.name)
       const v = d.source === 'target' ? (d.version || '0.0') : d.version
       Content(`    "${d.name}>=${v}",
 `)
@@ -49,12 +58,24 @@ dependencies = [
     Content(`]
 
 [project.urls]
-Homepage = "https://github.com/voxgig/${model.name}-sdk"
+Homepage = "${repoUrl}"
+Repository = "${repoUrl}"
+Issues = "${issuesUrl}"
+
+# Ship the top-level single-file modules (setuptools find only discovers
+# package dirs, never these) so the documented import actually installs.
+# ${model.const.Name.toLowerCase()}_types holds the generated @dataclass models.
+[tool.setuptools]
+py-modules = ["${model.const.Name.toLowerCase()}_sdk", "${model.const.Name.toLowerCase()}_types", "config", "features"]
 
 # Explicit package list — setuptools auto-discovery refuses to pick when
 # multiple top-level dirs (core/entity/feature/utility) are present.
 [tool.setuptools.packages.find]
 include = ["core*", "entity*", "feature*", "utility*"]
+
+# Ship the PEP 561 py.typed marker(s) so the inline type hints reach consumers.
+[tool.setuptools.package-data]
+"*" = ["py.typed"]
 `)
   })
 })

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,12 +7,27 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, JSON-serialisable Python literal for a field's canonical
+// type. The create example is EXECUTED by the doc test (the body is
+// JSON-serialised), so an Ellipsis (`...`) placeholder would raise
+// "Object of type ellipsis is not JSON serializable" — use a real value.
+// Strings render the quoted placeholder.
+function pyLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'True'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return `"${placeholder}"`
+}
+
+
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
 // methods with optional ctrl. The op descriptions are language-agnostic.
 const OP_DESC: Record<string, { method: string, desc: string }> = {
   load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
-  list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
+  list:   { method: 'list()',        desc: 'List entities, optionally matching the given criteria.' },
   create: { method: 'create(data)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(data)',  desc: 'Update an existing entity.' },
   remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
@@ -41,6 +56,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
     const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
 
     Content(`
 ### ${entity.Name}
@@ -53,7 +70,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+    Content(`Create an instance: \`${entity.name} = client.${entity.Name}()\`
 
 `)
 
@@ -84,7 +101,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
       each(fields, (field: any) => {
         const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
 `)
       })
 
@@ -93,10 +110,22 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{${loadItems.map((it: any) =>
+          `"${it.name}": ${pyLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')}}`
+        : ''
       Content(`#### Example: Load
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+\`\`\`python
+${entity.name} = client.${entity.Name}().load(${loadArg})
 \`\`\`
 
 `)
@@ -105,24 +134,29 @@ const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_
     if (opnames.includes('list')) {
       Content(`#### Example: List
 
-\`\`\`ts
-const ${entity.name}s = await client.${entity.Name}().list()
+\`\`\`python
+${entity.name}s = client.${entity.Name}().list()
 \`\`\`
 
 `)
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id — with a real, executable
+      // literal (the doc test RUNS this block, so a comment placeholder
+      // would break it).
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().create({
+\`\`\`python
+${entity.name} = client.${entity.Name}().create({
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+      createItems.map((it: any) => {
+        Content(`    "${it.name}": ${pyLit(it.type, 'example_' + it.name)},  # ${canonToType(it.type, target.name)}
 `)
-        }
       })
       Content(`})
 \`\`\`