Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
changeKind: internal
packages:
- "@typespec/http-client-python"
---

Add usage examples for the `generation-subdir` emitter option in the docs.
66 changes: 30 additions & 36 deletions packages/http-client-python/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Welcome! This guide will help you set up your development environment and contri

Before you begin, ensure you have the following installed:

- [Node.js](https://nodejs.org/) (version 18 or higher)
- [Node.js](https://nodejs.org/) (version 22 or higher)
- [npm](https://www.npmjs.com/) (comes with Node.js)
- [pnpm](https://pnpm.io/) (for workspace management)
- [Git](https://git-scm.com/)
Expand Down Expand Up @@ -85,6 +85,24 @@ npm run ci
- Run linting: `npm run lint`
- Format code: `npm run format`

### Updating Emitter Option Documentation

The emitter options documentation is **auto-generated** — do not edit it by hand.

- The single source of truth is the option definitions in [`emitter/src/lib.ts`](./emitter/src/lib.ts). Update the `description` (and other schema fields) there.
- Running `npm run regen-docs` regenerates **both** targets from that source:
- This package's [`README.md`](./README.md) (the `Emitter options` section).
- The website reference docs under `website/src/content/docs/docs/emitters/clients/http-client-python/reference/`.

Because `regen-docs` reads the **compiled** emitter, always build first:

```bash
npm run build
npm run regen-docs
```

If you edit `lib.ts` but skip `npm run build`, `regen-docs` will regenerate from the stale `dist/` output and your changes won't appear.

## Creating Pull Requests

### 1. Prepare Your PR
Expand All @@ -95,7 +113,7 @@ Before creating a pull request:
- [ ] Ensure code is properly formatted: `npm run format`
- [ ] Ensure code is properly linted: `npm run lint`
- [ ] Add a changeset: `pnpm change add` (from repo root)
- [ ] Update documentation if needed
- [ ] Update documentation if needed (if you changed emitter options in `lib.ts`, run `npm run build && npm run regen-docs` — see [Updating Emitter Option Documentation](#updating-emitter-option-documentation))

### 2. Create the PR

Expand All @@ -119,45 +137,19 @@ Both must pass before your PR can be merged.

### Manual Regeneration Testing

You can manually trigger the [TypeSpec Python Regenerate Tests](https://github.com/Azure/azure-sdk-for-python/actions/workflows/typespec-python-regenerate.yml) workflow in `azure-sdk-for-python` to regenerate tests with either emitter:

- **Branded** (`@azure-tools/typespec-python`): Select "branded" and optionally specify a version. If no version is given, it uses the version from [`eng/emitter-package.json`](https://github.com/Azure/azure-sdk-for-python/blob/main/eng/emitter-package.json).
- **Unbranded** (`@typespec/http-client-python`): Select "unbranded" and optionally specify a version. If no version is given, it uses the latest published version on npm.

The workflow checks out `microsoft/typespec` (at the ref you specify, defaulting to `main`), builds the regeneration infrastructure, installs the target emitter from npm, and runs the full regeneration.
You can manually trigger the [TypeSpec Python Regenerate Tests](https://github.com/Azure/azure-sdk-for-python/actions/workflows/typespec-python-regenerate.yml) workflow in `azure-sdk-for-python` to regenerate tests. The workflow checks out `microsoft/typespec` (at the ref you specify, defaulting to `main`), builds the regeneration infrastructure, installs the target emitter from npm, and runs the full regeneration.

### Post-Release: Updating azure-sdk-for-python

Once a new version of the branded emitter (`@azure-tools/typespec-python`) is released, follow these steps to update `azure-sdk-for-python`:
Once a new version of this emitter is released, follow these steps to update `azure-sdk-for-python`:

1. **Update `eng/emitter-package.json`** in [Azure/azure-sdk-for-python](https://github.com/Azure/azure-sdk-for-python):
1. Follow skill [emitter-package-update](https://github.com/Azure/azure-sdk-for-python/tree/main/.github/skills/emitter-package-update) to **create a PR** to update `eng/emitter-package.json` and `eng/emitter-package-lock.json` and submit them to `azure-sdk-for-python`.

Update the `@azure-tools/typespec-python` version to the newly released version:
2. **Automatic regeneration**: Once the PR merges to `main`, the [TypeSpec Python Regenerate Tests](https://github.com/Azure/azure-sdk-for-python/actions/workflows/typespec-python-regenerate.yml) workflow triggers automatically (it watches for changes to `eng/emitter-package.json`). It regenerates all test code and creates a follow-up issue with the updated generated files.

```json
{
"dependencies": {
"@azure-tools/typespec-python": "<new-version>"
}
}
```

2. **Regenerate config files** using `tsp-client`:

```bash
tsp-client generate-config-files \
--package-json= < path-to-local-typespec-azure > /packages/typespec-python/package.json
```

This updates the `devDependencies` in `eng/emitter-package.json` to match the branded emitter's peer dependencies.

3. **Create a PR** with the updated `eng/emitter-package.json` and submit it to `azure-sdk-for-python`.

4. **Automatic regeneration**: Once the PR merges to `main`, the [TypeSpec Python Regenerate Tests](https://github.com/Azure/azure-sdk-for-python/actions/workflows/typespec-python-regenerate.yml) workflow triggers automatically (it watches for changes to `eng/emitter-package.json`). It regenerates all test code and creates a follow-up PR with the updated generated files.

5. **Generated code location**: The regenerated tests are checked in at [`eng/tools/azure-sdk-tools/emitter/generated/`](https://github.com/Azure/azure-sdk-for-python/tree/main/eng/tools/azure-sdk-tools/emitter/generated) in `azure-sdk-for-python`, split into:
- `azure/` — Tests generated with the branded emitter (Azure SDK specs)
- `unbranded/` — Tests generated with the unbranded emitter (TypeSpec HTTP specs)
3. **Generated code location**: The regenerated tests are checked in at [`eng/tools/azure-sdk-tools/emitter/generated`](https://github.com/Azure/azure-sdk-for-python/tree/typespec-python-generated-tests/eng/tools/azure-sdk-tools/emitter/generated) in `azure-sdk-for-python`, split into:
- `azure/` — Tests generated with the branded emitter (Azure HTTP specs)
- `unbranded/` — Tests generated with the unbranded emitter (HTTP specs)

## Release Process

Expand All @@ -175,13 +167,15 @@ This consumes all pending change files under `.chronus/changes/` for this packag

### 2. Create a Release PR

Create a branch from the version bump commit and open a PR to `main`:
Create a branch from the version bump commit, push it, and open a PR to `main`:

```bash
git checkout -b publish/python-release-<MM-DD>
git push origin publish/python-release-<MM-DD>
```

Then open a pull request targeting `main` (for example, via the GitHub UI or `gh pr create --base main`).

> **Note:** The branch **must** use the `publish/` prefix. This tells CI to skip certain checks (consistency, external-integration) and enables auto-publish on merge.

### 3. Merge and Publish
Expand Down
28 changes: 25 additions & 3 deletions packages/http-client-python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,9 @@ See [Configuring output directory for more info](https://typespec.io/docs/handbo

### `api-version`

**Type:** `string`
**Type:** `undefined`

Use this flag if you would like to generate the sdk only for a specific version. Default value is the latest version. Also accepts values `latest` and `all`.
Use this flag if you would like to generate the sdk only for a specific version. Default value is the latest version. Also accepts values `latest` and `all`. For multi-service packages, provide a map from each service namespace's full name to its desired version; services not listed default to their latest version.

### `license`

Expand Down Expand Up @@ -112,16 +112,38 @@ Whether to validate the versioning of the package. Defaults to `true`. If set to

**Type:** `string`

The subdirectory to generate the code in. If not specified, the code will be generated in the root folder. Note: if you're using this flag, you will need to add and maintain the versioning file yourself.
The subdirectory (relative to the package namespace folder) to generate the code in. Use this to keep emitter-generated code separate from hand-written/customized code, so regeneration only overwrites the subdirectory and leaves your customizations untouched. If not specified, the code is generated directly in the package namespace folder. Note: if you're using this flag, you will need to add and maintain the versioning file (`_version.py`) yourself.

Example: for `namespace: azure.storage.blob` with `generation-subdir: _generated`, generated code lands in `azure/storage/blob/_generated/` while your customized code lives in `azure/storage/blob/`. A typical `tspconfig.yaml` looks like:

```yaml
options:
"@azure-tools/typespec-python":
emitter-output-dir: "{output-dir}/{service-dir}/azure-storage-blob"
namespace: "azure.storage.blob"
generation-subdir: "_generated"
```

### `keep-setup-py`

**Type:** `boolean`

Whether to keep the existing `setup.py` when `generate-packaging-files` is `true`. If set to `false` and by default, `pyproject.toml` will be generated instead. To generate `setup.py`, use `basic-setup-py`.

### `keep-pyproject-fields`

**Type:** `object`

Which manually customized `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Set a field to `true` to keep it. By default no fields are preserved.

### `clear-output-folder`

**Type:** `boolean`

Whether to clear the output folder before generating the code. Defaults to `false`.

### `emit-yaml-only`

**Type:** `boolean`

Emit YAML code model only, without running Python generator. For batch processing.
2 changes: 1 addition & 1 deletion packages/http-client-python/emitter/src/lib.ts
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ export const PythonEmitterOptionsSchema: JSONSchemaType<PythonEmitterOptions> =
type: "string",
nullable: true,
description:
"The subdirectory to generate the code in. If not specified, the code will be generated in the root folder. Note: if you're using this flag, you will need to add and maintain the versioning file yourself.",
'The subdirectory (relative to the package namespace folder) to generate the code in. Use this to keep emitter-generated code separate from hand-written/customized code, so regeneration only overwrites the subdirectory and leaves your customizations untouched. If not specified, the code is generated directly in the package namespace folder. Note: if you\'re using this flag, you will need to add and maintain the versioning file (`_version.py`) yourself.\n\nExample: for `namespace: azure.storage.blob` with `generation-subdir: _generated`, generated code lands in `azure/storage/blob/_generated/` while your customized code lives in `azure/storage/blob/`. A typical `tspconfig.yaml` looks like:\n\n```yaml\noptions:\n "@azure-tools/typespec-python":\n emitter-output-dir: "{output-dir}/{service-dir}/azure-storage-blob"\n namespace: "azure.storage.blob"\n generation-subdir: "_generated"\n```',
Comment thread
msyyc marked this conversation as resolved.
Resolved
},
"keep-setup-py": {
type: "boolean",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,9 @@ See [Configuring output directory for more info](https://typespec.io/docs/handbo

### `api-version`

**Type:** `string`
**Type:** `undefined`

Use this flag if you would like to generate the sdk only for a specific version. Default value is the latest version. Also accepts values `latest` and `all`.
Use this flag if you would like to generate the sdk only for a specific version. Default value is the latest version. Also accepts values `latest` and `all`. For multi-service packages, provide a map from each service namespace's full name to its desired version; services not listed default to their latest version.

### `license`

Expand Down Expand Up @@ -106,7 +106,17 @@ Whether to validate the versioning of the package. Defaults to `true`. If set to

**Type:** `string`

The subdirectory to generate the code in. If not specified, the code will be generated in the root folder. Note: if you're using this flag, you will need to add and maintain the versioning file yourself.
The subdirectory (relative to the package namespace folder) to generate the code in. Use this to keep emitter-generated code separate from hand-written/customized code, so regeneration only overwrites the subdirectory and leaves your customizations untouched. If not specified, the code is generated directly in the package namespace folder. Note: if you're using this flag, you will need to add and maintain the versioning file (`_version.py`) yourself.

Example: for `namespace: azure.storage.blob` with `generation-subdir: _generated`, generated code lands in `azure/storage/blob/_generated/` while your customized code lives in `azure/storage/blob/`. A typical `tspconfig.yaml` looks like:

```yaml
options:
"@azure-tools/typespec-python":
emitter-output-dir: "{output-dir}/{service-dir}/azure-storage-blob"
namespace: "azure.storage.blob"
generation-subdir: "_generated"
```

### `keep-setup-py`

Expand All @@ -118,10 +128,16 @@ Whether to keep the existing `setup.py` when `generate-packaging-files` is `true

**Type:** `object`

Which manually customized `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Set a field to `true` to keep it. Supported fields: `authors`, `description`, `classifiers`, `urls`. By default no fields are preserved.
Which manually customized `[project]` fields to preserve in an existing `pyproject.toml` instead of overwriting them on regeneration. Set a field to `true` to keep it. By default no fields are preserved.

### `clear-output-folder`

**Type:** `boolean`

Whether to clear the output folder before generating the code. Defaults to `false`.

### `emit-yaml-only`

**Type:** `boolean`

Emit YAML code model only, without running Python generator. For batch processing.
Loading