yquoter 0.3.1

A unified financial data interface and analysis toolkit for CN/HK/US markets.

Yquoter

Yquoter: Your universal cross-market quote fetcher. Fetch A-shares, H-shares, and US stock prices easily via one interface.

---

🌟 Major Update: v0.3.1 — Async, AI & Multi-Market

🆕 Object-Oriented Design (v0.3.0)

From v0.3.0, all core operations are now methods of the Stock class.

from yquoter import Stock

# Chained-style API
df = Stock(market="us", code="AAPL").get_history(start_date="2023-01-01")

🚀 v0.3.1 Highlights

• Async Concurrent Architecture: Report generation uses asyncio.gather to fetch history, realtime, profile, and factors simultaneously (up to 2.5x speedup).
• AI-Powered Analysis: Integrated LLM Gateway supports DeepSeek, ChatGPT, Claude, Qwen, Kimi, and Gemini with automatic fallback.
• Multi-Market Support: Seamless access to CN (A-shares), HK (H-shares), and US stocks via a single interface.

⚠️ Compatibility Notice

• Old functions still work (get_stock_history, get_ma_n, etc.)
• Deprecated — will be removed in v1.0.0

---

🧠 Project Info

• Version: 0.3.1

Yquoter is developed by the Yquoter Team, co-founded by four students from SYSU and SCUT.

Project Lead: @Yodeesy
Core Contributors: @Sukice, @encounter666741, @Gaeulczy

The first version (v0.1.0) was completed collaboratively in 2025.

---

📦 Installation

## Installation Options
# Minimal:
pip install yquoter
# With Tushare Module
pip install yquoter[tushare]
# With Plotting
pip install yquoter[plotting]
# Full install
pip install yquoter[all]

---

📂 Project Structure

This is a high-level overview of the Yquoter package structure:

Yquoter/
├── src/ 
│   └── yquoter/
│       ├── __init__.py             # Public API exports (Stock, LLMGateway, etc.)
│       ├── reporting.py            # Stock report generation (Markdown + charts)
│       ├── datasource.py           # Unified data source interface & registry
│       ├── tushare_source.py       # TuShare data source module (optional)
│       ├── spider_source.py        # Default web-scraping data source
│       ├── spider_core.py          # Async concurrency engine (httpx + asyncio)
│       ├── llm_gateway.py          # AI analysis gateway (multi-provider)
│       ├── llm_prompts.py          # LLM prompt templates for analysis
│       ├── config.py               # Configuration management (env, YAML)
│       ├── models.py               # Stock class (type-safe OOP interface)
│       ├── indicators.py           # Technical indicators (MA, RSI, BOLL, etc.)
│       ├── logger.py               # Logging configuration
│       ├── cache.py                # Local data caching (LRU)
│       ├── utils.py                # General-purpose utilities
│       ├── exceptions.py           # Custom exception classes
│       ├── compat.py               # Backward-compat legacy function wrappers
│       └── configs/
│           ├── mapping.yaml        # API field name mappings
│           ├── standard.yaml       # Data standard definitions
│           └── dictionary.yaml     # Localized report dictionary (CN/EN)
│
├── examples/
│   └── basic_usage.ipynb           # Jupyter Notebook with usage examples
│
├── assets/                         # Non-code assets (logos, banners)
├── out/                            # Generated reports (ignored by Git)
├── .cache/                         # Cache directory (ignored by Git)
├── pyproject.toml        # Package configuration for distribution (PyPI)
├── requirements.txt      # Declaration of project dependencies
├── LICENSE               # Apache 2.0 Open Source License details
├── README.md             # Project documentation (this file)
├── .gitignore            # Files/directories to exclude from version control
└── .github/workflows/ci.yml  # GitHub Actions workflow for Continuous Integration

---

🚀 Core API Reference

The Yquoter library exposes a set of standardized functions for data acquisition and technical analysis.

For detailed descriptions of all function parameters (e.g., market, klt, report_type), please refer to the dedicated Parameters Reference.

📝 Note: Yquoter internally integrates and standardizes external data sources like Tushare. This means Tushare users can leverage Yquoter's unified API and caching mechanisms without dealing with complex native interface calls. To learn more about the underlying data source, visit the Tushare GitHub repository.

Returns: pandas.DataFrame

Stock Class Methods Reference (Optimized for O-O)

