v3 docs update including migration doc

README.md

@@ -1,4 +1,4 @@
-# OpenAPI JSON Schema Generator</h1>
+# OpenAPI JSON Schema Generator
 
 [![CI Tests](https://dl.circleci.com/status-badge/img/gh/openapi-json-schema-tools/openapi-json-schema-generator/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/openapi-json-schema-tools/openapi-json-schema-generator/tree/master)
 [![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-orange)](./LICENSE)
@@ -23,39 +23,43 @@ You can join us here: https://discord.gg/mHB8WEQuYQ
 
 ## Reasons To Use the Python Generator
 
-- [Autogenerated thorough testing of json schema keyword features in models and endpoints](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python/test) which come from the [json schema test suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) 
-- [Tests are passing in CI](https://app.circleci.com/pipelines/github/openapi-json-schema-tools/openapi-json-schema-generator?branch=master)
-- [Test endpoints are tagged by the relevant keyword like type/format/allOf 25+ keywords and counting](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python/docs/apis/tags)
+- Type hints on
+  - schema payload inputs in SomeSchema.validate ![validate screen capture](docs/schema_validate.gif)
+    - Note: to make input dictionaries TypedDicts like the Money.validate example, set additionalProperties to false in the schema in your openapi document
+  - schema keyword argument inputs in `SomeSchemaDict.__new__` ![validate screen capture](docs/schemadict_new.gif)
+  - accessing properties in object instances so some_val in some_val = some_inst.someKey will have the correct type hint ![instance properties screen capture](docs/instance_properties.gif)
+  - accessing array items in array instances so some_val in some_val = array_inst[0] will have the correct type hint
+  - endpoint inputs + responses
 - Run time type checking and validation checking when:
   - instantiating models
   - sending to endpoints
   - receiving from endpoints
-- Type hints on
-  - all model inputs in `__new__`
-  - accessing properties in object instances so some_val in some_val = some_inst['someKey'] will have the correct type hint
-  - accessing array items in array instances so some_val in some_val = array_inst[0] will have the correct type hint
-  - endpoint inputs + responses
+  - Note: if needed, validation of json schema keywords can be deactivated via a SchemaConfiguration class
+- [mypy](samples/client/petstore/python/test_python.sh) runs on sample petstore client and passes
+  - passing mypy tests means that this generator could be ported into compiled languages lik java/kotlin/golang
+- [Autogenerated thorough testing of json schema keyword features in models and endpoints](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python/test) which come from the [json schema test suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
+- [Tests are passing in CI](https://app.circleci.com/pipelines/github/openapi-json-schema-tools/openapi-json-schema-generator?branch=master)
+- [Test endpoints are tagged by the relevant keyword like type/format/allOf 25+ keywords and counting](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python/docs/apis/tags)
 - Code re-use built in from the ground up
   - components/schemas/headers etc are generated as separate classes and imported when used via $ref
 - Openapi spec inline schemas supported at any depth in any location
 - Format support for: int32, int64, float, double, binary, date, datetime, uuid
 - Invalid (in python) property names supported like `from`, `1var`, `hi-there` etc in
   - schema property names
   - endpoint parameter names
-- If needed, validation of some json schema keywords can be deactivated via a configuration class
 - Payload values are not coerced when validated, so a datetime value can pass other validations that describe the payload only as type string
-- String transmission of numbers supported with type: string, format: number, value can be accessed as a Decimal with inst.as_decimal_
+- types are generated for enums of type string/integer/boolean using typing.Literal
+- String transmission of numbers supported with type: string, format: number, value can be accessed as a Decimal with schemas.as_decimal(inst)
 - Multiple content types supported for request and response bodies
 - Endpoint response always also includes the urllib3.HTTPResponse
 - Endpoint response deserialization can be skipped with the skip_deserialization argument
-- Validated payload instances subclass all validated schemas so no need to run validate twice, just use isinstance(some_inst, SomeSchemaClass)
 
 And many more!
-- [Docs for the python generator](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/blob/master/docs/generators/python.md)
-- [Openapi v3.0.3 general petstore spec, general features](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/blob/master/src/test/resources/3_0/python/petstore_customized.yaml)
-  - [generated client sample code](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/petstore/python)
-- [Openapi json schema v3.0.3 unit test spec](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/blob/master/src/test/resources/3_0/unit_test_spec/3_0_3_unit_test_spec.yaml)
-  - [generated client sample code](https://github.com/openapi-json-schema-tools/openapi-json-schema-generator/tree/master/samples/client/3_0_3_unit_test/python)
+- [Docs for the python generator](docs/generators/python.md)
+- [generated client sample code](samples/client/petstore/python)
+  - [Openapi v3.0.3 general petstore spec, general features](src/test/resources/3_0/python/petstore_customized.yaml)
+- [generated client sample code](samples/client/3_0_3_unit_test/python)
+  - [Openapi json schema v3.0.3 unit test spec](src/test/resources/3_0/unit_test_spec/3_0_3_unit_test_spec.yaml)
 
 ### Can I build here?
 
@@ -67,28 +71,29 @@ Submit a PR if you want to add a new server scaffold, client sdk, or documentati
   - [OpenAPI JSON Schema Generator](#openapi-json-schema-generator)
   - [Overview](#overview)
   - [Table of Contents](#table-of-contents)
-  - [1 - Installation](#1---installation)
-    - [1.1 - Compatibility](#11---compatibility)
-    - [1.2 - Build Projects](#12---build-projects)
-    - [1.3 - Docker](#13---docker)
-  - [2 - Getting Started](#2---getting-started)
-  - [3 - Usage](#3---usage)
-    - [3.1 - Customization](#31---customization)
-    - [3.2 - Workflow Integration](#32---workflow-integration-maven-gradle-github-cicd)
-    - [3.3 - License Information on Generated Code](#34---license-information-on-generated-code)
-  - [4 - Companies/Projects using OpenAPI JSON Schema Generator](#4---companiesprojects-using-openapi-json-schema-generator)
-  - [5 - About Us](#5---about-us)
-    - [5.1 - History of OpenAPI JSON Schema Generator](#51---history-of-openapi-json-schema-generator)
-  - [6 - License](#6---license)
-
-## [1 - Installation](#table-of-contents)
-
-### [1.1 - Compatibility](#table-of-contents)
+  - [Installation](#installation)
+    - [Compatibility](#compatibility)
+    - [Build Projects](#build-projects)
+    - [Docker](#docker)
+  - [Getting Started](#getting-started)
+  - [Usage](#usage)
+    - [Customization](#customization)
+    - [Workflow Integration](#workflow-integration)
+    - [License Information](#license-information)
+  - [Companies/Projects using OpenAPI JSON Schema Generator](#companiesprojects-using-openapi-json-schema-generator)
+  - [About Us](#about-us)
+    - [History of OpenAPI JSON Schema Generator](#history-of-openapi-json-schema-generator)
+  - [License](#license)
+
+## Installation
+
+### Compatibility
 
 The OpenAPI Specification has undergone 3 revisions since initial creation in 2010.  The openapi-json-schema-generator project has the following compatibilities with the OpenAPI Specification:
 
 | OpenAPI JSON Schema Generator Version | OpenAPI Spec compatibility  |
 |---------------------------------------|-----------------------------|
+| 3.0.0                                 | 3.0.0 - 3.0.3               |
 | 2.0.3                                 | 3.0.0 - 3.0.3               |
 | 2.0.2                                 | 3.0.0 - 3.0.3               |
 | 2.0.1                                 | 3.0.0 - 3.0.3               |
@@ -100,7 +105,7 @@ The OpenAPI Specification has undergone 3 revisions since initial creation in 20
 | 1.0.0                                 | 3.0.0 - 3.0.3               |
 
 
-### [1.2 - Build Projects](#table-of-contents)
+### Build Projects
 
 To build from source, you need the following installed and available in your `$PATH:`
 
@@ -119,7 +124,7 @@ The default build contains minimal static analysis (via CheckStyle). To run your
 mvn -Pstatic-analysis clean install
 ```
 
-### [1.3 - Docker](#table-of-contents)
+### Docker
 
 #### Public Pre-built Docker images
 
@@ -182,7 +187,7 @@ If an error like this occurs, just execute the **mvn clean install -U** command:
 Right now: no solution for this one :|
 
 <!-- /RELEASE_VERSION -->
-## [2 - Getting Started](#table-of-contents)
+## Getting Started
 
 To generate a python client for [petstore.yaml](https://raw.githubusercontent.com/openapi-json-schema-tools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml), please run the following
 ```sh
@@ -204,7 +209,7 @@ To get a list of **general** options available, please run `java -jar target/ope
 
 To get a list of PHP specified options (which can be passed to the generator with a config file via the `-c` option), please run `java -jar target/openapi-json-schema-generator-cli.jar config-help -g php`
 
-## [3 - Usage](#table-of-contents)
+## Usage
 
 ### To generate a sample client library
 You can build a client against the [Petstore API](https://raw.githubusercontent.com/openapijsonschematools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml) as follows:
@@ -283,17 +288,17 @@ OPTIONS
 
 You can then use the auto-generated client. The README.md is a good starting point.
 
-Other generators have [samples](https://github.com/OpenAPITools/openapi-json-schema-generator/tree/master/samples) too.
+Other generators have [samples](samples) too.
 
-### [3.1 - Customization](#table-of-contents)
+### Customization
 
 Please refer to [customization.md](docs/customization.md) on how to customize the output (e.g. package name, version)
 
-### [3.2 - Workflow Integration (Maven, Gradle, Github, CI/CD)](#table-of-contents)
+### Workflow Integration
 
 Please refer to [integration.md](docs/integration.md) on how to integrate OpenAPI generator with Maven, Gradle,  Github and CI/CD.
 
-### [3.3 - License information on Generated Code](#table-of-contents)
+### License Information
 
 The OpenAPI JSON Schema Generator project is intended as a benefit for users of the Open API Specification.  The project itself has the [License](#license) as specified. In addition, please understand the following points:
 
@@ -302,13 +307,15 @@ The OpenAPI JSON Schema Generator project is intended as a benefit for users of
 
 When code is generated from this project, it shall be considered **AS IS** and owned by the user of the software.  There are no warranties--expressed or implied--for generated code.  You can do what you wish with it, and once generated, the code is your responsibility and subject to the licensing terms that you deem appropriate.
 
-## [4 - Companies/Projects using OpenAPI JSON Schema Generator](#table-of-contents)
+## Companies/Projects using OpenAPI JSON Schema Generator
+
+[Github code search](https://github.com/search?q=DateSchema+DateTimeSchema+language%3APython+path%3A**%2Fschemas.py&type=code)
 
-## [5 - About Us](#table-of-contents)
+## About Us
 
 This repo is based on v6.2.0 of OpenAPI Generator. This project focuses on making the output 100% compliant with JSON schema as part of the OpenAPI 3.1 specification with a focus on complex cases (top-down approach). The goal is to fully support everything defined in JSON schema so that developers can leverage JSON schema as well as OpenAPI specification in their API design. Building here allows for more rapid progress supporting new features in OpenAPI 3.X without having to support many older generators which don't use the new features.
 
-### [5.1 - History of OpenAPI JSON Schema Generator](#table-of-contents)
+### History of OpenAPI JSON Schema Generator
 
 OpenAPI JSON Schema Generator is based on OpenAPI Generator v6.2.0.
 The project was created here because the openapi-generator core team required the removal of the python generator 
@@ -331,10 +338,10 @@ Below is a timeline of those events and some of their reasons:
 - The fact that it is more fully passing json schema tests (including the feature keywords oneOf/anyOf/allOf/additionalProperties) does not warrant keeping it in the repo
 - The openapi-generator core team refused to consider the option of keeping the python generator as another generator option in their repo, and building another python generator that looks more conventional and making that generator primary
 
-## [7 - License](#table-of-contents)
+## License
 
 -------
-
+Copyright 2023 OpenAPI-Json-Schema-Generator Contributors
 Copyright 2018 OpenAPI-Generator Contributors (https://openapi-generator.tech)
 Copyright 2018 SmartBear Software
 

docs/generators/python.md

@@ -12,7 +12,7 @@ title: Documentation for the python generator
 | generator language | Python | |
 | generator language version | >=3.8 | |
 | generator default templating engine | handlebars | |
-| helpTxt | Generates a Python client library<br /><br />Features in this generator:<br />- type hints on endpoints and model creation<br />- model parameter names use the spec defined keys and cases<br />- robust composition (oneOf/anyOf/allOf/not) where payload data is stored in one instance only<br />- endpoint parameter names use the spec defined keys and cases<br />- inline schemas are supported at any location including composition<br />- multiple content types supported in request body and response bodies<br />- run time type checking<br />- Sending/receiving decimals as strings supported with type:string format: number -> DecimalSchema<br />- Sending/receiving uuids as strings supported with type:string format: uuid -> UUIDSchema<br />- quicker load time for python modules (a single endpoint can be imported and used without loading others)<br />- all instances of schemas dynamically inherit from all matching schemas so one can use isinstance to check if validation passed<br />- composed schemas with type constraints supported (type:object + oneOf/anyOf/allOf)<br />- schemas are not coerced/cast. For example string + date are both stored as string, and there is a date accessor<br />    - Exceptions: int/float is stored as Decimal, When receiving data from headers it will start as str and may need to be cast for example to int | |
+| helpTxt | Generates a Python client library<br /><br />Features in this generator:<br />- type hints on endpoints and model creation<br />- model parameter names use the spec defined keys and cases<br />- robust composition (oneOf/anyOf/allOf/not) where payload data is stored in one instance only<br />- endpoint parameter names use the spec defined keys and cases<br />- inline schemas are supported at any location including composition<br />- multiple content types supported in request body and response bodies<br />- run time type checking + json schema validation<br />- json schema keyword validation may be selectively disabled with SchemaConfiguration<br />- enums of type string/integer/boolean typed using typing.Literal<br />- mypy static type checking run on generated sample<br />- Sending/receiving decimals as strings supported with type:string format: number -> DecimalSchema<br />- Sending/receiving uuids as strings supported with type:string format: uuid -> UUIDSchema<br />- quicker load time for python modules (a single endpoint can be imported and used without loading others)<br />- composed schemas with type constraints supported (type:object + oneOf/anyOf/allOf)<br />- 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](https://openapi-generator.tech/docs/configuration) for more details.

samples/client/3_0_3_unit_test/python/.openapi-generator/FILES

@@ -468,6 +468,7 @@ docs/paths/response_body_post_uri_template_format_response_body_for_content_type
 docs/servers/server_0.md
 git_push.sh
 migration_2_0_0.md
+migration_3_0_0.md
 migration_other_python_generators.md
 pyproject.toml
 src/unit_test_api/__init__.py