# vuthanhdatt/vnstock-data-python architecture

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

- Interactive diagram: https://gitdiagram.com/vuthanhdatt/vnstock-data-python
- Repository: https://github.com/vuthanhdatt/vnstock-data-python

## Overview

##### Project Type and Purpose
- This is a Python package designed to fetch and process data related to the Vietnam stock market.
- Its main goal is to provide functionalities similar to pandas-datareader but specifically for Vietnam—covering price data (OHLCV), financial information (balance sheets, ratios), and ticket data.
- It supports multiple exchange types via dedicated modules (e.g., hnx.py, hose.py, upcom.py) and requires user-provided authentication (Vietstock cookies).

##### File Structure
- Top-Level Structure:
- Main files like README.md, setup.py for package installation, and documentation files (docs folder and mkdocs.yml).
- The presence of a tests directory containing unit tests for key modules indicates an emphasis on stability and functionality.
- Package Components (vnstock_data folder):
- The core functionality is contained in the vnstock_data package.
- There is an "all_exchange.py" module that likely serves as a unified interface for different data sources.
- The "data" subfolder includes modules such as price.py, financeinfo.py, and ticket.py, which encapsulate logic for retrieving and processing specific types of financial data.
- The "helpers" subfolder contains utility modules (e.g., financeinfo_helper.py, price_helper.py, ticket_helper.py) that support the data modules.
- Separate modules (hnx.py, hose.py, upcom.py) indicate that each stock exchange might have its specialized handling or API specifics.

##### Key Components to Highlight
- Client/Consumer:
- The user/application that imports and uses the package functionality (as shown in the README with the VnStock class instantiation).
- Core Interface:
- The VnStock class (likely in all_exchange.py); acts as the facade for all data calls.
- Data Modules:
- Price Data Module: vnstock_data/data/price.py and helper (price_helper.py).
- Financial Information Module: vnstock_data/data/financeinfo.py and helper (financeinfo_helper.py).
- Ticket Data Module: vnstock_data/data/ticket.py and helper (ticket_helper.py).
- Exchange Modules:
- Modules for specific exchanges (hnx.py, hose.py, upcom.py) which likely abstract exchange-specific logic.
- Base and Shared Utilities:
- vnstock_data/base.py may hold common definitions or base classes used throughout the package.
- Tests and Documentation:
- Tests are maintained separately to ensure the reliability of each component.
- Documentation components (docs folder, README, mkdocs.yml) guide users on installation, usage, and API details.

##### Important Architectural Patterns and Design Principles
- Modular Design:
- Each major functionality (price, finance info, ticket, exchange specifics) is separated into distinct modules.
- Separation of Concerns:
- The package cleanly separates API handling, data processing, and utility functions.
- Extensibility:
- New data functionalities or support for additional stock exchanges can be integrated by adding new modules in the same structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Client / Application"]:::client
    B["VnStock Interface"]:::api
    C["Base and Shared Utilities"]:::base

    A -->|"API_Call(cookies)"| B
    B -->|"uses"| C

    subgraph "Data Modules"
        direction TB
        D["Price Data Module"]:::datamodule
        E["Price Helper Module"]:::helper
        F["Financial Info Module"]:::datamodule
        G["Financial Info Helper Module"]:::helper
        H["Ticket Data Module"]:::datamodule
        I["Ticket Helper Module"]:::helper
        D -->|"helper"| E
        F -->|"helper"| G
        H -->|"helper"| I
    end

    subgraph "Exchange Handlers"
        direction TB
        J["Exchange Module (HNX)"]:::exchange
        K["Exchange Module (HOSE)"]:::exchange
        L["Exchange Module (UPCOM)"]:::exchange
    end

    B -->|"price"| D
    B -->|"financial"| F
    B -->|"ticket"| H
    B -->|"exchange"| J
    B -->|"exchange"| K
    B -->|"exchange"| L

    M["Tests"]:::test
    N["Documentation"]:::doc

    M -->|"tests"| B
    N -->|"docs"| B

    click B "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/all_exchange.py"
    click C "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/base.py"
    click D "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/data/price.py"
    click E "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/helpers/price_helper.py"
    click F "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/data/financeinfo.py"
    click G "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/helpers/financeinfo_helper.py"
    click H "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/data/ticket.py"
    click I "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/helpers/ticket_helper.py"
    click J "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/hnx.py"
    click K "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/hose.py"
    click L "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/vnstock_data/upcom.py"
    click M "https://github.com/vuthanhdatt/vnstock-data-python/tree/main/tests"
    click N "https://github.com/vuthanhdatt/vnstock-data-python/blob/main/README.md"

    classDef client fill:#f9d5e5,stroke:#333,stroke-width:2px;
    classDef api fill:#a0c4ff,stroke:#333,stroke-width:2px;
    classDef datamodule fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef helper fill:#ffadad,stroke:#333,stroke-width:2px;
    classDef exchange fill:#fdffb6,stroke:#333,stroke-width:2px;
    classDef base fill:#d0f4de,stroke:#333,stroke-width:2px;
    classDef test fill:#bde0fe,stroke:#333,stroke-width:2px;
    classDef doc fill:#ffc6ff,stroke:#333,stroke-width:2px;
```
