CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-vnstock

A beginner-friendly yet powerful Python toolkit for financial analysis and automation — built to make modern investing accessible to everyone

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

VNStock

A beginner-friendly yet powerful Python toolkit for financial analysis and automation of Vietnamese stock market data. VNStock provides comprehensive access to real-time and historical financial data from Vietnamese stock exchanges, including stocks, indices, derivatives, bonds, forex, and cryptocurrency data with built-in visualization capabilities.

Package Information

  • Package Name: vnstock
  • Language: Python
  • Installation: pip install vnstock
  • Python Version: >=3.10
  • License: Custom (Personal, research, non-commercial use)

Core Imports

import vnstock
from vnstock import Vnstock, Quote, Company, Finance, Listing, Trading, Screener, Fund

For charts and visualization:

from vnstock import chart_wrapper

Basic Usage

import vnstock
from vnstock import Vnstock

# Initialize the main VNStock client
stock = Vnstock()

# Get historical stock data
tcb_data = stock.stock(symbol="TCB", source="VCI")
price_history = tcb_data.quote.history(start="2023-01-01", end="2023-12-31")

# Get company information
company_info = tcb_data.company.overview()

# Get financial statements
financials = tcb_data.finance.balance_sheet(period="quarter")

# Create visualizations
chart = chart_wrapper(price_history)
chart.timeseries()

Architecture

VNStock follows a modular adapter pattern with multiple data sources:

  • Main Class (Vnstock): Central orchestrator returning specialized component objects
  • API Adapters: Quote, Company, Finance, Listing, Trading, Screener classes with dynamic method dispatch
  • Data Sources: VCI, TCBS, MSN, FMARKET providers with automatic failover
  • Fund Explorer: Specialized Fund class for mutual fund data
  • Visualization: Integrated charting through vnstock_ezchart

The library supports multiple Vietnamese financial data providers and uses dynamic method resolution for source-specific functionality with built-in retry logic and caching.

Capabilities

Main Client Interface

Core VNStock client providing access to all stock market data types through a unified interface. Returns specialized component objects for different asset classes.

class Vnstock:
    def __init__(self, symbol: str = None, source: str = "VCI", show_log: bool = True): ...
    def stock(self, symbol: Optional[str] = None, source: Optional[str] = None): ...
    def fx(self, symbol: Optional[str] = 'EURUSD', source: Optional[str] = "MSN"): ...
    def crypto(self, symbol: Optional[str] = 'BTC', source: Optional[str] = "MSN"): ...
    def world_index(self, symbol: Optional[str] = 'DJI', source: Optional[str] = "MSN"): ...
    def fund(self, source: Optional[str] = "FMARKET"): ...

Main Client

Quote Data Management

Historical and real-time price data including OHLC history, intraday trading data, and market depth information with support for multiple data sources.

class Quote:
    def __init__(self, source: str = "vci", symbol: str = "", random_agent: bool = False, show_log: bool = False): ...
    def history(self, *args, **kwargs): ...
    def intraday(self, *args, **kwargs): ...
    def price_depth(self, *args, **kwargs): ...

Quote Data

Company Information

Comprehensive company data including overview, shareholders, management, subsidiaries, affiliates, news, and corporate events.

class Company:
    def __init__(self, source: str = "vci", symbol: str = None, random_agent: bool = False, show_log: bool = False): ...
    def overview(self, *args, **kwargs): ...
    def shareholders(self, *args, **kwargs): ...
    def officers(self, *args, **kwargs): ...
    def subsidiaries(self, *args, **kwargs): ...
    def affiliate(self, *args, **kwargs): ...
    def news(self, *args, **kwargs): ...
    def events(self, *args, **kwargs): ...

Company Information

Financial Statements

Financial reporting data including balance sheets, income statements, cash flow statements, and financial ratios with quarterly and annual reporting periods.

class Finance:
    def __init__(self, source: str, symbol: str, period: str = "quarter", get_all: bool = True, show_log: bool = False): ...
    def balance_sheet(self, *args, **kwargs): ...
    def income_statement(self, *args, **kwargs): ...
    def cash_flow(self, *args, **kwargs): ...
    def ratio(self, *args, **kwargs): ...

Financial Statements

Market Listings

Securities listing data including symbol directories, industry classifications, exchange groupings, and various market segments.

