# geopython/pycql architecture

> Architecture diagram of the GitHub repository geopython/pycql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geopython/pycql
- Repository: https://github.com/geopython/pycql

## Overview

##### Project Type and Purpose
- This project is a Python library that implements a parser for the OGC CQL standard.
- The key purpose is to convert a CQL filter expression string into an AST, which is then recursively evaluated to generate filters for use in ORM systems.
- It offers integrations for Django (and also SQLAlchemy) to bridge the AST evaluation into actual query construction.

##### File Structure
- The top-level directories include configuration files (.github, debian), documentation (docs), library source files (pycql), and tests.
- In the pycql directory, you have modules such as:
- Core parser components (lexer.py, parser.py, ast.py, values.py, util.py).
- Integration support directories (pycql/integrations/django and pycql/integrations/sqlalchemy) which implement methods to convert the AST into ORM-specific filters.
- The tests directory includes test cases for Django integration and for lexer and parser, illustrating how the parser is exercised in different contexts.

##### Key Components
- Input / CQL Expression: Represents the raw filter string supplied to the parser.
- Lexer Component:
- Source: pycql/lexer.py (and the generated/auxiliary files lextab.py)
- Function: Tokenize the input string.
- Parser Component:
- Source: pycql/parser.py (along with the output file parser.out and supporting tables in parsetab.py)
- Function: Convert the stream of tokens into an AST.
- AST Representation:
- Source: pycql/ast.py and values.py
- Represents the hierarchical structure of conditions, comparisons, and operations (e.g., attribute comparisons, logical conditions, arithmetic expressions).
- Evaluator / Filter Builder:
- Contains the recursive evaluator code (illustrated in the README under the FilterEvaluator class), which uses the AST to build filters.
- Depending on usage, conversion methods like to_filter recursively evaluate AST nodes.
- Integration Adapters:
- Django Integration: Located under pycql/integrations/django. They include modules (evaluate.py, filters.py, parser.py) that convert AST nodes into Django Q objects or ORM filters.
- SQLAlchemy Integration: Located under pycql/integrations/sqlalchemy with similar responsibilities.
- External Tools and Frameworks:
- Although this is a library, it depends on external systems like Django ORM or SQLAlchemy for database filtering.
- CI/CD components (in .github/workflows) and packaging (debian) can be illustrated as supporting infrastructure.

##### Relationships and Interactions
- A user supplies a CQL filter string.
- The string flows into the Lexer, which tokenizes the input.
- Tokens are fed to the Parser, which constructs the AST.
- The AST is then processed by an Evaluator component.
- Depending on the target integration, the Evaluator uses:
- Django integration (or SQLAlchemy integration) to convert the AST into ORM-specific filtering objects.
- Finally, in an end-to-end scenario (as shown in tests), the filters are applied to execute ORM queries.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Parsing, AST generation, and evaluation into filters are cleanly separated.
- Recursion: Note the recursive descent in AST evaluation (the evaluator calls itself on subnodes).
- Modularity: Integration modules (Django, SQLAlchemy) are isolated from the core parser so that extensions or alternative integrations are straightforward.
- Testability: The tests directory indicates a commitment to thorough testing via pytest and Django test projects.
- Extensibility: The integration adapters show design flexibility, where support for additional backends could be added.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Parsing Components
    A["Input (CQL String)"]:::input
    subgraph "Core Parsing Components"
        L["Lexer"]:::core
        LT["LexTab"]:::aux
        P["Parser"]:::core
        POut["ParserOutput"]:::aux
        PTab["ParseTab"]:::aux
        ASt["AST"]:::core
        AStVal["ASTValues"]:::aux
        Eval["Evaluator/Filter Builder"]:::core
    end

    %% Integration Adapters
    subgraph "Integration Adapters"
        subgraph "Django Integration"
            D_eval["Evaluate Module"]:::integration
            D_filt["Filters Module"]:::integration
            D_parser["Parser Module"]:::integration
        end
        subgraph "SQLAlchemy Integration"
            SA_eval["Evaluate Module"]:::integration
            SA_filt["Filters Module"]:::integration
            SA_parser["Parser Module"]:::integration
        end
    end

    %% External ORM Systems
    EORM["Django ORM"]:::external
    SAORM["SQLAlchemy ORM"]:::external

    %% Data Flow
    A -->|"tokenizes"| L
    L ---|"auxiliary"| LT
    L -->|"generates_tokens"| P
    P ---|"auxiliary"| POut
    P ---|"auxiliary"| PTab
    P -->|"constructs_AST"| ASt
    ASt ---|"auxiliary"| AStVal
    ASt -->|"evaluated_recursively"| Eval
    Eval -->|"builds_filters"| D_eval
    Eval -->|"builds_filters"| SA_eval
    D_eval -->|"works_with"| D_filt
    D_filt -->|"works_with"| D_parser
    SA_eval -->|"works_with"| SA_filt
    SA_filt -->|"works_with"| SA_parser
    D_eval -->|"converts_to_Q_objects"| EORM
    SA_eval -->|"converts_to_filters"| SAORM

    %% Click Events for Core Components
    click L "https://github.com/geopython/pycql/blob/master/pycql/lexer.py"
    click LT "https://github.com/geopython/pycql/blob/master/pycql/lextab.py"
    click P "https://github.com/geopython/pycql/blob/master/pycql/parser.py"
    click POut "https://github.com/geopython/pycql/blob/master/pycql/parser.out"
    click PTab "https://github.com/geopython/pycql/blob/master/pycql/parsetab.py"
    click ASt "https://github.com/geopython/pycql/blob/master/pycql/ast.py"
    click AStVal "https://github.com/geopython/pycql/blob/master/pycql/values.py"

    %% Click Events for Django Integration Adapter
    click D_eval "https://github.com/geopython/pycql/blob/master/pycql/integrations/django/evaluate.py"
    click D_filt "https://github.com/geopython/pycql/blob/master/pycql/integrations/django/filters.py"
    click D_parser "https://github.com/geopython/pycql/blob/master/pycql/integrations/django/parser.py"

    %% Click Events for SQLAlchemy Integration Adapter
    click SA_eval "https://github.com/geopython/pycql/blob/master/pycql/integrations/sqlalchemy/evaluate.py"
    click SA_filt "https://github.com/geopython/pycql/blob/master/pycql/integrations/sqlalchemy/filters.py"
    click SA_parser "https://github.com/geopython/pycql/blob/master/pycql/integrations/sqlalchemy/parser.py"

    %% Styles
    classDef input fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef aux fill:#e0ffff,stroke:#333,stroke-width:2px;
    classDef integration fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef external fill:#ffc0cb,stroke:#333,stroke-width:2px;
```
