@voxgig/sdkgen 1.2.0 → 1.3.1

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 } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,12 +7,26 @@ 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.
+function pyLit(type: any): 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 '"example"'
+}
+
+
 // 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 +55,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 +69,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 +100,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} |
 `)
       })
 
@@ -95,8 +111,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     if (opnames.includes('load')) {
       Content(`#### Example: Load
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+\`\`\`python
+${entity.name} = client.${entity.Name}().load(${idF ? `{"${idF}": "${entity.name}_id"}` : ''})
 \`\`\`
 
 `)
@@ -105,8 +121,8 @@ 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()
 \`\`\`
 
 `)
@@ -115,12 +131,12 @@ const ${entity.name}s = await client.${entity.Name}().list()
     if (opnames.includes('create')) {
       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'} */,
+          Content(`    "${field.name}": ${pyLit(field.type)},  # ${canonToType(field.type, target.name)}
 `)
         }
       })