unction	Description	Primary Parameters	Returns	Notes
get_history	Fetch historical OHLCV (K-line) data for a date range.	start_date, end_date, klt, fqt, fields('basic' or 'full')	DataFrame (OHLCV)	These parameters define the data range and frequency.
get_realtime	Fetch the latest trading snapshot (real-time quotes).	fields (optional)	DataFrame (Realtime Quotes)	The stock is determined by the instance's code.
get_factors	Fetch historical valuation/market factors (e.g., PE, PB).	trade_date	DataFrame (Factors)	trade_date specifies the day for the factor data.
get_profile	Fetch basic profile information (company name, listing date, industry).	None	DataFrame (Profile)	Requires no parameters; uses the object's stored code.
get_financials	Fetch fundamental financial statements (e.g., Income Statement, Balance Sheet).	end_day, report_type, limit	DataFrame (Financials)	end_day is the cutoff date for the report.
get_ma	Calculate N-period Moving Average (MA).	n (default 5)	DataFrame (MA column)	The calculation is run on the instance's latest history data.
get_boll	Calculate N-period Bollinger Bands (BOLL).	n (default 20)	DataFrame (BOLL, Upper/Lower bands)	-
get_rsi	Calculate N-period Relative Strength Index (RSI).	n (default 5)	DataFrame (RSI column)	-
get_rv	Calculate N-period Rolling Volatility (RV).	n (default 5)	DataFrame (RV column)	-
get_max_drawdown	Calculate Maximum Drawdown and Recovery over a period.	n (default 5)	Dict (Max Drawdown)	Runs on the instance's history or an optionally provided df.
get_vol_ratio	Calculate Volume Ratio (Volume to its N-period average).	n (default 20)	DataFrame (Volume Ratio)	-
get_report	Generate a comprehensive Markdown report with profile, realtime, history chart, summary stats, and optional AI analysis.	start, end, language, llm_provider (optional)	str (Markdown content)	When llm_provider is set (e.g. "deepseek"), AI-powered market analysis is appended.

Data Acquisition Functions

Function	Description	Primary Parameters	Returns
get_stock_history	Fetch historical OHLCV (K-line) data for a date range.	market, code, start, end	DataFrame (OHLCV)
get_stock_realtime	Fetch the latest trading snapshot (real-time quotes).	market, code	DataFrame (Realtime Quotes)
get_stock_factors	Fetch historical valuation/market factors (e.g., PE, PB).	market, code, trade_day	DataFrame (Factors)
get_stock_profile	Fetch basic profile information (e.g., company name, listing date, industry).	market, code	DataFrame (Profile)
get_stock_financials	Fetch fundamental financial statements (e.g., Income Statement, Balance Sheet).	market, code, end_day, report_type	DataFrame (Financials)

Technical Analysis Functions

These functions primarily take an existing DataFrame (df) or data request parameters (market, code, start, end) and calculate indicators.

Function	Description	Primary Parameters	Returns
get_ma_n	Calculate N-period Moving Average (MA).	df, n (default 5)	DataFrame (MA column)
get_boll_n	Calculate N-period Bollinger Bands (BOLL).	df, n (default 20)	DataFrame (BOLL, Upper/Lower bands)
get_rsi_n	Calculate N-period Relative Strength Index (RSI).	df, n (default 14)	DataFrame (RSI column)
get_rv_n	Calculate N-period Rolling Volatility (RV).	df, n (default 5)	DataFrame (RV column)
get_max_drawdown	Calculate Maximum Drawdown and Recovery over a period.	df	Dict (Max Drawdown)
get_vol_ratio	Calculate Volume Ratio (Volume to its N-period average).	df, n (default 5)	DataFrame (Volume Ratio)

Utility Functions

Function	Description	Primary Parameters
init_cache_manager	Initialize the cache manager with a maximum LRU entry count.	max_entries
generate_stock_report	Generate a visualized report of history, realtime, profile of a stock.	market, code, start_date, end_date, language('cn' or 'en')
register_source	Register a new custom data source plugin.	source_name, func_type (e.g., "realtime")
set_default_source	Set a new default data source.	name
init_tushare	Initialize TuShare connection with your API token and registerTuShare data interfaces.	token (or None)
get_newest_df_path	Get the path of the newest cached data file.	None

---

🤖 LLM Gateway (AI-Powered Analysis)

Yquoter includes a built-in LLM Gateway that connects to multiple AI providers for automated market analysis. It supports automatic provider detection and priority-based fallback.

Configured via environment variables

Provider	Env Variable	Default Model
DeepSeek	DEEPSEEK_API_KEY	deepseek-chat
OpenAI	OPENAI_API_KEY	gpt-4o-mini
Qwen	QWEN_API_KEY	qwen-plus
Kimi	KIMI_API_KEY	moonshot-v1-8k
Claude	CLAUDE_API_KEY	claude-3-5-haiku-latest
Gemini	GEMINI_API_KEY	gemini-2.0-flash

Usage

from yquoter import get_llm_gateway

gateway = get_llm_gateway()

# Check if any provider is configured
print(gateway.is_available())  # True / False

# List active providers
print(gateway.list_providers())

# Direct LLM analysis
result = gateway.analyze(
    system_prompt="You are a financial analyst.",
    user_prompt="Analyze the recent price trend...",
    provider_name="deepseek",  # optional; auto-fallback if omitted
)

Use AI in stock reports

from yquoter import Stock

# Generate a report with DeepSeek AI analysis
report = Stock("cn", "600519").get_report(
    language="cn",
    llm_provider="deepseek",
)
# The AI section is appended after the data sections

---

🛠️ Usage Example

📘 View the Basic Usage Tutorial (Jupyter Notebook)

---

🤝 Contribution Guide

We welcome contributions of all forms, including bug reports, documentation improvements, feature requests, and code contributions.

Before submitting a Pull Request, please ensure that you:

Adhere to the project's coding standards.

Add necessary test cases to cover new or modified logic.

Update relevant documentation (docstrings, README, or examples).

For major feature changes, please open an Issue first to discuss the idea with the community.

---

📜 License

This project is licensed under the Apache License 2.0. See the LICENSE file for more details.

---