occ-symbol 0.1.0__tar.gz

occ_symbol-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# Python build & test artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/

occ_symbol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Murphy
+
+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.

occ_symbol-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: occ-symbol
+Version: 0.1.0
+Summary: Parse, validate, and build OCC option symbols — SPY260825C00500000 ⇄ {underlying, expiration, right, strike}. Zero dependencies, stdlib only.
+Project-URL: Homepage, https://github.com/chiefsmurph/occ-symbol
+Project-URL: Repository, https://github.com/chiefsmurph/occ-symbol
+Project-URL: Issues, https://github.com/chiefsmurph/occ-symbol/issues
+Author-email: John Murphy <chiefsmurph@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: derivatives,finance,occ,option-parser,option-symbol,options,options-trading,osi,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# occ-symbol
+
+**Parse, validate, and build OCC option symbols.** A tiny, dependency-free
+Python module (stdlib only) that turns the broker-agnostic listed-option string
+(the OSI symbol) into structured parts — and back again.
+
+> Python port of the [`occ-symbol`](https://github.com/chiefsmurph/occ-symbol)
+> TypeScript package. Same behavior, same test cases.
+
+```python
+from occ_symbol import parse_occ_symbol, format_occ_symbol, is_occ_symbol, OccParts
+
+parse_occ_symbol("SPY260825C00500000")
+# OccParts(underlying='SPY', expiration='2026-08-25', right='call', strike=500.0)
+
+format_occ_symbol(OccParts(underlying="SPY", expiration="2026-08-25", right="call", strike=500))
+# "SPY260825C00500000"
+
+is_occ_symbol("SPY260825C00500000")  # True
+is_occ_symbol("SPY")                 # False
+```
+
+## The format
+
+An OCC (a.k.a. OSI) option symbol packs four fields into one string:
+
+```
+SPY260825C00500000
+└┬┘└──┬─┘│└───┬──┘
+ │    │  │    └── strike × 1000, 8 digits, zero-padded (00500000 = 500.000)
+ │    │  └─────── C = call, P = put
+ │    └────────── expiration YYMMDD (20YY)
+ └─────────────── underlying / root
+```
+
+## Install
+
+```bash
+pip install occ-symbol
+```
+
+## API
+
+| Function | Description |
+|---|---|
+| `parse_occ_symbol(symbol)` | Parse a symbol into `OccParts`, or `None` if it isn't a valid OCC string. Tolerates space-padded roots (Schwab-style `"AAPL  240119C00150000"`). |
+| `format_occ_symbol(parts)` | Build a canonical (unpadded) OCC symbol from `OccParts`. The inverse of `parse_occ_symbol`. |
+| `is_occ_symbol(symbol)` | `True` if the string is a valid OCC option symbol (padded or not). |
+
+```python
+from dataclasses import dataclass
+from typing import Literal
+
+OptionRight = Literal["call", "put"]
+
+@dataclass(frozen=True)
+class OccParts:
+    underlying: str
+    expiration: str  # 'YYYY-MM-DD'
+    right: OptionRight
+    strike: float
+```
+
+`parse_occ_symbol` and `format_occ_symbol` round-trip: parsing a symbol and
+formatting the result yields the canonical symbol, and formatting parts then
+parsing them returns the original parts.
+
+## Scope & limitations
+
+- Two-digit years are interpreted as `20YY`, matching current listed-option conventions.
+- `format_occ_symbol` emits the canonical **unpadded** root; space-padded input is normalized on the round trip.
+- Strikes are scaled by 1000 (rounded to the nearest thousandth), so fractional strikes down to a tenth of a cent are preserved.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT © John Murphy

occ_symbol-0.1.0/README.md

@@ -0,0 +1,83 @@
+# occ-symbol
+
+**Parse, validate, and build OCC option symbols.** A tiny, dependency-free
+Python module (stdlib only) that turns the broker-agnostic listed-option string
+(the OSI symbol) into structured parts — and back again.
+
+> Python port of the [`occ-symbol`](https://github.com/chiefsmurph/occ-symbol)
+> TypeScript package. Same behavior, same test cases.
+
+```python
+from occ_symbol import parse_occ_symbol, format_occ_symbol, is_occ_symbol, OccParts
+
+parse_occ_symbol("SPY260825C00500000")
+# OccParts(underlying='SPY', expiration='2026-08-25', right='call', strike=500.0)
+
+format_occ_symbol(OccParts(underlying="SPY", expiration="2026-08-25", right="call", strike=500))
+# "SPY260825C00500000"
+
+is_occ_symbol("SPY260825C00500000")  # True
+is_occ_symbol("SPY")                 # False
+```
+
+## The format
+
+An OCC (a.k.a. OSI) option symbol packs four fields into one string:
+
+```
+SPY260825C00500000
+└┬┘└──┬─┘│└───┬──┘
+ │    │  │    └── strike × 1000, 8 digits, zero-padded (00500000 = 500.000)
+ │    │  └─────── C = call, P = put
+ │    └────────── expiration YYMMDD (20YY)
+ └─────────────── underlying / root
+```
+
+## Install
+
+```bash
+pip install occ-symbol
+```
+
+## API
+
+| Function | Description |
+|---|---|
+| `parse_occ_symbol(symbol)` | Parse a symbol into `OccParts`, or `None` if it isn't a valid OCC string. Tolerates space-padded roots (Schwab-style `"AAPL  240119C00150000"`). |
+| `format_occ_symbol(parts)` | Build a canonical (unpadded) OCC symbol from `OccParts`. The inverse of `parse_occ_symbol`. |
+| `is_occ_symbol(symbol)` | `True` if the string is a valid OCC option symbol (padded or not). |
+
+```python
+from dataclasses import dataclass
+from typing import Literal
+
+OptionRight = Literal["call", "put"]
+
+@dataclass(frozen=True)
+class OccParts:
+    underlying: str
+    expiration: str  # 'YYYY-MM-DD'
+    right: OptionRight
+    strike: float
+```
+
+`parse_occ_symbol` and `format_occ_symbol` round-trip: parsing a symbol and
+formatting the result yields the canonical symbol, and formatting parts then
+parsing them returns the original parts.
+
+## Scope & limitations
+
+- Two-digit years are interpreted as `20YY`, matching current listed-option conventions.
+- `format_occ_symbol` emits the canonical **unpadded** root; space-padded input is normalized on the round trip.
+- Strikes are scaled by 1000 (rounded to the nearest thousandth), so fractional strikes down to a tenth of a cent are preserved.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT © John Murphy

occ_symbol-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "occ-symbol"
+version = "0.1.0"
+description = "Parse, validate, and build OCC option symbols — SPY260825C00500000 ⇄ {underlying, expiration, right, strike}. Zero dependencies, stdlib only."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "John Murphy", email = "chiefsmurph@gmail.com" }]
+keywords = [
+    "occ",
+    "option-symbol",
+    "options",
+    "options-trading",
+    "osi",
+    "option-parser",
+    "derivatives",
+    "finance",
+    "trading",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/chiefsmurph/occ-symbol"
+Repository = "https://github.com/chiefsmurph/occ-symbol"
+Issues = "https://github.com/chiefsmurph/occ-symbol/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/occ_symbol"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

occ_symbol-0.1.0/src/occ_symbol/__init__.py

@@ -0,0 +1,95 @@
+"""OCC option-symbol parsing and building.
+
+The broker-agnostic listed-option format, also known as the OSI symbol::
+
+    SPY260825C00500000  =  <ROOT><YYMMDD><C|P><STRIKE*1000, 8 digits, zero-padded>
+
+e.g. ``SPY260825C00500000`` -> ``SPY``, ``2026-08-25``, call, strike 500.
+
+The layout is: an alphabetic underlying/root, a 6-digit YYMMDD expiration (the
+2-digit year is interpreted as 20YY), a single ``C``/``P`` for call/put, and an
+8-digit strike price scaled by 1000 (so ``00500000`` = 500.000,
+``00500500`` = 500.5).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+__all__ = [
+    "OptionRight",
+    "OccParts",
+    "is_occ_symbol",
+    "parse_occ_symbol",
+    "format_occ_symbol",
+]
+
+OptionRight = Literal["call", "put"]
+
+_OCC_RE = re.compile(r"^([A-Z]+)(\d{6})([CP])(\d{8})$")
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+@dataclass(frozen=True)
+class OccParts:
+    """The four structured fields packed into an OCC/OSI option symbol."""
+
+    underlying: str
+    expiration: str  # 'YYYY-MM-DD'
+    right: OptionRight
+    strike: float
+
+
+def is_occ_symbol(symbol: str) -> bool:
+    """Return ``True`` if ``symbol`` is a valid OCC option symbol (padded or not).
+
+    Some brokers space-pad the root to 6 chars (Schwab:
+    ``"AAPL  240119C00150000"``); whitespace is stripped so the same matcher
+    handles both padded and unpadded forms.
+    """
+    return _OCC_RE.match(_WHITESPACE_RE.sub("", symbol)) is not None
+
+
+def parse_occ_symbol(symbol: str) -> Optional[OccParts]:
+    """Parse a symbol into :class:`OccParts`, or ``None`` if it isn't valid.
+
+    Tolerates space-padded roots (Schwab-style ``"AAPL  240119C00150000"``).
+    """
+    m = _OCC_RE.match(_WHITESPACE_RE.sub("", symbol))
+    if m is None:
+        return None
+    underlying, ymd, cp, strike_str = m.group(1), m.group(2), m.group(3), m.group(4)
+    strike = int(strike_str) / 1000
+    return OccParts(
+        underlying=underlying,
+        expiration=f"20{ymd[0:2]}-{ymd[2:4]}-{ymd[4:6]}",
+        right="call" if cp == "C" else "put",
+        strike=strike,
+    )
+
+
+def format_occ_symbol(parts: OccParts) -> str:
+    """Build a canonical (unpadded) OCC symbol from parts.
+
+    The inverse of :func:`parse_occ_symbol`. Strikes are scaled by 1000 and
+    rounded to the nearest thousandth, matching the OSI convention.
+    """
+    ymd = parts.expiration[2:4] + parts.expiration[5:7] + parts.expiration[8:10]
+    cp = "C" if parts.right == "call" else "P"
+    strike_str = str(_round_half_away_from_zero(parts.strike * 1000)).zfill(8)
+    return f"{parts.underlying}{ymd}{cp}{strike_str}"
+
+
+def _round_half_away_from_zero(value: float) -> int:
+    """Match JavaScript ``Math.round`` semantics (round half toward +infinity).
+
+    Python's built-in ``round`` uses banker's rounding, which would disagree
+    with the JS reference implementation on exact ``*.5`` thousandths. Strikes
+    are never negative in practice, so half-up and half-away-from-zero coincide;
+    we implement half toward +infinity to mirror ``Math.round`` exactly.
+    """
+    import math
+
+    return math.floor(value + 0.5)

occ_symbol-0.1.0/tests/test_occ_symbol.py

@@ -0,0 +1,130 @@
+"""Ported from occ-symbol/src/index.test.ts — same fixtures and expected values."""
+
+import pytest
+
+from occ_symbol import (
+    OccParts,
+    format_occ_symbol,
+    is_occ_symbol,
+    parse_occ_symbol,
+)
+
+
+# --- parseOccSymbol ---------------------------------------------------------
+
+def test_parses_a_standard_occ_call():
+    assert parse_occ_symbol("SMR260919C00009000") == OccParts(
+        underlying="SMR",
+        expiration="2026-09-19",
+        right="call",
+        strike=9,
+    )
+
+
+def test_parses_a_put_with_a_fractional_strike():
+    assert parse_occ_symbol("SPY260825P00500500") == OccParts(
+        underlying="SPY",
+        expiration="2026-08-25",
+        right="put",
+        strike=500.5,
+    )
+
+
+def test_tolerates_a_space_padded_root_schwab_style():
+    assert parse_occ_symbol("AAPL  240119C00150000") == OccParts(
+        underlying="AAPL",
+        expiration="2024-01-19",
+        right="call",
+        strike=150,
+    )
+
+
+def test_returns_none_for_a_plain_equity_symbol():
+    assert parse_occ_symbol("AAPL") is None
+    assert is_occ_symbol("AAPL") is False
+
+
+def test_is_occ_symbol_detects_occ_strings_padded_or_not():
+    assert is_occ_symbol("SMR260919C00009000") is True
+    assert is_occ_symbol("AAPL  240119C00150000") is True
+    assert is_occ_symbol("SMR") is False
+
+
+# --- formatOccSymbol --------------------------------------------------------
+
+def test_builds_a_standard_occ_call():
+    assert (
+        format_occ_symbol(
+            OccParts(
+                underlying="SPY",
+                expiration="2026-08-25",
+                right="call",
+                strike=500,
+            )
+        )
+        == "SPY260825C00500000"
+    )
+
+
+def test_builds_a_put():
+    assert (
+        format_occ_symbol(
+            OccParts(
+                underlying="SPY",
+                expiration="2026-08-25",
+                right="put",
+                strike=500,
+            )
+        )
+        == "SPY260825P00500000"
+    )
+
+
+def test_handles_a_fractional_strike():
+    assert (
+        format_occ_symbol(
+            OccParts(
+                underlying="SPY",
+                expiration="2026-08-25",
+                right="put",
+                strike=500.5,
+            )
+        )
+        == "SPY260825P00500500"
+    )
+
+
+# --- round-trip -------------------------------------------------------------
+
+PARTS_CASES = [
+    OccParts(underlying="SPY", expiration="2026-08-25", right="call", strike=500),
+    OccParts(underlying="SPY", expiration="2026-08-25", right="put", strike=500.5),
+    OccParts(underlying="SMR", expiration="2026-09-19", right="call", strike=9),
+    OccParts(underlying="AAPL", expiration="2024-01-19", right="call", strike=150),
+]
+
+
+@pytest.mark.parametrize("parts", PARTS_CASES, ids=[p.underlying for p in PARTS_CASES])
+def test_parse_of_format_deep_equals_parts(parts):
+    assert parse_occ_symbol(format_occ_symbol(parts)) == parts
+
+
+SYM_CASES = [
+    "SPY260825C00500000",
+    "SPY260825P00500500",
+    "SMR260919C00009000",
+    "AAPL240119C00150000",
+]
+
+
+@pytest.mark.parametrize("sym", SYM_CASES)
+def test_format_of_parse_equals_the_normalized_symbol(sym):
+    parsed = parse_occ_symbol(sym)
+    assert parsed is not None
+    assert format_occ_symbol(parsed) == sym
+
+
+def test_normalizes_a_space_padded_symbol_through_parse_format():
+    parsed = parse_occ_symbol("AAPL  240119C00150000")
+    assert parsed is not None
+    assert format_occ_symbol(parsed) == "AAPL240119C00150000"