python.md

August 31, 2023 · View on GitHub

METADATA

PropertyValueNotes
generator namepythonpass this to the generate command after -g
generator stabilitySTABLE
generator typeCLIENT
generator languagePython
generator language version>=3.8
generator default templating enginehandlebars
helpTxtGenerates a Python client library

Features in this generator:
- type hints on endpoints and model creation
- model parameter names use the spec defined keys and cases
- robust composition (oneOf/anyOf/allOf/not) where payload data is stored in one instance only
- endpoint parameter names use the spec defined keys and cases
- inline schemas are supported at any location including composition
- multiple content types supported in request body and response bodies
- run time type checking + json schema validation
- json schema keyword validation may be selectively disabled with SchemaConfiguration
- enums of type string/integer/boolean typed using typing.Literal
- mypy static type checking run on generated sample
- Sending/receiving decimals as strings supported with type:string format: number -> DecimalSchema
- Sending/receiving uuids as strings supported with type:string format: uuid -> UUIDSchema
- quicker load time for python modules (a single endpoint can be imported and used without loading others)
- composed schemas with type constraints supported (type:object + oneOf/anyOf/allOf)
- schemas are not coerced/cast. For example string + date are both stored as string, and there is a date accessor

CONFIG OPTIONS

These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to configuration docs for more details.

OptionDescriptionValuesDefault
generateSourceCodeOnlySpecifies that only a library source code is to be generated.false
hideGenerationTimestampHides the generation timestamp when files are generated.true
librarylibrary template (sub-template) to use: urllib3urllib3
nonCompliantUseDiscriminatorIfCompositionFailsWhen true, If the payload fails to validate against composed schemas (allOf/anyOf/oneOf/not) and a discriminator is present, then ignore the composition validation errors and attempt to use the discriminator to validate the payload.
Note: setting this to true makes the generated client not comply with json schema because it ignores composition validation errors. Please consider making your schemas more restrictive rather than setting this to true. You can do that by:
  • defining the propertyName as an enum with only one value in the schemas that are in your discriminator map
  • setting additionalProperties: false in your schemas
true
If composition fails and a discriminator exists, the composition errors will be ignored and validation will be attempted with the discriminator
false
Composition validation must succeed. Discriminator validation must succeed.
false
packageNamepython package name (convention: snake_case).openapi_client
packageUrlpython package URL.null
packageVersionpython package version.1.0.0
projectNamepython project name in setup.py (e.g. petstore-api).null
recursionLimitSet the recursion limit. If not set, use the system default value.null
templatingEnginetemplate engine
handlebars
handlebars templating engine
handlebars
useNoseuse the nose test frameworkfalse

INSTANTIATION TYPES

Type/AliasInstantiated By
arraytuple
booleanbool
integerint
nullNone
numbertyping.Union[float, int]
objectimmutabledict.immutabledict
stringstr

LANGUAGE PRIMITIVES

  • bool
  • bytes
  • date
  • datetime
  • dict
  • file
  • file_type
  • float
  • int
  • list
  • none_type
  • object
  • str

RESERVED WORDS

  • and
  • as
  • assert
  • async
  • await
  • bool
  • break
  • class
  • continue
  • def
  • del
  • dict
  • elif
  • else
  • except
  • exec
  • false
  • finally
  • float
  • for
  • from
  • global
  • if
  • immutabledict
  • import
  • in
  • int
  • is
  • lambda
  • list
  • none
  • nonlocal
  • not
  • or
  • pass
  • print
  • property
  • raise
  • return
  • self
  • str
  • true
  • try
  • tuple
  • while
  • with
  • yield

FEATURE SET

Client Modification Feature

NameSupportedDefined By
BasePath✗ToolingExtension
Authorizations✗ToolingExtension
UserAgent✗ToolingExtension
MockServer✗ToolingExtension

Components Feature

NameSupportedDefined By
schemas✓OAS3
responses✓OAS3
parameters✓OAS3
examples✗OAS3
requestBodies✓OAS3
headers✓OAS3
securitySchemes✓OAS3
links✗OAS3
callbacks✗OAS3
pathItems✗OAS3

Data Type Feature

