How xdevplatform/xdk works
Project Type and Purpose
• This is an open-source, multi-crate Rust workspace whose primary goal is to generate type-safe SDKs (“XDKs”) for the X APIs from OpenAPI 3.0 specs.
• It provides:
• xdk-openapi – a minimal OpenAPI parser
• xdk-gen – a generic code-generation library
• xdk-build – a command-line wrapper that drives parsing and generation
• utils/python – post-processing (e.g., code formatting)
• Python SDK output under xdk/python
• The user workflow: supply an OpenAPI spec → xdk-build CLI → xdk-openapi parser + xdk-gen templates → formatted Python SDK.
Key Components
• Input
• OpenAPI spec files (YAML/JSON)
• xdk-openapi (Rust crate)
• Reads and parses the spec into an AST/context
• Exports core models and reference resolution
• xdk-gen (Rust crate)
• Core library: transforms parser AST into language-agnostic model
• Language‐specific backend (python generator) that applies Jinja2 templates
• Contains templates for Python client, models, auth, README, setup.py, etc.
• xdk-build (Rust CLI)
• User-facing tool
• Invokes xdk-openapi → xdk-gen → utils/python.format
• Handles CLI args, file I/O, error reporting, logging
• utils/python
• Simple Python-based code formatter applied to generated files
• Output
• A ready-to-install Python package under xdk/python
• Packaged modules for each API area (tweets, users, likes, etc.)
• Tests
• OpenAPI spec sanity tests under tests/openapi
• Python integration/orchestration tests under tests/python
Relationships and Data Flow
1. User passes openapi.yaml to xdk-build CLI
2. xdk-build calls xdk-openapi parser → builds internal spec model
3. Parsed model flows into xdk-gen core → constructs generator context
4. xdk-gen python backend applies Jinja2 templates → emits raw .py files
5. utils/python.format script tidies up code style
6. Final files land in --output directory (xdk/python)
7. tests drive both parser unit tests and generated SDK integration
Architectural Patterns & Principles
• Separation of Concerns: parsing, model transformation, templating, formatting, CLI orchestration all in separate crates/modules
• Plugin-style Backends: xdk-gen core is language-agnostic; language-specific generators live under src/python and templates/python
• Workspace-level Modularity: each crate builds independently, can be tested/published separately
• Template-Driven Generation: uses Jinja2 (.j2) templates for maximum flexibility
• Parser (xdk-openapi)
• Generator Core (xdk-gen/core)
• Python Generator (xdk-gen/python + templates)
• CLI (xdk-build)
• Formatter (utils/python)
• Output SDK (xdk/python)
• Tests
• Spec → CLI → Parser → Generator Core → Templates → Formatter → SDK Output
• CLI directly orchestrates each step
• Tests target Parser and SDK Output
• Template files in another (e.g., orange)
• Python code/formatter in green
• Tests in gray