# xowap/easy-leasy architecture

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

- Interactive diagram: https://gitdiagram.com/xowap/easy-leasy
- Repository: https://github.com/xowap/easy-leasy

## Overview

##### Main Components
- DSL Input & Parser Module: This corresponds to the _parser.py file. It takes the multi-line DSL expressions (which can include import, let, and return statements) and converts them into the internal representation.
- Core TimeSet Abstraction: Represented in _base.py where the BaseTimeSet class is defined. This class serves as the parent for different time set implementations.
- Operations Module: Found in _operations.py, it implements the logic behind set operators (union, intersection, difference) that combine individual time set components.
- Scalars and Specific Time Components: In _scalars.py, submodules like HourRange, Day, Month, and the Always/Never classes are defined to encapsulate specific time rules.
- Testing Components: Although external to the core system, the tests directory (including test_operations.py, test_parser.py, test_scalars.py) verifies the correctness of each module.

- The “Parser” component (module _parser.py) processes the DSL input and produces an abstract syntax tree (AST) or directly instantiates one or more subclasses of BaseTimeSet.
- Data flows from the Parser into the “Core TimeSet” component (module _base.py) which provides the common interface for query methods like value_at and next_change.
- The “Scalar Components” (from _scalars.py) implement the concrete time components (like HourRange, Day, Month, Always, Never) that are used by the BaseTimeSet to represent actual time periods.

##### Important Architectural Patterns
- Modularity: Each module (parser, base, operations, scalars) represents a well-defined part of the DSL processing and time-set evaluation.
- Composability: The time set objects are designed to be composed using mathematical set operations, which is a central design principle.
- API Abstraction: Through the BaseTimeSet and its subclasses, the library isolates DSL parsing from time evaluation, facilitating a clear separation of concerns.

##### Specific Elements

- Next, represent the “Parser” component to handle language constructs such as “from … import …”, “let … be when …”, and “return …”.
- Then branch to the “Core TimeSet System”, which is subdivided into abstract classes (BaseTimeSet) and its concrete implementations from both the Scalar and Operations modules.
- Optionally, add a “Testing” block that ensures each of these components functions correctly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and Parsing Layers
    subgraph "Client Layer"
        Client("User/Client"):::client
    end

    subgraph "Parsing Layer"
        Parser("DSL Parser (_parser.py)"):::parser
    end

    %% Core TimeSet System
    subgraph "Core TimeSet System"
        Base("Core TimeSet Abstraction (_base.py)"):::core
        Operations("TimeSet Operations (_operations.py)"):::ops
        Scalars("Scalar Definitions (_scalars.py)"):::scalars
    end

    %% Evaluation Layer
    subgraph "Evaluation Layer"
        Eval("Evaluation Methods (value_at,next_change)"):::eval
        Datetime("External: datetime"):::external
        Zoneinfo("External: zoneinfo"):::external
    end

    %% Testing Components
    subgraph "Testing"
        TP("test_parser.py"):::test
        TO("test_operations.py"):::test
        TS("test_scalars.py"):::test
    end

    %% Arrows / Flow Connections
    Client -->|"DSLExpression"| Parser
    Parser -->|"producesAST"| Base
    Base -->|"composes"| Operations
    Base -->|"composes"| Scalars
    Operations -->|"utilizes"| Base
    Scalars -->|"instantiates"| Base
    Base -->|"evaluatedBy"| Eval
    Eval --> Datetime
    Eval --> Zoneinfo

    %% Testing connections
    TP ---|"tests"| Parser
    TO ---|"tests"| Operations
    TS ---|"tests"| Scalars

    %% Click Events
    click Parser "https://github.com/xowap/easy-leasy/blob/develop/src/easy_leasy/_parser.py"
    click Base "https://github.com/xowap/easy-leasy/blob/develop/src/easy_leasy/_base.py"
    click Operations "https://github.com/xowap/easy-leasy/blob/develop/src/easy_leasy/_operations.py"
    click Scalars "https://github.com/xowap/easy-leasy/blob/develop/src/easy_leasy/_scalars.py"
    click TP "https://github.com/xowap/easy-leasy/blob/develop/tests/test_parser.py"
    click TO "https://github.com/xowap/easy-leasy/blob/develop/tests/test_operations.py"
    click TS "https://github.com/xowap/easy-leasy/blob/develop/tests/test_scalars.py"

    %% Styles
    classDef client fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px;
    classDef parser fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef ops fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef scalars fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef eval fill:#F0F4C3,stroke:#7CB342,stroke-width:2px;
    classDef external fill:#DCEDC8,stroke:#558B2F,stroke-width:2px;
    classDef test fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
```
