Skip to content

Commit 01bfbe8

Browse files
iscai-msftiscai-msfttadelesh
authored and
mario-guerra
committed
[python] add emitter options and docs (#6537)
1. Update to `@azure-tools/typespec-client-generator-core` version `0.53.0` (and update corresponding libraries 2. Have your library's emitter options in `lib.ts` extend from tcgc's `SdkEmitterOptions` ([code](https://github.com/microsoft/typespec/pull/6537/files#diff-312d0aa386e3732696ebc167c3a63647ce3d44791fbe44392b01042119635f87R9)) 3. Spread `SdkEmitterOptionsSchema.properties` into the implementation of your options ([code](https://github.com/microsoft/typespec/pull/6537/files#diff-312d0aa386e3732696ebc167c3a63647ce3d44791fbe44392b01042119635f87R57)) - If you haven't added documentation for each of your emitter options, be sure to include them so they properly render in the website 4. Split your flags between your unbranded and branded emitter. Include only `azure` specific flags in your branded emitter 5. Now, we need to make sure these changes get published to the website. Follow the remaining steps if you haven't already started adding website documentation 6. Suggestion is to add `"regen-docs": "node ../../packages/tspd/cmd/tspd.js doc . --enable-experimental --output-dir ../../website/src/content/docs/docs/emitters/clients/http-client-<emitter-name>/reference --skip-js"` to your `package.json` - Make sure you pull from main before doing this step and building `tspd` - If you have any custom documentation in your `README.md`, this will overwrite everything. If you have any extra handwritten content you'd like to add, you can add `.tspd/docs/usage.md` file, and that will get injected into your readme 7. Add `npm run regen-docs` to your generation pipeline - I added it in [`Generate.ps1`](https://github.com/microsoft/typespec/pull/6537/files#diff-d01183da000e95538fa4d2d813fb61cc208ffc624c406f53a0a8c22047d106a0R13) 8. Add an entry into [`website/src/content/current-sidebar.ts`](https://github.com/microsoft/typespec/pull/6537/files#diff-2dedc394c7548f077bab3ebbc97904b254707dc4107e83bbd841d34900b7a202R153) with your emitter --------- Co-authored-by: iscai-msft <isabellavcai@gmail.com> Co-authored-by: tadelesh <tadelesh.shi@live.cn>
1 parent 1c9397b commit 01bfbe8

18 files changed

Lines changed: 1032 additions & 1352 deletions

File tree

‎packages/http-client-python/README.md‎

Lines changed: 110 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,144 @@
1-
# TypeSpec Python Client Emitter
1+
# @typespec/http-client-python
22

3-
## Getting started
3+
TypeSpec emitter for Python SDKs
44

5-
### Initialize TypeSpec Project
5+
## Install
66

7-
Follow [TypeSpec Getting Started](https://typespec.io/docs) to initialize your TypeSpec project.
7+
```bash
8+
npm install @typespec/http-client-python
9+
```
10+
11+
## Usage
812

9-
Make sure `npx tsp compile .` runs correctly.
13+
1. Via the command line
1014

11-
### Add `@typespec/http-client-python` to your project
15+
```bash
16+
tsp compile . --emit=@typespec/http-client-python
17+
```
1218

13-
Include `@typespec/http-client-python` in `package.json`:
19+
2. Via the config
1420

15-
```diff
16-
"dependencies": {
17-
+ "@typespec/http-client-python": "latest"
18-
},
21+
```yaml
22+
emit:
23+
- "@typespec/http-client-python"
1924
```
2025
21-
Run `npm install` to install the dependency.
26+
The config can be extended with options as follows:
2227
23-
### Generate a Python client library
28+
```yaml
29+
emit:
30+
- "@typespec/http-client-python"
31+
options:
32+
"@typespec/http-client-python":
33+
option: value
34+
```
2435
25-
You can either specify `@typespec/http-client-python` on the commandline or through tspconfig.yaml.
36+
## Emitter options
2637
27-
#### Generate with `--emit` command
38+
### `package-version`
2839

29-
Run command `npx tsp compile --emit @typespec/http-client-python <path-to-typespec-file>`
40+
**Type:** `string`
3041

31-
e.g.
42+
The version of the package.
3243

33-
```cmd
34-
npx tsp compile main.tsp --emit @typespec/http-client-python
35-
```
44+
### `package-name`
3645

37-
or
46+
**Type:** `string`
3847

39-
```cmd
40-
npx tsp compile client.tsp --emit @typespec/http-client-python
41-
```
48+
The name of the package.
4249

43-
#### Generate with tspconfig.yaml
50+
### `generate-packaging-files`
4451

45-
Add the following configuration in tspconfig.yaml:
52+
**Type:** `boolean`
4653

47-
```diff
48-
emit:
49-
- "@typespec/http-client-python"
50-
options:
51-
"@typespec/http-client-python":
52-
+ package-dir: "contoso"
53-
+ package-name: "contoso"
54-
```
54+
Whether to generate packaging files. Packaging files refer to the `setup.py`, `README`, and other files that are needed to package your code.
5555

56-
Run the command to generate your library:
56+
### `packaging-files-dir`
5757

58-
```cmd
59-
npx tsp compile main.tsp
60-
```
58+
**Type:** `string`
6159

62-
or
60+
If you are using a custom packaging files directory, you can specify it here. We won't generate with the default packaging files we have.
6361

64-
```cmd
65-
npx tsp compile client.tsp
66-
```
62+
### `packaging-files-config`
6763

68-
## Configure the generated library
64+
**Type:** `object`
6965

70-
You can further configure the generated client library using the emitter options provided through @typespec/http-client-python.
66+
If you are using a custom packaging files directory, and have additional configuration parameters you want to pass in during generation, you can specify it here. Only applicable if `packaging-files-dir` is set.
7167

72-
You can set options in the command line directly via `--option @typespec/http-client-python.<optionName>=XXX`, e.g. `--option @typespec/http-client-python.package-name="contoso"`
68+
### `package-pprint-name`
7369

74-
or
70+
**Type:** `string`
7571

76-
Modify `tspconfig.yaml` in the TypeSpec project to add emitter options under options/@typespec/http-client-python.
72+
The name of the package to be used in pretty-printing. Will be the name of the package in `README` and pprinting of `setup.py`.
7773

78-
```diff
79-
emit:
80-
- "@typespec/http-client-python"
81-
options:
82-
"@typespec/http-client-python":
83-
+ package-dir: "{package-dir}"
84-
+ package-name: "contoso"
85-
```
74+
### `head-as-boolean`
8675

87-
### Supported emitter options
76+
**Type:** `boolean`
8877

89-
Common emitter configuration example:
78+
Whether to return responses from HEAD requests as boolean. Defaults to `true`.
9079

91-
```yaml
92-
emit:
93-
- "@typespec/http-client-python"
94-
options:
95-
"@typespec/http-client-python":
96-
package-dir: "{package-dir}"
97-
package-name: "contoso"
98-
```
80+
### `models-mode`
81+
82+
**Type:** `"dpg" | "none"`
83+
84+
What kind of models to generate. If you pass in `none`, we won't generate models. `dpg` models are the default models we generate.
85+
86+
### `company-name`
87+
88+
**Type:** `string`
89+
90+
The name of the company. This will be reflected in your license files and documentation.
91+
92+
### `use-pyodide`
93+
94+
**Type:** `boolean`
95+
96+
Whether to generate using `pyodide` instead of `python`. If there is no python installed on your device, we will default to using pyodide to generate the code.
97+
98+
### `flavor`
99+
100+
**Type:** `string`
101+
102+
The flavor of the SDK.
103+
104+
### `generate-test`
105+
106+
**Type:** `boolean`
107+
108+
Whether to generate test files, for basic testing of your generated sdks. Defaults to `false`.
109+
110+
### `generate-protocol-methods`
111+
112+
**Type:** `boolean`
113+
114+
When set to `true`, the emitter will generate low-level protocol methods for each service operation if `@protocolAPI` is not set for an operation. Default value is `true`.
115+
116+
### `generate-convenience-methods`
117+
118+
**Type:** `boolean`
119+
120+
When set to `true`, the emitter will generate low-level protocol methods for each service operation if `@convenientAPI` is not set for an operation. Default value is `true`.
121+
122+
### `examples-dir`
123+
124+
**Type:** `string`
125+
126+
Specifies the directory where the emitter will look for example files. If the flag isn’t set, the emitter defaults to using an `examples` directory located at the project root.
127+
128+
### `namespace`
129+
130+
**Type:** `string`
131+
132+
Specifies the namespace you want to override for namespaces set in the spec. With this config, all namespace for the spec types will default to it.
133+
134+
### `api-version`
135+
136+
**Type:** `string`
137+
138+
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`.
139+
140+
### `license`
141+
142+
**Type:** `object`
99143

100-
| Option | Type | Description |
101-
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
102-
| `package-version` | string | Specify the package version. Default version: `1.0.0b1`. |
103-
| `package-name` | string | Specify the package name. |
104-
| `package-dir` | string | Specify the output directory for the package. |
105-
| `generate-packaging-files` | boolean | Indicate if packaging files, such as setup.py, should be generated. |
106-
| `package-pprint-name` | string | Specify the pretty print name for the package. |
107-
| `flavor` | string | Represents the type of SDK that will be generated. By default, there will be no branding in the generated client library. Specify `"azure"` to generate an SDK following Azure guidelines. |
108-
| `company-name` | string | Specify the company name to be inserted into licensing data. For `"azure"` flavor, the default value inserted is `Microsoft`. |
109-
110-
**Advanced emitter options**
111-
112-
| Option | Type | Description |
113-
| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
114-
| `head-as-boolean` | boolean | Generate head calls to return a boolean. Default: `true`. |
115-
| `packaging-files-dir` | string | Pass in the path to a custom directory with SDK packaging files. |
116-
| `packaging-files-config` | object | Specify configuration options that will be passed directly into the packaging files specified by the `packaging-files-dir` option. |
117-
| `tracing` | boolean | Only available for the `"azure"` flavor of SDKs, provide tracing support in the generated client library. Default: `true`. |
118-
| `debug` | boolean | Enable debugging. |
144+
License information for the generated client code.

‎packages/http-client-python/emitter/src/code-model.ts‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ import {
3535
import { emitParamBase, getClientNamespace, getImplementation, getRootNamespace } from "./utils.js";
3636

3737
function emitBasicMethod<TServiceOperation extends SdkServiceOperation>(
38-
context: PythonSdkContext<TServiceOperation>,
38+
context: PythonSdkContext,
3939
rootClient: SdkClientType<TServiceOperation>,
4040
method: SdkBasicServiceMethod<TServiceOperation>,
4141
operationGroupName: string,
@@ -51,7 +51,7 @@ function emitBasicMethod<TServiceOperation extends SdkServiceOperation>(
5151
}
5252

5353
function emitLroMethod<TServiceOperation extends SdkServiceOperation>(
54-
context: PythonSdkContext<TServiceOperation>,
54+
context: PythonSdkContext,
5555
rootClient: SdkClientType<TServiceOperation>,
5656
method: SdkLroServiceMethod<TServiceOperation>,
5757
operationGroupName: string,
@@ -67,7 +67,7 @@ function emitLroMethod<TServiceOperation extends SdkServiceOperation>(
6767
}
6868

6969
function emitPagingMethod<TServiceOperation extends SdkServiceOperation>(
70-
context: PythonSdkContext<TServiceOperation>,
70+
context: PythonSdkContext,
7171
rootClient: SdkClientType<TServiceOperation>,
7272
method: SdkPagingServiceMethod<TServiceOperation>,
7373
operationGroupName: string,
@@ -83,7 +83,7 @@ function emitPagingMethod<TServiceOperation extends SdkServiceOperation>(
8383
}
8484

8585
function emitLroPagingMethod<TServiceOperation extends SdkServiceOperation>(
86-
context: PythonSdkContext<TServiceOperation>,
86+
context: PythonSdkContext,
8787
rootClient: SdkClientType<TServiceOperation>,
8888
method: SdkLroPagingServiceMethod<TServiceOperation>,
8989
operationGroupName: string,
@@ -98,8 +98,8 @@ function emitLroPagingMethod<TServiceOperation extends SdkServiceOperation>(
9898
}
9999
}
100100

101-
function emitMethodParameter<TServiceOperation extends SdkServiceOperation>(
102-
context: PythonSdkContext<TServiceOperation>,
101+
function emitMethodParameter(
102+
context: PythonSdkContext,
103103
parameter: SdkEndpointParameter | SdkCredentialParameter | SdkMethodParameter,
104104
): Record<string, any>[] {
105105
if (parameter.kind === "endpoint") {
@@ -153,7 +153,7 @@ function emitMethodParameter<TServiceOperation extends SdkServiceOperation>(
153153
}
154154

155155
function emitMethod<TServiceOperation extends SdkServiceOperation>(
156-
context: PythonSdkContext<TServiceOperation>,
156+
context: PythonSdkContext,
157157
rootClient: SdkClientType<TServiceOperation>,
158158
method: SdkServiceMethod<TServiceOperation>,
159159
operationGroupName: string,
@@ -171,7 +171,7 @@ function emitMethod<TServiceOperation extends SdkServiceOperation>(
171171
}
172172

173173
function emitOperationGroups<TServiceOperation extends SdkServiceOperation>(
174-
context: PythonSdkContext<TServiceOperation>,
174+
context: PythonSdkContext,
175175
client: SdkClientType<TServiceOperation>,
176176
rootClient: SdkClientType<TServiceOperation>,
177177
prefix: string,
@@ -227,7 +227,7 @@ function emitOperationGroups<TServiceOperation extends SdkServiceOperation>(
227227
}
228228

229229
function emitClient<TServiceOperation extends SdkServiceOperation>(
230-
context: PythonSdkContext<TServiceOperation>,
230+
context: PythonSdkContext,
231231
client: SdkClientType<TServiceOperation>,
232232
): Record<string, any> {
233233
if (client.clientInitialization) {
@@ -270,9 +270,7 @@ function onlyUsedByPolling(usage: UsageFlags): boolean {
270270
);
271271
}
272272

273-
export function emitCodeModel<TServiceOperation extends SdkServiceOperation>(
274-
sdkContext: PythonSdkContext<TServiceOperation>,
275-
) {
273+
export function emitCodeModel(sdkContext: PythonSdkContext) {
276274
// Get types
277275
const sdkPackage = sdkContext.sdkPackage;
278276
const codeModel: Record<string, any> = {

0 commit comments

Comments
 (0)