[Python experimental] Readme improvements

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

@@ -1,13 +1,13 @@
 ```python
 from __future__ import print_function
+{{#apiInfo}}{{#apis}}{{^hasMore}}{{#hasHttpSignatureMethods}}import datetime{{/hasHttpSignatureMethods}}{{/hasMore}}{{/apis}}{{/apiInfo}}
 import time
 import {{{packageName}}}
 from {{{packageName}}}.rest import ApiException
 from pprint import pprint
 {{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
 {{> python_doc_auth_partial}}
-# Defining host is optional and default to {{{basePath}}}
-configuration.host = "{{{basePath}}}"
+
 # Enter a context with an instance of the API client
 with {{{packageName}}}.ApiClient(configuration) as api_client:
     # Create an instance of the API class

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

@@ -62,10 +62,12 @@ class Configuration(object):
             name: JSESSIONID  # cookie name
 
     You can programmatically set the cookie:
-      conf = {{{packageName}}}.Configuration(
-        api_key={'cookieAuth': 'abc123'}
-        api_key_prefix={'cookieAuth': 'JSESSIONID'}
-      )
+
+conf = {{{packageName}}}.Configuration(
+    api_key={'cookieAuth': 'abc123'}
+    api_key_prefix={'cookieAuth': 'JSESSIONID'}
+)
+
     The following cookie will be added to the HTTP request:
        Cookie: JSESSIONID abc123
 {{/hasApiKeyMethods}}
@@ -80,10 +82,12 @@ class Configuration(object):
             scheme: basic
 
     Configure API client with HTTP basic authentication:
-      conf = {{{packageName}}}.Configuration(
-          username='the-user',
-          password='the-password',
-      )
+
+conf = {{{packageName}}}.Configuration(
+    username='the-user',
+    password='the-password',
+)
+
 {{/hasHttpBasicMethods}}
 {{#hasHttpSignatureMethods}}
 
@@ -107,24 +111,24 @@ class Configuration(object):
     load balancers may add/modify/remove headers. Include the HTTP headers that you know
     are not going to be modified in transit.
 
-      conf = {{{packageName}}}.Configuration(
-        signing_info = {{{packageName}}}.signing.HttpSigningConfiguration(
-            key_id =                 'my-key-id',
-            private_key_path =       'rsa.pem',
-            signing_scheme =         signing.SCHEME_HS2019,
-            signing_algorithm =      signing.ALGORITHM_RSASSA_PSS,
-            signed_headers =         [signing.HEADER_REQUEST_TARGET,
-                                      signing.HEADER_CREATED,
-                                      signing.HEADER_EXPIRES,
-                                      signing.HEADER_HOST,
-                                      signing.HEADER_DATE,
-                                      signing.HEADER_DIGEST,
-                                      'Content-Type',
-                                      'User-Agent'
-                                     ],
-            signature_max_validity = datetime.timedelta(minutes=5)
-        )
-      )
+conf = {{{packageName}}}.Configuration(
+    signing_info = {{{packageName}}}.signing.HttpSigningConfiguration(
+        key_id =                 'my-key-id',
+        private_key_path =       'rsa.pem',
+        signing_scheme =         {{{packageName}}}.signing.SCHEME_HS2019,
+        signing_algorithm =      {{{packageName}}}.signing.ALGORITHM_RSASSA_PSS,
+        signed_headers =         [{{{packageName}}}.signing.HEADER_REQUEST_TARGET,
+                                    {{{packageName}}}.signing.HEADER_CREATED,
+                                    {{{packageName}}}.signing.HEADER_EXPIRES,
+                                    {{{packageName}}}.signing.HEADER_HOST,
+                                    {{{packageName}}}.signing.HEADER_DATE,
+                                    {{{packageName}}}.signing.HEADER_DIGEST,
+                                    'Content-Type',
+                                    'User-Agent'
+                                    ],
+        signature_max_validity = datetime.timedelta(minutes=5)
+    )
+)
 {{/hasHttpSignatureMethods}}
 {{/hasAuthMethods}}
     """

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

@@ -1,12 +1,12 @@
 ```python
 from __future__ import print_function
