ScalarScalar API

Python

This section details the available configuration options for the Python SDK. All configuration is managed in the gen.yaml file under the python section.

Version and general configuration 

python:
  version: 1.2.3
  authors: ["Author Name"]
  packageName: "openapi"
  moduleName: "openapi"
Name Required Default Value Description
version true 0.0.1 The current version of the SDK.
packageName true openapi The distribution name of the PyPI package. See Python Package Metadata.
moduleName false Same as packageName The name of the module users will import from. Allows using a different name for imports than the package name. PEP 420 implicit namespace packages are supported with period (.) characters, such as speakeasy.api_client. Custom code regions will be removed by updating the ModuleName
authors true ["Speakeasy"] Authors of the published package. See Poetry Authors Field.

Description and URLs 

python:
  description: "Python Client SDK Generated by Speakeasy."
  homepage: "https://example.com"
  documentationUrl: "https://example.com/docs"
Name Required Default Value Description
description false "Python Client SDK Generated by Speakeasy." A short description of the project. See Poetry Description Field.
homepage false null The URL for the homepage of the project.
documentationUrl false null The URL for the project documentation.

Different package and module names

You can configure a different name for the PyPI package and the module users will import from:

python:
  packageName: "my-package" # Users will install with: pip install my-package
  moduleName: "my_module" # Users will import with: from my_module import SDK

This can be useful when you want the package name to follow PyPI conventions (using hyphens) but the module name to follow Python conventions (using underscores).

Additional dependencies 

python:
  additionalDependencies:
    main:
      requests: "^2.25.1"
    dev:
      pytest: "^6.2.1"
Name Required Default Value Description
additionalDependencies false {} Add additional dependencies to include in the generated pyproject.toml file.

Method and parameter management 

python:
  maxMethodParams: 4
  flatteningOrder: "parameters-first"
  methodArguments: "infer-optional-args"
Name Required Default Value Description
flattenRequests false true Turn request parameters and body fields into a flat list of method arguments. This takes precedence over maxMethodParams. If there is no request body then maxMethodParams will be respected.
maxMethodParams false 9999 Maximum number of parameters before an input object is generated. 0 means input objects are always used.
flatteningOrder false parameters-first Determines the ordering of method arguments when flattening parameters and body fields. parameters-first or body-first
methodArguments false require-security-and-request Determines how arguments for SDK methods are generated.

Security configuration 

python:
  envVarPrefix: "SPEAKEASY"
  flattenGlobalSecurity: true
Name Required Default Value Description
flattenGlobalSecurity false true Enables inline security credentials during SDK instantiation.
envVarPrefix false "" Sets a prefix for environment variables that allows users to configure global parameters and security.

Import management 

python:
  imports:
    option: "openapi"
    paths:
      callbacks: "models/callbacks"
      errors: "models/errors"
      operations: "models/operations"
      shared: "models/shared"
      webhooks: "models/webhooks"
Field Required Default Value Description
option false "openapi" Defines the type of import strategy. Typically set to "openapi", indicating that the structure is based on the OpenAPI document.
paths false {} Customizes where different parts of the SDK (e.g., callbacks, errors, and operations) will be imported from.

Import paths

Component Default Value Description
callbacks models/callbacks The directory where callback models will be imported from.
errors models/errors The directory where error models will be imported from.
operations models/operations The directory where operation models (i.e., API endpoints) will be imported from.
shared models/components The directory for shared components, such as reusable schemas, and data models imported from the OpenAPI spec.
webhooks models/webhooks The directory for webhook models, if the SDK includes support for webhooks.

Error and response handling 

python:
  clientServerStatusCodesAsErrors: true
  responseFormat: "flat"
  enumFormat: "enum"
Name Required Default Value Description
clientServerStatusCodesAsErrors false true Whether to treat 4XX and 5XX status codes as errors.
responseFormat false flat Defines how responses are structured. Options: envelope, envelope-http, or flat.
enumFormat false enum Determines how enums are generated. Options: enum (Python enums) or union (union types).

Pytest configuration 

python:
  pytestFilterWarnings:
    - error
    - "ignore::DeprecationWarning"
  pytestTimeout: 300
Name Required Default Value Description
pytestFilterWarnings false [] Global pytest filterwarnings configuration value, which are filters to control Python warnings. Use to ignore warnings or raise warnings as errors. Additional reference: https://docs.python.org/3/library/warnings.html#warning-filter
pytestTimeout false 0 When value is greater than 0, installs pytest-timeout and sets the global pytest-timeout configuration value, which is the number of seconds before individual tests are timed out.