How-to › Ship an SDK

How to rename a generated SDK package and its import path#

Set the npm, PyPI, and Go names of a generated SDK in configuration, regenerate from clean, install each package in a throwaway consumer, and grep for the old names.

Audience
Library maintainer
Level
intermediate
Topic
Customize a generator without forking
Languages
TypeScript, Go and Python
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
A post-generation rename scriptThe generator has no key for the name and you cannot wait for oneIt runs after every generate, and any spelling it misses ships under the old nameThe generator has a key, which survives regeneration
Kiota class name and namespace flagsA 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 flagYou publish the client as its own package
OpenAPI Generator additional propertiesOne tool generates several languages, each from its own command lineA different key per generator, and the git options repeated, or placeholders stayOne name should reach every language from one place
openapi-python-client overridesA Python client whose distribution and import names you want to set apartPython only, so every other language’s name lives in another tool’s configYou ship the same SDK in other languages
sdkgen project.aontu keysAn sdkgen project whose npm, PyPI, and Go names differ from the derived onesFour keys cover npm, PyPI, and Go; the Python import follows the project name aloneThe 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.

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

  1. Python’s name normalization rule puts a name in lowercase and replaces every run of ., -, and _ with one -, so acme_shelf and acme-shelf are one distribution to an installer. acme-shelf-client normalizes to itself, so the rule leaves it a different name. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.