NameSupportedDefined By
Custom✗OAS2,OAS3
Int32✓OAS2,OAS3
Int64✓OAS2,OAS3
Integer✓OAS2,OAS3
Float✓OAS2,OAS3
Double✓OAS2,OAS3
Number✓OAS2,OAS3
String✓OAS2,OAS3
Byte✗OAS2,OAS3
Binary✓OAS2,OAS3
Boolean✓OAS2,OAS3
Date✓OAS2,OAS3
DateTime✓OAS2,OAS3
Password✗OAS2,OAS3
File✓OAS2
Uuid✓OAS2,OAS3
Array✓OAS2,OAS3
Null✓OAS3
AnyType✓OAS2,OAS3
Object✓OAS2,OAS3
Enum✓OAS2,OAS3

Documentation Feature

NameSupportedDefined By
Readme✓ToolingExtension
Servers✓OAS3
Security✓OAS2,OAS3
ComponentSchemas✓OAS3
ComponentResponses✓OAS3
ComponentParameters✓OAS3
ComponentRequestBodies✓OAS3
ComponentHeaders✓OAS3
ComponentSecuritySchemes✓OAS3
ComponentLinks✗OAS3
ComponentCallbacks✗OAS3
ComponentPathItems✗OAS3
Api✓ToolingExtension

Global Feature

NameSupportedDefined By
Info✓OAS2,OAS3
Servers✓OAS3
Paths✓OAS2,OAS3
Webhooks✗OAS3
Components✓OAS3
Security✓OAS2,OAS3
Tags✓OAS2,OAS3
ExternalDocs✗OAS2,OAS3

Operation Feature

NameSupportedDefined By
Responses_HttpStatusCode✓OAS3
Responses_RangedResponseCodes✓OAS3
Responses_Default✓OAS3
Responses_RedirectionResponse✓OAS3

Parameter Feature

NameSupportedDefined By
Name✓OAS2,OAS3
Required✓OAS2,OAS3
In_Path✓OAS2,OAS3
In_Query✓OAS2,OAS3
In_Header✓OAS2,OAS3
In_Cookie✗OAS3
Style_Matrix✓OAS3
Style_Label✓OAS3
Style_Form✓OAS3
Style_Simple✓OAS3
Style_SpaceDelimited✓OAS3
Style_PipeDelimited✓OAS3
Style_DeepObject✗OAS3
Explode✓OAS3
Schema✓OAS3
Content✓OAS3

Schema Feature

NameSupportedDefined By
AdditionalProperties✓OAS2,OAS3
AllOf✓OAS2,OAS3
AnyOf✓OAS3
Const✓OAS3
Contains✓OAS3
Default✓OAS2,OAS3
DependentRequired✓OAS3
DependentSchemas✓OAS3
Discriminator✓OAS2,OAS3
Enum✓OAS2,OAS3
ExclusiveMinimum✓OAS2,OAS3
ExclusiveMaximum✓OAS2,OAS3
Format✓OAS2,OAS3
Items✓OAS2,OAS3
MaxContains✓OAS3
MaxItems✓OAS2,OAS3
MaxLength✓OAS2,OAS3
MaxProperties✓OAS2,OAS3
Maximum✓OAS2,OAS3
MinContains✓OAS3
MinItems✓OAS2,OAS3
MinLength✓OAS2,OAS3
MinProperties✓OAS2,OAS3
Minimum✓OAS2,OAS3
MultipleOf✓OAS2,OAS3
Not✓OAS3
Nullable✓OAS3
OneOf✓OAS3
Pattern✓OAS2,OAS3
PatternProperties✓OAS3
PrefixItems✓OAS3
Properties✓OAS2,OAS3
PropertyNames✓OAS3
Required✓OAS2,OAS3
Type✓OAS2,OAS3
UnevaluatedItems✓OAS3
UnevaluatedProperties✓OAS3
UniqueItems✓OAS2,OAS3
Xml✗OAS2,OAS3

Security Feature

NameSupportedDefined By
HTTP_Basic✓OAS2,OAS3
ApiKey✓OAS2,OAS3
OpenIDConnect✗OAS3
HTTP_Bearer✓OAS2,OAS3
OAuth2_Implicit✗OAS2,OAS3
OAuth2_Password✗OAS2,OAS3
OAuth2_ClientCredentials✗OAS2,OAS3
OAuth2_AuthorizationCode✗OAS2,OAS3

Wire Format Feature

NameSupportedDefined By
JSON✓OAS2,OAS3
XML✗OAS2,OAS3
PROTOBUF✗ToolingExtension
Custom✓OAS2,OAS3