How vuthanhdatt/vnstock-data-python works
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.