How kurloc/alchemancer works
Project Type and Purpose
• This project is a Python library (“Alchemancer”) for advanced query generation and AST parsing that supports multiple SQL variants (Postgres, MySQL, SQLite, etc.). It offers a modular, plugin-like system for configuring various aspects such as resolvers, JSON query support, and more.
• The README and file tree show that the project is structured into a core library (in the “alchemancer” directory), along with adapters/extensions tailored for different databases and frameworks (observed via examples, fastapi, and references in the README to Flask, Django, etc.). It also incorporates testing and CI workflows.
Project’s File Structure
• Main Directories:
• alchemancer: Contains the core modules – notably the AST handling, query generation, reflection handling, and type-specific implementations. This directory forms the heart of the library.
• examples: Provides usage examples demonstrating various query capabilities, such as basic resolvers, subqueries, and function support.
• fastapi: Contains an example integration with FastAPI, showing how the library can be used within a web application framework.
• tests: Comprises unit and integration tests along with fixtures that simulate models and database configurations.
• Supporting Files:
• .github: Includes CI configuration files (which indicate linting and testing on push) that ensure code quality.
• Configuration files such as pyproject.toml, setup.py, and pre-commit hooks manage the project’s build and development processes.
README
• The README outlines key features such as resolver support (including temporary tables vs. literal subqueries), plugin (module) system for extensibility, and a range of supported databases.
a. Main Components:
• Alchemancer Core:
• AST Handler
• Query Generator
• Reflection Handler
• Core Plugin Hooks (for injecting modules and custom behavior)
• Database-Specific Adapter Modules:
• Separate modules within the core which support various databases (Postgres, MySQL, SQLite, MsSql, Oracle).
• Plugin/Module System:
• The mechanism for adding or overriding behavior (e.g., resolvers for JSON query support, rule systems to control field-level access).
• Framework Integrations/Examples:
• Integration examples for FastAPI (and placeholders for Django and Flask).
• Testing Suite:
• Unit tests, integration tests, and example queries ensuring functionality and stability.
• CI/CD and Tooling:
• Linting and testing workflows as defined in the .github/workflows directory.
b. Relationships and Interactions:
• The Core Library (alchemancer) provides the essential functionality. It is extended by database-specific extensions which are clearly delineated as different modules.
• The Plugin System (Core Plugin Hooks) provides configuration slots where user-defined or extended modules (present in user code via examples or frameworks) can be integrated.
• User Applications (shown in FastAPI or other potential integrations) interface directly with the core, submitting queries that pass through the query generator and resolver pipelines.
• Testing and examples simulate real-world usage, ensuring each component integrates with the others.
c. Architectural Patterns and Design Principles:
• Modularity: Emphasize the separation between the core functionality and its extensions.
• Plug-in/Module Pattern: Clearly separate the parts that allow for custom modules, as described in the README’s “Plugin systems” section.
• Layered Architecture: Represent the layered approach where the query generation logic resides in the core, which interacts with database-specific adaptations and then is invoked by user interface layers.
d. Relevant Technologies, Frameworks, and Libraries:
• Python as the underlying language.
• FastAPI (explicitly represented via the fastapi directory), and potential integrations with Django/Flask.
• Testing frameworks (as seen in the tests directory) along with Docker compose for emulating database environments.