# Yquoter
[](https://pypi.org/project/yquoter/)
[](https://test.pypi.org/project/yquoter/)
[](https://github.com/Yodeesy/Yquoter/actions/workflows/ci.yml)
[](https://discord.gg/UpyzsF2Kj4)
[](./LICENSE)
---
Yquoter: Your **universal cross-market quote fetcher**. Fetch **A-shares, H-shares, and US stock prices** easily via one interface.
> 🧠 **Project Info**
>
> **Yquoter** is developed by the **Yquoter Team**, co-founded by four students from SYSU and SCUT.
>
> **Project Lead:** [@Yodeesy](https://github.com/Yodeesy)
> **Core Contributors:** [@Sukice](https://github.com/Sukice), [@encounter666741](https://github.com/encounter666741), [@Gaeulczy](https://github.com/Gaeulczy)
>
> The first version (v0.1.0) was completed collaboratively in 2025.
---
## 📦 Installation
```bash
pip install yquoter
# If you need tuShare Module, please use:
# pip install yquoter[tushare]
```
---
## 📂 Project Structure
This is a high-level overview of the Yquoter package structure:
```
Yquoter/
├── src/
│ └── yquoter/
│ ├── __init__.py # Exposes the main API interfaces (e.g., get_quotes)
│ ├── datasource.py # Unified interface for all data fetching sources
│ ├── tushare_source.py # A module for Tushare users, requires activation
│ ├── spider_source.py # Default data source using internal web scraping
│ ├── spider_core.py # Core logic and mechanism for the internal spider
│ ├── config.py # Manages configuration settings (tokens, paths)
│ ├── .env # Stores sensitive environment variables (e.g., Tushare token)
│ ├── indicators.py # Utility for calculating technical indicators
│ ├── logger.py # Logging configuration and utilities
│ ├── cache.py # Manages local data caching mechanisms
│ ├── utils.py # General-purpose utility functions
│ └── configs/
│ ├── mapping.yaml # Mapping for Data & configs
│ └── standard.yaml # Yquoter's data standard
│
├── examples/
│ └── basic_usage.ipynb # Detailed usage examples in Jupyter Notebook
│
├── assets/ # Non-code assets (e.g., logos, screenshots for README)
├── temp/ # Temporary files for test (ignored by Git)
├── .cache/ # Cache files (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](./PARAMETERS.md)**.
> 📝 **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](https://github.com/waditu/tushare).
**Returns**: `pandas.DataFrame`
### 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` |
| `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 **register`TuShare` data interfaces**. | `token (or None)` |
| `get_newest_df_path` | **Get the path** of the newest cached data file. | **None** |
---
## 🛠️ Usage Example
**[📘 View the Basic Usage Tutorial (Jupyter Notebook)](./examples/basic_usage.ipynb)**
---
## 🤝 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.
---
Raw data
{
"_id": null,
"home_page": null,
"name": "yquoter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "finance, stock, tushare, quant, data, crawler",
"author": null,
"author_email": "Yodeesy <yodeeshi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7a/cb/571e3916614a904924abe72c60f49228b46a4fa3bd091c28c334eb111e5b/yquoter-0.2.0.tar.gz",
"platform": null,
"description": "# Yquoter\r\n\r\n[](https://pypi.org/project/yquoter/)\r\n[](https://test.pypi.org/project/yquoter/)\r\n[](https://github.com/Yodeesy/Yquoter/actions/workflows/ci.yml)\r\n\r\n[](https://discord.gg/UpyzsF2Kj4)\r\n[](./LICENSE)\r\n\r\n---\r\nYquoter: Your **universal cross-market quote fetcher**. Fetch **A-shares, H-shares, and US stock prices** easily via one interface.\r\n\r\n> \ud83e\udde0 **Project Info**\r\n> \r\n> **Yquoter** is developed by the **Yquoter Team**, co-founded by four students from SYSU and SCUT. \r\n> \r\n> **Project Lead:** [@Yodeesy](https://github.com/Yodeesy) \r\n> **Core Contributors:** [@Sukice](https://github.com/Sukice), [@encounter666741](https://github.com/encounter666741), [@Gaeulczy](https://github.com/Gaeulczy) \r\n> \r\n> The first version (v0.1.0) was completed collaboratively in 2025.\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\npip install yquoter\r\n# If you need tuShare Module, please use:\r\n# pip install yquoter[tushare]\r\n```\r\n\r\n---\r\n## \ud83d\udcc2 Project Structure\r\nThis is a high-level overview of the Yquoter package structure:\r\n```\r\nYquoter/\r\n\u251c\u2500\u2500 src/ \r\n\u2502 \u2514\u2500\u2500 yquoter/\r\n\u2502 \u251c\u2500\u2500 __init__.py # Exposes the main API interfaces (e.g., get_quotes)\r\n\u2502 \u251c\u2500\u2500 datasource.py # Unified interface for all data fetching sources\r\n\u2502 \u251c\u2500\u2500 tushare_source.py # A module for Tushare users, requires activation\r\n\u2502 \u251c\u2500\u2500 spider_source.py # Default data source using internal web scraping\r\n\u2502 \u251c\u2500\u2500 spider_core.py # Core logic and mechanism for the internal spider\r\n\u2502 \u251c\u2500\u2500 config.py # Manages configuration settings (tokens, paths)\r\n\u2502 \u251c\u2500\u2500 .env # Stores sensitive environment variables (e.g., Tushare token)\r\n\u2502 \u251c\u2500\u2500 indicators.py # Utility for calculating technical indicators\r\n\u2502 \u251c\u2500\u2500 logger.py # Logging configuration and utilities\r\n\u2502 \u251c\u2500\u2500 cache.py # Manages local data caching mechanisms\r\n\u2502 \u251c\u2500\u2500 utils.py # General-purpose utility functions\r\n\u2502 \u2514\u2500\u2500 configs/\r\n\u2502 \u251c\u2500\u2500 mapping.yaml # Mapping for Data & configs\r\n\u2502 \u2514\u2500\u2500 standard.yaml # Yquoter's data standard\r\n\u2502\r\n\u251c\u2500\u2500 examples/\r\n\u2502 \u2514\u2500\u2500 basic_usage.ipynb # Detailed usage examples in Jupyter Notebook\r\n\u2502\r\n\u251c\u2500\u2500 assets/ # Non-code assets (e.g., logos, screenshots for README)\r\n\u251c\u2500\u2500 temp/ # Temporary files for test (ignored by Git)\r\n\u251c\u2500\u2500 .cache/ # Cache files (ignored by Git)\r\n\u251c\u2500\u2500 pyproject.toml # Package configuration for distribution (PyPI)\r\n\u251c\u2500\u2500 requirements.txt # Declaration of project dependencies\r\n\u251c\u2500\u2500 LICENSE # Apache 2.0 Open Source License details\r\n\u251c\u2500\u2500 README.md # Project documentation (this file)\r\n\u251c\u2500\u2500 .gitignore # Files/directories to exclude from version control\r\n\u2514\u2500\u2500 .github/workflows/ci.yml # GitHub Actions workflow for Continuous Integration\r\n```\r\n---\r\n## \ud83d\ude80 Core API Reference\r\n\r\nThe **Yquoter** library exposes a set of standardized functions for data acquisition and technical analysis.\r\n\r\nFor detailed descriptions of all function parameters (e.g., market, klt, report_type), please refer to the dedicated **[Parameters Reference](./PARAMETERS.md)**.\r\n\r\n> \ud83d\udcdd **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](https://github.com/waditu/tushare).\r\n\r\n**Returns**: `pandas.DataFrame`\r\n\r\n### Data Acquisition Functions\r\n\r\n| Function | Description | Primary Parameters | Returns |\r\n| ---------------------- | ------------------------------------------------------------ | ----------------------------------------- | ----------------------------- |\r\n| `get_stock_history` | Fetch historical **OHLCV** (K-line) data for a date range. | `market`, `code`, `start`, `end` | `DataFrame` (OHLCV) |\r\n| `get_stock_realtime` | Fetch the **latest trading snapshot** (real-time quotes). | `market`, `code` | `DataFrame` (Realtime Quotes) |\r\n| `get_stock_factors` | Fetch historical **valuation/market factors** (e.g., PE, PB). | `market`, `code`, `trade_day` | `DataFrame` (Factors) |\r\n| `get_stock_profile` | Fetch **basic profile information** (e.g., company name, listing date, industry). | `market`, `code` | `DataFrame` (Profile) |\r\n| `get_stock_financials` | Fetch **fundamental financial statements** (e.g., Income Statement, Balance Sheet). | `market`, `code`, `end_day`, `report_type` | `DataFrame` (Financials) |\r\n\r\n### Technical Analysis Functions\r\n\r\nThese functions primarily take an existing DataFrame (`df`) or data request parameters (`market`, `code`, `start`, `end`) and calculate indicators.\r\n\r\n| Function | Description | Primary Parameters | Returns |\r\n| ------------------ |----------------------------------------------------------------| ---------------------- |---------------------------------------|\r\n| `get_ma_n` | Calculate **N-period Moving Average** (MA). | `df`, `n` (default 5) | `DataFrame` (MA column) |\r\n| `get_boll_n` | Calculate **N-period Bollinger Bands** (BOLL). | `df`, `n` (default 20) | `DataFrame` (BOLL, Upper/Lower bands) |\r\n| `get_rsi_n` | Calculate **N-period Relative Strength Index** (RSI). | `df`, `n` (default 14) | `DataFrame` (RSI column) |\r\n| `get_rv_n` | Calculate **N-period Rolling Volatility** (RV). | `df`, `n` (default 5) | `DataFrame` (RV column) |\r\n| `get_max_drawdown` | Calculate **Maximum Drawdown** and **Recovery** over a period. | `df` | `Dict` (Max Drawdown) |\r\n| `get_vol_ratio` | Calculate **Volume Ratio** (Volume to its N-period average). | `df`, `n` (default 5) | `DataFrame` (Volume Ratio) |\r\n\r\n### Utility Functions\r\n\r\n| Function | Description | Primary Parameters |\r\n| ------------------------- | ------------------------------------------------------------ |--|\r\n| `init_cache_manager` | **Initialize the cache manager** with a maximum LRU entry count. | `max_entries` |\r\n| `register_source` | **Register** a new custom data **source** plugin. | `source_name`, `func_type (e.g., \"realtime\")` |\r\n| `set_default_source` | **Set a new default data source.** | `name` |\r\n| `init_tushare` | **Initialize `TuShare` connection** with your API token and **register`TuShare` data interfaces**. | `token (or None)` |\r\n| `get_newest_df_path` | **Get the path** of the newest cached data file. | **None** |\r\n\r\n---\r\n\r\n## \ud83d\udee0\ufe0f Usage Example\r\n\r\n**[\ud83d\udcd8 View the Basic Usage Tutorial (Jupyter Notebook)](./examples/basic_usage.ipynb)**\r\n\r\n---\r\n\r\n## \ud83e\udd1d Contribution Guide\r\n\r\nWe welcome contributions of all forms, including bug reports, documentation improvements, feature requests, and code contributions.\r\n\r\nBefore submitting a Pull Request, please ensure that you:\r\n\r\nAdhere to the project's **coding standards**.\r\n\r\nAdd **necessary test cases** to cover new or modified logic.\r\n\r\nUpdate **relevant documentation** (docstrings, README, or examples).\r\n\r\nFor major feature changes, please open an Issue first to discuss the idea with the community.\r\n\r\n---\r\n\r\n## \ud83d\udcdc License\r\nThis project is licensed under the **Apache License 2.0**. See the LICENSE file for more details.\r\n\r\n---\r\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A unified financial data interface and analysis toolkit for CN/HK/US markets.",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/Yodeesy/Yquoter#readme",
"Homepage": "https://github.com/Yodeesy/Yquoter",
"Issues": "https://github.com/Yodeesy/Yquoter/issues",
"Source": "https://github.com/Yodeesy/Yquoter"
},
"split_keywords": [
"finance",
" stock",
" tushare",
" quant",
" data",
" crawler"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "60be0469ae1f4033e69da046b4110afa771ac291317fcc1ba613123e4a56a9e9",
"md5": "94857659bc63636771f4315c9dfdadfb",
"sha256": "bdb664163ccad716754e088433d0e1d572ccc68a8b7eb47353729fba3e8505be"
},
"downloads": -1,
"filename": "yquoter-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94857659bc63636771f4315c9dfdadfb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 41796,
"upload_time": "2025-10-11T11:29:00",
"upload_time_iso_8601": "2025-10-11T11:29:00.826071Z",
"url": "https://files.pythonhosted.org/packages/60/be/0469ae1f4033e69da046b4110afa771ac291317fcc1ba613123e4a56a9e9/yquoter-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7acb571e3916614a904924abe72c60f49228b46a4fa3bd091c28c334eb111e5b",
"md5": "c94463e671155e0e4bb533ea648efe77",
"sha256": "b8dcf4839a9a6ff002896abd2e069dedf7dd95730b3ce2cb341bc8ddc5bcafb3"
},
"downloads": -1,
"filename": "yquoter-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "c94463e671155e0e4bb533ea648efe77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 152702,
"upload_time": "2025-10-11T11:29:02",
"upload_time_iso_8601": "2025-10-11T11:29:02.375667Z",
"url": "https://files.pythonhosted.org/packages/7a/cb/571e3916614a904924abe72c60f49228b46a4fa3bd091c28c334eb111e5b/yquoter-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 11:29:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Yodeesy",
"github_project": "Yquoter#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "tushare",
"specs": [
[
">=",
"1.2.89"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.5.3"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"~=",
"6.0.2"
]
]
},
{
"name": "dotenv",
"specs": [
[
"~=",
"0.9.9"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"~=",
"1.1.1"
]
]
}
],
"lcname": "yquoter"
}
JSON
