yfinance

A structured Python interface for retrieving and validating market data using yfinance. Implements the DataSource protocol from pydantic-market-data to provide type-safe security resolution and historical data fetching.

Features

• Protocol-Oriented: Implements DataSource interface.
• Security Resolution: Resolve ISINs and Symbols to valid yfinance tickers.
• Validation:
  • Price Validation: Verify tickers against daily high/low range.
  • Date Validation: Validate prices on specific historical dates.
• CLI: Optional command-line interface for lookup and history.

Installation

uv pip install py-yfinance

Usage

As a Library

from py_yfinance import YFinanceDataSource
from pydantic_market_data.models import PriceOnDate, SecurityQuery

source = YFinanceDataSource()

# 1. Simple lookup by symbol
result = source.resolve(SecurityQuery(symbol="AAPL"))
print(result.symbol, result.price)

# 2. Strict validation by date and price
# Useful for verifying ISIN mappings or ensuring data quality
query = SecurityQuery(
    isin="NL0010273215",
    price_on=PriceOnDate(date="2025-12-15", price=923.4),
)
match = source.resolve(query)
if match:
    print(f"Verified: {match.symbol}")
else:
    print("Validation failed: price mismatch or symbol not found")

Dates accept YYYY-MM-DD, YYYY/MM/DD or YYYYMMDD; any other string raises ValidationError.

Fundamentals, analyst data and bulk prices

from pydantic_market_data.models import HistoryPeriod
from py_yfinance import YahooFundamentals

yahoo = YahooFundamentals()
stats = yahoo.key_statistics("MSFT")          # price, market cap, multiples, analyst targets
counts = yahoo.recommendation_counts("MSFT")  # None without analyst coverage
statements = yahoo.annual_statements("MSFT")  # newest fiscal year first; empty for funds
earnings = yahoo.earnings_dates("MSFT")       # newest first, upcoming reports included
ratings = yahoo.rating_changes("MSFT")        # analyst upgrades and downgrades
bulk = yahoo.bulk_prices(["MSFT", "VWRA.L"], HistoryPeriod.Y1)
print(bulk.closes.tail(), bulk.missing)

Each method raises YahooDataError when Yahoo fails to answer or answers in an unexpected shape.

CLI Usage

Lookup

Resolve a security by symbol or ISIN.

# Basic lookup
uv run yfinance lookup --symbol AAPL

# ISIN lookup with strict validation
# Verifies that NL0010273215 traded near 923.4 on 2025-12-15
uv run yfinance lookup --isin NL0010273215 --date 2025-12-15 --price 923.4

History

Fetch daily candles.

uv run yfinance history --symbol AAPL --period 5d

Search

uv run yfinance search tesla

Output is a JSON envelope when stdout is not a terminal; pass --format plain for text. Run uv run yfinance <command> --schema for a command's input and output schema.

Development

This project uses uv for dependency management.

# Sync dependencies
uv sync

# Run Tests
uv run pytest

License

MIT