tessl/pypi-vnstock

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

Overview

Eval results

Files

Company Information

Name: tessl/pypi-vnstock
Author: tessl

The Company class provides comprehensive access to corporate data including company overview, shareholder structure, management information, subsidiaries, affiliates, news, and corporate events. It supports Vietnamese data sources with detailed corporate governance and business intelligence.

Capabilities

Company Class

Adapter for company-related data with dynamic method dispatch supporting VCI and TCBS data sources. Provides detailed corporate information for Vietnamese listed companies.

class Company:
    """
    Company data adapter for corporate information.
    
    Supported sources: VCI, TCBS
    """
    
    def __init__(self, source: str = "vci", symbol: str = None, random_agent: bool = False, show_log: bool = False):
        """
        Initialize Company data adapter.
        
        Args:
            source (str): Data source ("vci", "tcbs"), defaults to "vci"
            symbol (str): Default company symbol, defaults to None
            random_agent (bool): Use random user agent, defaults to False
            show_log (bool): Enable logging, defaults to False
        """

Company Overview

Comprehensive company profile including business description, key metrics, financial highlights, and basic corporate information.

def overview(self, *args, **kwargs) -> pd.DataFrame:
    """
    Get comprehensive company overview and profile data.
    
    Common parameters (vary by source):
        symbol (str): Company symbol
        lang (str): Language ("vi", "en"), defaults to "vi"
        
    Returns:
        pd.DataFrame: Company overview with information including:
            - company_name: Official company name
            - symbol: Trading symbol
            - exchange: Stock exchange (HOSE, HNX, UPCOM)
            - industry: Industry classification
            - sector: Business sector
            - market_cap: Market capitalization
            - shares_outstanding: Number of shares outstanding
            - book_value: Book value per share
            - eps: Earnings per share
            - pe_ratio: Price-to-earnings ratio
            - dividend_yield: Dividend yield percentage
            - business_summary: Company business description
            - address: Company headquarters address
            - phone: Contact phone number
            - website: Company website
            - established_date: Company establishment date
            - listing_date: Stock listing date
    """

Usage Examples

from vnstock import Company

# Initialize Company adapter
company = Company(source="vci", symbol="TCB")

# Get company overview
tcb_overview = company.overview(symbol="TCB", lang="vi")

# Get overview for multiple companies
vcb_overview = company.overview(symbol="VCB")
hpg_overview = company.overview(symbol="HPG")

# Using TCBS source
tcbs_company = Company(source="tcbs")
company_profile = tcbs_company.overview(symbol="FPT", lang="en")

Shareholder Information

Detailed shareholder structure including major shareholders, ownership percentages, and shareholding changes over time.

def shareholders(self, *args, **kwargs) -> pd.DataFrame:
    """
    Get company shareholder structure and ownership information.
    
    Common parameters (vary by source):
        symbol (str): Company symbol
        page_size (int): Number of records per page
        page (int): Page number for pagination
        
    Returns:
        pd.DataFrame: Shareholder data including:
            - shareholder_name: Name of shareholder
            - shareholding_percentage: Ownership percentage
            - shares_held: Number of shares held
            - shareholder_type: Type ("individual", "institutional", "foreign")
            - change_percentage: Recent change in ownership
            - report_date: Reporting date
    """

Usage Examples

# Get shareholder structure
shareholders_data = company.shareholders(symbol="TCB")

# Get detailed shareholder information with pagination
detailed_shareholders = company.shareholders(
    symbol="VCB", 
    page_size=50,
    page=1
)

# Track shareholder changes
historical_shareholders = company.shareholders(symbol="HPG")

Management Information

Company officers and management team including board of directors, executives, and key personnel with their roles and background.

def officers(self, *args, **kwargs) -> pd.DataFrame:
    """
    Get company management and officer information.
    
    Common parameters (vary by source):
        symbol (str): Company symbol
        filter_by (str): Filter criteria ("working", "resigned", "all")
        
    Returns:
        pd.DataFrame: Management data including:
            - full_name: Officer full name
            - position: Job title/position
            - status: Employment status ("working", "resigned")
            - start_date: Start date in position
            - end_date: End date (if resigned)
            - shares_held: Number of shares held by officer
            - ownership_percentage: Ownership percentage
            - background: Professional background
            - education: Educational background
    """

Usage Examples

# Get current management team
current_officers = company.officers(symbol="TCB", filter_by="working")

# Get all officers including resigned ones
all_officers = company.officers(symbol="VCB", filter_by="all")

# Get only resigned officers
former_officers = company.officers(symbol="HPG", filter_by="resigned")

Subsidiary Companies

Information about subsidiary and affiliated companies including ownership structure and business relationships.

def subsidiaries(self, *args, **kwargs) -> pd.DataFrame:
    """
    Get company subsidiary and affiliate information.
    
    Common parameters (vary by source):
        symbol (str): Company symbol
        filter_by (str): Filter criteria ("all", "subsidiary")
        
    Returns:
        pd.DataFrame: Subsidiary data including:
            - subsidiary_name: Name of subsidiary company
            - ownership_percentage: Ownership percentage by parent
            - business_type: Type of business
            - established_date: Establishment date
            - capital: Registered capital
            - address: Business address
            - main_business: Primary business activities
            - relationship_type: Relationship type ("subsidiary", "affiliate")
    """

Usage Examples

# Get all subsidiaries
subsidiaries_data = company.subsidiaries(symbol="TCB", filter_by="all")

# Get only direct subsidiaries
direct_subs = company.subsidiaries(symbol="VCB", filter_by="subsidiary")

