ticker-classifier 0.1.0

A robust stock, crypto, and forex classifier with async support.

ticker-classifier

---

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
• Installation
• Usage
• API
• Development
• Release and Versioning
• Citation
• Contributing
• 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:

pip install -r requirements.txt

or

pip install git+https://github.com/StephanAkkerman/ticker-classifier.git

Usage ⌨️

Basic synchronous usage:

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:

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:

{'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:

& .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):

@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.

License 📜

This project is licensed under the MIT License. See the LICENSE file for details.