@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,31 +7,44 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, JSON-serialisable Python literal — never an Ellipsis (`...`),
+// which is not JSON-serialisable when a create body is executed by the doc
+// test. 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}"`
+}
+
+
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'load(reqmatch, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'Load a single entity matching the given criteria.',
+    sig: 'load(reqmatch, ctrl=None) -> dict',
+    returns: 'the entity data',
+    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
   },
   list: {
-    sig: 'list(reqmatch, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    sig: 'list(reqmatch=None, ctrl=None) -> list',
+    returns: 'a list of entities',
+    desc: 'List entities matching the given criteria. The match is optional — call `list()` with no argument to list all records. Returns a list and raises on error.',
   },
   create: {
-    sig: 'create(reqdata, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'Create a new entity with the given data.',
+    sig: 'create(reqdata, ctrl=None) -> dict',
+    returns: 'the created entity data',
+    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
   },
   update: {
-    sig: 'update(reqdata, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    sig: 'update(reqdata, ctrl=None) -> dict',
+    returns: 'the updated entity data',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
   },
   remove: {
-    sig: 'remove(reqmatch, ctrl=None) -> tuple',
-    returns: '(result, err)',
-    desc: 'Remove the entity matching the given criteria.',
+    sig: 'remove(reqmatch, ctrl=None) -> dict',
+    returns: 'the removed entity data',
+    desc: 'Remove the entity matching the given criteria. Raises on error.',
   },
 }
 
@@ -60,7 +73,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
 `)
 
     Content(`\`\`\`python
-from ${model.name}_sdk import ${model.const.Name}SDK
+from ${model.const.Name.toLowerCase()}_sdk import ${model.const.Name}SDK
 
 client = ${model.const.Name}SDK(options)
 \`\`\`
@@ -72,8 +85,7 @@ Create a new SDK client instance.
 | Name | Type | Description |
 | --- | --- | --- |
 | \`options\` | \`dict\` | SDK configuration options. |
-| \`options["apikey"]\` | \`str\` | API key for authentication. |
-| \`options["base"]\` | \`str\` | Base URL for API requests. |
+${isAuthActive(model) ? '| \`options["apikey"]\` | \`str\` | API key for authentication. |\n' : ''}| \`options["base"]\` | \`str\` | Base URL for API requests. |
 | \`options["prefix"]\` | \`str\` | URL prefix appended after base. |
 | \`options["suffix"]\` | \`str\` | URL suffix appended after path. |
 | \`options["headers"]\` | \`dict\` | Custom headers for all requests. |
@@ -123,9 +135,9 @@ Return a deep copy of the current SDK options.
 
 Return a copy of the SDK utility object.
 
-#### \`direct(fetchargs=None) -> tuple\`
+#### \`direct(fetchargs=None) -> dict\`
 
-Make a direct HTTP request to any API endpoint. Returns \`(result, err)\`.
+Make a direct HTTP request to any API endpoint. Returns a result \`dict\` with \`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure). This escape hatch never raises — branch on \`result["ok"]\`.
 
 **Parameters:**
 
@@ -138,11 +150,11 @@ Make a direct HTTP request to any API endpoint. Returns \`(result, err)\`.
 | \`fetchargs["headers"]\` | \`dict\` | Request headers (merged with defaults). |
 | \`fetchargs["body"]\` | \`any\` | Request body (dicts are JSON-serialized). |
 
-**Returns:** \`(result_dict, err)\`
+**Returns:** \`result_dict\`
 
-#### \`prepare(fetchargs=None) -> tuple\`
+#### \`prepare(fetchargs=None) -> dict\`
 
-Prepare a fetch definition without sending. Returns \`(fetchdef, err)\`.
+Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises on error.
 
 `)
 
@@ -151,6 +163,9 @@ Prepare a fetch definition without sending. Returns \`(fetchdef, err)\`.
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = ent.fields || []
+      // Model-driven id key: null when this entity has no id-like field, in
+      // which case load/remove match on no argument and update omits the id.
+      const idF = entityIdField(ent)
 
       Content(`
 ---
