Skip to content

Commit 655edfb

Browse files
SamuelMarksSamuelMarks
committed
[README.md] New rewrite, consistent across all cdd-python-all
1 parent fd841c7 commit 655edfb

1 file changed

Lines changed: 54 additions & 135 deletions

File tree

‎README.md‎

Lines changed: 54 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
cdd-python-all
2-
==============
1+
# cdd-python-all
32

43
[![License](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg)](https://opensource.org/licenses/Apache-2.0)
54
[![CI/CD](https://github.com/offscale/cdd-python-all/workflows/CI/badge.svg)](https://github.com/offscale/cdd-python-all/actions)
@@ -11,88 +10,88 @@ OpenAPI ↔ Python. This is one compiler in a suite, all focussed on the same ta
1110
Each compiler is written in its target language, is whitespace and comment sensitive, and has both an SDK and CLI.
1211

1312
The CLI—at a minimum—has:
14-
- `python3 -m cdd_python_all --help`
15-
- `python3 -m cdd_python_all --version`
16-
- `python3 -m cdd_python_all from_openapi -i spec.json`
17-
- `python3 -m cdd_python_all to_openapi -f path/to/code`
18-
- `python3 -m cdd_python_all to_docs_json --no-imports --no-wrapping -i spec.json`
1913

20-
The goal of this project is to enable rapid application development without tradeoffs. Tradeoffs of Protocol Buffers / Thrift etc. are an untouchable "generated" directory and package, compile-time and/or runtime overhead. Tradeoffs of Java or JavaScript for everything are: overhead in hardware access, offline mode, ML inefficiency, and more. And neither of these alterantive approaches are truly integrated into your target system, test frameworks, and bigger abstractions you build in your app. Tradeoffs in CDD are code duplication (but CDD handles the synchronisation for you).
14+
- `cdd-python-all --help`
15+
- `cdd-python-all --version`
16+
- `cdd-python-all from_openapi to_sdk_cli -i spec.json`
17+
- `cdd-python-all from_openapi to_sdk -i spec.json`
18+
- `cdd-python-all from_openapi to_server -i spec.json`
19+
- `cdd-python-all to_openapi -f path/to/code`
20+
- `cdd-python-all to_docs_json --no-imports --no-wrapping -i spec.json`
21+
- `cdd-python-all serve_json_rpc --port 8080 --listen 0.0.0.0`
22+
23+
The goal of this project is to enable rapid application development without tradeoffs. Tradeoffs of Protocol Buffers / Thrift etc. are an untouchable "generated" directory and package, compile-time and/or runtime overhead. Tradeoffs of Java or JavaScript for everything are: overhead in hardware access, offline mode, ML inefficiency, and more. And neither of these alternative approaches are truly integrated into your target system, test frameworks, and bigger abstractions you build in your app. Tradeoffs in CDD are code duplication (but CDD handles the synchronisation for you).
2124

2225
## 🚀 Capabilities
2326

2427
The `cdd-python-all` compiler leverages a unified architecture to support various facets of API and code lifecycle management.
2528

26-
* **Compilation**:
27-
* **OpenAPI → `Python`**: Generate idiomatic native models, network routes, client SDKs, database schemas, and boilerplate directly from OpenAPI (`.json` / `.yaml`) specifications.
28-
* **`Python` → OpenAPI**: Statically parse existing `Python` source code and emit compliant OpenAPI specifications.
29-
* **AST-Driven & Safe**: Employs static analysis (Abstract Syntax Trees) instead of unsafe dynamic execution or reflection, allowing it to safely parse and emit code even for incomplete or un-compilable project states.
30-
* **Seamless Sync**: Keep your docs, tests, database, clients, and routing in perfect harmony. Update your code, and generate the docs; or update the docs, and generate the code.
29+
- **Compilation**:
30+
- **OpenAPI → `Python`**: Generate idiomatic native models, network routes, client SDKs, and boilerplate directly from OpenAPI (`.json` / `.yaml`) specifications.
31+
- **`Python` → OpenAPI**: Statically parse existing `Python` source code and emit compliant OpenAPI specifications.
32+
- **AST-Driven & Safe**: Employs static analysis instead of unsafe dynamic execution or reflection, allowing it to safely parse and emit code even for incomplete or un-compilable project states.
33+
- **Seamless Sync**: Keep your docs, tests, database, clients, and routing in perfect harmony. Update your code, and generate the docs; or update the docs, and generate the code.
3134

32-
## 📦 Installation
35+
## 📦 Installation & Build
3336

34-
Requires Python 3.9+. Run `pip install cdd-python-all`
37+
### Native Tooling
3538

36-
## 🛠 Usage
39+
```bash
40+
python3 -m pip install -e .
41+
python3 -m pytest
42+
```
3743

38-
### Command Line Interface
44+
### Makefile / make.bat
3945

46+
You can also use the included cross-platform Makefiles to fetch dependencies, build, and test:
4047

4148
```bash
42-
# Generate a Python SDK and an interactive CLI from an OpenAPI spec
43-
python3 -m cdd_python_all from_openapi to_sdk_cli -i ./openapi.json -o ./my_generated_client
49+
# Install dependencies
50+
make deps
4451

45-
# Extract an OpenAPI spec from your modified Python client code
46-
python3 -m cdd_python_all to_openapi -f ./my_generated_client/client.py -o ./updated_openapi.json
52+
# Build the project
53+
make build
4754

48-
# Extract documentation JSON from your OpenAPI spec
49-
python3 -m cdd_python_all to_docs_json --no-imports --no-wrapping -i ./openapi.json -o docs.json
55+
# Run tests
56+
make test
5057
```
5158

59+
## 🛠 Usage
5260

53-
### Programmatic SDK / Library
54-
55-
56-
```python
57-
import libcst as cst
58-
from openapi_client.openapi.parse import parse_openapi_json
59-
from openapi_client.routes.emit import ClientGenerator
60-
61-
# Load and parse an OpenAPI specification
62-
with open("openapi.json", "r") as f:
63-
spec = parse_openapi_json(f.read())
61+
### Command Line Interface
6462

65-
# Generate a Client SDK
66-
generator = ClientGenerator(spec)
67-
client_code = generator.generate_code()
63+
```bash
64+
# Generate Python models from an OpenAPI spec
65+
cdd-python-all from_openapi to_sdk -i spec.json -o src/models
6866

69-
# Write the generated code to a file
70-
with open("client.py", "w") as f:
71-
f.write(client_code)
67+
# Generate an OpenAPI spec from your Python code
68+
cdd-python-all to_openapi -f src/models -o openapi.json
7269
```
7370

71+
### Programmatic SDK / Library
7472

75-
## Design choices
73+
```py
74+
from cdd import generate_sdk, Config
7675

77-
We use `libcst` to safely parse and generate Python ASTs. This allows us to modify source code accurately while retaining comments and whitespace.
76+
if __name__ == '__main__':
77+
config = Config(input_path='spec.json', output_dir='src/models')
78+
generate_sdk(config)
79+
print("SDK generation complete.")
80+
```
7881

7982
## 🏗 Supported Conversions for Python
8083

8184
*(The boxes below reflect the features supported by this specific `cdd-python-all` implementation)*
8285

83-
84-
| Concept | Parse (From) | Emit (To) |
85-
|---------|--------------|-----------|
86-
| OpenAPI (JSON/YAML) | [x] | [x] |
87-
| `Python` Models / Structs / Types | [x] | [x] |
88-
| `Python` Server Routes / Endpoints | [x] | [x] |
89-
| `Python` API Clients / SDKs | [x] | [x] |
90-
| `Python` ORM / DB Schemas | [ ] | [ ] |
91-
| `Python` CLI Argument Parsers | [x] | [x] |
92-
| `Python` Docstrings / Comments | [x] | [x] |
93-
94-
95-
86+
| Features | Parse (From) | Emit (To) |
87+
| --- | --- | --- |
88+
| OpenAPI 3.2.0 | ✅ | ✅ |
89+
| API Client SDK | ✅ | ✅ |
90+
| API Client CLI | [ ] | ✅ |
91+
| Server Routes / Endpoints | ✅ | ✅ |
92+
| ORM / DB Schema | [ ] | [ ] |
93+
| Mocks + Tests | ✅ | ✅ |
94+
| Model Context Protocol (MCP) | [ ] | [ ] |
9695

9796
---
9897

@@ -110,83 +109,3 @@ at your option.
110109
Unless you explicitly state otherwise, any contribution intentionally submitted
111110
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
112111
dual licensed as above, without any additional terms or conditions.
113-
114-
## CLI Help
115-
116-
```
117-
$ cdd-python --help
118-
usage: cdd-python [-h] [--version]
119-
{from_openapi,to_openapi,sync,to_docs_json,server_json_rpc}
120-
...
121-
122-
CDD Python Client generator and extractor.
123-
124-
positional arguments:
125-
{from_openapi,to_openapi,sync,to_docs_json,server_json_rpc}
126-
from_openapi Generate code from OpenAPI
127-
to_openapi Extract OpenAPI from code
128-
sync Sync a directory containing client.py, mock_server.py,
129-
test_client.py, cli_main.py
130-
to_docs_json Generate JSON documentation
131-
server_json_rpc Run JSON-RPC server
132-
133-
options:
134-
-h, --help show this help message and exit
135-
--version show program's version number and exit
136-
```
137-
138-
### `from_openapi`
139-
140-
```
141-
$ cdd-python from_openapi --help
142-
usage: cdd-python from_openapi [-h] [-i INPUT | --input-dir INPUT_DIR]
143-
[-o OUTPUT] [--no-github-actions]
144-
[--no-installable-package]
145-
{to_sdk,to_sdk_cli,to_server} ...
146-
147-
positional arguments:
148-
{to_sdk,to_sdk_cli,to_server}
149-
150-
options:
151-
-h, --help show this help message and exit
152-
-i INPUT, --input INPUT
153-
Path to OpenAPI JSON file
154-
--input-dir INPUT_DIR
155-
Directory containing OpenAPI specs
156-
-o OUTPUT, --output OUTPUT
157-
Output directory
158-
--no-github-actions Do not generate GitHub Actions
159-
--no-installable-package
160-
Do not generate installable package scaffolding
161-
```
162-
163-
### `to_openapi`
164-
165-
```
166-
$ cdd-python to_openapi --help
167-
usage: cdd-python to_openapi [-h] -i INPUT [-o OUTPUT]
168-
169-
options:
170-
-h, --help show this help message and exit
171-
-i INPUT, --input INPUT
172-
Path to Python source file or directory
173-
-o OUTPUT, --output OUTPUT
174-
Output OpenAPI JSON file
175-
```
176-
177-
### `to_docs_json`
178-
179-
```
180-
$ cdd-python to_docs_json --help
181-
usage: cdd-python to_docs_json [-h] -i INPUT [--no-imports] [--no-wrapping]
182-
[-o OUTPUT]
183-
184-
options:
185-
-h, --help show this help message and exit
186-
-i INPUT, --input INPUT
187-
Path or URL to the OpenAPI specification
188-
--no-imports Omit the imports field
189-
--no-wrapping Omit the wrapper fields
190-
-o OUTPUT, --output OUTPUT
191-
Output JSON file (defaults to stdout)
192-
```

0 commit comments

Comments
 (0)