How dog-egg/zangar works
Project type and purpose
• Project type: an open-source Python library/tool (no standalone frontend or service)
• Purpose: expose a programmable API for defining type schemas, converting between representations, and compiling those types into OpenAPI (and other) artifacts
File structure
• Top-level “src/zangar” folder holds all runtime code.
– _core.py: core entry points / orchestrator
– _functional.py: functional‐style facade / helpers
– _conversions.py: routines to convert between Python data and schema representations
– _messages.py: centralized message templates / error messages
– compilation.py: logic to compile type definitions into output artifacts (e.g., OpenAPI JSON)
– exceptions.py: custom exception classes
– utils/version.py: version lookup, etc.
– _types/ subpackage: classes modeling primitives, dataclasses, compound structures, and base interfaces
• “docs/” contains Sphinx sources (API docs, type schemas, OpenAPI guide)
• “tests/” contains unit tests, OpenAPI integration tests, type‐checking tests
README insights
• Minimal README with link to full documentation
• Repository badges for CI and coverage
• Emphasis on OpenAPI support in docs
Main components & relationships
a. Public API layer:
– Modules: zangar._core and zangar._functional
– Exposed to library consumers
b. Type system:
– zangar._types (base.py, primitives.py, dataclass.py, structures.py)
– Models user-defined or built-in types
c. Conversion engine:
– zangar._conversions
– Translates Python values ↔ intermediate schema representations
d. Compilation engine:
– zangar.compilation
– Takes type definitions + conversions, emits OpenAPI specs or other target artifacts
e. Messaging & exceptions:
– zangar._messages for user-facing strings
– zangar.exceptions for control flow and error handling
f. Utilities:
– zangar.utils.version
1. Consumer calls Public API → Core/Functional facade
2. Core invokes Conversion engine (to normalize inputs)
3. Core passes normalized types to Compilation engine
4. Compilation engine produces schema JSON/YAML
5. Any errors trigger Exceptions, formatted via Messages module
Architectural patterns & technologies
• Layered modular architecture – clear separation of API, domain models (types), conversion logic, and compilation
• Functional facade for ergonomic API (seen in _functional.py)
• Domain model pattern in _types
• Pluggable compilation targets (via compilation.py)
• Sphinx for docs generation, pytest for tests, GitHub Actions for CI