# Comprehensive subsidiary analysis
hpg_subsidiaries = company.subsidiaries(symbol="HPG")

Affiliate Information

Details about affiliated companies and business partnerships including joint ventures and strategic alliances.

def affiliate(self, *args, **kwargs) -> pd.DataFrame:
    """
    Get company affiliate and partnership information.
    
    Common parameters (vary by source):
        symbol (str): Company symbol
        
    Returns:
        pd.DataFrame: Affiliate data including:
            - affiliate_name: Name of affiliated company
            - relationship_type: Type of relationship
            - partnership_percentage: Partnership or ownership percentage
            - business_cooperation: Areas of business cooperation
            - agreement_date: Partnership agreement date
            - main_activities: Primary cooperative activities
    """

Usage Examples

# Get affiliate information
affiliates_data = company.affiliate(symbol="TCB")

# Comprehensive affiliate analysis
vcb_affiliates = company.affiliate(symbol="VCB")

Company News

Recent news, press releases, and announcements related to the company including corporate events and market updates.

def news(self, *args, **kwargs) -> pd.DataFrame:
    """
    Get company news and press releases.
    
    Common parameters (vary by source):
        symbol (str): Company symbol
        page_size (int): Number of news items per page
        page (int): Page number for pagination
        start_date (str): Start date for news filter
        end_date (str): End date for news filter
        
    Returns:
        pd.DataFrame: News data including:
            - title: News headline
            - summary: News summary
            - publish_date: Publication date
            - source: News source
            - category: News category
            - url: Link to full article
            - importance: News importance level
    """

Usage Examples

# Get recent company news
recent_news = company.news(symbol="TCB", page_size=20)

# Get news for specific date range
filtered_news = company.news(
    symbol="VCB",
    start_date="2023-01-01",
    end_date="2023-12-31",
    page_size=50
)

# Get latest news updates
latest_news = company.news(symbol="HPG", page=1)

Corporate Events

Corporate events including dividends, stock splits, shareholder meetings, and other significant corporate actions.

def events(self, *args, **kwargs) -> pd.DataFrame:
    """
    Get corporate events and actions.
    
    Common parameters (vary by source):
        symbol (str): Company symbol
        event_type (str): Type of event filter
        start_date (str): Start date for events
        end_date (str): End date for events
        
    Returns:
        pd.DataFrame: Corporate events including:
            - event_type: Type of corporate event
            - event_date: Event date
            - ex_date: Ex-dividend/ex-rights date
            - record_date: Record date
            - event_description: Event description
            - dividend_rate: Dividend rate (if applicable)
            - split_ratio: Stock split ratio (if applicable)
            - meeting_type: Meeting type (AGM, EGM)
            - announcement_date: Event announcement date
    """

Usage Examples

# Get all corporate events
all_events = company.events(symbol="TCB")

# Get dividend events only
dividend_events = company.events(
    symbol="VCB", 
    event_type="dividend",
    start_date="2023-01-01",
    end_date="2023-12-31"
)

# Get upcoming shareholder meetings
upcoming_meetings = company.events(
    symbol="HPG",
    event_type="meeting"
)

Data Source Specifics

VCI (Vietnam Capital Securities)

Coverage: All Vietnamese listed companies (HOSE, HNX, UPCOM)
Data Depth: Comprehensive corporate governance data
Update Frequency: Daily updates for corporate actions
Languages: Vietnamese and English support
Historical Data: Multi-year historical corporate data

VCI-Specific Features

Detailed shareholder tracking with ownership changes
Comprehensive management background information
Complete subsidiary mapping with ownership percentages
Real-time corporate event notifications

TCBS (Techcombank Securities)

Coverage: Vietnamese listed companies with focus on major stocks
Data Depth: Detailed financial and corporate information
Update Frequency: Real-time corporate event updates
Languages: Vietnamese and English
Specialization: Enhanced analytical data and ratios

TCBS-Specific Features

Advanced company screening capabilities
Enhanced financial ratio analysis
Comprehensive industry comparisons
Real-time news aggregation from multiple sources

Data Integration Examples

Comprehensive Company Analysis

from vnstock import Company

# Initialize company adapter
company = Company(source="vci")

# Get complete company profile
symbol = "TCB"

# Basic information
overview = company.overview(symbol=symbol)
shareholders = company.shareholders(symbol=symbol)
management = company.officers(symbol=symbol, filter_by="working")

# Corporate structure
subsidiaries = company.subsidiaries(symbol=symbol, filter_by="all")
affiliates = company.affiliate(symbol=symbol)

# Recent developments
news = company.news(symbol=symbol, page_size=10)
events = company.events(symbol=symbol)

# Combine for comprehensive analysis
print(f"Company: {overview['company_name'].iloc[0]}")
print(f"Market Cap: {overview['market_cap'].iloc[0]}")
print(f"Number of Shareholders: {len(shareholders)}")
print(f"Management Team Size: {len(management)}")
print(f"Subsidiaries Count: {len(subsidiaries)}")
print(f"Recent News Items: {len(news)}")

Multi-Company Comparison

# Compare multiple companies
symbols = ["TCB", "VCB", "BID"]
comparison_data = {}

for symbol in symbols:
    comparison_data[symbol] = {
        'overview': company.overview(symbol=symbol),
        'shareholders': company.shareholders(symbol=symbol),
        'management': company.officers(symbol=symbol, filter_by="working")
    }

# Analyze comparative metrics
for symbol, data in comparison_data.items():
    overview = data['overview']
    print(f"{symbol}: Market Cap = {overview['market_cap'].iloc[0]}, P/E = {overview['pe_ratio'].iloc[0]}")

Install with Tessl CLI