# Expirations (Python SDK)

Get a list of current or historical option expiration dates for an underlying symbol.

## Making Requests

Use the `expirations()` method on the `options` resource to fetch expiration dates. The method supports multiple output formats:

| Output Format | Return Type                                               | Description                                                                                                                                           |
|---------------|-----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame`                  | Returns a DataFrame with expiration dates indexed by expirations (default).                                                                           |
| **INTERNAL**  | `OptionsExpirations` or `OptionsExpirationsHumanReadable` | Returns an OptionsExpirations object. When `use_human_readable=True`, returns an OptionsExpirationsHumanReadable object with capitalized field names. |
| **JSON**      | `dict`                                                    | Returns the raw JSON response as a dictionary.                                                                                                        |
| **CSV**       | `str`                                                     | Writes CSV data to file and returns the filename string.                                                                                              |

<a name="expirations"></a>
## expirations

```python
def expirations(
    symbol: str,
    *,
    strike: float = None,
    date: str | datetime.datetime = None,
    output_format: OutputFormat = OutputFormat.DATAFRAME,
    date_format: DateFormat = None,
    columns: list[str] = None,
    add_headers: bool = None,
    use_human_readable: bool = False,
    mode: Mode = None,
    filename: str | Path = None,
) -> OptionsExpirations | OptionsExpirationsHumanReadable | dict | str | MarketDataClientErrorResult
```

Fetches available expiration dates for a given symbol. The `symbol` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.

### Parameters

- `symbol` (str)

  The underlying stock symbol for which to fetch expiration dates.

- `strike` (float, optional)

  Filter by strike price.

- `date` (str | datetime.datetime, optional)

  Historical date for the expiration dates.

- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)

  The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)

  The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)

  Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)

  Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)

  Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)

  The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.

- `filename` (str | Path, optional)

  File path for CSV output (only used with `output_format=OutputFormat.CSV`).

### Returns

- `OptionsExpirations` | `OptionsExpirationsHumanReadable` | `dict` | `str` | `MarketDataClientErrorResult`

  The expiration dates in the requested format, or a `MarketDataClientErrorResult` if an error occurred.

### Example (DataFrame)

```python
from marketdata import MarketDataClient

client = MarketDataClient()

# Get options expirations as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.options.expirations("AAPL")
# or
df = client.options.expirations(symbol="AAPL")

print(df)
```

### Example (Internal)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get options expirations as internal object
expirations = client.options.expirations("AAPL", output_format=OutputFormat.INTERNAL)

# Access expiration dates
print(f"Expirations: {expirations.expirations}")
```

### Example (JSON)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get options expirations as JSON
expirations = client.options.expirations("AAPL", output_format=OutputFormat.JSON)

print(expirations)
```

### Example (CSV)

```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get options expirations as CSV
csv_file = client.options.expirations(
    "AAPL",
    output_format=OutputFormat.CSV,
    filename=Path("expirations.csv")
)

print(f"CSV file saved to: {csv_file}")
```

### Example (Human Readable)

```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get options expirations in human-readable format
expirations = client.options.expirations(
    "AAPL",
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

# Access expiration dates
print(f"Expirations: {expirations.Expirations}")
print(f"Date: {expirations.Date}")
```

<a name="OptionsExpirations"></a>
## OptionsExpirations

```python
@dataclass
class OptionsExpirations:
    s: str
    expirations: list[datetime.datetime]
    updated: datetime.datetime
```

OptionsExpirations represents expiration dates for options, encapsulating a list of expiration dates and an update timestamp.

### Properties

- `s` (str): Status indicator ("ok" for successful responses).
- `expirations` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `updated` (datetime.datetime): The time when the data was last updated (automatically converted from timestamp).

### Notes

- The `expirations` list contains `datetime.datetime` objects automatically converted from Unix timestamps.
- The `updated` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.

<a name="OptionsExpirationsHumanReadable"></a>
## OptionsExpirationsHumanReadable

```python
@dataclass
class OptionsExpirationsHumanReadable:
    Expirations: list[datetime.datetime]
    Date: datetime.datetime
```

OptionsExpirationsHumanReadable represents expiration dates in human-readable format with capitalized field names and formatted values.

### Properties

- `Expirations` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `Date` (datetime.datetime): The time when the data was last updated (automatically converted from timestamp).

### Notes

- The `Expirations` list contains `datetime.datetime` objects automatically converted from Unix timestamps.
- The `Date` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
- Field names use capitalized format (e.g., `Expirations` instead of `expirations`, `Date` instead of `updated`).