# Quantdle Python Client
[](https://github.com/quantdle/quantdle-python/actions/workflows/test.yml)
[](https://codecov.io/gh/quantdle/quantdle-python)
[](https://badge.fury.io/py/quantdle)
[](https://pypi.org/project/quantdle/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/psf/black)
A user-friendly Python client for downloading financial market data from [Quantdle](https://quantdle.com). This client simplifies the process of accessing historical market data by handling all the complexity of data downloading, extraction, and processing.
## Features
- **Simple Data Access**: Download historical market data with just a few lines of code
- **High Performance**: Parallel downloads for faster data retrieval
- **Multiple Formats**: Support for both pandas and polars DataFrames
- **Smart Chunking**: Automatically handles large date ranges to avoid timeouts
- **Robust Error Handling**: Graceful handling of network issues and data errors
- **Zero Configuration**: Works out of the box with minimal setup
## Installation
Install the package using pip:
```bash
pip install quantdle
```
For polars support, install with the optional dependency:
```bash
pip install quantdle[polars]
```
## Quick Start
```python
import quantdle as qdl
# Initialize the client with your API credentials
client = qdl.Client(
api_key="your-api-key",
api_key_id="your-api-key-id"
)
# Download data for EURUSD
df = client.download_data(
symbol="EURUSD",
timeframe="H1",
start_date="2023-01-01",
end_date="2023-12-31"
)
print(df.head())
```
## Usage Examples
### Different Symbols and Timeframes
```python
import quantdle as qdl
# Initialize client once
client = qdl.Client(
api_key="your-api-key",
api_key_id="your-api-key-id"
)
# Download different symbols and timeframes
xau_data = client.download_data("XAUUSD", "D1", "2023-01-01", "2023-12-31")
eur_data = client.download_data("EURUSD", "H1", "2023-01-01", "2023-01-31")
```
### Using Polars DataFrames
```python
import quantdle as qdl
client = qdl.Client(
api_key="your-api-key",
api_key_id="your-api-key-id"
)
# Get data as a polars DataFrame
df = client.download_data(
symbol="XAUUSD",
timeframe="D1",
start_date="2023-01-01",
end_date="2023-12-31",
output_format="polars"
)
```
### Listing Available Symbols
```python
import quantdle as qdl
client = qdl.Client(
api_key="your-api-key",
api_key_id="your-api-key-id"
)
# Get all available symbols for your account
symbols = client.get_available_symbols()
print(f"Available symbols: {symbols}")
# Get information about a specific symbol
info = client.get_symbol_info("EURUSD")
print(f"EURUSD available from {info['available_from']} to {info['available_to']}")
```
### Downloading Large Date Ranges
The client automatically handles large date ranges by splitting them into smaller chunks:
```python
import quantdle as qdl
client = qdl.Client(
api_key="your-api-key",
api_key_id="your-api-key-id"
)
# Download 10 years of data - will be automatically chunked
df = client.download_data(
symbol="EURUSD",
timeframe="H1",
start_date="2014-01-01",
end_date="2023-12-31",
chunk_size_years=5 # Download in 5-year chunks
)
```
### Advanced Options
```python
import quantdle as qdl
client = qdl.Client(
api_key="your-api-key",
api_key_id="your-api-key-id"
)
# Customize download behavior
df = client.download_data(
symbol="EURUSD",
timeframe="M5",
start_date="2023-01-01",
end_date="2023-12-31",
max_workers=8, # Increase parallel downloads
show_progress=True, # Show progress bars
chunk_size_years=3 # Smaller chunks for more frequent updates
)
```
## Available Timeframes
- `M1` - 1 minute
- `M5` - 5 minutes
- `M15` - 15 minutes
- `M30` - 30 minutes
- `H1` - 1 hour
- `H4` - 4 hours
- `D1` - 1 day
## DataFrame Structure
The returned DataFrame contains the following columns:
| Column | Type | Description |
|--------|------|-------------|
| timestamp | datetime | Candle timestamp |
| open | float | Opening price |
| high | float | Highest price |
| low | float | Lowest price |
| close | float | Closing price |
| volume | int | Trading volume |
## Error Handling
The client includes robust error handling:
```python
import quantdle as qdl
client = qdl.Client(
api_key="your-api-key",
api_key_id="your-api-key-id"
)
try:
df = client.download_data(
symbol="INVALID",
timeframe="H1",
start_date="2023-01-01",
end_date="2023-12-31"
)
except Exception as e:
print(f"Error downloading data: {e}")
```
## Performance Tips
1. **Use parallel downloads**: The `max_workers` parameter controls the number of parallel downloads
2. **Choose appropriate chunk sizes**: Larger chunks mean fewer API calls but longer wait times
3. **Cache downloaded data**: Save DataFrames locally to avoid re-downloading
4. **Use polars for large datasets**: Polars DataFrames are more memory-efficient for large datasets
## API Rate Limits
Please be aware of Quantdle's API rate limits. The client automatically handles chunking to avoid timeouts, but you should still be mindful of making too many requests in a short period.
## Development & Testing
### Running Tests
The project has comprehensive test coverage with unit tests, integration tests, and end-to-end tests.
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run all tests
pytest
# Run tests with coverage
pytest --cov=quantdle
# Run only unit tests (fast)
pytest -m unit
# Run only integration tests (may be slow)
pytest -m integration
# Run tests in parallel for speed
pytest -n auto
```
### Code Quality
We maintain high code quality standards:
```bash
# Format code with black
black quantdle tests
# Lint with flake8
flake8 quantdle
# Type checking with mypy
mypy quantdle
```
### Test Coverage
Our comprehensive test suite includes:
- **Unit Tests**: Fast, isolated tests for individual functions and classes
- **Integration Tests**: Tests that verify modules work together correctly
- **Mock Testing**: Extensive use of mocks to test API interactions without real API calls
- **Performance Tests**: Tests for large dataset handling and memory efficiency
- **Error Handling Tests**: Comprehensive error condition testing
Current test coverage is maintained above 85% with detailed reporting available in CI/CD.
### Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes and add tests
4. Run the test suite (`pytest`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## Requirements
- Python 3.9 or higher
- pandas >= 1.3.0
- requests >= 2.25.0
- tqdm >= 4.60.0
- polars >= 0.16.0 (optional)
## License
This project is licensed under the Apache License 2.0. See the LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
For issues with the client, please open an issue on [GitHub](https://github.com/quantdle/quantdle-python/issues).
For questions about Quantdle's data or API access, please contact [Quantdle support](https://docs.quantdle.com).
Raw data
{
"_id": null,
"home_page": "https://quantdle.com/",
"name": "quantdle",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "quantdle, financial-data, market-data, trading, forex, cryptocurrency",
"author": "Quantdle",
"author_email": "support@quantdle.com",
"download_url": "https://files.pythonhosted.org/packages/86/93/2301f1e6e8df6c193e35a69e6d626bd4eecc7a5296f4afc7fa56bc83d008/quantdle-1.0.0.tar.gz",
"platform": null,
"description": "# Quantdle Python Client\n\n[](https://github.com/quantdle/quantdle-python/actions/workflows/test.yml)\n[](https://codecov.io/gh/quantdle/quantdle-python)\n[](https://badge.fury.io/py/quantdle)\n[](https://pypi.org/project/quantdle/)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://github.com/psf/black)\n\nA user-friendly Python client for downloading financial market data from [Quantdle](https://quantdle.com). This client simplifies the process of accessing historical market data by handling all the complexity of data downloading, extraction, and processing.\n\n## Features\n\n- **Simple Data Access**: Download historical market data with just a few lines of code\n- **High Performance**: Parallel downloads for faster data retrieval\n- **Multiple Formats**: Support for both pandas and polars DataFrames\n- **Smart Chunking**: Automatically handles large date ranges to avoid timeouts\n- **Robust Error Handling**: Graceful handling of network issues and data errors\n- **Zero Configuration**: Works out of the box with minimal setup\n\n## Installation\n\nInstall the package using pip:\n\n```bash\npip install quantdle\n```\n\nFor polars support, install with the optional dependency:\n\n```bash\npip install quantdle[polars]\n```\n\n## Quick Start\n\n```python\nimport quantdle as qdl\n\n# Initialize the client with your API credentials\nclient = qdl.Client(\n api_key=\"your-api-key\",\n api_key_id=\"your-api-key-id\"\n)\n\n# Download data for EURUSD\ndf = client.download_data(\n symbol=\"EURUSD\",\n timeframe=\"H1\",\n start_date=\"2023-01-01\",\n end_date=\"2023-12-31\"\n)\n\nprint(df.head())\n```\n\n## Usage Examples\n\n### Different Symbols and Timeframes\n\n```python\nimport quantdle as qdl\n\n# Initialize client once\nclient = qdl.Client(\n api_key=\"your-api-key\",\n api_key_id=\"your-api-key-id\"\n)\n\n# Download different symbols and timeframes\nxau_data = client.download_data(\"XAUUSD\", \"D1\", \"2023-01-01\", \"2023-12-31\")\neur_data = client.download_data(\"EURUSD\", \"H1\", \"2023-01-01\", \"2023-01-31\")\n```\n\n### Using Polars DataFrames\n\n```python\nimport quantdle as qdl\n\nclient = qdl.Client(\n api_key=\"your-api-key\",\n api_key_id=\"your-api-key-id\"\n)\n\n# Get data as a polars DataFrame\ndf = client.download_data(\n symbol=\"XAUUSD\",\n timeframe=\"D1\",\n start_date=\"2023-01-01\",\n end_date=\"2023-12-31\",\n output_format=\"polars\"\n)\n```\n\n### Listing Available Symbols\n\n```python\nimport quantdle as qdl\n\nclient = qdl.Client(\n api_key=\"your-api-key\",\n api_key_id=\"your-api-key-id\"\n)\n\n# Get all available symbols for your account\nsymbols = client.get_available_symbols()\nprint(f\"Available symbols: {symbols}\")\n\n# Get information about a specific symbol\ninfo = client.get_symbol_info(\"EURUSD\")\nprint(f\"EURUSD available from {info['available_from']} to {info['available_to']}\")\n```\n\n### Downloading Large Date Ranges\n\nThe client automatically handles large date ranges by splitting them into smaller chunks:\n\n```python\nimport quantdle as qdl\n\nclient = qdl.Client(\n api_key=\"your-api-key\",\n api_key_id=\"your-api-key-id\"\n)\n\n# Download 10 years of data - will be automatically chunked\ndf = client.download_data(\n symbol=\"EURUSD\",\n timeframe=\"H1\",\n start_date=\"2014-01-01\",\n end_date=\"2023-12-31\",\n chunk_size_years=5 # Download in 5-year chunks\n)\n```\n\n### Advanced Options\n\n```python\nimport quantdle as qdl\n\nclient = qdl.Client(\n api_key=\"your-api-key\",\n api_key_id=\"your-api-key-id\"\n)\n\n# Customize download behavior\ndf = client.download_data(\n symbol=\"EURUSD\",\n timeframe=\"M5\",\n start_date=\"2023-01-01\",\n end_date=\"2023-12-31\",\n max_workers=8, # Increase parallel downloads\n show_progress=True, # Show progress bars\n chunk_size_years=3 # Smaller chunks for more frequent updates\n)\n```\n\n## Available Timeframes\n\n- `M1` - 1 minute\n- `M5` - 5 minutes\n- `M15` - 15 minutes\n- `M30` - 30 minutes\n- `H1` - 1 hour\n- `H4` - 4 hours\n- `D1` - 1 day\n\n## DataFrame Structure\n\nThe returned DataFrame contains the following columns:\n\n| Column | Type | Description |\n|--------|------|-------------|\n| timestamp | datetime | Candle timestamp |\n| open | float | Opening price |\n| high | float | Highest price |\n| low | float | Lowest price |\n| close | float | Closing price |\n| volume | int | Trading volume |\n\n## Error Handling\n\nThe client includes robust error handling:\n\n```python\nimport quantdle as qdl\n\nclient = qdl.Client(\n api_key=\"your-api-key\",\n api_key_id=\"your-api-key-id\"\n)\n\ntry:\n df = client.download_data(\n symbol=\"INVALID\",\n timeframe=\"H1\",\n start_date=\"2023-01-01\",\n end_date=\"2023-12-31\"\n )\nexcept Exception as e:\n print(f\"Error downloading data: {e}\")\n```\n\n## Performance Tips\n\n1. **Use parallel downloads**: The `max_workers` parameter controls the number of parallel downloads\n2. **Choose appropriate chunk sizes**: Larger chunks mean fewer API calls but longer wait times\n3. **Cache downloaded data**: Save DataFrames locally to avoid re-downloading\n4. **Use polars for large datasets**: Polars DataFrames are more memory-efficient for large datasets\n\n## API Rate Limits\n\nPlease be aware of Quantdle's API rate limits. The client automatically handles chunking to avoid timeouts, but you should still be mindful of making too many requests in a short period.\n\n## Development & Testing\n\n### Running Tests\n\nThe project has comprehensive test coverage with unit tests, integration tests, and end-to-end tests.\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run all tests\npytest\n\n# Run tests with coverage\npytest --cov=quantdle\n\n# Run only unit tests (fast)\npytest -m unit\n\n# Run only integration tests (may be slow)\npytest -m integration\n\n# Run tests in parallel for speed\npytest -n auto\n```\n\n### Code Quality\n\nWe maintain high code quality standards:\n\n```bash\n# Format code with black\nblack quantdle tests\n\n# Lint with flake8\nflake8 quantdle\n\n# Type checking with mypy\nmypy quantdle\n```\n\n### Test Coverage\n\nOur comprehensive test suite includes:\n\n- **Unit Tests**: Fast, isolated tests for individual functions and classes\n- **Integration Tests**: Tests that verify modules work together correctly\n- **Mock Testing**: Extensive use of mocks to test API interactions without real API calls\n- **Performance Tests**: Tests for large dataset handling and memory efficiency\n- **Error Handling Tests**: Comprehensive error condition testing\n\nCurrent test coverage is maintained above 85% with detailed reporting available in CI/CD.\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes and add tests\n4. Run the test suite (`pytest`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## Requirements\n\n- Python 3.9 or higher\n- pandas >= 1.3.0\n- requests >= 2.25.0\n- tqdm >= 4.60.0\n- polars >= 0.16.0 (optional)\n\n## License\n\nThis project is licensed under the Apache License 2.0. See the LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor issues with the client, please open an issue on [GitHub](https://github.com/quantdle/quantdle-python/issues).\n\nFor questions about Quantdle's data or API access, please contact [Quantdle support](https://docs.quantdle.com).\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Official Python client for downloading clean market data from Quantdle",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/quantdle/quantdle-python/issues",
"Documentation": "https://github.com/quantdle/quantdle-python#readme",
"Homepage": "https://quantdle.com/",
"Repository": "https://github.com/quantdle/quantdle-python"
},
"split_keywords": [
"quantdle",
" financial-data",
" market-data",
" trading",
" forex",
" cryptocurrency"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "345051ae4149b96c99ac9473e6a64e9afe6fd356a706f45bc2ef887851e2367f",
"md5": "617e11dfa368362c5849c414b75927ff",
"sha256": "a3097322c592b2ab46e95350775d169c4b7e202df425d6b92939c3888ee0faff"
},
"downloads": -1,
"filename": "quantdle-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "617e11dfa368362c5849c414b75927ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 15142,
"upload_time": "2025-08-02T10:53:36",
"upload_time_iso_8601": "2025-08-02T10:53:36.463486Z",
"url": "https://files.pythonhosted.org/packages/34/50/51ae4149b96c99ac9473e6a64e9afe6fd356a706f45bc2ef887851e2367f/quantdle-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "86932301f1e6e8df6c193e35a69e6d626bd4eecc7a5296f4afc7fa56bc83d008",
"md5": "4e7910e5b026e44f677584dac751db5c",
"sha256": "c5dad5f1db3356b62897c8a231fb3d01fb21570322388987b94426d2dd57a72e"
},
"downloads": -1,
"filename": "quantdle-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "4e7910e5b026e44f677584dac751db5c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 14658,
"upload_time": "2025-08-02T10:53:37",
"upload_time_iso_8601": "2025-08-02T10:53:37.793044Z",
"url": "https://files.pythonhosted.org/packages/86/93/2301f1e6e8df6c193e35a69e6d626bd4eecc7a5296f4afc7fa56bc83d008/quantdle-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 10:53:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantdle",
"github_project": "quantdle-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quantdle"
}
JSON
