Quick Start¶

Welcome to Global-Data-Finance! This introductory guide will help you build your foundational financial extraction scripts using clear, executable code examples.

Prerequisites¶

Before running the code examples below, confirm that you have:

✅ Installed Global-Data-Finance (see installation guide)
✅ Verified Python 3.12 or superior is running
✅ An active internet connection for communicating with regulatory and market feeds

Example 1: Downloading CVM Regulatory Filings¶

Let’s begin by downloading fundamental corporate financial disclosures directly from CVM (Securities and Exchange Commission of Brazil).

Minimal Script¶

from globaldatafinance import FundamentalStocksDataCVM

# 1. Instantiate the CVM public client
cvm = FundamentalStocksDataCVM()

# 2. Download DFP (Standardized Annual Financial Statements)
cvm.download(
    destination_path="/home/user/data_cvm",
    list_docs=["DFP"],
    initial_year=2022,
    last_year=2023
)

What Happens Behind the Scenes?¶

Client Initialization: Prepares the CVM client equipped with custom retry policies and adaptive concurrency throttling.
Download Execution: Asynchronously downloads official DFP archives spanning fiscal years 2022 through 2023.
Persisted Output: Validates file integrity and persists raw ZIP files into /home/user/data_cvm.

Expected Console Summary¶

📥 Download de Documentos CVM
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Documentos baixados com sucesso!

📊 Resumo:
  • Total de arquivos: 2
  • Sucesso: 2
  • Erros: 0
  • Tempo decorrido: 45.3s

📁 Arquivos baixados:
  ✓ DFP - 2022
  ✓ DFP - 2023

Console Reporting Language

Console execution progress and formatting output generated by the library (*_formatter.py) natively display in Portuguese, adhering to standardized Brazilian market and regulatory domain naming conventions.

Example 2: Extracting B3 Historical Market Quotes¶

Next, let’s extract and normalize official market exchange quotes from B3 (Brazilian Stock Exchange).

Minimal Script¶

from globaldatafinance import HistoricalQuotesB3

# 1. Instantiate the B3 public client
b3 = HistoricalQuotesB3()

# 2. Extract spot market stock quotes from COTAHIST files
result = b3.extract(
    path_of_docs="/home/user/cotahist_zips",
    assets_list=["ações"],
    initial_year=2023,
    destination_path="/home/user/extracted_quotes"
)

What Happens Behind the Scenes?¶

Client Initialization: Prepares the B3 processing client.
Parsing & Extraction: Reads official positional COTAHIST archives (ZIP or TXT) inside /home/user/cotahist_zips, filtering exclusively for spot market stocks (ações).
Columnar Normalization: Converts raw records into typed, columnar schema structures.
Persisted Output: Atomically writes a consolidated Apache Parquet file (.parquet) containing all filtered historical quotes into /home/user/extracted_quotes.

Expected Console Summary¶

📊 Extração de Cotações B3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Extração concluída com sucesso!

📈 Resumo:
  • Arquivos processados: 2
  • Total de registros: 836,978
  • Classes de ativos: ações
  • Modo de processamento: fast
  • Tempo decorrido: 77.9s

💾 Arquivo gerado:
  /home/user/extracted_quotes/cotahist_extracted.parquet

Console Reporting Language

As shown above, terminal execution summaries natively output in Portuguese (*_formatter.py), matching the standard domain terms of Brazilian financial institutions.

Discovering Available Metadata and Assets¶

Before initiating large data extraction jobs, programmatically query the available document types and historical time windows.

Inspecting CVM Document Catalogs¶

from globaldatafinance import FundamentalStocksDataCVM

cvm = FundamentalStocksDataCVM()

# Retrieve descriptions for all supported document codes
docs = cvm.get_available_docs()
for code, description in docs.items():
    print(f"{code}: {description}")

# Check supported historical range
years = cvm.get_available_years()
print(f"\nData available spanning from {years['General Document Years']} to {years['Current Year']}")

Console Output:

DFP: Demonstração Financeira Padronizada
ITR: Informação Trimestral
FRE: Formulário de Referência
FCA: Formulário Cadastral
...

Data available spanning from 2010 to current year

Inspecting B3 Asset Classes¶

from globaldatafinance import HistoricalQuotesB3

