ticker-classifier 0.1.0__tar.gz

ticker_classifier-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stephan Akkerman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ticker_classifier-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: ticker_classifier
+Version: 0.1.0
+Summary: A robust stock, crypto, and forex classifier with async support.
+Author-email: Stephan Akkerman <stephan@akkerman.ai>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: aiohttp
+Dynamic: license-file
+
+# ticker-classifier
+
+<!-- Add a banner here like: https://github.com/StephanAkkerman/fintwit-bot/blob/main/img/logo/fintwit-banner.png -->
+
+---
+<!-- Adjust the link of the first and second badges to your own repo -->
+<p align="center">
+  <img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/StephanAkkerman/ticker-classifier/pyversions.yml?label=python%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13&logo=python&style=flat-square">
+  <img src="https://img.shields.io/github/license/StephanAkkerman/ticker-classifier.svg?color=brightgreen" alt="License">
+  <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black"></a>
+</p>
+
+## Introduction
+
+`ticker-classifier` is a small Python library for classifying ticker-like symbols (for example `AAPL`, `BTC`, `EUR`, `GOLD`) into a simple market/category representation.
+It uses Yahoo Finance for equities, CoinGecko for cryptocurrencies and a few heuristics for currencies/commodities. The output indicates the most likely category, a display name, market cap when available, and a `yahoo_lookup` value to fetch further data if desired.
+
+## Table of Contents 🗂
+
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API](#api)
+- [Development](#development)
+- [Release and Versioning](#release-and-versioning)
+- [Citation](#citation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Key Features 🔑
+
+- Classify symbols as `Equity`, `Crypto`, `Forex`, `Commodity`, `Index` or `Unknown`.
+- Uses multiple public APIs and simple heuristics to make robust decisions.
+- Provides both synchronous and asynchronous APIs.
+- Lightweight disk cache to avoid repeated lookups (`TickerCache`).
+
+## Installation ⚙️
+
+Install from pip using the provided `requirements.txt` or install the package directly from the repository for latest changes:
+
+```bash
+pip install -r requirements.txt
+```
+
+or
+
+```bash
+pip install git+https://github.com/StephanAkkerman/ticker-classifier.git
+```
+
+## Usage ⌨️
+
+Basic synchronous usage:
+
+```python
+from ticker_classifier.classifier import TickerClassifier
+
+classifier = TickerClassifier()
+symbols = ["AAPL", "BTC", "EUR", "GOLD", "UNKNOWN123"]
+results = classifier.classify(symbols)
+for r in results:
+    print(r)
+```
+
+Example asynchronous usage:
+
+```python
+import asyncio
+from ticker_classifier.classifier import TickerClassifier
+
+async def main():
+    classifier = TickerClassifier()
+    symbols = ["AAPL", "BTC", "ETH", "JPY"]
+    results = await classifier.classify_async(symbols)
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
+The output for each symbol is a dictionary like:
+
+```python
+{'category': 'EQUITY', 'ticker': 'AAPL', 'name': 'Apple Inc.', 'market_cap': 4029017227264, 'yahoo_lookup': 'AAPL', 'alternatives': ['crypto'], 'source': 'api'}
+{'category': 'crypto', 'ticker': 'BTC', 'name': 'Bitcoin', 'market_cap': 1736590593460.9607, 'yahoo_lookup': 'BTC-USD', 'alternatives': ['stock'], 'source': 'api'}
+{'category': 'crypto', 'ticker': 'ETH', 'name': 'Ethereum', 'market_cap': 338145915081.1455, 'yahoo_lookup': 'ETH-USD', 'alternatives': ['stock'], 'source': 'cache'}
+{'category': 'forex', 'ticker': 'JPY', 'name': 'JPY Currency', 'market_cap': None, 'yahoo_lookup': 'JPYUSD=X', 'alternatives': ['stock'], 'source': 'cache'}
+```
+
+Notes
+- The classifier caches positive classifications (non-`Unknown`) in an
+SQLite database (default `ticker_cache.db`) for `24` hours by default.
+- You can customize the cache filename and expiry by passing `db_name` and
+`hours_to_expire` to `TickerClassifier`.
+
+## API
+
+- `ticker_classifier.classifier.TickerClassifier`
+- `classify(symbols: List[str]) -> List[dict]` – synchronous classification.
+- `classify_async(symbols: List[str]) -> List[dict]` – async classification.
+- `ticker_classifier.apis.yahoo.YahooClient` – low-level Yahoo quote fetcher (sync + async helpers).
+- `ticker_classifier.apis.coingecko.CoinGeckoClient` – crypto lookup + market cap helpers (sync + async).
+- `ticker_classifier.db.cache.TickerCache` – tiny SQLite-backed cache used by `TickerClassifier`.
+
+## Development
+
+Run formatting and linting tools you prefer (project uses `black` code style).
+
+Run a quick smoke check by running the `classifier.py` module directly:
+
+```powershell
+& .venv\Scripts\python.exe ticker_classifier\classifier.py
+```
+
+If you add tests, run them with your chosen test runner (e.g. `pytest`).
+
+## Release and Versioning
+
+This package is published to PyPI through GitHub Actions:
+
+- Workflow: `.github/workflows/publish.yml`
+- Trigger: GitHub Release published
+- Publisher: `pypa/gh-action-pypi-publish` using trusted publishing (OIDC)
+
+Release flow:
+
+1. Update version in `pyproject.toml`.
+2. Update `ticker_classifier/__init__.py` `__version__` to match.
+3. Commit and push.
+4. Create a GitHub release with tag `vX.Y.Z` (or `X.Y.Z`).
+
+The publish workflow validates that the release tag version matches `pyproject.toml` before uploading to PyPI.
+
+## Citation ✍️
+If you use this project in your research, please cite as follows (adjust
+metadata accordingly):
+
+```bibtex
+@misc{ticker-classifier,
+author  = {Stephan Akkerman},
+title   = {ticker-classifier},
+year    = {2025},
+publisher = {GitHub},
+howpublished = {\url{https://github.com/StephanAkkerman/ticker-classifier}}
+}
+```
+
+## Contributing 🛠
+
+Contributions are welcome. Suggested workflow:
+
+1. Fork the repository and create a feature branch.
+2. Run tests and format your changes with `black`.
+3. Open a pull request with a clear description of the change.
+
+Please open issues for feature requests or bugs and include a small
+reproducible example when possible.
+
+![https://github.com/StephanAkkerman/ticker-classifier/graphs/contributors](https://contributors-img.firebaseapp.com/image?repo=StephanAkkerman/ticker-classifier)
+
+## License 📜
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

ticker_classifier-0.1.0/README.md

@@ -0,0 +1,163 @@
+# ticker-classifier
+
+<!-- Add a banner here like: https://github.com/StephanAkkerman/fintwit-bot/blob/main/img/logo/fintwit-banner.png -->
+
+---
+<!-- Adjust the link of the first and second badges to your own repo -->
+<p align="center">
+  <img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/StephanAkkerman/ticker-classifier/pyversions.yml?label=python%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13&logo=python&style=flat-square">
+  <img src="https://img.shields.io/github/license/StephanAkkerman/ticker-classifier.svg?color=brightgreen" alt="License">
+  <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black"></a>
+</p>
+
+## Introduction
+
+`ticker-classifier` is a small Python library for classifying ticker-like symbols (for example `AAPL`, `BTC`, `EUR`, `GOLD`) into a simple market/category representation.
+It uses Yahoo Finance for equities, CoinGecko for cryptocurrencies and a few heuristics for currencies/commodities. The output indicates the most likely category, a display name, market cap when available, and a `yahoo_lookup` value to fetch further data if desired.
+
+## Table of Contents 🗂
+
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API](#api)
+- [Development](#development)
+- [Release and Versioning](#release-and-versioning)
+- [Citation](#citation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Key Features 🔑
+
+- Classify symbols as `Equity`, `Crypto`, `Forex`, `Commodity`, `Index` or `Unknown`.
+- Uses multiple public APIs and simple heuristics to make robust decisions.
+- Provides both synchronous and asynchronous APIs.
+- Lightweight disk cache to avoid repeated lookups (`TickerCache`).
+
+## Installation ⚙️
+
+Install from pip using the provided `requirements.txt` or install the package directly from the repository for latest changes:
+
+```bash
+pip install -r requirements.txt
+```
+
+or
+
+```bash
+pip install git+https://github.com/StephanAkkerman/ticker-classifier.git
+```
+
+## Usage ⌨️
+
+Basic synchronous usage:
+
+```python
+from ticker_classifier.classifier import TickerClassifier
+
+classifier = TickerClassifier()
+symbols = ["AAPL", "BTC", "EUR", "GOLD", "UNKNOWN123"]
+results = classifier.classify(symbols)
+for r in results:
+    print(r)
+```
+
+Example asynchronous usage:
+
+```python
+import asyncio
+from ticker_classifier.classifier import TickerClassifier
+
+async def main():
+    classifier = TickerClassifier()
+    symbols = ["AAPL", "BTC", "ETH", "JPY"]
+    results = await classifier.classify_async(symbols)
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
+The output for each symbol is a dictionary like:
+
+```python
+{'category': 'EQUITY', 'ticker': 'AAPL', 'name': 'Apple Inc.', 'market_cap': 4029017227264, 'yahoo_lookup': 'AAPL', 'alternatives': ['crypto'], 'source': 'api'}
+{'category': 'crypto', 'ticker': 'BTC', 'name': 'Bitcoin', 'market_cap': 1736590593460.9607, 'yahoo_lookup': 'BTC-USD', 'alternatives': ['stock'], 'source': 'api'}
+{'category': 'crypto', 'ticker': 'ETH', 'name': 'Ethereum', 'market_cap': 338145915081.1455, 'yahoo_lookup': 'ETH-USD', 'alternatives': ['stock'], 'source': 'cache'}
+{'category': 'forex', 'ticker': 'JPY', 'name': 'JPY Currency', 'market_cap': None, 'yahoo_lookup': 'JPYUSD=X', 'alternatives': ['stock'], 'source': 'cache'}
+```
+
+Notes
+- The classifier caches positive classifications (non-`Unknown`) in an
+SQLite database (default `ticker_cache.db`) for `24` hours by default.
+- You can customize the cache filename and expiry by passing `db_name` and
+`hours_to_expire` to `TickerClassifier`.
+
+## API
+
+- `ticker_classifier.classifier.TickerClassifier`
+- `classify(symbols: List[str]) -> List[dict]` – synchronous classification.
+- `classify_async(symbols: List[str]) -> List[dict]` – async classification.
+- `ticker_classifier.apis.yahoo.YahooClient` – low-level Yahoo quote fetcher (sync + async helpers).
+- `ticker_classifier.apis.coingecko.CoinGeckoClient` – crypto lookup + market cap helpers (sync + async).
+- `ticker_classifier.db.cache.TickerCache` – tiny SQLite-backed cache used by `TickerClassifier`.
+
+## Development
+
+Run formatting and linting tools you prefer (project uses `black` code style).
+
+Run a quick smoke check by running the `classifier.py` module directly:
+
+```powershell
+& .venv\Scripts\python.exe ticker_classifier\classifier.py
+```
+
+If you add tests, run them with your chosen test runner (e.g. `pytest`).
+
+## Release and Versioning
+
+This package is published to PyPI through GitHub Actions:
+
+- Workflow: `.github/workflows/publish.yml`
+- Trigger: GitHub Release published
+- Publisher: `pypa/gh-action-pypi-publish` using trusted publishing (OIDC)
+
+Release flow:
+
+1. Update version in `pyproject.toml`.
+2. Update `ticker_classifier/__init__.py` `__version__` to match.
+3. Commit and push.
+4. Create a GitHub release with tag `vX.Y.Z` (or `X.Y.Z`).
+
+The publish workflow validates that the release tag version matches `pyproject.toml` before uploading to PyPI.
+
+## Citation ✍️
+If you use this project in your research, please cite as follows (adjust
+metadata accordingly):
+
+```bibtex
+@misc{ticker-classifier,
+author  = {Stephan Akkerman},
+title   = {ticker-classifier},
+year    = {2025},
+publisher = {GitHub},
+howpublished = {\url{https://github.com/StephanAkkerman/ticker-classifier}}
+}
+```
+
+## Contributing 🛠
+
+Contributions are welcome. Suggested workflow:
+
+1. Fork the repository and create a feature branch.
+2. Run tests and format your changes with `black`.
+3. Open a pull request with a clear description of the change.
+
+Please open issues for feature requests or bugs and include a small
+reproducible example when possible.
+
+![https://github.com/StephanAkkerman/ticker-classifier/graphs/contributors](https://contributors-img.firebaseapp.com/image?repo=StephanAkkerman/ticker-classifier)
+
+## License 📜
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

ticker_classifier-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "ticker_classifier"
+version = "0.1.0"
+description = "A robust stock, crypto, and forex classifier with async support."
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+  { name = "Stephan Akkerman", email = "stephan@akkerman.ai" },
+]
+dependencies = [
+    "requests",
+    "aiohttp"
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["ticker_classifier*"]
+
+[tool.isort]
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+line_length = 88
+profile = "black"
+
+[tool.ruff]
+line-length = 88
+#select = ["I001"]
+
+[tool.ruff.lint.pydocstyle]
+# Use Google-style docstrings.
+convention = "numpy"

ticker_classifier-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ticker_classifier-0.1.0/ticker_classifier/__init__.py

@@ -0,0 +1,4 @@
+from .classifier import TickerClassifier
+
+__all__ = ["TickerClassifier"]
+__version__ = "0.1.0"

ticker_classifier-0.1.0/ticker_classifier/apis/coingecko.py

@@ -0,0 +1,217 @@
+from collections import defaultdict
+from typing import Dict, List
+
+import aiohttp
+import requests
+
+
+class CoinGeckoClient:
+    def __init__(self):
+        """Initialize CoinGecko client.
+
+        Sets up base endpoints used for retrieving the coin list and simple
+        price information and initializes an internal cache for symbol -> id
+        mappings.
+
+        Notes
+        -----
+        The client keeps an in-memory `_crypto_map` that maps uppercase
+        symbols to a list of CoinGecko ids. This map is populated lazily by
+        `_load_map_sync` or `_load_map_async` when price lookup is requested.
+        """
+        self.list_url = "https://api.coingecko.com/api/v3/coins/list"
+        self.price_url = "https://api.coingecko.com/api/v3/simple/price"
+        self._crypto_map = None  # { 'BTC': ['bitcoin', 'bitcoin-token'], ... }
+
+    def _load_map_sync(self):
+        """Load the CoinGecko symbol->id map synchronously.
+
+        This method fetches the full coin list from the CoinGecko API and
+        populates the in-memory `_crypto_map` mapping uppercase symbol strings
+        to lists of CoinGecko ids. If the map is already loaded this is a
+        no-op.
+
+        Errors
+        ------
+        Any exceptions raised while fetching/parsing are caught and the map
+        falls back to an empty dict.
+        """
+        if self._crypto_map:
+            return
+        try:
+            resp = requests.get(self.list_url, timeout=10)
+            data = resp.json()
+            self._crypto_map = defaultdict(list)
+            for coin in data:
+                self._crypto_map[coin["symbol"].upper()].append(coin["id"])
+        except Exception:
+            self._crypto_map = {}
+
+    async def _load_map_async(self, session: aiohttp.ClientSession):
+        """Asynchronously load the CoinGecko symbol->id map.
+
+        Parameters
+        ----------
+        session : aiohttp.ClientSession
+            Active aiohttp session used for making the HTTP request.
+
+        Notes
+        -----
+        This is the async counterpart to `_load_map_sync`. If the internal map
+        is already populated this method returns immediately. Exceptions are
+        caught and the map will be set to an empty dict on failure.
+        """
+        if self._crypto_map:
+            return
+        try:
+            async with session.get(self.list_url) as resp:
+                data = await resp.json()
+                self._crypto_map = defaultdict(list)
+                for coin in data:
+                    self._crypto_map[coin["symbol"].upper()].append(coin["id"])
+        except Exception:
+            self._crypto_map = {}
+
+    def _get_candidate_ids(
+        self, symbols: List[str]
+    ) -> tuple[List[str], Dict[str, str]]:
+        """Return candidate CoinGecko ids for a list of symbols.
+
+        Parameters
+        ----------
+        symbols : list[str]
+            Uppercase ticker symbols to map to CoinGecko ids.
+
+        Returns
+        -------
+        ids : list[str]
+            Flat list of candidate CoinGecko ids (limited to first 10
+            collisions per symbol).
+        id_to_parent : dict
+            Mapping of coin id -> original symbol (parent) used to group
+            results later.
+        """
+        ids = []
+        id_to_parent = {}
+        if not self._crypto_map:
+            return ids, id_to_parent
+
+        for sym in symbols:
+            if sym in self._crypto_map:
+                # Top 10 collisions only
+                for cid in self._crypto_map[sym][:10]:
+                    ids.append(cid)
+                    id_to_parent[cid] = sym
+        return ids, id_to_parent
+
+    def get_prices_sync(self, symbols: List[str]) -> Dict[str, Dict]:
+        """Synchronous price lookup for a list of symbols using CoinGecko.
+
+        This method ensures the internal symbol->id map is loaded, finds
+        candidate CoinGecko ids for the requested symbols, and retrieves USD
+        prices and market caps in chunks. The highest market cap candidate is
+        selected per symbol in `_process_response`.
+
+        Parameters
+        ----------
+        symbols : list[str]
+            Uppercase ticker symbols to look up.
+
+        Returns
+        -------
+        dict[str, dict]
+            Mapping of symbol -> {"market_cap": ..., "name": ..., "id": ...}
+            for matches found. Returns an empty dict if nothing matched.
+        """
+        self._load_map_sync()
+        results = {}
+        ids, id_map = self._get_candidate_ids(symbols)
+        if not ids:
+            return results
+
+        chunk_size = 200
+        for i in range(0, len(ids), chunk_size):
+            chunk = ids[i : i + chunk_size]
+            try:
+                resp = requests.get(
+                    self.price_url,
+                    params={
+                        "ids": ",".join(chunk),
+                        "vs_currencies": "usd",
+                        "include_market_cap": "true",
+                    },
+                    timeout=10,
+                )
+                data = resp.json()
+                self._process_response(data, id_map, results)
+            except Exception:
+                pass
+        return results
+
+    async def get_prices_async(
+        self, session: aiohttp.ClientSession, symbols: List[str]
+    ) -> Dict[str, Dict]:
+        """Asynchronously retrieve prices and market caps for symbols.
+
+        Parameters
+        ----------
+        session : aiohttp.ClientSession
+            Active aiohttp session used to make HTTP requests.
+        symbols : list[str]
+            Uppercase ticker symbols to query.
+
+        Returns
+        -------
+        dict[str, dict]
+            Mapping of symbol -> {"market_cap": ..., "name": ..., "id": ...}.
+
+        Notes
+        -----
+        Uses the async map loader `_load_map_async` and requests CoinGecko in
+        chunks. Failures for a chunk are swallowed and processing continues.
+        """
+        await self._load_map_async(session)
+        results = {}
+        ids, id_map = self._get_candidate_ids(symbols)
+        if not ids:
+            return results
+
+        chunk_size = 200
+        for i in range(0, len(ids), chunk_size):
+            chunk = ids[i : i + chunk_size]
+            try:
+                params = {
+                    "ids": ",".join(chunk),
+                    "vs_currencies": "usd",
+                    "include_market_cap": "true",
+                }
+                async with session.get(self.price_url, params=params) as resp:
+                    data = await resp.json()
+                    self._process_response(data, id_map, results)
+            except Exception:
+                pass
+        return results
+
+    def _process_response(self, data, id_map, results):
+        """Process a CoinGecko price response and update results.
+
+        Parameters
+        ----------
+        data : dict
+            JSON-decoded response from the CoinGecko simple/price endpoint.
+        id_map : dict
+            Mapping of coin id -> parent symbol used to group results.
+        results : dict
+            Mutable mapping that will be updated in-place with the best
+            candidate per parent symbol (highest market cap wins).
+        """
+        for cid, val in data.items():
+            parent = id_map.get(cid)
+            if parent:
+                mcap = val.get("usd_market_cap", 0)
+                if mcap > results.get(parent, {}).get("market_cap", 0):
+                    results[parent] = {
+                        "market_cap": mcap,
+                        "name": cid.title(),
+                        "id": cid,
+                    }