Your generated SDK publishes as @voxgig-sdk/bookshelf-sdk on npm, voxgig-sdk-bookshelf-sdk on
PyPI, and github.com/voxgig-sdk/bookshelf-sdk/go in Go: names the scaffold derived, not yours. A find
and replace over the output fixes them until the next generate writes them back, and one missed
bookshelf_sdk breaks every Python import.
What you get
You will end up with each package name and import path set in configuration, a tree regenerated from clean, and a consumer per language that imports the package by its new name. This is for you if you publish a generated SDK under your own names.
Short answer
Set the names in the generator’s configuration and regenerate from clean. In sdkgen, four keys in
.sdk/model/project.aontu set the npm and PyPI names and the Go module path and package. The
Python import name follows the project name, so scaffold under the name you want.
openapi-python-client takes project_name_override and package_name_override, and OpenAPI
Generator takes packageName, npmName, and the git options. Then import each package and grep for
the old names.
You will need
Node 22 or later and a generated SDK you can regenerate from clean. Go and Python run the
consumers. This page scaffolds sdkgen projects from the five-operation Bookshelf document with
ts, go, and py targets, and runs the other two generators on the same document. The names
it moves to are @acme/shelf-client, acme-shelf-client, and github.com/acme/shelf-client/go.
read-names.mjs reads each generated tree’s manifests and counts the files that still carry an
old name.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| A post-generation rename script | The generator has no key for the name and you cannot wait for one | It runs after every generate, and any spelling it misses ships under the old name | The generator has a key, which survives regeneration |
| Kiota class name and namespace flags | A Kiota client inside your own project, with no package of its own | --class-name and --namespace-name set the client class and its namespace or module; the using page lists no package-name flag | You publish the client as its own package |
| OpenAPI Generator additional properties | One tool generates several languages, each from its own command line | A different key per generator, and the git options repeated, or placeholders stay | One name should reach every language from one place |
openapi-python-client overrides | A Python client whose distribution and import names you want to set apart | Python only, so every other language’s name lives in another tool’s config | You ship the same SDK in other languages |
| sdkgen project.aontu keys | An sdkgen project whose npm, PyPI, and Go names differ from the derived ones | Four keys cover npm, PyPI, and Go; the Python import follows the project name alone | The Python import must differ from the project name |
Voxgig maintains sdkgen. It is one of five rows here, and its row says where it stops.
A rename script is the option the others exist to replace: it repeats on every run and misses
what it does not spell out. openapi-python-client sets both Python names from two keys and
nothing else. OpenAPI Generator covers more languages at the price of one option set per generator.
sdkgen holds every target’s names in one file, except the Python import.
Read the names sdkgen derives and set your own
A scaffold derives every name from two values in .sdk/model/sdk.aontu: the project name,
bookshelf here, and the origin, voxgig-sdk. The
model reference lists the
keys that override them, and they go in project.aontu, the overlay the scaffold never
overwrites:
# Package names and import paths, held once for every target.
main: kit: repo: { host: 'github.com', path: 'acme/shelf-client' }
main: kit: target: ts: publish: registry: package: '@acme/shelf-client'
main: kit: target: py: publish: registry: package: 'acme-shelf-client'
main: kit: target: go: module: { path: 'github.com/acme/shelf-client/go', package: 'shelfclient' }
generate.sh appended that block to a bookshelf project, generated again, then tried two ways of
renaming the project itself. names.mjs prints what each tree carried.
node names.mjs sdkgen
scaffolded as bookshelf
npm @voxgig-sdk/bookshelf-sdk
PyPI voxgig-sdk-bookshelf-sdk
import py/bookshelf_sdk
Go module github.com/voxgig-sdk/bookshelf-sdk/go
Go package voxgigbookshelfsdk
files naming an old name: @voxgig-sdk/bookshelf-sdk in 4, voxgig-sdk-bookshelf-sdk in 2, github.com/voxgig-sdk/bookshelf-sdk in 66, voxgigbookshelfsdk in 1, bookshelf_sdk in 51
the four keys in project.aontu
npm @acme/shelf-client
PyPI acme-shelf-client
import py/bookshelf_sdk
Go module github.com/acme/shelf-client/go
Go package shelfclient
files naming an old name: bookshelf_sdk in 51
renamed to shelf in sdk.aontu, generated again
npm @acme/shelf-client
PyPI acme-shelf-client
import py/shelf_sdk
Go module github.com/acme/shelf-client/go
Go package shelfclient
files naming an old name: bookshelf_sdk in 1
files left behind in py/bookshelf_sdk: 4
scaffolded as shelf, the same four keys
npm @acme/shelf-client
PyPI acme-shelf-client
import py/shelf_sdk
Go module github.com/acme/shelf-client/go
Go package shelfclient
files naming an old name: none
The four keys moved npm, PyPI, and both Go names, and left the Python import as bookshelf_sdk in
51 files. No key reaches it: 16 of the Python target’s 28 components write it as the project
name plus _sdk, Config_py.ts at line 116 as model.const.Name.toLowerCase() + '_sdk'. Setting
main: kit: target: py: module: name in project.aontu stopped the build with a unification
conflict, because the project’s .sdk/model/target/py.aontu already sets it to 'bookshelf'. @voxgig/sdkgen 4.45.0, which a scaffold does
not install, gave the same 51 files.
So the project name is the lever for Python, and it renames classes in every target with it,
BookshelfSDK to ShelfSDK. Changing it in place in sdk.aontu left four files behind in
py/bookshelf_sdk/: bookshelf_types.py, config.py, schema.py, and utility/prepare_auth.py. Scaffolding under the name shelf with the same four keys left none.
Import each package from a throwaway consumer
generate.sh built and installed each renamed package outside its tree: the TypeScript SDK from
npm pack, the Go module through a replace directive, and the Python packages into
separate virtual environments with uv.
node consumers.mjs
sdkgen, TypeScript, installed from npm pack
ts require("@acme/shelf-client") function
sdkgen, Go, through a replace directive
go import "github.com/acme/shelf-client/go" *core.ShelfSDK
sdkgen, Python, installed with uv
py import shelf_sdk ok: True
py distribution acme-shelf-client 0.0.1
openapi-python-client, Python
py import acme_shelf ok: True
py distribution acme-shelf-client 1.0.0
OpenAPI Generator, Python
py import acme_shelf ok: True
py distribution acme-shelf-client not installed
py distribution acme-shelf 1.0.0
Set the same names in the two other generators
openapi-python-client reads project_name_override and package_name_override from the file
given with --config, as its README documents. The first names the distribution and the output
directory, the second the import package.
project_name_override: acme-shelf-client
package_name_override: acme_shelf
node names.mjs opc
no config
PyPI bookshelf-client
import bookshelf_client
files naming an old name: bookshelf_client in 3, bookshelf-client in 4
opc-config.yaml
PyPI acme-shelf-client
import acme_shelf
files naming an old name: none
OpenAPI Generator takes a different key per generator: packageName for
python and
go, and npmName for
typescript-fetch, which writes
no package.json without it. The Go module path comes from --git-host, --git-user-id, and
--git-repo-id, global options whose placeholders otherwise stay in the README, the push script, or the manifest.
node names.mjs oag
python, no options
PyPI openapi_client
import openapi_client
files naming an old name: openapi_client in 19, GIT_USER_ID in 3, GIT_REPO_ID in 3
python, packageName and projectName
PyPI acme_shelf
import acme_shelf
files naming an old name: GIT_USER_ID in 3, GIT_REPO_ID in 3
go, no options
Go module github.com/GIT_USER_ID/GIT_REPO_ID
Go package openapi
files naming an old name: GIT_USER_ID in 5, GIT_REPO_ID in 5
go, packageName and the three git options
Go module github.com/acme/shelf-client
Go package shelfclient
files naming an old name: none
typescript-fetch, no options
no package manifest
files naming an old name: none
typescript-fetch, npmName
npm @acme/shelf-client
files naming an old name: GIT_USER_ID in 1, GIT_REPO_ID in 1
Check it worked
The test runs read-names.mjs on a small tree it builds, with a test package, a nested module and
a .sdk folder that must not count. It then checks every recorded tree and consumer against the
names in project-names.aontu and opc-config.yaml.
node --test names.test.mjs
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
When it goes wrong
The Python package installs and imports under its old name. The name came from the project, and the keys never reached it. Grep the output for the old import name after every rename.
The old package is still there after a rename. Generating again in the same tree removed most of
py/bookshelf_sdk/ and kept four files, so the tree carries a package nothing generates. Regenerate from
clean, a fresh scaffold or an emptied output directory, before you build.
OpenAPI Generator’s python generator, on its default urllib3 library, installs the package as
acme-shelf, not acme-shelf-client. Its options page scopes projectName to setup.py, and the
pyproject.toml that the installer read takes its name from packageName.1 Set packageName to the import name you want,
and check the distribution name a consumer sees.
GIT_USER_ID stays in the output of a generator run without the git options: three files of the
Python run here, and the package.json of the TypeScript run. Pass the three options to every
generator.
When not to do this
Do not rename with a script over the output when the generator has a key. The next generate puts the old name back, and the script only knows the spellings you gave it.
Do not expect sdkgen’s project file to rename the Python import. If that name must differ from the project name, choose the project name for it at scaffold time, and accept that the class names follow.
openapi-python-client is the cleaner tool for a Python-only client whose distribution name and
import name differ, because it sets both from two keys and left nothing behind here. OpenAPI
Generator fits a team that already drives each language from its own command line or config file,
so a key per generator costs it little.
Do not publish under a new name without a release note. To a consumer, a renamed package is a new dependency, and the old one stops receiving fixes.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen
4.44.3 and 4.45.0, @voxgig/apidef 8.32.4, openapi-python-client 0.30.0, and OpenAPI Generator
7.27.0 on OpenJDK 21.0.13. generate.sh ran once, with network access, on Go 1.24.7 and Python
3.13.18 with uv 0.11.32. It generated every tree, built and installed each consumer, and wrote
the JSON and text records under generated/. The gate re-runs only the commands on this page,
which print those records, and the test. Kiota was not run for this page; its flags come from its
using page.
Footnotes
-
Python’s name normalization rule puts a name in lowercase and replaces every run of
.,-, and_with one-, soacme_shelfandacme-shelfare one distribution to an installer.acme-shelf-clientnormalizes to itself, so the rule leaves it a different name. ↩︎ Back to text