+{{#apiInfo}}{{#apis}}{{^hasMore}}{{#hasHttpSignatureMethods}}import datetime{{/hasHttpSignatureMethods}}{{/hasMore}}{{/apis}}{{/apiInfo}}
 import time
 import {{{packageName}}}
 from pprint import pprint
 {{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
 {{> python_doc_auth_partial}}
-# Defining host is optional and default to {{{basePath}}}
-configuration.host = "{{{basePath}}}"
+
 # Enter a context with an instance of the API client
 with {{{packageName}}}.ApiClient(configuration) as api_client:
     # Create an instance of the API class

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

@@ -1,51 +1,113 @@
+# Defining the host is optional and defaults to {{{basePath}}}
+# See configuration.py for a list of all supported configuration parameters.
+configuration = {{{packageName}}}.Configuration(
+    host = "{{{basePath}}}"
+)
+
 {{#hasAuthMethods}}
+# The client must configure the authentication and authorization parameters
+# in accordance with the API server security policy.
+# Examples for each auth method are provided below, use the example that
+# satisfies your auth use case.
 {{#authMethods}}
-configuration = {{{packageName}}}.Configuration()
 {{#isBasic}}
 {{#isBasicBasic}}
+
 # Configure HTTP basic authorization: {{{name}}}
-configuration.username = 'YOUR_USERNAME'
-configuration.password = 'YOUR_PASSWORD'
+configuration = {{{packageName}}}.Configuration(
+    username = 'YOUR_USERNAME',
+    password = 'YOUR_PASSWORD'
+)
 {{/isBasicBasic}}
 {{#isBasicBearer}}
+
 # Configure Bearer authorization{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}: {{{name}}}
-configuration.access_token = 'YOUR_BEARER_TOKEN'
+configuration = {{{packageName}}}.Configuration(
+    access_token = 'YOUR_BEARER_TOKEN'
+)
 {{/isBasicBearer}}
 {{#isHttpSignature}}
-# Configure HTTP signature authorization: {{{name}}}
-# You can specify the signing key-id, private key path, signing scheme, signing algorithm,
-# list of signed headers and signature max validity.
-configuration.signing_info = {{{packageName}}}.signing.HttpSigningConfiguration(
-    key_id =                 'my-key-id',
-    private_key_path =       'rsa.pem',
-    signing_scheme =         signing.SCHEME_HS2019,
-    signing_algorithm =      signing.ALGORITHM_RSASSA_PSS,
-    signed_headers =         [signing.HEADER_REQUEST_TARGET,
-                                signing.HEADER_CREATED,
-                                signing.HEADER_EXPIRES,
-                                signing.HEADER_HOST,
-                                signing.HEADER_DATE,
-                                signing.HEADER_DIGEST,
-                                'Content-Type',
-                                'Content-Length',
-                                'User-Agent'
-                                ],
-    signature_max_validity = datetime.timedelta(minutes=5)
+
+# Configure HTTP message signature: {{{name}}}
+# The HTTP Signature Header mechanism that can be used by a client to
+# authenticate the sender of a message and ensure that particular headers
+# have not been modified in transit.
+#
+# You can specify the signing key-id, private key path, signing scheme,
+# signing algorithm, list of signed headers and signature max validity.
+# The 'key_id' parameter is an opaque string that the API server can use
+# to lookup the client and validate the signature.
+# The 'private_key_path' parameter should be the path to a file that
+# contains a DER or base-64 encoded private key.
+# The 'private_key_passphrase' parameter is optional. Set the passphrase
+# if the private key is encrypted.
+# The 'signed_headers' parameter is used to specify the list of
+# HTTP headers included when generating the signature for the message.
+# You can specify HTTP headers that you want to protect with a cryptographic
+# signature. Note that proxies may add, modify or remove HTTP headers
+# for legitimate reasons, so you should only add headers that you know
+# will not be modified. For example, if you want to protect the HTTP request
+# body, you can specify the Digest header. In that case, the client calculates
+# the digest of the HTTP request body and includes the digest in the message
+# signature.
+# The 'signature_max_validity' parameter is optional. It is configured as a
+# duration to express when the signature ceases to be valid. The client calculates
+# the expiration date every time it generates the cryptographic signature
+# of an HTTP request. The API server may have its own security policy
+# that controls the maximum validity of the signature. The client max validity
+# must be lower than the server max validity.
+# The time on the client and server must be synchronized, otherwise the
+# server may reject the client signature.
+#
+# The client must use a combination of private key, signing scheme,
+# signing algorithm and hash algorithm that matches the security policy of
+# the API server.
+#
+# See {{{packageName}}}.signing for a list of all supported parameters.
+configuration = {{{packageName}}}.Configuration(
+    host = "{{{basePath}}}",
+    signing_info = {{{packageName}}}.signing.HttpSigningConfiguration(
+        key_id = 'my-key-id',
+        private_key_path = 'private_key.pem',
+        private_key_passphrase = 'YOUR_PASSPHRASE',
+        signing_scheme = {{{packageName}}}.signing.SCHEME_HS2019,
+        signing_algorithm = {{{packageName}}}.signing.ALGORITHM_ECDSA_MODE_FIPS_186_3,
+        hash_algorithm = {{{packageName}}}.signing.SCHEME_RSA_SHA256,
+        signed_headers = [
+                            {{{packageName}}}.signing.HEADER_REQUEST_TARGET,
+                            {{{packageName}}}.signing.HEADER_CREATED,
+                            {{{packageName}}}.signing.HEADER_EXPIRES,
+                            {{{packageName}}}.signing.HEADER_HOST,
+                            {{{packageName}}}.signing.HEADER_DATE,
+                            {{{packageName}}}.signing.HEADER_DIGEST,
+                            'Content-Type',
+                            'Content-Length',
+                            'User-Agent'
+                         ],
+        signature_max_validity = datetime.timedelta(minutes=5)
+    )
 )
 {{/isHttpSignature}}
 {{/isBasic}}
 {{#isApiKey}}
+
 # Configure API key authorization: {{{name}}}
-configuration.api_key['{{{keyParamName}}}'] = 'YOUR_API_KEY'
+configuration = {{{packageName}}}.Configuration(
+    host = "{{{basePath}}}",
+    api_key = {
+        '{{{keyParamName}}}': 'YOUR_API_KEY'
+    }
+)
 # Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
 # configuration.api_key_prefix['{{{keyParamName}}}'] = 'Bearer'
 {{/isApiKey}}
 {{#isOAuth}}
+
 # Configure OAuth2 access token for authorization: {{{name}}}
+configuration = {{{packageName}}}.Configuration(
+    host = "{{{basePath}}}"
+)
 configuration.access_token = 'YOUR_ACCESS_TOKEN'
 {{/isOAuth}}
 {{/authMethods}}
-
-# Defining host is optional and default to {{{basePath}}}
-configuration.host = "{{{basePath}}}"
 {{/hasAuthMethods}}

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

@@ -46,14 +46,20 @@ Please follow the [installation procedure](#installation--usage) and then run th
 
 ```python
 from __future__ import print_function
+
 import time
 import petstore_api
 from petstore_api.rest import ApiException
 from pprint import pprint
 
+# Defining the host is optional and defaults to http://petstore.swagger.io:80/v2
+# See configuration.py for a list of all supported configuration parameters.
+configuration = petstore_api.Configuration(
+    host = "http://petstore.swagger.io:80/v2"
+)
+
+
 
-# Defining host is optional and default to http://petstore.swagger.io:80/v2
-configuration.host = "http://petstore.swagger.io:80/v2"
 # Enter a context with an instance of the API client
 with petstore_api.ApiClient(configuration) as api_client:
     # Create an instance of the API class

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

@@ -22,6 +22,12 @@ import time
 import petstore_api
 from petstore_api.rest import ApiException
 from pprint import pprint
+# Defining the host is optional and defaults to http://petstore.swagger.io:80/v2
+# See configuration.py for a list of all supported configuration parameters.
+configuration = petstore_api.Configuration(
+    host = "http://petstore.swagger.io:80/v2"
+)
+
 
 # Enter a context with an instance of the API client
 with petstore_api.ApiClient() as api_client: