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 TypeScript package. Same behavior, same test cases.

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

pip install occ-symbol

API

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

pip install -e ".[dev]"
pytest

License

MIT © John Murphy