# g1879/drissionpage architecture

> Architecture diagram of the GitHub repository g1879/drissionpage, 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/g1879/drissionpage
- Repository: https://github.com/g1879/drissionpage

## Overview

This project is DrissionPage – a Python-based web automation library designed to combine the ease of browser automation with the efficiency of direct HTTP requests. It is built to control Chromium-based browsers without the overhead of WebDriver and is structured to offer intuitive element selection, page object patterns, and a self-developed core for browser management and data packet handling.

##### Main Components
- Browser Controller/Driver Layer:
– Represented by the modules in the “_base” directories (base.py, chromium.py, driver.py).
– This is the lowest level that establishes and maintains a connection with Chromium-based browsers, handling browser launches, session management, and direct interactions.

- Configuration Manager:
– Found in “_configs” (chromium_options.py, configs.ini, options_manage.py, session_options.py).
– Responsible for loading and managing browser and session settings (via ini files), offering user-friendly interfaces to set parameters for browser behavior.

- DOM Elements Management:
– Modules under “_elements” (chromium_element.py, session_element.py, none_element.py).
– These encapsulate the representation of web elements, handling interactions and operations on DOM elements (like clicking, attribute reading, etc.).

- Page Object Layer:
– Located in the “_pages” directories (chromium_page.py, session_page.py, web_page.py, chromium_tab.py, etc.).
– Implements a Page Object Model (POM) pattern to abstract different types of web pages (browser pages, session pages, mixed-mode pages). They are key to encapsulating operations on different page types.

- Core Functional Utilities:
– Found in “_functions” (browser.py, cli.py, cookies.py, elements.py, keys.py, locator.py, settings.py, texts.py, tools.py, web.py, etc.).
– These modules provide common utility functions for handling browser actions, element location, cookie manipulation, working with cookies, keys, and other low-level procedures bridging the gap between user commands and the underlying automation tasks.

- Interaction Units/Actions:
– Under “_units” (actions.py, clicker.py, console.py, cookies_setter.py, downloader.py, listener.py, rect.py, screencast.py, scroller.py, selector.py, setter.py, states.py, waiter.py).
– They encapsulate specific user actions (e.g., clicking, scrolling, downloading, waiting, and recording screens) and provide a modular way to extend and manage browser interactions.

- Documentation & Examples:
– The “docs_en” directory contains extensive documentation, tutorials, demos, and feature explanations. Although not part of the runtime architecture, it is crucial for understanding the intended design pattern and interactions.

##### Relationships and Interactions
- The Application Programming Interface (API) exposed by DrissionPage is built on top of these layers.
- User code interacts with high-level page objects and utility functions that in turn call into the core driver layer to send commands to the browser.
- Configuration components are referenced by both the page objects and the core functions to initialize browser options and session settings.
- The element management modules sit in-between, as they wrap the native browser elements and expose user-friendly functions for element location, action execution, etc.
- The action units act as orchestrators that use the functions and elements to carry out complex sequences like clicking, waiting, or scrolling.

##### Architectural Patterns and Design Principles
- Layered Architecture:
– The project is clearly segregated into layers (configs, base, pages, functions, units) which communicate primarily in a top-down, usage-oriented flow.
- Page Object Model (POM):
– The “_pages” directory indicates the use of page objects to encapsulate page-specific behaviors.
- Modular Design:
– Clear separation between configuration, browser communication, page abstraction, and functional utilities that make the system extensible.
- Abstraction and Reusability:
– Use of both “.py” and “.pyi” files suggests a focus on type hinting and code clarity for better developer experience and maintenance.

##### Relevant Technologies/Frameworks
- Python (version 3.6+).
- Chromium-based browsers (Chrome, Edge, electron apps).
- lxml is mentioned in documentation as the parsing engine for DOM processing.
- Lightweight configuration management via ini files.
- Integration with network/HTTP libraries for data packet management.

##### Specific Elements
– Browser Controller/Driver Layer (from _base)
– Configuration Manager (from _configs)
– DOM Element Abstraction (from _elements)
– Page Object Layer (from _pages)
– Core Utility Functions (from _functions)
– Action Units (from _units)
- Data Flow:
– Illustrate configuration settings flowing from the Configuration Manager into the Browser Controller.
– Show interactions between page objects and the DOM elements module.
- Annotations for Architectural Patterns:
– Include labels like “Layered Architecture” or “POM” alongside the corresponding components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["Documentation & Examples (User API)"]:::docs

    subgraph "DrissionPage Library Architecture"
        direction TB
        PC["Page Object Layer"]:::page
        DE["DOM Elements Management"]:::dom
        CF["Core Functional Utilities"]:::core
        AU["Interaction Units/Actions"]:::action
        CM["Configuration Manager"]:::config
        BC["Browser Controller/Driver Layer"]:::driver
    end

    U -->|"triggers"| PC
    CM -->|"supplies_config"| PC
    PC -->|"wraps_element"| DE
    PC -->|"invokes_utilities"| CF
    AU -->|"executes_actions"| CF
    CM -->|"configures_browser"| BC
    CF -->|"sends_commands"| BC

    click BC "https://github.com/g1879/drissionpage/tree/master/DrissionPage/_base"
    click CM "https://github.com/g1879/drissionpage/tree/master/DrissionPage/_configs"
    click DE "https://github.com/g1879/drissionpage/tree/master/DrissionPage/_elements"
    click PC "https://github.com/g1879/drissionpage/tree/master/DrissionPage/_pages"
    click CF "https://github.com/g1879/drissionpage/tree/master/DrissionPage/_functions"
    click AU "https://github.com/g1879/drissionpage/tree/master/DrissionPage/_units"
    click U "https://github.com/g1879/drissionpage/tree/master/docs_en"

    classDef docs fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef driver fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef config fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef dom fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef page fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef core fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef action fill:#FFE4B5,stroke:#000,stroke-width:2px;
```
