tickerapi 0.1.0__tar.gz

tickerapi-0.1.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: tickerapi
+Version: 0.1.0
+Summary: Python SDK for the TickerAPI financial data API
+Project-URL: Homepage, https://tickerapi.ai
+Project-URL: Documentation, https://tickerapi.ai/docs
+Project-URL: Repository, https://github.com/tickerapi/tickerapi-python
+Project-URL: Issues, https://github.com/tickerapi/tickerapi-python/issues
+Author-email: TickerAPI <support@tickerapi.ai>
+License-Expression: MIT
+Keywords: api,crypto,etf,finance,market-data,stocks,ticker
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# TickerAPI Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/tickerapi.svg)](https://pypi.org/project/tickerapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tickerapi.svg)](https://pypi.org/project/tickerapi/)
+
+The official Python SDK for [TickerAPI](https://tickerapi.ai) -- financial data and market intelligence API.
+
+- Sync and async clients
+- Full type hints for IDE autocompletion
+- Typed exceptions for every error class
+- Rate limit information on every response
+
+**Full API documentation:** [https://tickerapi.ai/docs](https://tickerapi.ai/docs)
+
+## Installation
+
+```bash
+pip install tickerapi
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+from tickerapi import TickerAPI
+
+client = TickerAPI("your_api_key")
+
+# Get a ticker summary
+result = client.summary("AAPL")
+print(result["data"])
+
+# Rate limit info is included on every response
+print(result["rate_limits"]["requests_remaining"])
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from tickerapi import AsyncTickerAPI
+
+async def main():
+    async with AsyncTickerAPI("your_api_key") as client:
+        result = await client.summary("AAPL")
+        print(result["data"])
+
+asyncio.run(main())
+```
+
+## Endpoints
+
+### Summary
+
+Get a detailed summary for a single ticker.
+
+```python
+result = client.summary("AAPL")
+result = client.summary("AAPL", timeframe="weekly")
+result = client.summary("AAPL", date="2025-01-15")
+```
+
+### Compare
+
+Compare multiple tickers side-by-side.
+
+```python
+result = client.compare(["AAPL", "MSFT", "GOOGL"])
+result = client.compare("AAPL,MSFT,GOOGL", timeframe="weekly")
+```
+
+### Watchlist
+
+Post a list of tickers to get watchlist data.
+
+```python
+result = client.watchlist(["AAPL", "MSFT", "TSLA"])
+result = client.watchlist(["AAPL", "MSFT"], timeframe="weekly")
+```
+
+### Assets
+
+List all available assets.
+
+```python
+result = client.assets()
+```
+
+### Scan: Oversold
+
+Find oversold assets across markets.
+
+```python
+result = client.scan_oversold()
+result = client.scan_oversold(
+    asset_class="stock",
+    min_severity="deep_oversold",
+    sort_by="severity",
+    limit=10,
+)
+```
+
+### Scan: Breakouts
+
+Detect breakout patterns.
+
+```python
+result = client.scan_breakouts(direction="bullish", asset_class="stock", limit=20)
+```
+
+### Scan: Unusual Volume
+
+Spot unusual volume activity.
+
+```python
+result = client.scan_unusual_volume(min_ratio_band="high", limit=10)
+```
+
+### Scan: Valuation
+
+Find valuation outliers.
+
+```python
+result = client.scan_valuation(direction="undervalued", sort_by="pe_vs_history")
+```
+
+### Scan: Insider Activity
+
+Track notable insider trading activity.
+
+```python
+result = client.scan_insider_activity(direction="buying", sort_by="net_ratio", limit=15)
+```
+
+## Error Handling
+
+The SDK raises typed exceptions for all API errors:
+
+```python
+from tickerapi import TickerAPI, TickerAPIError, RateLimitError, NotFoundError
+
+client = TickerAPI("your_api_key")
+
+try:
+    result = client.summary("INVALID_TICKER")
+except NotFoundError as e:
+    print(f"Ticker not found: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited! Resets at: {e.reset}")
+    print(f"Upgrade: {e.upgrade_url}")
+except TickerAPIError as e:
+    print(f"API error [{e.status_code}]: {e.message}")
+```
+
+### Exception Hierarchy
+
+| Exception | Status Code | Description |
+|---|---|---|
+| `TickerAPIError` | any | Base exception for all API errors |
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `ForbiddenError` | 403 | Endpoint restricted to higher tier |
+| `NotFoundError` | 404 | Asset not found |
+| `RateLimitError` | 429 | Rate limit exceeded |
+| `DataUnavailableError` | 503 | Data temporarily unavailable |
+
+All exceptions include `status_code`, `error_type`, `message`, and optionally `upgrade_url` and `reset` attributes.
+
+## Rate Limits
+
+Every response includes a `rate_limits` dict parsed from the API headers:
+
+```python
+result = client.summary("AAPL")
+limits = result["rate_limits"]
+
+print(limits["request_limit"])           # Total request limit
+print(limits["requests_remaining"])      # Requests remaining
+print(limits["request_reset"])           # Reset timestamp
+print(limits["hourly_request_limit"])    # Hourly limit
+print(limits["hourly_requests_remaining"])  # Hourly remaining
+```
+
+## Links
+
+- [TickerAPI Website](https://tickerapi.ai)
+- [API Documentation](https://tickerapi.ai/docs)
+- [PyPI Package](https://pypi.org/project/tickerapi/)

tickerapi-0.1.0/README.md

@@ -0,0 +1,188 @@
+# TickerAPI Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/tickerapi.svg)](https://pypi.org/project/tickerapi/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tickerapi.svg)](https://pypi.org/project/tickerapi/)
+
+The official Python SDK for [TickerAPI](https://tickerapi.ai) -- financial data and market intelligence API.
+
+- Sync and async clients
+- Full type hints for IDE autocompletion
+- Typed exceptions for every error class
+- Rate limit information on every response
+
+**Full API documentation:** [https://tickerapi.ai/docs](https://tickerapi.ai/docs)
+
+## Installation
+
+```bash
+pip install tickerapi
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+from tickerapi import TickerAPI
+
+client = TickerAPI("your_api_key")
+
+# Get a ticker summary
+result = client.summary("AAPL")
+print(result["data"])
+
+# Rate limit info is included on every response
+print(result["rate_limits"]["requests_remaining"])
+```
+
+### Asynchronous
+
+```python
+import asyncio
+from tickerapi import AsyncTickerAPI
+
+async def main():
+    async with AsyncTickerAPI("your_api_key") as client:
+        result = await client.summary("AAPL")
+        print(result["data"])
+
+asyncio.run(main())
+```
+
+## Endpoints
+
+### Summary
+
+Get a detailed summary for a single ticker.
+
+```python
+result = client.summary("AAPL")
+result = client.summary("AAPL", timeframe="weekly")
+result = client.summary("AAPL", date="2025-01-15")
+```
+
+### Compare
+
+Compare multiple tickers side-by-side.
+
+```python
+result = client.compare(["AAPL", "MSFT", "GOOGL"])
+result = client.compare("AAPL,MSFT,GOOGL", timeframe="weekly")
+```
+
+### Watchlist
+
+Post a list of tickers to get watchlist data.
+
+```python
+result = client.watchlist(["AAPL", "MSFT", "TSLA"])
+result = client.watchlist(["AAPL", "MSFT"], timeframe="weekly")
+```
+
+### Assets
+
+List all available assets.
+
+```python
+result = client.assets()
+```
+
+### Scan: Oversold
+
+Find oversold assets across markets.
+
+```python
+result = client.scan_oversold()
+result = client.scan_oversold(
+    asset_class="stock",
+    min_severity="deep_oversold",
+    sort_by="severity",
+    limit=10,
+)
+```
+
+### Scan: Breakouts
+
+Detect breakout patterns.
+
+```python
+result = client.scan_breakouts(direction="bullish", asset_class="stock", limit=20)
+```
+
+### Scan: Unusual Volume
+
+Spot unusual volume activity.
+
+```python
+result = client.scan_unusual_volume(min_ratio_band="high", limit=10)
+```
+
+### Scan: Valuation
+
+Find valuation outliers.
+
+```python
+result = client.scan_valuation(direction="undervalued", sort_by="pe_vs_history")
+```
+
+### Scan: Insider Activity
+
+Track notable insider trading activity.
+
+```python
+result = client.scan_insider_activity(direction="buying", sort_by="net_ratio", limit=15)
+```
+
+## Error Handling
+
+The SDK raises typed exceptions for all API errors:
+
+```python
+from tickerapi import TickerAPI, TickerAPIError, RateLimitError, NotFoundError
+
+client = TickerAPI("your_api_key")
+
+try:
+    result = client.summary("INVALID_TICKER")
+except NotFoundError as e:
+    print(f"Ticker not found: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limited! Resets at: {e.reset}")
+    print(f"Upgrade: {e.upgrade_url}")
+except TickerAPIError as e:
+    print(f"API error [{e.status_code}]: {e.message}")
+```
+
+### Exception Hierarchy
+
+| Exception | Status Code | Description |
+|---|---|---|
+| `TickerAPIError` | any | Base exception for all API errors |
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `ForbiddenError` | 403 | Endpoint restricted to higher tier |
+| `NotFoundError` | 404 | Asset not found |
+| `RateLimitError` | 429 | Rate limit exceeded |
+| `DataUnavailableError` | 503 | Data temporarily unavailable |
+
+All exceptions include `status_code`, `error_type`, `message`, and optionally `upgrade_url` and `reset` attributes.
+
+## Rate Limits
+
+Every response includes a `rate_limits` dict parsed from the API headers:
+
+```python
+result = client.summary("AAPL")
+limits = result["rate_limits"]
+
+print(limits["request_limit"])           # Total request limit
+print(limits["requests_remaining"])      # Requests remaining
+print(limits["request_reset"])           # Reset timestamp
+print(limits["hourly_request_limit"])    # Hourly limit
+print(limits["hourly_requests_remaining"])  # Hourly remaining
+```
+
+## Links
+
+- [TickerAPI Website](https://tickerapi.ai)
+- [API Documentation](https://tickerapi.ai/docs)
+- [PyPI Package](https://pypi.org/project/tickerapi/)

tickerapi-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tickerapi"
+version = "0.1.0"
+description = "Python SDK for the TickerAPI financial data API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "TickerAPI", email = "support@tickerapi.ai" },
+]
+keywords = ["finance", "stocks", "crypto", "etf", "market-data", "api", "ticker"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.urls]
+Homepage = "https://tickerapi.ai"
+Documentation = "https://tickerapi.ai/docs"
+Repository = "https://github.com/tickerapi/tickerapi-python"
+Issues = "https://github.com/tickerapi/tickerapi-python/issues"

tickerapi-0.1.0/tickerapi/__init__.py

@@ -0,0 +1,40 @@
+"""TickerAPI Python SDK - Financial data at your fingertips.
+
+Usage::
+
+    from tickerapi import TickerAPI
+
+    client = TickerAPI("your_api_key")
+    result = client.summary("AAPL")
+
+For async usage::
+
+    from tickerapi import AsyncTickerAPI
+
+    async with AsyncTickerAPI("your_api_key") as client:
+        result = await client.summary("AAPL")
+"""
+
+from .async_client import AsyncTickerAPI
+from .client import TickerAPI
+from .exceptions import (
+    AuthenticationError,
+    DataUnavailableError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TickerAPIError,
+)
+
+__all__ = [
+    "TickerAPI",
+    "AsyncTickerAPI",
+    "TickerAPIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "DataUnavailableError",
+]
+
+__version__ = "0.1.0"