Skip to content

codegen #

Code formatting and generation

Downloaders #

List of available methods for downloading Companies House Swagger Specifications.

download_folder #

download_folder(url: CHOASType | str, threaded: bool = True, flags: ReFormatFlags | None = SELECT_ALL_FORMAT_FLAGS, diff: bool = False) -> SchemaFolder

Downloads a Comapanies House Swagger specification folder and formats each file in it.

Parameters:

Name Type Description Default

url #

 str

the URL to download the API.

 required

threaded #

 bool

If True then will use multithreading to download the API.

NOTE: On my machine this increased the speed of the download process by between 4 and 5 times.

 True

flags #

 ReFormatFlags | None

selects various formatting rules. Default companies_house_codegen.constants.SELECT_ALL_FORMAT_FLAGS.

 SELECT_ALL_FORMAT_FLAGS

diff #

 bool

If True, logs the difference between pre and post formatting to stderr at INFO level logging. Default False.

 False

Returns:

Name Type Description
folder SchemaFolder

A dictionary mapping Remote JSON Reference paths (as strings) to dictionariess representing JSON data.
Also See

reformat_swagger : Reformats Companies House Swagger 2.0 specifications (in-place) and returns refs defined in the schema. CHOAS: enum of available Swagger 2.0 specfications.

Raises:

Type Description
HTTPError

If a bad HTTP request occurs

download_swagger #

download_swagger(url: CHOASType, threaded: bool = True, flags: ReFormatFlags | None = SELECT_ALL_FORMAT_FLAGS, diff: bool = False) -> JSONSchema

Downloads a Companies House Swagger specification.

Parameters:

Name Type Description Default

url #

 str

the URL to download the API.

 required

threaded #

 bool

If True then will use multithreading to download the API.

NOTE: On my machine this increased the speed of the download process by between 4 and 5 times.

 True

flags #

 ReFormatFlags | None

selects various formatting rules. Default companies_house_codegen.constants.SELECT_ALL_FORMAT_FLAGS.

 SELECT_ALL_FORMAT_FLAGS

diff #

 bool

If True, logs the difference between pre and post formatting to stderr at INFO level logging. Default False.

 False

Returns:

Name Type Description
swagger JSONSchema

A Companies House Swagger specification

Raises:

Type Description
HTTPError

If a bad HTTP request occurs
See Also

download_folder : Downloads a Comapanies House Swagger specification folder. zip_folder : Zips/compresses/packages a folder of Companies House Swagger specifications into a single Swagger specification.

Notes

A composite function of zip_folder and download_folder.

download_openapi #

download_openapi(url: CHOASType, threaded: bool = True, flags: ReFormatFlags | None = SELECT_ALL_FORMAT_FLAGS, diff: bool = False) -> JSONSchema

Convenient helper function for downloading a Companies House Swagger schema and converting it to

Parameters:

Name Type Description Default

url #

 str

the URL to download the API.

 required

threaded #

 bool

If True then will use multithreading to download the API.

NOTE: On my machine this increased the speed of the download process by between 4 and 5 times.

 True

flags #

 ReFormatFlags | None

selects various formatting rules. Default companies_house_codegen.constants.SELECT_ALL_FORMAT_FLAGS.

 SELECT_ALL_FORMAT_FLAGS

diff #

 bool

If True, logs the difference between pre and post formatting to stderr at INFO level logging. Default False.

 False

Returns:

Name Type Description
openapi JSONSchema

A OpenAPI 3.0.1 specification for a Companies House API.

Raises:

Type Description
HTTPError

If a bad HTTP request occurs
See Also

swagger_converter : Converts a 1.x or 2.x Swagger definition to the OpenAPI 3.0.1 format. download_swagger : Downloads a Companies House Swagger specification.

Notes

A composite function of swagger_converter and download_swagger.

Formatters #

List of format converters and linters for Companies House Swagger specifications.

reformat_swagger #

reformat_swagger(swagger: JSONSchema, remote_path: RemoteJsonRefPathStr, host: str = COMPANIES_HOUSE_HOST, scheme: URLSchemeType = HTTPS, flags: ReFormatFlags | None = SELECT_ALL_FORMAT_FLAGS, diff: bool = False) -> list[SplitResult]

Reformats Companies House Swagger 2.0 specifications (in-place) and returns refs defined in the schema.

Parameters:

Name Type Description Default

swagger #

 JSONSchema

A Companies House Swagger schema

 required

remote_path #

 RemoteJsonRefPathStr

Represents the part of a Remote JSON reference as described in Using $ref | Swagger Docs <https://swagger.io/docs/specification/v3_0/using-ref>_.

 required

host #

 str

The host name that overrides the feedback adress. Default 'developer-specs.company-information.service.gov.uk'.

 COMPANIES_HOUSE_HOST

scheme #

 URLSchemeType

The scheme that will be used for http request Default 'https'.

 HTTPS

flags #

 ReFormatFlags | None

selects various formatting rules. Default companies_house_codegen.constants.SELECT_ALL_FORMAT_FLAGS.

 SELECT_ALL_FORMAT_FLAGS

diff #

 bool

If True, logs the difference between pre and post formatting to stderr at INFO level logging. Default False.

 False
Notes

This function acts in-place.

Returns:

Name Type Description
refs SplitResult

All references defined in the schema

zip_folder #

zip_folder(folder: SchemaFolder, remote_path: RemoteJsonRefPathStr) -> JSONSchema

Zips/compresses/packages folder of Companies House Swagger specifications into a single Swagger specification.

Parameters:

Name Type Description Default

folder #

 SchemaFolder

A dictionary mapping Remote JSON Reference paths (as strings) to dictionaries reprenting JSON data.

 required

remote_path #

 RemoteJsonRefPathStr

the path the where the main swagger.json file is stored with folder

 required

Returns:

Name Type Description
swagger JSONSchema

A Companies House Swagger specification
Notes

Due to difference in parsing strategy this procedure will not yield the same result as what you would get by parsing the folder through version of the swagger-codegen-cli <https://github.com/swagger-api/swagger-codegen>_

The differences are as follows * This procedure will cull all unused defintions * This procedure will not change the defintion of schemas objects produce the same result as if you - JSON schemas will be fully resolved

See Also

download_folder : downloads a Companies House Swagger specification folder swagger_converter : Converts Swagger schemas to OpenAPI

swagger_converter #

swagger_converter(swagger: JSONSchema) -> JSONSchema

Converts a 1.x or 2.x Swagger definition to the OpenAPI 3.0.1 format.

Parameters:

Name Type Description Default

swagger #

 JSONSchema

A Companies House Swagger specification

 required

Returns:

Name Type Description
openapi JSONSchema

A OpenAPI 3.0.1 specification.
See Also

zip_folder : Zips/compresses/packages folder of Companies House Swagger specifications into a single Swagger specification. Swagger Converter : https://converter.swagger.io/api/openapi.json

Notes

This a wrapper for the Swagger Converter<https://converter.swagger.io/api/openapi.json>_ API

Raises:

Type Description
HTTPError

If a bad HTTP request occurs
ValueError

if scheme is malformed
NotImplementationError

if attempting to pass a fragment of a scheme