# Poligon Wrapper
## Overview
**Poligon Wrapper** is a Python package designed to interact with Poligon.io API to fetch aggregate bar data for single or multiple stocks over customizable timeframes. It leverages both synchronous and asynchronous API calls for efficient data retrieval. The package is built with logging, progress tracking, and robust error handling to ensure seamless performance.
## Features
- Retrieve **aggregate stock bar data** (open, high, low, close, volume, etc.) for single or multiple stocks.
- Supports multiple timeframes and custom parameters.
- Synchronous and asynchronous API calls for optimal performance.
- Handles large date ranges by splitting them into monthly intervals.
- Built-in logging and progress bar support using `tqdm`.
---
## Installation
To install the package, use the following:
```bash
pip install poligon-wrapper
```
---
## Usage
### 1. Setting the API Key
When you import the package for the first time, you will be asked to provide an API key. The key will be stored in a `.env` file in the same directory as the source code.
You can use the following features to manage your API key:
- **Change the API key**: Update the stored key using a dedicated function.
- **Delete the API key**: Remove the key from the `.env` file.
#### Example:
```python
import poligon_wrapper
# change api_key
poligon_wrapper.change_api_key()
# delete api_key
poligon_wrapper.delete_api_key()
```
---
### 2. Single Stock Data Retrieval
Use the `SingleStockBarRetriever` class to retrieve aggregate bar data for a single stock.
#### Example:
```python
from poligon_wrapper.dataloader_stocks import SingleStockBarRetriever
# Parameters
symbol = "AAPL"
start_date = "2023-02-01"
end_date = "2023-03-01"
# Initialize retriever
retriever = SingleStockBarRetriever(symbol, start_date, end_date)
# Fetch data
data = retriever.get_data()
print(data.head())
```
#### Output:
| time | open | high | low | close | volume | ticker |
|---------------------|--------|--------|--------|--------|--------|--------|
| 2023-02-01 09:30:00 | 145.60 | 146.00 | 145.20 | 145.85 | 150000 | AAPL |
| 2023-02-01 09:31:00 | 145.85 | 146.10 | 145.60 | 146.00 | 160000 | AAPL |
| ... | ... | ... | ... | ... | ... | ... |
---
### 3. Multiple Stock Data Retrieval
Use the `MultipleStockBarRetriever` class to retrieve aggregate bar data for multiple stocks over a given date range.
#### Example:
```python
from poligon_wrapper.dataloader_stocks import MultipleStockBarRetriever
# Parameters
tickers = ["AAPL", "TSLA"]
start_date = "2023-02-01"
end_date = "2023-03-01"
# Initialize retriever
retriever = MultipleStockBarRetriever(tickers, start_date, end_date)
# Fetch data
data = retriever.get_data()
print(data.head())
```
#### Output:
| time | open | high | low | close | volume | ticker |
|---------------------|--------|--------|--------|--------|--------|--------|
| 2023-02-01 09:30:00 | 145.60 | 146.00 | 145.20 | 145.85 | 150000 | AAPL |
| 2023-02-01 09:31:00 | 145.85 | 146.10 | 145.60 | 146.00 | 160000 | AAPL |
| 2023-02-01 09:30:00 | 195.20 | 196.00 | 194.50 | 195.90 | 200000 | TSLA |
| ... | ... | ... | ... | ... | ... | ... |
---
### 4. Work in Progress: Ticker Retrieval
The `TickerRetriever` class is under development and will allow users to retrieve all available tickers from the Polygon API.
#### Features:
- Retrieve all active tickers.
- Handle large datasets using **pagination**.
- Return data in a structured `pandas.DataFrame` format.
#### Example (Upcoming):
```python
from poligon_wrapper.dataloader_stocks import TickerRetriever
# Initialize retriever
ticker_retriever = TickerRetriever()
# Fetch all tickers
tickers_df = ticker_retriever.fetch_tickers()
print(tickers_df.head())
```
This module will make it easier to work with all available tickers when analyzing or retrieving stock data.
---
## Customizing Parameters
Both `SingleStockBarRetriever` and `MultipleStockBarRetriever` allow you to customize API parameters using the `custom_params` argument:
```python
custom_params = {
"multiplier": 1, # Time multiplier for aggregation
"timespan": "minute", # Timespan (e.g., minute, day)
"limit": 1000, # Limit on the number of results
"api_key": "YOUR_API_KEY" # Your API key
}
retriever = SingleStockBarRetriever("AAPL", "2023-02-01", "2023-03-01", custom_params=custom_params)
data = retriever.get_data()
print(data)
```
---
## Dependencies
This package relies on the following libraries:
- `requests` for synchronous HTTP requests
- `aiohttp` for asynchronous HTTP requests
- `pandas` for data manipulation
- `tqdm` for progress bars
- `nest_asyncio` to handle nested event loops
- `logging` for logging errors and progress
To install all dependencies, run:
```bash
pip install -r requirements.txt
```
---
## Logging
By default, logging is set to `ERROR` level. You can configure the logging level as needed by modifying the `setup_logging` function in `logging_config.py`.
Example:
```python
from poligon_wrapper.logging_config import setup_logging
setup_logging(level=logging.DEBUG)
```
---
## Contributing
Contributions are welcome! To contribute:
1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Submit a pull request with a clear description of the changes.
---
## License
This package is licensed under the MIT License.
---
## Author
Filippo Caretti
filippo.caretti@icloud.com
fcaretti01
Raw data
{
"_id": null,
"home_page": null,
"name": "poligon-wrapper",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "fcaretti01 <filippo.caretti@icloud.com>",
"keywords": "api, asyncio, fast, poligon, poligon.io, stocks, wrapper",
"author": null,
"author_email": "fcaretti01 <filippo.caretti@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/fd/d4/836f3def8b09a7bc99ff7f79e331e55700c0d1c1b5551fe23df470c7b673/poligon_wrapper-0.1.1.tar.gz",
"platform": null,
"description": "# Poligon Wrapper\n\n## Overview\n\n**Poligon Wrapper** is a Python package designed to interact with Poligon.io API to fetch aggregate bar data for single or multiple stocks over customizable timeframes. It leverages both synchronous and asynchronous API calls for efficient data retrieval. The package is built with logging, progress tracking, and robust error handling to ensure seamless performance.\n\n## Features\n- Retrieve **aggregate stock bar data** (open, high, low, close, volume, etc.) for single or multiple stocks.\n- Supports multiple timeframes and custom parameters.\n- Synchronous and asynchronous API calls for optimal performance.\n- Handles large date ranges by splitting them into monthly intervals.\n- Built-in logging and progress bar support using `tqdm`.\n\n---\n\n## Installation\nTo install the package, use the following:\n\n```bash\npip install poligon-wrapper\n```\n\n---\n\n## Usage\n\n### 1. Setting the API Key\nWhen you import the package for the first time, you will be asked to provide an API key. The key will be stored in a `.env` file in the same directory as the source code.\n\nYou can use the following features to manage your API key:\n- **Change the API key**: Update the stored key using a dedicated function.\n- **Delete the API key**: Remove the key from the `.env` file.\n\n#### Example:\n```python\nimport poligon_wrapper\n\n# change api_key\npoligon_wrapper.change_api_key()\n\n# delete api_key\npoligon_wrapper.delete_api_key()\n```\n\n---\n\n### 2. Single Stock Data Retrieval\nUse the `SingleStockBarRetriever` class to retrieve aggregate bar data for a single stock.\n\n#### Example:\n```python\nfrom poligon_wrapper.dataloader_stocks import SingleStockBarRetriever\n\n# Parameters\nsymbol = \"AAPL\"\nstart_date = \"2023-02-01\"\nend_date = \"2023-03-01\"\n\n# Initialize retriever\nretriever = SingleStockBarRetriever(symbol, start_date, end_date)\n\n# Fetch data\ndata = retriever.get_data()\nprint(data.head())\n```\n\n#### Output:\n| time | open | high | low | close | volume | ticker |\n|---------------------|--------|--------|--------|--------|--------|--------|\n| 2023-02-01 09:30:00 | 145.60 | 146.00 | 145.20 | 145.85 | 150000 | AAPL |\n| 2023-02-01 09:31:00 | 145.85 | 146.10 | 145.60 | 146.00 | 160000 | AAPL |\n| ... | ... | ... | ... | ... | ... | ... |\n\n---\n\n### 3. Multiple Stock Data Retrieval\nUse the `MultipleStockBarRetriever` class to retrieve aggregate bar data for multiple stocks over a given date range.\n\n#### Example:\n```python\nfrom poligon_wrapper.dataloader_stocks import MultipleStockBarRetriever\n\n# Parameters\ntickers = [\"AAPL\", \"TSLA\"]\nstart_date = \"2023-02-01\"\nend_date = \"2023-03-01\"\n\n# Initialize retriever\nretriever = MultipleStockBarRetriever(tickers, start_date, end_date)\n\n# Fetch data\ndata = retriever.get_data()\nprint(data.head())\n```\n\n#### Output:\n| time | open | high | low | close | volume | ticker |\n|---------------------|--------|--------|--------|--------|--------|--------|\n| 2023-02-01 09:30:00 | 145.60 | 146.00 | 145.20 | 145.85 | 150000 | AAPL |\n| 2023-02-01 09:31:00 | 145.85 | 146.10 | 145.60 | 146.00 | 160000 | AAPL |\n| 2023-02-01 09:30:00 | 195.20 | 196.00 | 194.50 | 195.90 | 200000 | TSLA |\n| ... | ... | ... | ... | ... | ... | ... |\n\n\n---\n\n### 4. Work in Progress: Ticker Retrieval\nThe `TickerRetriever` class is under development and will allow users to retrieve all available tickers from the Polygon API.\n\n#### Features:\n- Retrieve all active tickers.\n- Handle large datasets using **pagination**.\n- Return data in a structured `pandas.DataFrame` format.\n\n#### Example (Upcoming):\n```python\nfrom poligon_wrapper.dataloader_stocks import TickerRetriever\n\n# Initialize retriever\nticker_retriever = TickerRetriever()\n\n# Fetch all tickers\ntickers_df = ticker_retriever.fetch_tickers()\nprint(tickers_df.head())\n```\n\nThis module will make it easier to work with all available tickers when analyzing or retrieving stock data.\n\n---\n\n## Customizing Parameters\nBoth `SingleStockBarRetriever` and `MultipleStockBarRetriever` allow you to customize API parameters using the `custom_params` argument:\n\n```python\ncustom_params = {\n \"multiplier\": 1, # Time multiplier for aggregation\n \"timespan\": \"minute\", # Timespan (e.g., minute, day)\n \"limit\": 1000, # Limit on the number of results\n \"api_key\": \"YOUR_API_KEY\" # Your API key\n}\n\nretriever = SingleStockBarRetriever(\"AAPL\", \"2023-02-01\", \"2023-03-01\", custom_params=custom_params)\ndata = retriever.get_data()\nprint(data)\n```\n\n---\n\n## Dependencies\nThis package relies on the following libraries:\n- `requests` for synchronous HTTP requests\n- `aiohttp` for asynchronous HTTP requests\n- `pandas` for data manipulation\n- `tqdm` for progress bars\n- `nest_asyncio` to handle nested event loops\n- `logging` for logging errors and progress\n\nTo install all dependencies, run:\n```bash\npip install -r requirements.txt\n```\n\n---\n\n## Logging\nBy default, logging is set to `ERROR` level. You can configure the logging level as needed by modifying the `setup_logging` function in `logging_config.py`.\n\nExample:\n```python\nfrom poligon_wrapper.logging_config import setup_logging\nsetup_logging(level=logging.DEBUG)\n```\n\n---\n\n## Contributing\nContributions are welcome! To contribute:\n1. Fork the repository.\n2. Create a new branch for your feature or bug fix.\n3. Submit a pull request with a clear description of the changes.\n\n---\n\n## License\nThis package is licensed under the MIT License.\n\n---\n\n## Author\nFilippo Caretti \nfilippo.caretti@icloud.com \nfcaretti01\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Add your description here",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"api",
" asyncio",
" fast",
" poligon",
" poligon.io",
" stocks",
" wrapper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3708c5f4863fc46c67fff072214faeae2eae42b548aba2360245eb855a4bba01",
"md5": "d86af98f16c0b4956c3aaa4483bcccb6",
"sha256": "891a23c1622e51f03c086a1210caef0984f8190ebdadbea6bf297e422e8b3fdf"
},
"downloads": -1,
"filename": "poligon_wrapper-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d86af98f16c0b4956c3aaa4483bcccb6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 10680,
"upload_time": "2024-12-18T04:46:08",
"upload_time_iso_8601": "2024-12-18T04:46:08.102055Z",
"url": "https://files.pythonhosted.org/packages/37/08/c5f4863fc46c67fff072214faeae2eae42b548aba2360245eb855a4bba01/poligon_wrapper-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fdd4836f3def8b09a7bc99ff7f79e331e55700c0d1c1b5551fe23df470c7b673",
"md5": "111d1cee5a3c24fd4bc9d47bccfac113",
"sha256": "e3d9657683756e5445a275b765a7d1bec76acaaf671d189b9027be14cf1c65c8"
},
"downloads": -1,
"filename": "poligon_wrapper-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "111d1cee5a3c24fd4bc9d47bccfac113",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 65766,
"upload_time": "2024-12-18T04:46:10",
"upload_time_iso_8601": "2024-12-18T04:46:10.658609Z",
"url": "https://files.pythonhosted.org/packages/fd/d4/836f3def8b09a7bc99ff7f79e331e55700c0d1c1b5551fe23df470c7b673/poligon_wrapper-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 04:46:10",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "poligon-wrapper"
}
JSON