b3 = HistoricalQuotesB3()

# List supported asset filtering strings
assets = b3.get_available_assets()
print("Supported asset categories:")
for asset in assets:
    print(f"  • {asset}")

# Check permitted historical range
years = b3.get_available_years()
print(f"\nQuotes available spanning from {years['minimal_year']} to {years['current_year']}")

Console Output:

Supported asset categories:
  • ações
  • etf
  • opções
  • termo
  • exercicio_opcoes
  • forward
  • leilao

Quotes available spanning from 1986 to current year

Comprehensive Example: Automated Financial Pipeline¶

Here is an end-to-end processing pipeline illustrating combined regulatory and market data ingestion:

from globaldatafinance import FundamentalStocksDataCVM, HistoricalQuotesB3

# === PART 1: CVM Regulatory Ingestion ===
print("=" * 60)
print("PHASE 1: Ingesting CVM Financial Statements")
print("=" * 60)

cvm = FundamentalStocksDataCVM()
cvm.download(
    destination_path="/home/user/financial_data/cvm",
    list_docs=["DFP", "ITR"],
    initial_year=2022,
    last_year=2023,
    automatic_extractor=True  # Automatically extracts ZIP files into columnar Parquet datasets
)

# === PART 2: B3 Quotes Processing ===
print("\n" + "=" * 60)
print("PHASE 2: Normalizing B3 Historical Market Quotes")
print("=" * 60)

b3 = HistoricalQuotesB3()
result = b3.extract(
    path_of_docs="/home/user/financial_data/raw_cotahist",
    assets_list=["ações", "etf"],
    initial_year=2022,
    last_year=2023,
    destination_path="/home/user/financial_data/quotes",
    output_filename="stocks_etfs_2022_2023",
    processing_mode="fast"
)

# === PART 3: Diagnostic Results ===
print("\n" + "=" * 60)
print("EXECUTION SUMMARY")
print("=" * 60)

if result['success']:
    print(f"✓ Pipeline finished successfully!")
    print(f"✓ Total consolidated records written: {result['total_records']:,}")
    print(f"✓ Persisted Parquet artifact: {result['output_file']}")
else:
    print(f"✗ Exceptions encountered during processing")
    if 'errors' in result:
        for error in result['errors']:
            print(f"  • {error}")

Working with Extracted Data¶

Once extracted into columnar Parquet format, consume your datasets using either Pandas or Polars:

Analyzing with Pandas¶

import pandas as pd

# Load the generated Parquet file
df = pd.read_parquet("/home/user/extracted_quotes/cotahist_extracted.parquet")

# Preview initial rows
print(df.head())

# Display basic dataset diagnostics
print(f"\nTotal records: {len(df):,}")
print(f"Columns: {list(df.columns)}")
print(f"Time series interval: {df['data'].min()} to {df['data'].max()}")

Analyzing with Polars (Optimized for Large Datasets)¶

import polars as pl

# Read Parquet dataset natively
df = pl.read_parquet("/home/user/extracted_quotes/cotahist_extracted.parquet")

# Quick preview and estimation
print(df.head())
print(f"\nDataframe shape: {df.shape}")
print(f"In-memory estimation: {df.estimated_size('mb'):.2f} MB")

Tips for Beginners¶

Start with a Narrow Scope

When developing scripts or running validation tests, request small temporal intervals (e.g., 1 fiscal year) to verify pipeline behavior before triggering multi-decade batch jobs.

Use Fast Mode for Market Data

When extracting B3 quotes, processing_mode="fast" leverages in-memory parallelization and provides superior processing speed for most standard hardware configurations.

Verify Free Disk Space

Historical COTAHIST datasets and multi-year corporate regulatory filings consume substantial storage. Verify adequate local disk capacity prior to extensive historical downloads.

Next Steps¶

Now that you are familiar with foundational operations, dive deeper into detailed reference guides:

📄 CVM Documents - Deep dive into regulatory financial filings
📈 B3 Quotes - Detailed specifications for market quote processing
💻 Practical Examples - Real-world quantitative recipes and pipelines
❓ FAQ - Frequently asked questions and troubleshooting

Congratulations!

You have completed the quick start guide! You are now prepared to build production-grade financial extraction scripts with Global-Data-Finance. 🚀