[python] add emitter options and docs

packages/http-client-python/README.md

@@ -1,118 +1,144 @@
-# TypeSpec Python Client Emitter
+# @typespec/http-client-python
 
-## Getting started
+TypeSpec emitter for Python SDKs
 
-### Initialize TypeSpec Project
+## Install
 
-Follow [TypeSpec Getting Started](https://typespec.io/docs) to initialize your TypeSpec project.
+```bash
+npm install @typespec/http-client-python
+```
+
+## Usage
 
-Make sure `npx tsp compile .` runs correctly.
+1. Via the command line
 
-### Add `@typespec/http-client-python` to your project
+```bash
+tsp compile . --emit=@typespec/http-client-python
+```
 
-Include `@typespec/http-client-python` in `package.json`:
+2. Via the config
 
-```diff
- "dependencies": {
-+      "@typespec/http-client-python": "latest"
-  },
+```yaml
+emit:
+  - "@typespec/http-client-python"
 ```
 
-Run `npm install` to install the dependency.
+The config can be extended with options as follows:
 
-### Generate a Python client library
+```yaml
+emit:
+  - "@typespec/http-client-python"
+options:
+  "@typespec/http-client-python":
+    option: value
+```
 
-You can either specify `@typespec/http-client-python` on the commandline or through tspconfig.yaml.
+## Emitter options
 
-#### Generate with `--emit` command
+### `package-version`
 
-Run command `npx tsp compile --emit @typespec/http-client-python <path-to-typespec-file>`
+**Type:** `string`
 
-e.g.
+The version of the package.
 
-```cmd
-npx tsp compile main.tsp --emit @typespec/http-client-python
-```
+### `package-name`
 
-or
+**Type:** `string`
 
-```cmd
-npx tsp compile client.tsp --emit @typespec/http-client-python
-```
+The name of the package.
 
-#### Generate with tspconfig.yaml
+### `generate-packaging-files`
 
-Add the following configuration in tspconfig.yaml:
+**Type:** `boolean`
 
-```diff
-emit:
-  - "@typespec/http-client-python"
-options:
-  "@typespec/http-client-python":
-+    package-dir: "contoso"
-+    package-name: "contoso"
-```
+Whether to generate packaging files. Packaging files refer to the `setup.py`, `README`, and other files that are needed to package your code.
 
-Run the command to generate your library:
+### `packaging-files-dir`
 
-```cmd
-npx tsp compile main.tsp
-```
+**Type:** `string`
 
-or
+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.
 
-```cmd
-npx tsp compile client.tsp
-```
+### `packaging-files-config`
 
-## Configure the generated library
+**Type:** `object`
 
-You can further configure the generated client library using the emitter options provided through @typespec/http-client-python.
+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.
 
-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"`
+### `package-pprint-name`
 
-or
+**Type:** `string`
 
-Modify `tspconfig.yaml` in the TypeSpec project to add emitter options under options/@typespec/http-client-python.
+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`.
 
-```diff
-emit:
-  - "@typespec/http-client-python"
-options:
-  "@typespec/http-client-python":
-+    package-dir: "{package-dir}"
-+    package-name: "contoso"
-```
+### `head-as-boolean`
 
-### Supported emitter options
+**Type:** `boolean`
 
-Common emitter configuration example:
+Whether to return responses from HEAD requests as boolean. Defaults to `true`.
 
-```yaml
-emit:
-  - "@typespec/http-client-python"
-options:
-  "@typespec/http-client-python":
-    package-dir: "{package-dir}"
-    package-name: "contoso"
-```
+### `models-mode`
+
+**Type:** `"dpg" | "none"`
+
+What kind of models to generate. If you pass in `none`, we won't generate models. `dpg` models are the default models we generate.
+
+### `company-name`
+
+**Type:** `string`
+
+The name of the company. This will be reflected in your license files and documentation.
+
+### `use-pyodide`
+
+**Type:** `boolean`
+
+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.
+
+### `flavor`
+
+**Type:** `string`
+
+The flavor of the SDK.
+
+### `generate-test`
+
+**Type:** `boolean`
+
+Whether to generate test files, for basic testing of your generated sdks. Defaults to `false`.
+
+### `generate-protocol-methods`
+
+**Type:** `boolean`
+
+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`.
+
+### `generate-convenience-methods`
+
+**Type:** `boolean`
+
+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`.
+
+### `examples-dir`
+
+**Type:** `string`
+
+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.
+
+### `namespace`
+
+**Type:** `string`
+
+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.
+
+### `api-version`
+
+**Type:** `string`
+
+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`.
+
+### `license`
+
+**Type:** `object`
 
-| Option                     | Type    | Description                                                                                                                                                                                |
-| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `package-version`          | string  | Specify the package version. Default version: `1.0.0b1`.                                                                                                                                   |
-| `package-name`             | string  | Specify the package name.                                                                                                                                                                  |
-| `package-dir`              | string  | Specify the output directory for the package.                                                                                                                                              |
-| `generate-packaging-files` | boolean | Indicate if packaging files, such as setup.py, should be generated.                                                                                                                        |
-| `package-pprint-name`      | string  | Specify the pretty print name for the package.                                                                                                                                             |
-| `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. |
-| `company-name`             | string  | Specify the company name to be inserted into licensing data. For `"azure"` flavor, the default value inserted is `Microsoft`.                                                              |
-
-**Advanced emitter options**
-
-| Option                   | Type    | Description                                                                                                                        |
-| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `head-as-boolean`        | boolean | Generate head calls to return a boolean. Default: `true`.                                                                          |
-| `packaging-files-dir`    | string  | Pass in the path to a custom directory with SDK packaging files.                                                                   |
-| `packaging-files-config` | object  | Specify configuration options that will be passed directly into the packaging files specified by the `packaging-files-dir` option. |
-| `tracing`                | boolean | Only available for the `"azure"` flavor of SDKs, provide tracing support in the generated client library. Default: `true`.         |
-| `debug`                  | boolean | Enable debugging.                                                                                                                  |
+License information for the generated client code.

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

@@ -35,7 +35,7 @@ import {
 import { emitParamBase, getClientNamespace, getImplementation, getRootNamespace } from "./utils.js";
 
 function emitBasicMethod<TServiceOperation extends SdkServiceOperation>(
-  context: PythonSdkContext<TServiceOperation>,
+  context: PythonSdkContext,
   rootClient: SdkClientType<TServiceOperation>,
   method: SdkBasicServiceMethod<TServiceOperation>,
   operationGroupName: string,
@@ -51,7 +51,7 @@ function emitBasicMethod<TServiceOperation extends SdkServiceOperation>(
 }
 
 function emitLroMethod<TServiceOperation extends SdkServiceOperation>(
-  context: PythonSdkContext<TServiceOperation>,
+  context: PythonSdkContext,
   rootClient: SdkClientType<TServiceOperation>,
   method: SdkLroServiceMethod<TServiceOperation>,
   operationGroupName: string,
@@ -67,7 +67,7 @@ function emitLroMethod<TServiceOperation extends SdkServiceOperation>(
 }
 
 function emitPagingMethod<TServiceOperation extends SdkServiceOperation>(
-  context: PythonSdkContext<TServiceOperation>,
+  context: PythonSdkContext,
   rootClient: SdkClientType<TServiceOperation>,
   method: SdkPagingServiceMethod<TServiceOperation>,
   operationGroupName: string,
@@ -83,7 +83,7 @@ function emitPagingMethod<TServiceOperation extends SdkServiceOperation>(
 }
 
 function emitLroPagingMethod<TServiceOperation extends SdkServiceOperation>(
-  context: PythonSdkContext<TServiceOperation>,
+  context: PythonSdkContext,
   rootClient: SdkClientType<TServiceOperation>,
   method: SdkLroPagingServiceMethod<TServiceOperation>,
   operationGroupName: string,
@@ -98,8 +98,8 @@ function emitLroPagingMethod<TServiceOperation extends SdkServiceOperation>(
   }
 }
 
-function emitMethodParameter<TServiceOperation extends SdkServiceOperation>(
-  context: PythonSdkContext<TServiceOperation>,
+function emitMethodParameter(
+  context: PythonSdkContext,
   parameter: SdkEndpointParameter | SdkCredentialParameter | SdkMethodParameter,
 ): Record<string, any>[] {
   if (parameter.kind === "endpoint") {
@@ -153,7 +153,7 @@ function emitMethodParameter<TServiceOperation extends SdkServiceOperation>(
 }
 
 function emitMethod<TServiceOperation extends SdkServiceOperation>(
-  context: PythonSdkContext<TServiceOperation>,
+  context: PythonSdkContext,
   rootClient: SdkClientType<TServiceOperation>,
   method: SdkServiceMethod<TServiceOperation>,
   operationGroupName: string,
@@ -171,7 +171,7 @@ function emitMethod<TServiceOperation extends SdkServiceOperation>(
 }
 
 function emitOperationGroups<TServiceOperation extends SdkServiceOperation>(
-  context: PythonSdkContext<TServiceOperation>,
+  context: PythonSdkContext,
   client: SdkClientType<TServiceOperation>,
   rootClient: SdkClientType<TServiceOperation>,
   prefix: string,
@@ -227,7 +227,7 @@ function emitOperationGroups<TServiceOperation extends SdkServiceOperation>(
 }
 
 function emitClient<TServiceOperation extends SdkServiceOperation>(
-  context: PythonSdkContext<TServiceOperation>,
+  context: PythonSdkContext,
   client: SdkClientType<TServiceOperation>,
 ): Record<string, any> {
   if (client.clientInitialization) {
@@ -270,9 +270,7 @@ function onlyUsedByPolling(usage: UsageFlags): boolean {
   );
 }
 
-export function emitCodeModel<TServiceOperation extends SdkServiceOperation>(
-  sdkContext: PythonSdkContext<TServiceOperation>,
-) {
+export function emitCodeModel(sdkContext: PythonSdkContext) {
   // Get types
   const sdkPackage = sdkContext.sdkPackage;
   const codeModel: Record<string, any> = {