openapi-python-client

Features

• Allow references to non-object, non-enum types [#371][#418][#425]. Thanks @p1-ra!
• Allow for attrs 21.x in generated clients [#412]
• Allow for using any version of Black [#416] [#411]. Thanks @christhekeele!

Fixes

• Prevent crash when providing a non-string default to a string attribute. [#414] [#415]
• Deserialization of optional nullable properties when no value is returned from the API [#420] [#381]. Thanks @forest-benchling!

Breaking Changes

• Some generated names will be different, solving some inconsistencies. (closes #369) (#375) Thanks @ramnes!
• Change reference resolution to use reference path instead of class name (fixes #342) (#366)
• If a schema references exactly one other schema in allOf, oneOf, or anyOf that referenced generated model will be used directly instead of generating a copy with another name. (#361)
• Attributes shadowing any builtin except id and type will now be renamed in generated clients (#360, #378, #407). Thanks @dblanchette and @forest-benchling!

Features

• Allow httpx 0.18.x in generated clients (#400)
• Add summary attribute to Endpoint for use in custom templates (#404)
• Support common parameters for paths (#376). Thanks @ramnes!
• Add allOf support for model definitions (#98) (#321)

Fixes

• Attempt to deduplicate endpoint parameters based on name and location (fixes #305) (#406)
• Names of classes without titles will no longer include ref path (fixes #397) (#405). Thanks @ramnes!
• Problems with enum defaults in allOf (#363). Thanks @csymeonides-mf
• Prevent duplicate return types in generated api functions (#365)
• Support empty strings in enums (closes #357) (#358). Thanks @ramnes!
• Allow passing data with files in multipart. (Fixes #351) (#355)
• Deserialization of unions (#332). Thanks @forest-benchling!

Breaking Changes

• Generated clients will no longer pass through None to query parameters. Previously, any query params set to None would surface as empty strings (per the default behavior of httpx). This is contrary to the defaults indicated by the OpenAPI 3.0.3 spec. Ommitting these parameters makes us more compliant. If you require a style of null to be passed to your query parameters, please request support for the OpenAPI "style" attribute. Thank you to @forest-benchling and @bowenwr for a ton of input on this.

Additions

• New --meta command line option for specifying what type of metadata should be generated:
  • poetry is the default value, same behavior you're used to in previous versions
  • setup will generate a pyproject.toml with no Poetry information, and instead create a setup.py with the
    project info.
  • none will not create a project folder at all, only the inner package folder (which won't be inner anymore)
• Attempt to detect and alert users if they are using an unsupported version of OpenAPI (#281).
• The media type application/vnd.api+json will now be handled just like application/json (#307). Thanks @jrversteegh!
• Support passing models into query parameters (#316). Thanks @forest-benchling!
• Add support for cookie parameters (#326).
• New --file-encoding command line option (#330). Sets the encoding used when writing generated files (defaults to utf-8). Thanks @dongfangtianyu!

Changes

• Lowered the minimum version of python-dateutil to 2.8.0 for improved compatibility (#298 & #299). Thanks @bowenwr!
• The from_dict method on generated models is now a @classmethod instead of @staticmethod (#215 & #292). Thanks @forest-benchling!
• Renamed all templates to end in .jinja, and all python-templates to end in .py.jinja to fix confusion with the latest version of mypy. Note this will break existing custom templates until you update your template file names.

Fixes

• Endpoint tags are now sanitized during parsing to fix an issue where My Tag and MyTag are seen as two different tags but are then later unified, causing errors when creating directories. Thanks @p1-ra! (#328)
• Parser will softly ignore value error during schema responses' status code convertion from string to integer (not a number). Errors will be reported to the end user and parsing will continue to proceed (#327).
• The generated from_dict and to_dict methods of models will now properly handle nullable and not required properties that are themselves generated models (#315). Thanks @forest-benchling!
• Fixed a typo in the async example in generated README.md files (#337). Thanks @synchronizing!
• Fix deserialization of None and Unset properties for all types by unifying the checks (#334). Thanks @forest-benchling!
• If duplicate model names are detected during generation, you'll now get an error message instead of broken code (#336). Thanks @forest-benchling!
• Fixes Enum deserialization when the value is UNSET (#306). Thanks @bowenwr!

Fixes

• Spacing and extra returns for Union types of additionalProperties (#266 & #268). Thanks @joshzana & @packyg!
• Title of inline schemas will no longer be missing characters (#271 & #274). Thanks @kalzoo!
• Handling of nulls (Nones) when parsing or constructing dates (#267). Thanks @fyhertz!

Fixes

• A bug in handling optional properties that are themselves models (introduced in 0.7.1) (#262). Thanks @packyg!

Additions

• Support for additionalProperties attribute in OpenAPI schemas and "free-form" objects by adding an additional_properties attribute to generated models. COMPATIBILITY NOTE: this will prevent any model property with a name that would be coerced to "additional_properties" in the generated client from generating properly (#218 & #252). Thanks @packyg!

Fixes

• Enums will once again work with query parameters (#259). Thanks @packyg!
• Generated Poetry metadata in pyproject.toml will properly indicate Python 3.6 compatibility (#258). Thanks @bowenwr!

Breaking Changes

• Any request/response field that is not required and wasn't specified is now set to UNSET instead of None.
• Values that are UNSET will not be sent along in API calls
• Schemas defined with type=object will now be converted into classes, just like if they were created as ref components.
  The previous behavior was a combination of skipping and using generic Dicts for these schemas.
• Response schema handling was unified with input schema handling, meaning that responses will behave differently than before.
  Specifically, instead of the content-type deciding what the generated Python type is, the schema itself will.
  • As a result of this, endpoints that used to return bytes when content-type was application/octet-stream will now return a File object if the type of the data is "binary", just like if you were submitting that type instead of receiving it.
• Instead of skipping input properties with no type, enum, anyOf, or oneOf declared, the property will be declared as None.
• Class (models and Enums) names will now contain the name of their parent element (if any). For example, a property
  declared in an endpoint will be named like {endpoint_name}_{previous_class_name}. Classes will no longer be
  deduplicated by appending a number to the end of the generated name, so if two names conflict with this new naming
  scheme, there will be an error instead.

Additions

• Added a --custom-template-path option for providing custom jinja2 templates (#231 - Thanks @erichulburd!).
• Better compatibility for "required" (whether or not the field must be included) and "nullable" (whether or not the field can be null) (#205 & #208). Thanks @bowenwr & @emannguitar!
• Support for all the same schemas in responses as are supported in parameters.
• In template macros: added declare_type param to transform and initial_value param to construct to improve flexibility (#241 - Thanks @packyg!).

Fixes

• Fixed spacing and generation of properties of type Union in generated models (#241 - Thanks @packyg!).
• Fixed usage instructions in generated README.md (#247 - Thanks @theFong!).

Fixes

• Generated README instructions (#247 - Thanks @theFong!)
• Sub-model class names (#250 - Thanks @packyg!)

Additions

• In template macros: added declare_type param to transform and initial_value param to construct to improve flexibility (#241 - Thanks @packyg!).

Fixes

• Fixed spacing and generation of properties of type Union in generated models (#241 - Thanks @packyg!).

Fixed issue with non-required fields in a model not being marked as such

Breaking Changes

• Any request/response field that is not required and wasn't specified is now set to UNSET instead of None.
• Values that are UNSET will not be sent along in API calls
• Schemas defined with type=object will now be converted into classes, just like if they were created as ref components.
  The previous behavior was a combination of skipping and using generic Dicts for these schemas.
• Response schema handling was unified with input schema handling, meaning that responses will behave differently than before.
  Specifically, instead of the content-type deciding what the generated Python type is, the schema itself will.
  • As a result of this, endpoints that used to return bytes when content-type was application/octet-stream will now return a File object if the type of the data is "binary", just like if you were submitting that type instead of receiving it.
• Instead of skipping input properties with no type, enum, anyOf, or oneOf declared, the property will be declared as None.
• Class (models and Enums) names will now contain the name of their parent element (if any). For example, a property
  declared in an endpoint will be named like {endpoint_name}_{previous_class_name}. Classes will no longer be
  deduplicated by appending a number to the end of the generated name, so if two names conflict with this new naming
  scheme, there will be an error instead.

Additions

• Added a --custom-template-path option for providing custom jinja2 templates (#231 - Thanks @erichulburd!).
• Better compatibility for "required" (whether or not the field must be included) and "nullable" (whether or not the field can be null) (#205 & #208). Thanks @bowenwr & @emannguitar!
• Support for all the same schemas in responses as are supported in parameters.

Fixes

• Prefix generated identifiers to allow leading digits in field names (#206 - @kalzoo).
• Prevent autoflake from removing __init__.py imports during generation. (#223 - Thanks @fyhertz!)
• Update minimum Pydantic version to support Python 3.9

Additions

• Allow specifying the generated client's version using package_version_override in a config file. (#225 - Thanks @fyhertz!)

Changes

• Use httpx ^0.15.0 in generated clients

Fixes

• Properly remove spaces from generated Enum keys (#198). Thanks @bowenwr!

Additions

• Endpoints without operationIds will have a name generated from their method and path (#92). Thanks @Kerybas & @dtkav!
• autoflake will be run on generated clients to clean up unused imports / variables (#138). Thanks @pawamoy!
• Note to README about supported OpenAPI versions (#176). Thanks @filippog!

This release is the culmination of a ton of feedback around the structure of generated clients. A huge thank you to everyone involved in making these improvements. That being said, clients generated with this release are not compatible with clients generated with 0.5.x. Use care when updating existing clients.

Breaking Changes

• Reorganized api calls in generated clients. async_api will no longer be generated. Each path operation will now
  have it's own module under its tag. For example, if there was a generated function api.my_tag.my_function() it is
  replaced with api.my_tag.my_function.sync(). The async version can be called with asyncio() instead of sync().
  (#167)
• Removed support for mutable default values (e.g. dicts, lists). They may be added back in a future version given enough
  demand, but the existing implementation was not up to this project's standards. (#170)
• Removed generated errors module (and the ApiResponseError therein). Instead of raising an exception on failure,
  the sync() and asyncio() functions for a path operation will return None. This means all return types are now
  Optional, so mypy will require you to handle potential errors (or explicitly ignore them).
• Moved models.types generated module up a level, so just types.
• All generated classes that were dataclass now use the attrs package instead

Additions

• Every generated API module will have a sync_detailed() and asyncio_detailed() function which work like their
  non-detailed counterparts, but return a types.Response[T] instead of an Optional[T] (where T is the parsed body type).
  types.Response contains status_code, content (bytes of returned content), headers, and parsed (the
  parsed return type you would get from the non-detailed function). (#115)
• It's now possible to include custom headers and cookies in requests, as well as set a custom timeout. This can be done
  either by directly setting those parameters on a Client (e.g. my_client.headers = {"Header": "Value"}) or using
  a fluid api (e.g. my_endpoint.sync(my_client.with_cookies({"MyCookie": "cookie"}).with_timeout(10.0))).
• Unsupported content types or no responses at all will no longer result in an endpoint being completely skipped. Instead,
  only the detailed versions of the endpoint will be generated, where the resulting Response.parsed is always None.
  (#141)
• Support for Python 3.6 (#137 & #154)
• Support for enums with integer values

Changes

• The format of any errors/warnings has been spaced out a bit.

Changes since previous alpha

Fixes

• Negative integers in enums (#185). Thanks @rweinberger!

Changes since last alpha

Breaking Changes

• All generated classes that were dataclass now use the attrs package instead

Additions

• Support for Python 3.6 (#137 & #154)
• Support for enums with integer values

Only includes changes since 0.6.0-alpha.1

Included from 0.5.5

• Improved trailing comma handling in endpoint generation (#178 & #179). Thanks @dtkav!
• Optional is now properly imported for nullable fields (#177 & #180). Thanks @dtkav!

Fixes

• Improved trailing comma handling in endpoint generation (#178 & #179). Thanks @dtkav!
• Optional is now properly imported for nullable fields (#177 & #180). Thanks @dtkav!

Breaking Changes

• Reorganized api calls in generated clients. async_api will no longer be generated. Each path operation will now have it's own module under its tag. For example, if there was a generated function api.my_tag.my_function() it is replaced with api.my_tag.my_function.sync(). The async version can be called with asyncio() instead of sync(). (#167)
• Removed support for mutable default values (e.g. dicts, lists). They may be added back in a future version given enough demand, but the existing implementation was not up to this project's standards. (#170)
• Removed generated errors module (and the ApiResponseError therein). Instead of raising an exception on failure, the sync() and asyncio() functions for a path operation will return None. This means all return types are now Optional, so mypy will require you to handle potential errors (or explicitly ignore them).
• Moved models.types generated module up a level, so just types.
• Client and AuthenticatedClient are now declared using the attrs package instead of builtin dataclass

Additions

• Every generated API module will have a sync_detailed() and asyncio_detailed() function which work like their non-detailed counterparts, but return a types.Response[T] instead of an Optional[T] (where T is the parsed body type). types.Response contains status_code, content (bytes of returned content), headers, and parsed (the parsed return type you would get from the non-detailed function). (#115)
• It's now possible to include custom headers and cookies in requests, as well as set a custom timeout. This can be done either by directly setting those parameters on a Client (e.g. my_client.headers = {"Header": "Value"}) or using a fluid api (e.g. my_endpoint.sync(my_client.with_cookies({"MyCookie": "cookie"}).with_timeout(10.0))).
• Unsupported content types or no responses at all will no longer result in an endpoint being completely skipped. Instead, only the detailed versions of the endpoint will be generated, where the resulting Response.parsed is always None. (#141)

Changes

• The format of any errors/warnings has been spaced out a bit.

Additions

• Support for octet-stream content type (#116)
• Support for nullable (#99)
• Union properties can be defined using oneOf (#98)
• Support for lists of strings, integers, floats and booleans as responses (#165). Thanks @Maistho!