Metadata-Version: 2.1
Name: lapidary
Version: 0.4.0
Summary: Python async OpenAPI client generator
Home-page: https://github.com/python-lapidary/lapidary
License: AGPL-3.0
Author: Raphael Krupinski
Author-email: rafalkrupinski@users.noreply.github.com
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Dist: Jinja2 (>=3.1.2,<4.0.0)
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: black (>=22.8.0,<23.0.0)
Requires-Dist: inflection (>=0.5.1,<0.6.0)
Requires-Dist: jsonpatch (>=1.32,<2.0)
Requires-Dist: lapidary-base (>=0.3.0,<0.4.0)
Requires-Dist: pydantic[email] (>=1.9.2,<2.0.0)
Requires-Dist: python-mimeparse (>=1.6.0,<2.0.0)
Requires-Dist: tomlkit (>=0.11.4,<0.12.0)
Requires-Dist: typer (>=0.6.1,<0.7.0)
Project-URL: Repository, https://github.com/python-lapidary/lapidary
Description-Content-Type: text/markdown

# Lapidary - Python async OpenAPI client generator

Generate OpenAPI 3.0.3 client code that is easy to understand and debug.

Leverages [Pydantic](https://github.com/pydantic/pydantic) as the base classes
and [httpx](https://github.com/encode/httpx) as the HTTP client.

## Usage

lapidary [--errata path] spec_file target_dir root_package

Lapidary will create target_dir, all necessary directories and pyproject.toml if they don't exist.

Generated files will be placed in <target_dir>/gen/<root_package>

Errata is a JSON Patch file in JSON or YAML format; it's applied to the spec before any other processing.

## Supported OpenAPI features

- Parameter names: operation parameters are uniquely identified by their name the value of an `in` attribute. It is possible to have parameter named `param` in all of path, query, cookies and headers.
  
  Lapidary uses Hungarian notation for method parameter names.
- Enums: [TODO] there's no limitation that enum schema cannot be an object or an array.

  Enums might need two python classes - a subclass of `enum.Enum` and the schema class.
- oneOf: maps to typing.Union
- AllOf: [TODO] maps to a separate class that uses all the schemas as superclasses.
- AnyOf: [TODO] maps to similar class as in case of AllOf, all fields should be non-required and the object should validate against at least one of superclasses.
- Recursive references between schemas: supported.
- References to other schemas: unsupported.
- Read- and write-only attributes: [TODO] Read-only attributes are considered non-existent when the object is validated before being sent to the server.

## Broken and incomplete API specifications

- errata: use errata to update the specification document in cases where actual data doesn't match it, and the service provider is reluctant or slow to update it.

TODO: pre- and postprocessing of API specification (dict- and pydantic-based models) with python code, errata (jsonpatch), etc

## Backwards compatibility

Once stable, Lapidary should generate code that is backwards compatible as long as the API specification is too. The following rules are used to ensure that.

Names of interface elements (public functions, classes and methods) are fully deterministic and are derived only from their source elements and, in some cases, their parents.
For example, schemas of the same name are either placed in separate modules, or their names have the parent element name prepended. 

Each operation must have operationId which is used to create a unique package for its models.

The structure of the API specification is roughly reflected in the generated code.
Each schema under #/components/schemas together with all inline parameter schemas will become a single module in `<your_package>.components.schemas`.
Each operation must define `operationId` which will be used as a sub-package name for the module containing its all inline schemas. Operation packages will be placed under `<your_package>.paths`


