Skip to content

Commit 5b6ae10

Browse files
sebastien-rossetmichaelpro1
sebastien-rosset
authored and
michaelpro1
committed
[Python experimental] Readme improvements (OpenAPITools#6031)
* Python experimental readme improvements * Python experimental readme improvements * execute scripts in bin directory
1 parent d63481b commit 5b6ae10

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+2499
-543
lines changed

‎modules/openapi-generator/src/main/resources/python/common_README.mustache

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
```python
22
from __future__ import print_function
3+
{{#apiInfo}}{{#apis}}{{^hasMore}}{{#hasHttpSignatureMethods}}import datetime{{/hasHttpSignatureMethods}}{{/hasMore}}{{/apis}}{{/apiInfo}}
34
import time
45
import {{{packageName}}}
56
from {{{packageName}}}.rest import ApiException
67
from pprint import pprint
78
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
89
{{> python_doc_auth_partial}}
9-
# Defining host is optional and default to {{{basePath}}}
10-
configuration.host = "{{{basePath}}}"
10+
1111
# Enter a context with an instance of the API client
1212
with {{{packageName}}}.ApiClient(configuration) as api_client:
1313
# Create an instance of the API class

‎modules/openapi-generator/src/main/resources/python/configuration.mustache

Lines changed: 30 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -62,10 +62,12 @@ class Configuration(object):
6262
name: JSESSIONID # cookie name
6363

6464
You can programmatically set the cookie:
65-
conf = {{{packageName}}}.Configuration(
66-
api_key={'cookieAuth': 'abc123'}
67-
api_key_prefix={'cookieAuth': 'JSESSIONID'}
68-
)
65+
66+
conf = {{{packageName}}}.Configuration(
67+
api_key={'cookieAuth': 'abc123'}
68+
api_key_prefix={'cookieAuth': 'JSESSIONID'}
69+
)
70+
6971
The following cookie will be added to the HTTP request:
7072
Cookie: JSESSIONID abc123
7173
{{/hasApiKeyMethods}}
@@ -80,10 +82,12 @@ class Configuration(object):
8082
scheme: basic
8183

8284
Configure API client with HTTP basic authentication:
83-
conf = {{{packageName}}}.Configuration(
84-
username='the-user',
85-
password='the-password',
86-
)
85+
86+
conf = {{{packageName}}}.Configuration(
87+
username='the-user',
88+
password='the-password',
89+
)
90+
8791
{{/hasHttpBasicMethods}}
8892
{{#hasHttpSignatureMethods}}
8993

@@ -107,24 +111,24 @@ class Configuration(object):
107111
load balancers may add/modify/remove headers. Include the HTTP headers that you know
108112
are not going to be modified in transit.
109113

110-
conf = {{{packageName}}}.Configuration(
111-
signing_info = {{{packageName}}}.signing.HttpSigningConfiguration(
112-
key_id = 'my-key-id',
113-
private_key_path = 'rsa.pem',
114-
signing_scheme = signing.SCHEME_HS2019,
115-
signing_algorithm = signing.ALGORITHM_RSASSA_PSS,
116-
signed_headers = [signing.HEADER_REQUEST_TARGET,
117-
signing.HEADER_CREATED,
118-
signing.HEADER_EXPIRES,
119-
signing.HEADER_HOST,
120-
signing.HEADER_DATE,
121-
signing.HEADER_DIGEST,
122-
'Content-Type',
123-
'User-Agent'
124-
],
125-
signature_max_validity = datetime.timedelta(minutes=5)
126-
)
127-
)
114+
conf = {{{packageName}}}.Configuration(
115+
signing_info = {{{packageName}}}.signing.HttpSigningConfiguration(
116+
key_id = 'my-key-id',
117+
private_key_path = 'rsa.pem',
118+
signing_scheme = {{{packageName}}}.signing.SCHEME_HS2019,
119+
signing_algorithm = {{{packageName}}}.signing.ALGORITHM_RSASSA_PSS,
120+
signed_headers = [{{{packageName}}}.signing.HEADER_REQUEST_TARGET,
121+
{{{packageName}}}.signing.HEADER_CREATED,
122+
{{{packageName}}}.signing.HEADER_EXPIRES,
123+
{{{packageName}}}.signing.HEADER_HOST,
124+
{{{packageName}}}.signing.HEADER_DATE,
125+
{{{packageName}}}.signing.HEADER_DIGEST,
126+
'Content-Type',
127+
'User-Agent'
128+
],
129+
signature_max_validity = datetime.timedelta(minutes=5)
130+
)
131+
)
128132
{{/hasHttpSignatureMethods}}
129133
{{/hasAuthMethods}}
130134
"""

‎modules/openapi-generator/src/main/resources/python/python-experimental/README_common.mustache

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
```python
22
from __future__ import print_function
3+
{{#apiInfo}}{{#apis}}{{^hasMore}}{{#hasHttpSignatureMethods}}import datetime{{/hasHttpSignatureMethods}}{{/hasMore}}{{/apis}}{{/apiInfo}}
34
import time
45
import {{{packageName}}}
56
from pprint import pprint
67
{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
78
{{> python_doc_auth_partial}}
8-
# Defining host is optional and default to {{{basePath}}}
9-
configuration.host = "{{{basePath}}}"
9+
1010
# Enter a context with an instance of the API client
1111
with {{{packageName}}}.ApiClient(configuration) as api_client:
1212
# Create an instance of the API class

‎modules/openapi-generator/src/main/resources/python/python_doc_auth_partial.mustache

Lines changed: 89 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,113 @@
1+
# Defining the host is optional and defaults to {{{basePath}}}
2+
# See configuration.py for a list of all supported configuration parameters.
3+
configuration = {{{packageName}}}.Configuration(
4+
host = "{{{basePath}}}"
5+
)
6+
17
{{#hasAuthMethods}}
8+
# The client must configure the authentication and authorization parameters
9+
# in accordance with the API server security policy.
10+
# Examples for each auth method are provided below, use the example that
11+
# satisfies your auth use case.
212
{{#authMethods}}
3-
configuration = {{{packageName}}}.Configuration()
413
{{#isBasic}}
514
{{#isBasicBasic}}
15+
616
# Configure HTTP basic authorization: {{{name}}}
7-
configuration.username = 'YOUR_USERNAME'
8-
configuration.password = 'YOUR_PASSWORD'
17+
configuration = {{{packageName}}}.Configuration(
18+
username = 'YOUR_USERNAME',
19+
password = 'YOUR_PASSWORD'
20+
)
921
{{/isBasicBasic}}
1022
{{#isBasicBearer}}
23+
1124
# Configure Bearer authorization{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}: {{{name}}}
12-
configuration.access_token = 'YOUR_BEARER_TOKEN'
25+
configuration = {{{packageName}}}.Configuration(
26+
access_token = 'YOUR_BEARER_TOKEN'
27+
)
1328
{{/isBasicBearer}}
1429
{{#isHttpSignature}}
15-
# Configure HTTP signature authorization: {{{name}}}
16-
# You can specify the signing key-id, private key path, signing scheme, signing algorithm,
17-
# list of signed headers and signature max validity.
18-
configuration.signing_info = {{{packageName}}}.signing.HttpSigningConfiguration(
19-
key_id = 'my-key-id',
20-
private_key_path = 'rsa.pem',
21-
signing_scheme = signing.SCHEME_HS2019,
22-
signing_algorithm = signing.ALGORITHM_RSASSA_PSS,
23-
signed_headers = [signing.HEADER_REQUEST_TARGET,
24-
signing.HEADER_CREATED,
25-
signing.HEADER_EXPIRES,
26-
signing.HEADER_HOST,
27-
signing.HEADER_DATE,
28-
signing.HEADER_DIGEST,
29-
'Content-Type',
30-
'Content-Length',
31-
'User-Agent'
32-
],
33-
signature_max_validity = datetime.timedelta(minutes=5)
30+
31+
# Configure HTTP message signature: {{{name}}}
32+
# The HTTP Signature Header mechanism that can be used by a client to
33+
# authenticate the sender of a message and ensure that particular headers
34+
# have not been modified in transit.
35+
#
36+
# You can specify the signing key-id, private key path, signing scheme,
37+
# signing algorithm, list of signed headers and signature max validity.
38+
# The 'key_id' parameter is an opaque string that the API server can use
39+
# to lookup the client and validate the signature.
40+
# The 'private_key_path' parameter should be the path to a file that
41+
# contains a DER or base-64 encoded private key.
42+
# The 'private_key_passphrase' parameter is optional. Set the passphrase
43+
# if the private key is encrypted.
44+
# The 'signed_headers' parameter is used to specify the list of
45+
# HTTP headers included when generating the signature for the message.
46+
# You can specify HTTP headers that you want to protect with a cryptographic
47+
# signature. Note that proxies may add, modify or remove HTTP headers
48+
# for legitimate reasons, so you should only add headers that you know
49+
# will not be modified. For example, if you want to protect the HTTP request
50+
# body, you can specify the Digest header. In that case, the client calculates
51+
# the digest of the HTTP request body and includes the digest in the message
52+
# signature.
53+
# The 'signature_max_validity' parameter is optional. It is configured as a
54+
# duration to express when the signature ceases to be valid. The client calculates
55+
# the expiration date every time it generates the cryptographic signature
56+
# of an HTTP request. The API server may have its own security policy
57+
# that controls the maximum validity of the signature. The client max validity
58+
# must be lower than the server max validity.
59+
# The time on the client and server must be synchronized, otherwise the
60+
# server may reject the client signature.
61+
#
62+
# The client must use a combination of private key, signing scheme,
63+
# signing algorithm and hash algorithm that matches the security policy of
64+
# the API server.
65+
#
66+
# See {{{packageName}}}.signing for a list of all supported parameters.
67+
configuration = {{{packageName}}}.Configuration(
68+
host = "{{{basePath}}}",
69+
signing_info = {{{packageName}}}.signing.HttpSigningConfiguration(
70+
key_id = 'my-key-id',
71+
private_key_path = 'private_key.pem',
72+
private_key_passphrase = 'YOUR_PASSPHRASE',
73+
signing_scheme = {{{packageName}}}.signing.SCHEME_HS2019,
74+
signing_algorithm = {{{packageName}}}.signing.ALGORITHM_ECDSA_MODE_FIPS_186_3,
75+
hash_algorithm = {{{packageName}}}.signing.SCHEME_RSA_SHA256,
76+
signed_headers = [
77+
{{{packageName}}}.signing.HEADER_REQUEST_TARGET,
78+
{{{packageName}}}.signing.HEADER_CREATED,
79+
{{{packageName}}}.signing.HEADER_EXPIRES,
80+
{{{packageName}}}.signing.HEADER_HOST,
81+
{{{packageName}}}.signing.HEADER_DATE,
82+
{{{packageName}}}.signing.HEADER_DIGEST,
83+
'Content-Type',
84+
'Content-Length',
85+
'User-Agent'
86+
],
87+
signature_max_validity = datetime.timedelta(minutes=5)
88+
)
3489
)
3590
{{/isHttpSignature}}
3691
{{/isBasic}}
3792
{{#isApiKey}}
93+
3894
# Configure API key authorization: {{{name}}}
39-
configuration.api_key['{{{keyParamName}}}'] = 'YOUR_API_KEY'
95+
configuration = {{{packageName}}}.Configuration(
96+
host = "{{{basePath}}}",
97+
api_key = {
98+
'{{{keyParamName}}}': 'YOUR_API_KEY'
99+
}
100+
)
40101
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
41102
# configuration.api_key_prefix['{{{keyParamName}}}'] = 'Bearer'
42103
{{/isApiKey}}
43104
{{#isOAuth}}
105+
44106
# Configure OAuth2 access token for authorization: {{{name}}}
107+
configuration = {{{packageName}}}.Configuration(
108+
host = "{{{basePath}}}"
109+
)
45110
configuration.access_token = 'YOUR_ACCESS_TOKEN'
46111
{{/isOAuth}}
47112
{{/authMethods}}
48-
49-
# Defining host is optional and default to {{{basePath}}}
50-
configuration.host = "{{{basePath}}}"
51113
{{/hasAuthMethods}}

‎samples/client/petstore/python-asyncio/README.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,14 +46,20 @@ Please follow the [installation procedure](#installation--usage) and then run th
4646

4747
```python
4848
from __future__ import print_function
49+
4950
import time
5051
import petstore_api
5152
from petstore_api.rest import ApiException
5253
from pprint import pprint
5354

55+
# Defining the host is optional and defaults to http://petstore.swagger.io:80/v2
56+
# See configuration.py for a list of all supported configuration parameters.
57+
configuration = petstore_api.Configuration(
58+
host = "http://petstore.swagger.io:80/v2"
59+
)
60+
61+
5462

55-
# Defining host is optional and default to http://petstore.swagger.io:80/v2
56-
configuration.host = "http://petstore.swagger.io:80/v2"
5763
# Enter a context with an instance of the API client
5864
with petstore_api.ApiClient(configuration) as api_client:
5965
# Create an instance of the API class

‎samples/client/petstore/python-asyncio/docs/AnotherFakeApi.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ import time
2222
import petstore_api
2323
from petstore_api.rest import ApiException
2424
from pprint import pprint
25+
# Defining the host is optional and defaults to http://petstore.swagger.io:80/v2
26+
# See configuration.py for a list of all supported configuration parameters.
27+
configuration = petstore_api.Configuration(
28+
host = "http://petstore.swagger.io:80/v2"
29+
)
30+
2531

2632
# Enter a context with an instance of the API client
2733
with petstore_api.ApiClient() as api_client:

0 commit comments

Comments
 (0)