@@ -182,7 +197,7 @@ ${ent.name} = client.${ent.Name}()
         each(fields, (field: any) => {
           const req = field.req ? 'Yes' : 'No'
           const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${req} | ${desc} |
+          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -192,15 +207,18 @@ ${ent.name} = client.${ent.Name}()
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
+          // Only emit columns for operations this entity actually exposes —
+          // never advertise a create/update/remove column the entity lacks.
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
-| Field | load | list | create | update | remove |
-| --- | --- | --- | --- | --- | --- |
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
 `)
           each(fields, (field: any) => {
             const fops = field.op || {}
-            const cols = ['load', 'list', 'create', 'update', 'remove'].map((op: string) => {
-              if (!opnames.includes(op)) return '-'
+            const cols = opcols.map((op: string) => {
               const fop = fops[op]
               if (null == fop) return '-'
               if (fop.active === false) return '-'
@@ -232,30 +250,50 @@ ${info.desc}
 
 `)
 
-          // Show example
+          // Show example. Entity ops return the bare result and raise on
+          // error; direct() is the only method that returns a result dict.
           if ('load' === opname || 'remove' === opname) {
+            // 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 matchItems = opRequestShape(ent, opname).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 arg = 0 < matchItems.length
+              ? `{${matchItems.map((it: any) =>
+                `"${it.name}": ${pyLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')}}`
+              : ''
             Content(`\`\`\`python
-result, err = client.${ent.Name}().${opname}({"id": "${ent.name}_id"})
+result = client.${ent.Name}().${opname}(${arg})
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`python
-results, err = client.${ent.Name}().list({})
+results = client.${ent.Name}().list()
+for ${ent.name} in results:
+    print(${ent.name})
 \`\`\`
 
 `)
           }
           else if ('create' === opname) {
+            // 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(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`python
-result, err = client.${ent.Name}().create({
+result = client.${ent.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(`})
 \`\`\`
@@ -263,10 +301,18 @@ result, err = client.${ent.Name}().create({
 `)
           }
           else if ('update' === opname) {
+            // The id key plus every REQUIRED data member — the same shape the
+            // runtime validates — then the patch-fields note.
+            const updateItems = opRequestShape(ent, 'update').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 updateLines = updateItems.map((it: any) =>
+              `    "${it.name}": ${pyLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`python
-result, err = client.${ent.Name}().update({
-    "id": "${ent.name}_id",
-    # Fields to update
+result = client.${ent.Name}().update({
+${updateLines}    # Fields to update
 })
 \`\`\`
 

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

@@ -7,7 +7,7 @@ const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
 
   Content(`**Python:**
 \`\`\`python
-result, err = client.direct({
+result = client.direct({
     "path": "/api/resource/{id}",
     "method": "GET",
     "params": {"id": "example"},

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,20 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, executable Python literal for a param: numeric/boolean/
+// array/object params render a typed literal; strings render the quoted
+// placeholder (the doc test EXECUTES this block, so a comment placeholder
+// would break it).
+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}"`
+}
+
+
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -17,34 +31,54 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const authActive = isAuthActive(model)
   const apikeyImport = authActive ? `import os\n` : ''
-  const apikeyArg = authActive
-    ? `\n    "apikey": os.environ.get("${model.NAME}_APIKEY"),\n`
-    : ''
+  const ctor = authActive
+    ? `${model.const.Name}SDK({\n    "apikey": os.environ.get("${envName(model)}_APIKEY"),\n})`
+    : `${model.const.Name}SDK()`
 
   Content(`\`\`\`python
 ${apikeyImport}from ${model.const.Name.toLowerCase()}_sdk import ${model.const.Name}SDK
 
-client = ${model.const.Name}SDK({${apikeyArg}})
+client = ${ctor}
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field, in which
+    // case the load example takes no match argument.
+    const idF = entityIdField(exampleEntity)
+
+    let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`# List all ${eName.toLowerCase()}s
-${eName.toLowerCase()}s, err = client.${eName}(None).list(None, None)
+      Content(`# List all ${eName.toLowerCase()}s (returns a list, raises on error)
+${eName.toLowerCase()}s = client.${eName}().list()
+for ${eName.toLowerCase()} in ${eName.toLowerCase()}s:
+    print(${eName.toLowerCase()})
 `)
+      hasCall = true
     }
 
     if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(exampleEntity, '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 ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
+        : ''
       Content(`
-# Load a specific ${eName.toLowerCase()}
-${eName.toLowerCase()}, err = client.${eName}(None).load(
-    {"id": "example_id"}, None
-)
+# Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+${eName.toLowerCase()} = client.${eName}().load(${loadArg})
+print(${eName.toLowerCase()})
 `)
+      hasCall = true
     }
   }
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,17 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct Python literal for a field's canonical type.
+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"'
+}
+
+
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -16,14 +27,41 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
   Content(`\`\`\`python
-client = ${model.const.Name}SDK.test(None, None)
+client = ${model.const.Name}SDK.test()
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`result, err = client.${eName}(None).load(
-    {"id": "test01"}, None
-)
+    // Drive the test-mode example off the entity's PRIMARY op (never a
+    // hardcoded `load` a create-only entity lacks).
+    const idF = entityIdField(exampleEntity)
+    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = ''
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's Match type, so the block also satisfies the mypy doc gate.
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      arg = 0 < items.length
+        ? `{${items.map((it: any) =>
+          `"${it.name}": ${it.name === idF ? '"test01"' : pyLit(it.type)}`).join(', ')}}`
+        : ''
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      arg = `{${chosen.map((it: any) => `"${it.name}": ${pyLit(it.type)}`).join(', ')}}`
+    }
+    // A list() result is a list — name the variable accordingly (the root
+    // README doc gate concatenates blocks, so reusing the singular name for
+    // a different type is a mypy assignment error).
+    const eVar = eName.toLowerCase() + ('list' === primaryOp ? 's' : '')
+    Content(`${eVar} = client.${eName}().${primaryOp}(${arg})
+print(${eVar})
 `)
   }
 

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

@@ -192,7 +192,7 @@ ${listSkipBlock}        client = setup["client"]
 `)
         }
         Content(`
-        result, err = client.direct({
+        result = client.direct({
             "path": "${listPath}",
             "method": "GET",
             "params": params,
@@ -200,7 +200,7 @@ ${listSkipBlock}        client = setup["client"]
 `)
       } else {
         Content(`
-        result, err = client.direct({
+        result = client.direct({
             "path": "${listPath}",
             "method": "GET",
             "params": {},
@@ -212,8 +212,8 @@ ${listSkipBlock}        client = setup["client"]
             # Live mode is lenient: synthetic IDs frequently 4xx and the
             # list-response shape varies wildly across public APIs. Skip
             # rather than fail when the call doesn't return a usable list.
-            if err is not None:
-                pytest.skip(f"list call failed (likely synthetic IDs against live API): {err}")
+            if result.get("err") is not None:
+                pytest.skip(f"list call failed (likely synthetic IDs against live API): {result.get('err')}")
                 return
             if not result.get("ok"):
                 pytest.skip("list call not ok (likely synthetic IDs against live API)")
@@ -223,7 +223,6 @@ ${listSkipBlock}        client = setup["client"]
                 pytest.skip(f"expected 2xx status, got {status}")
                 return
         else:
-            assert err is None
             assert result["ok"] is True
             assert helpers.to_int(result["status"]) == 200
             assert isinstance(result["data"], list)
@@ -291,7 +290,7 @@ ${loadLiveQueryLines}
       }
 
       Content(`
-        result, err = client.direct({
+        result = client.direct({
             "path": "${loadPath}",
             "method": "GET",
 `)
@@ -308,8 +307,8 @@ ${loadLiveQueryLines}
             # Live mode is lenient: synthetic IDs frequently 4xx. Skip
             # rather than fail when the load endpoint isn't reachable
             # with the IDs we can construct from setup.idmap.
-            if err is not None:
-                pytest.skip(f"load call failed (likely synthetic IDs against live API): {err}")
+            if result.get("err") is not None:
+                pytest.skip(f"load call failed (likely synthetic IDs against live API): {result.get('err')}")
                 return
             if not result.get("ok"):
                 pytest.skip("load call not ok (likely synthetic IDs against live API)")
@@ -319,7 +318,6 @@ ${loadLiveQueryLines}
                 pytest.skip(f"expected 2xx status, got {status}")
                 return
         else:
-            assert err is None
             assert result["ok"] is True
             assert helpers.to_int(result["status"]) == 200
             assert result["data"] is not None

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

@@ -272,9 +272,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
   const hasEntIdC = null != ctx.entity.id
 
   Content(`
-        ${datavar}_result, err = ${entvar}.create(${datavar}, None)
-        assert err is None
-        ${datavar} = helpers.to_map(${datavar}_result)
+        ${datavar} = helpers.to_map(${entvar}.create(${datavar}, None))
         assert ${datavar} is not None
 `)
   if (hasEntIdC) {
@@ -318,8 +316,7 @@ const generateList: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-        ${listvar}_result, err = ${entvar}.list(${matchvar}, None)
-        assert err is None
+        ${listvar}_result = ${entvar}.list(${matchvar}, None)
         assert isinstance(${listvar}_result, list)
 `)
 
@@ -407,9 +404,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-        ${resdatavar}_result, err = ${entvar}.update(${datavar}_up, None)
-        assert err is None
-        ${resdatavar} = helpers.to_map(${resdatavar}_result)
+        ${resdatavar} = helpers.to_map(${entvar}.update(${datavar}_up, None))
         assert ${resdatavar} is not None
 `)
   if (hasEntIdU) {
@@ -472,8 +467,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
     Content(`        ${matchvar} = {
             "id": ${srcdatavar}["id"],
         }
-        ${datavar}_loaded, err = ${entvar}.load(${matchvar}, None)
-        assert err is None
+        ${datavar}_loaded = ${entvar}.load(${matchvar}, None)
         ${datavar}_load_result = helpers.to_map(${datavar}_loaded)
         assert ${datavar}_load_result is not None
         assert ${datavar}_load_result["id"] == ${srcdatavar}["id"]
@@ -481,8 +475,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
   }
   else {
     Content(`        ${matchvar} = {}
-        ${datavar}_loaded, err = ${entvar}.load(${matchvar}, None)
-        assert err is None
+        ${datavar}_loaded = ${entvar}.load(${matchvar}, None)
         assert ${datavar}_loaded is not None
 `)
   }
@@ -510,8 +503,7 @@ const generateRemove: OpGen = (ctx, step, index) => {
   Content(`        ${matchvar} = {
             "id": ${srcdatavar}["id"],
         }
-        _, err = ${entvar}.remove(${matchvar}, None)
-        assert err is None
+        ${entvar}.remove(${matchvar}, None)
 `)
 }
 

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

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_py'
 import { TestDirect } from './TestDirect_py'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_py'
 
 
 const Test = cmp(function Test(props: any) {
@@ -46,6 +47,9 @@ class TestExists:
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // Validate the documented python examples in the root README.
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/py/fragment/Entity.fragment.py

@@ -1,7 +1,10 @@
 # ProjectName SDK EntityName entity
 
+from __future__ import annotations
+
 from utility.voxgig_struct import voxgig_struct as vs
 from core import helpers
+# #TypeImports
 
 
 class EntityNameEntity:
@@ -44,7 +47,7 @@ class EntityNameEntity:
             self._data = helpers.to_map(vs.clone(args)) or {}
             self._utility.feature_hook(self._entctx, "SetData")
 
-    def data_get(self):
+    def data_get(self) -> EntityName:
         self._utility.feature_hook(self._entctx, "GetData")
         return vs.clone(self._data)
 
@@ -53,7 +56,7 @@ class EntityNameEntity:
             self._match = helpers.to_map(vs.clone(args)) or {}
             self._utility.feature_hook(self._entctx, "SetMatch")
 
-    def match_get(self):
+    def match_get(self) -> EntityName:
         self._utility.feature_hook(self._entctx, "GetMatch")
         return vs.clone(self._match)
 

package/project/.sdk/src/cmp/py/fragment/EntityCreateOp.fragment.py

@@ -5,7 +5,7 @@ entity_create_op = None
 
 # EJECT-START
 
-    def create(self, reqdata, ctrl=None):
+    def create(self, reqdata: EntityNameCreateData, ctrl=None) -> EntityName:
         utility = self._utility
         ctx = utility.make_context({
             "opname": "create",

package/project/.sdk/src/cmp/py/fragment/EntityListOp.fragment.py

@@ -2,8 +2,12 @@ entity_list_op = None
 
 # EJECT-START
 
-    def list(self, reqmatch, ctrl=None):
+    def list(self, reqmatch=None, ctrl=None) -> list[EntityName]:
         utility = self._utility
+        # reqmatch is optional: an omitted match lists all records. Treat None
+        # as an empty match so client.EntityName().list() works with no args.
+        if reqmatch is None:
+            reqmatch = {}
         ctx = utility.make_context({
             "opname": "list",
             "ctrl": ctrl,

package/project/.sdk/src/cmp/py/fragment/EntityLoadOp.fragment.py

@@ -5,8 +5,13 @@ entity_load_op = None
 
 # EJECT-START
 
-    def load(self, reqmatch, ctrl=None):
+    def load(self, reqmatch=None, ctrl=None) -> EntityName:
         utility = self._utility
+        # reqmatch is optional: an entity with no id-like key loads with no
+        # match. Treat None as an empty match so client.EntityName().load()
+        # works with no args.
+        if reqmatch is None:
+            reqmatch = {}
         ctx = utility.make_context({
             "opname": "load",
             "ctrl": ctrl,

package/project/.sdk/src/cmp/py/fragment/EntityRemoveOp.fragment.py

@@ -5,8 +5,13 @@ entity_remove_op = None
 
 # EJECT-START
 
-    def remove(self, reqmatch, ctrl=None):
+    def remove(self, reqmatch=None, ctrl=None) -> EntityName:
         utility = self._utility
+        # reqmatch is optional: an entity with no id-like key removes with no
+        # match. Treat None as an empty match so client.EntityName().remove()
+        # works with no args.
+        if reqmatch is None:
+            reqmatch = {}
         ctx = utility.make_context({
             "opname": "remove",
             "ctrl": ctrl,

package/project/.sdk/src/cmp/py/fragment/EntityUpdateOp.fragment.py

@@ -5,7 +5,7 @@ entity_update_op = None
 
 # EJECT-START
 
-    def update(self, reqdata, ctrl=None):
+    def update(self, reqdata: EntityNameUpdateData, ctrl=None) -> EntityName:
         utility = self._utility
         ctx = utility.make_context({
             "opname": "update",