tickerdata 0.1.0__py3-none-any.whl

tickerdata/reader.py

@@ -0,0 +1,99 @@
+from copy import deepcopy
+from importlib.resources import files
+import json
+import re
+
+
+_IDENTIFIER = re.compile(r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*")
+_MIC = re.compile(r"[A-Z0-9]{4}")
+
+
+def _read_json(name):
+    return json.loads(files("tickerdata").joinpath("data", name).read_text(encoding="utf-8"))
+
+
+_manifest = _read_json("manifest.json")
+_instruments_payload = _read_json("instruments.json")
+_index_payload = _read_json("symbol-index.json")
+
+if (
+    _manifest["schema_version"] != "4.0.0"
+    or _instruments_payload["schema_version"] != _manifest["schema_version"]
+    or _index_payload["schema_version"] != _manifest["schema_version"]
+    or _instruments_payload["data_version"] != _manifest["data_version"]
+    or _index_payload["data_version"] != _manifest["data_version"]
+):
+    raise RuntimeError("The embedded tickerdata snapshot has inconsistent versions")
+
+_records = {record["id"]: record for record in _instruments_payload["instruments"]}
+_entries_by_symbol = {}
+for _entry in _index_payload["entries"]:
+    _entries_by_symbol.setdefault(_entry["symbol"], []).append(_entry)
+
+
+class UnknownSymbolError(LookupError):
+    def __init__(self, symbol, mic, provider, include_inactive):
+        self.symbol = symbol
+        super().__init__(
+            "Unknown symbol {!r} (MIC={!r}, provider={!r}, active_only={})".format(
+                symbol, mic, provider, not include_inactive
+            )
+        )
+
+
+class AmbiguousSymbolError(LookupError):
+    def __init__(self, symbol, candidates):
+        self.symbol = symbol
+        self.candidates = candidates
+        detail = ", ".join(
+            "{} ({})".format(item["instrument_id"], item["mic"] or "no MIC")
+            for item in candidates
+        )
+        super().__init__("Ambiguous symbol {!r}: {}".format(symbol, detail))
+
+
+def lookup(symbol, *, mic=None, provider=None, include_inactive=True):
+    if not isinstance(symbol, str) or not symbol.strip():
+        raise TypeError("symbol must be a non-empty string")
+    normalized = symbol.strip().upper()
+    if mic is not None:
+        if not isinstance(mic, str):
+            raise TypeError("mic must be a string or None")
+        mic = mic.strip().upper()
+        if _MIC.fullmatch(mic) is None:
+            raise ValueError("mic must be a four-character MIC")
+    if provider is not None:
+        if not isinstance(provider, str):
+            raise TypeError("provider must be a string or None")
+        provider = provider.strip().lower()
+        if len(provider) > 100 or _IDENTIFIER.fullmatch(provider) is None:
+            raise ValueError("provider must be a lowercase identifier")
+    if not isinstance(include_inactive, bool):
+        raise TypeError("include_inactive must be a boolean")
+
+    candidates = {}
+    for entry in _entries_by_symbol.get(normalized, []):
+        record = _records.get(entry["instrument_id"])
+        if record is None:
+            raise RuntimeError(
+                "Snapshot index references missing instrument {}".format(entry["instrument_id"])
+            )
+        if mic is not None and entry["mic"] != mic:
+            continue
+        if provider is not None and entry["provider"] not in (None, provider):
+            continue
+        if not include_inactive and record["listing_status"] != "active":
+            continue
+        candidates[record["id"]] = record
+
+    if not candidates:
+        raise UnknownSymbolError(normalized, mic, provider, include_inactive)
+    if len(candidates) > 1:
+        raise AmbiguousSymbolError(
+            normalized,
+            [
+                {"instrument_id": identifier, "mic": candidates[identifier]["symbol"]["mic"]}
+                for identifier in sorted(candidates)
+            ],
+        )
+    return deepcopy(next(iter(candidates.values())))

tickerdata-0.1.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: tickerdata
+Version: 0.1.0
+Summary: Offline, versioned ticker metadata lookup
+Author: tickerdata contributors
+License-Expression: MIT AND ODC-By-1.0
+Project-URL: Repository, https://github.com/udlrdotai/tickerdata
+Keywords: ticker,symbol,metadata,offline
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE-MIT
+License-File: LICENSE-ODC-BY
+License-File: NOTICE.md
+Dynamic: license-file
+
+# tickerdata
+
+Offline, versioned ticker metadata lookup for Python. The package contains a
+fixed snapshot of reviewed metadata and never accesses the network.
+
+```python
+from tickerdata import lookup
+
+instrument = lookup(
+    "BRK-B",
+    mic="XNYS",
+    provider="yahoo",
+    include_inactive=False,
+)
+```
+
+`lookup` does not rewrite punctuation or guess between ambiguous listings.
+Unknown and ambiguous queries raise `UnknownSymbolError` and
+`AmbiguousSymbolError`.
+
+This package provides metadata only. It does not provide market data, trading,
+portfolio management, or investment advice.
+
+The reader code is MIT licensed. Database rights in the maintained compilation
+are licensed under ODC-By 1.0 subject to `NOTICE.md`; individual contents and
+external materials may remain subject to their own terms.

tickerdata-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+tickerdata/__init__.py,sha256=MYcsglhQQUMyXn9ID4BmDrogjeUNp2ZWv4BHCfA_nhA,137
+tickerdata/reader.py,sha256=iXplJqTjVYA7Ku9GNx8yQfjusN8QD-aqJuI4cOVz7mI,3768
+tickerdata/data/instruments.json,sha256=yo4haed6E8wE8OakFAm2p3-nV4IzOEPZz-1d-UvIOzY,85971
+tickerdata/data/manifest.json,sha256=BWedDXbVpNXQ8Co21mRqjXCwSzq3rxPKu5XPNc2c6DA,658
+tickerdata/data/symbol-index.json,sha256=jyexys7H_qQ4dH-iN3xC9in_PYZcWqA-o5YMl3tscOY,10806
+tickerdata/data/vocabulary.json,sha256=BtHR6FN9u_xyiUI8_RsQSHxh_GYdQ9V--pBqq1KstZ0,38305
+tickerdata-0.1.0.dist-info/licenses/LICENSE-MIT,sha256=tbdwlRoRYcIX0Yx_k7Jc0Pll69nZxiyyWL_yOkDEKwg,1267
+tickerdata-0.1.0.dist-info/licenses/LICENSE-ODC-BY,sha256=wBbrDc4y9WcKpTDHqMYdsvJ7WTfZbBPftovQw43gaec,275
+tickerdata-0.1.0.dist-info/licenses/NOTICE.md,sha256=036AQCQE7gy-dO3RbtRNtDEtikt4LADcB5giFiBmrMg,1080
+tickerdata-0.1.0.dist-info/METADATA,sha256=V1YTtsgQkkVyrpDhO-s3KRTPhsW3LFdPBy_GbK_H_2M,1359
+tickerdata-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tickerdata-0.1.0.dist-info/top_level.txt,sha256=j585Eymece4xgYEjfsDwH0fRnqZWgJa-oW2x77SOTWw,11
+tickerdata-0.1.0.dist-info/RECORD,,

tickerdata-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tickerdata-0.1.0.dist-info/licenses/LICENSE-MIT

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 tickerdata contributors
+
+This license applies to the software code in this project. Data, vocabulary
+content, suggestions, and third-party materials are excluded; see
+docs/licensing.md for their separate terms.
+
+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.

tickerdata-0.1.0.dist-info/licenses/LICENSE-ODC-BY

@@ -0,0 +1,8 @@
+Open Data Commons Attribution License 1.0 (ODC-By-1.0)
+
+Canonical license URI:
+
+https://opendatacommons.org/licenses/by/1-0/
+
+This URI is supplied under Section 4.2(b) of ODC-By-1.0. The attribution and
+rights notices for this database distribution are in PACKAGE-NOTICE.md.

tickerdata-0.1.0.dist-info/licenses/NOTICE.md

@@ -0,0 +1,25 @@
+# tickerdata package notice
+
+The reader software is provided under the MIT License.
+
+To the extent the tickerdata contributors hold copyright or database rights in
+the selection and arrangement of the maintained database, that database is
+made available under the Open Data Commons Attribution License 1.0
+(ODC-By-1.0).
+
+Required attribution for public use:
+
+> Contains information from tickerdata, made available under the Open Data
+> Commons Attribution License: https://opendatacommons.org/licenses/by/1-0/
+
+ODC-By licenses database rights and does not automatically license every
+individual item of content. Security names and trademarks belong to their
+respective owners. External classifications and source-derived facts may be
+subject to separate terms. See:
+
+- https://github.com/udlrdotai/tickerdata/blob/main/docs/licensing.md
+- https://github.com/udlrdotai/tickerdata/blob/main/docs/industry-classification.md
+
+This metadata is provided as-is and may be incomplete or incorrect. It is not
+market data, trading functionality, portfolio management, or investment
+advice.

tickerdata-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tickerdata