class Listing:
    def __init__(self, source: str = "vci", random_agent: bool = False, show_log: bool = False): ...
    def all_symbols(self, *args, **kwargs): ...
    def symbols_by_industries(self, *args, **kwargs): ...
    def symbols_by_exchange(self, *args, **kwargs): ...
    def industries_icb(self, *args, **kwargs): ...
    def symbols_by_group(self, *args, **kwargs): ...
    def all_future_indices(self, **kwargs): ...
    def all_government_bonds(self, **kwargs): ...
    def all_covered_warrant(self, **kwargs): ...
    def all_bonds(self, **kwargs): ...

Market Listings

Trading Analytics

Market trading statistics, order book data, foreign and proprietary trading flows, insider transactions, and various trading-related metrics.

class Trading:
    def __init__(self, source: str = "vci", symbol: str = "", random_agent: bool = False, show_log: bool = False): ...
    def trading_stats(self, *args, **kwargs): ...
    def side_stats(self, *args, **kwargs): ...
    def price_board(self, *args, **kwargs): ...
    def price_history(self, *args, **kwargs): ...
    def foreign_trade(self, *args, **kwargs): ...
    def prop_trade(self, *args, **kwargs): ...
    def insider_deal(self, *args, **kwargs): ...
    def order_stats(self, *args, **kwargs): ...

Trading Analytics

Stock Screening

Advanced stock filtering and screening capabilities using TCBS data source with customizable parameters and criteria.

class Screener:
    def __init__(self, source: str = "tcbs", random_agent: bool = False, show_log: bool = False): ...
    def stock(self, params: dict = None, limit: int = 50, id: str = None, lang: str = "vi"): ...

Stock Screening

Mutual Funds

Comprehensive mutual fund data including fund listings, portfolio holdings, NAV history, and asset allocation analysis.

class Fund:
    def __init__(self, random_agent: bool = False) -> None: ...
    def listing(self, fund_type: str = ""): ...
    def filter(self, symbol: str = ""): ...
    def top_holding(self, fundId: int = 23): ...
    def industry_holding(self, fundId: int = 23): ...
    def nav_report(self, fundId: int = 23): ...
    def asset_holding(self, fundId: int = 23): ...
    
    # Instance attributes
    fund_list: list
    details: FundDetails

Mutual Funds

Data Visualization

Integrated charting and visualization capabilities supporting multiple chart types with pandas DataFrame integration.

# chart_wrapper is an alias for the Chart class
chart_wrapper = Chart

class Chart:
    def __init__(self, data: Union[pd.DataFrame, pd.Series]): ...
    def help(self, func_name: str): ...
    def bar(self, **kwargs): ...
    def hist(self, **kwargs): ...
    def pie(self, labels=None, values=None, **kwargs): ...
    def timeseries(self, **kwargs): ...
    def heatmap(self, **kwargs): ...
    def scatter(self, x: str, y: str, **kwargs): ...
    def treemap(self, values, labels, **kwargs): ...
    def boxplot(self, **kwargs): ...
    def pairplot(self, **kwargs): ...
    def wordcloud(self, show_log=False, **kwargs): ...
    def table(self, **kwargs): ...
    def combo(self, bar_data, line_data, **kwargs): ...

Data Visualization

Types

Common Data Types

from typing import Optional, Union, Any, Dict, List
import pandas as pd

# Main component return types
StockComponents = object  # Contains quote, company, finance components
MSNComponents = object    # Contains MSN-specific data components

Data Source Constants

# Supported data sources by component
VNSTOCK_SOURCES = ["VCI", "TCBS", "MSN"]
QUOTE_SOURCES = ["VCI", "TCBS", "MSN"] 
COMPANY_SOURCES = ["VCI", "TCBS"]
FINANCE_SOURCES = ["VCI", "TCBS"]
LISTING_SOURCES = ["VCI", "MSN"]
TRADING_SOURCES = ["VCI", "TCBS"]
SCREENER_SOURCES = ["TCBS"]
FUND_SOURCES = ["FMARKET"]

# MSN symbol mappings
CURRENCY_PAIRS = ["USDVND", "EURUSD", "GBPUSD", ...]  # 38+ currency pairs
CRYPTO_SYMBOLS = ["BTC", "ETH", "BNB", ...]           # 10 crypto symbols  
GLOBAL_INDICES = ["DJI", "SPX", "IXIC", ...]          # 19 global indices

Configuration

# Retry and timeout configuration
RETRIES = 3
REQUEST_TIMEOUT = 30
CACHE_SIZE = 128
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/vnstock@3.2.x
Publish Source
CLI
Badge
tessl/pypi-vnstock badge