### start

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/live.md

Starts the live session and begins receiving data. Requires a handler function to process incoming records and an optional exception handler.

```APIDOC
## start

### Description
Starts the live session and begins receiving data. Requires a handler function to process incoming records and an optional exception handler.

### Method
None (This is a client method, not an HTTP endpoint)

### Endpoint
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **handler** (RecordCallback) - Required - Callback function invoked for each received DBNRecord. Signature: `(record: DBNRecord) -> None`
- **exception_handler** (ExceptionCallback) - Optional - Optional callback for exceptions. Signature: `(exception: Exception) -> None`

### Request Example
```python
def on_record(record):
    print(f"Received: {record}")

def on_error(exception):
    print(f"Error: {exception}")

client.subscribe(dataset='GLBX.MDP3', symbols='ES.FUT')
client.start(handler=on_record, exception_handler=on_error)
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Start Live Session with Callbacks

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/live.md

Start the live session and begin receiving data. Provide callback functions for handling incoming records and exceptions.

```python
def on_record(record):
    print(f"Received: {record}")

def on_error(exception):
    print(f"Error: {exception}")

client.subscribe(dataset='GLBX.MDP3', symbols='ES.FUT')
client.start(handler=on_record, exception_handler=on_error)
```

--------------------------------

### Install Databento Python Client

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Install the latest Databento client library using pip. Ensure you have the most recent version for full functionality.

```bash
pip install -U databento
```

--------------------------------

### Initialize Historical Client and Get Version

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Import the Databento library and initialize a historical client using your API key. This client is used for subsequent data requests. You can check the installed client version.

```python
import databento as db


client = db.Historical(key="YOUR_API_KEY")
db.__version__
```

```python
'0.17.0'
```

--------------------------------

### Get Help for Batch Download Method

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Displays the documentation for the `client.batch.download` method, outlining its parameters, return values, and potential exceptions.

```python
help(client.batch.download)
```

--------------------------------

### Type Hinting with Databento Components

Source: https://github.com/databento/databento-python/blob/main/_autodocs/module-structure.md

This example demonstrates how to use type hints for Databento client objects, schema types, and data types within function signatures. This improves code readability and allows for static analysis.

```python
from databento import Historical, DBNStore, Schema
from databento_dbn import SType

def process_data(
    client: Historical,
    schema: Schema,
    stype_in: SType,
) -> DBNStore:
    return client.timeseries.get_range(
        dataset='GLBX.MDP3',
        schema=schema,
        stype_in=stype_in,
        start='2022-06-10'
    )
```

--------------------------------

### Access DBNStore Metadata: Start Time

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Retrieve the start timestamp of the requested data range from the `DBNStore` object. This marks the beginning of the time series.

```python
data.start
```

--------------------------------

### Symbology Resolution Result Example

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

This is an example of the data structure returned for symbology resolution. It shows the input symbols, the desired output symbol type, date ranges, and a detailed mapping of input symbols to their corresponding instrument IDs.

```json
{
"symbols": ["ES.FUT"],
"stype_in": "parent",
"stype_out": "instrument_id",
"start_date": "2022-06-10",
"end_date": "2022-06-12",
"partial": [],
"not_found": [],
"mappings": {
"ESZ6": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "10252"}],
"ESU2": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "97042"}],
"ESZ2": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "206323"}],
"ESH3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "206299"}],
"ESM4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "5602"}],
"ESH4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "17077"}],
"ESU4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "118"}],
"ESZ3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "314863"}],
"ESM3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "95414"}],
"ESZ4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "183748"}],
"ESU3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "3445"}],
"ESZ5": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "294973"}],
"ESU2-ESF3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "16445"}],
"ESH3-ESU3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "20604"}],
"ESU3-ESH4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "18909"}],
"ESM3-ESH4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "2018"}],
"ESH4-ESM4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "17684"}],
"ESM2": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "3403"}],
"ESZ3-ESH4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "33040"}],
"ESZ2-ESZ3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "4931"}],
"ESZ2-ESH3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "344396"}],
"ESM3-ESU3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "28177"}],
"ESU2-ESM3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "26998"}],
"ESM2-ESU2": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "96293"}],
"ESM2-ESH3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "6817"}],
"ESU3-ESZ3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "35947"}],
"ESM2-ESM3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "25719"}],
"ESH3-ESZ3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "16567"}],
"ESM2-ESZ2": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "431109"}],
"ESZ3-ESM4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "2826"}],
"ESU2-ESH3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "431108"}],
"ESZ2-ESM3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "19355"}],
"ESH3-ESM3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "431569"}],
"ESM3-ESZ3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "37976"}],
"ESM4-ESU4": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "4155"}],
"ESU2-ESZ2": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "431796"}],
"ESZ2-ESU3": [{"start_date": datetime.date(2022, 6, 10),
"end_date": datetime.date(2022, 6, 12),
"symbol": "344396"}]
}
}
```

--------------------------------

### Stream Live Data with Databento

Source: https://github.com/databento/databento-python/blob/main/_autodocs/QUICKSTART.md

Subscribe to real-time data streams using the `Live` client. Define a handler function to process incoming records and start the stream. Remember to stop the stream when finished.

```python
import databento as db

client = db.Live()

# Subscribe to real-time data
client.subscribe(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    schema='trades'
)

# Define handler
def on_record(record):
    print(f"Price: {record.price}, Size: {record.size}")

# Start receiving data
client.start(handler=on_record)

# Stop when done
client.stop()
```

--------------------------------

### Stream Live Data with Python

Source: https://github.com/databento/databento-python/blob/main/_autodocs/00_START_HERE.md

Subscribe to live data streams for specified datasets and symbols, and start processing records using a handler function. Requires an active connection and a defined handler.

```python
client.subscribe(dataset='GLBX.MDP3', symbols='ES.FUT')
client.start(handler=on_record)
```

--------------------------------

### Get Dataset Details

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/metadata.md

Request details for a specific dataset. This provides comprehensive information about a dataset, including its description and vendor.

```python
dataset_info = client.metadata.get_dataset('GLBX.MDP3')
print(dataset_info['description'])
print(dataset_info['vendor'])
```

--------------------------------

### Get Historical Data with Python

Source: https://github.com/databento/databento-python/blob/main/_autodocs/00_START_HERE.md

Retrieve historical time series data for specified datasets, symbols, and date ranges. Ensure the client is initialized before use.

```python
data = client.timeseries.get_range(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    schema='trades',
    start='2022-06-10',
    end='2022-06-15'
)
```

--------------------------------

### Stream Live Data with Databento Python

Source: https://github.com/databento/databento-python/blob/main/_autodocs/README.md

Subscribes to live market data for a specified dataset and symbol. A handler function is defined to process incoming records, printing the price of each record. The client then starts streaming.

```python
import databento as db

client = db.Live()

# Subscribe
client.subscribe(dataset='GLBX.MDP3', symbols='ES.FUT')

# Define handler
def on_record(record):
    print(f"Price: {record.price}")

# Start streaming
client.start(handler=on_record)
```

--------------------------------

### Get Data Cost Estimate

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Use `get_cost` with previously defined parameters to query the estimated data cost in US dollars. The price is calculated based on unit cost and uncompressed size.

```python
client.metadata.get_cost(**params)
```

--------------------------------

### subscribe

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/live.md

Creates and sends a subscription request to the Databento Live Subscription Gateway. Specify the dataset, symbols, schema, symbology types, and an optional historical replay start point.

```APIDOC
## subscribe

### Description
Creates and sends a subscription request to the Databento Live Subscription Gateway. Specify the dataset, symbols, schema, symbology types, and an optional historical replay start point.

### Method
None (This is a client method, not an HTTP endpoint)

### Endpoint
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **dataset** (Dataset or str) - Required - The dataset code for the subscription.
- **symbols** (Iterable[str or int], str, or int) - Optional - ALL_SYMBOLS - The symbols to subscribe to. If not specified, subscribes to all.
- **schema** (Schema or str) - Optional - "trades" - The data record schema.
- **stype_in** (SType or str) - Optional - "raw_symbol" - The input symbology type.
- **stype_out** (SType or str) - Optional - "instrument_id" - The output symbology type.
- **start** (pd.Timestamp, datetime, date, str, or int) - Optional - None - Optional historical replay start point.

### Request Example
```python
# Subscribe to all trades for ES futures
sub = client.subscribe(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    stype_in='parent',
    schema='trades'
)
```

### Response
#### Success Response (200)
- **SubscriptionRequest** (`SubscriptionRequest`) - The subscription request object

#### Response Example
None
```

--------------------------------

### Subscribe to Market Data

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/live.md

Create and send a subscription request for market data. Specify the dataset, symbols, schema, and symbology types. An optional historical replay start point can also be provided.

```python
# Subscribe to all trades for ES futures
sub = client.subscribe(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    stype_in='parent',
    schema='trades'
)
```

--------------------------------

### Query Metadata with Databento

Source: https://github.com/databento/databento-python/blob/main/_autodocs/QUICKSTART.md

Access metadata about datasets, schemas, and other information using the `metadata` API. You can list all available datasets, get details for a specific dataset, list schemas for a dataset, and retrieve schema definitions.

```python
import databento as db

client = db.Historical()

# List all datasets
datasets = client.metadata.list_datasets()
print(datasets)

# Get dataset details
info = client.metadata.get_dataset('GLBX.MDP3')
print(info['description'])

# List available schemas
schemas = client.metadata.list_schemas('GLBX.MDP3')
print(schemas)  # ['mbo', 'mbp-1', 'trades', 'ohlcv-1m', ...]

# Get schema definition
schema_def = client.metadata.get_schema('GLBX.MDP3', 'trades')
```

--------------------------------

### Map Symbols in JSON Files

Source: https://github.com/databento/databento-python/blob/main/_autodocs/QUICKSTART.md

Map symbols in a JSON file using a symbology mapping file. The output is written to a new JSON file. Requires 'databento' to be installed.

```python
import databento as db

# Map symbols in JSON file
output = db.map_symbols_json(
    symbology_file='symbology.json',
    json_file='data.json',
    out_file='data_mapped.json'
)
```

--------------------------------

### Initialize Live Client

Source: https://github.com/databento/databento-python/blob/main/_autodocs/configuration.md

Instantiate the Live client with default settings. The API key will be read from the DATABENTO_API_KEY environment variable.

```python
import databento as db

# Basic configuration
client = db.Live()
```

--------------------------------

### Initialize Live Client

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/live.md

Initialize the live client with your API key. You can also enable automatic reconnection and Zstandard compression.

```python
import databento as db

# Initialize live client
client = db.Live('YOUR_API_KEY')
```

```python
client = db.Live(
    key='YOUR_API_KEY',
    reconnect_policy='reconnect',
    compression='zstd'
)
```

--------------------------------

### Configure Live Client with Reconnection and Compression

Source: https://github.com/databento/databento-python/blob/main/_autodocs/configuration.md

Initialize the Live client with a specific API key, enable automatic reconnection, set a heartbeat interval, and enable Zstandard compression for live data.

```python
client = db.Live(
    key='db-...',
    reconnect_policy='reconnect',
    compression='zstd',
    heartbeat_interval_s=10
)
```

--------------------------------

### Get Dataset Details

Source: https://github.com/databento/databento-python/blob/main/_autodocs/endpoints.md

Retrieves detailed information for a specific dataset.

```APIDOC
## GET /metadata.get_dataset

### Description
Get details for a specific dataset.

### Method
GET

### Endpoint
/metadata.get_dataset

### Python Method
`Historical.metadata.get_dataset()`

### Query Parameters
#### Query Parameters
- **dataset** (string) - Required - Dataset code

### Response
#### Success Response (200)
- Content-Type: application/json
- Body: Dataset details dictionary
- Returns: dict[str, Any]
```

--------------------------------

### Initialize Reference Client

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/reference.md

Instantiate the Reference client using either an explicit API key or by relying on the DATABENTO_API_KEY environment variable. Access sub-APIs like security_master after initialization.

```python
import databento as db

# Initialize with explicit API key
client = db.Reference('YOUR_API_KEY')

# Or use DATABENTO_API_KEY environment variable
client = db.Reference()

# Access sub-APIs
securities = client.security_master.get_securities(
    dataset='GLBX.MDP3',
    symbols='ES.FUT'
)
```

--------------------------------

### Get Instrument Definitions

Source: https://github.com/databento/databento-python/blob/main/_autodocs/endpoints.md

Retrieves instrument definitions based on provided criteria.

```APIDOC
## POST /metadata.get_instrument

### Description
Get instrument definitions.

### Method
POST

### Endpoint
/metadata.get_instrument

### Python Method
`Historical.metadata.get_instrument()`

### Request Body Parameters
#### Request Body Parameters
- **dataset** (string) - Required - Dataset code
- **symbols** (string) - Optional - Comma-separated symbols
- **stype_in** (string) - Optional (default: raw_symbol) - Input symbology type
- **date** (string) - Optional - Date for historical definitions
- **pretty_px** (boolean) - Optional - Format prices
- **pretty_ts** (boolean) - Optional - Format timestamps

### Response
#### Success Response (200)
- Content-Type: application/json
- Body: Instrument definition data
- Returns: dict[str, Any]
```

--------------------------------

### Get Schema Definition

Source: https://github.com/databento/databento-python/blob/main/_autodocs/endpoints.md

Retrieves the definition for a specific schema within a dataset.

```APIDOC
## GET /metadata.get_schema

### Description
Get schema definition.

### Method
GET

### Endpoint
/metadata.get_schema

### Python Method
`Historical.metadata.get_schema()`

### Query Parameters
#### Query Parameters
- **dataset** (string) - Required - Dataset code
- **schema** (string) - Required - Schema name
- **encoding** (string) - Optional (default: json) - json or dbn

### Response
#### Success Response (200)
- Content-Type: application/json
- Body: Schema definition dictionary
- Returns: dict[str, Any]
```

--------------------------------

### Configure Live Client for Slow Readers

Source: https://github.com/databento/databento-python/blob/main/_autodocs/configuration.md

Initialize the Live client and configure it to skip records when the client falls behind, preventing potential memory issues.

```python
client = db.Live(
    slow_reader_behavior='skip'
)
```

--------------------------------

### Get Batch Job Details

Source: https://github.com/databento/databento-python/blob/main/_autodocs/README.md

Retrieve detailed status information for a specific batch job.

```APIDOC
## GET /batch.get_job_details

### Description
Retrieve detailed status information for a specific batch job.

### Method
GET

### Endpoint
/batch.get_job_details

### Query Parameters
- **job_id** (string) - Required - The ID of the batch job.

### Response
#### Success Response (200)
- **job_details** (object) - An object containing the detailed status of the batch job.
```

--------------------------------

### Set Up Parameters for Data Cost Query

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Instantiate a dictionary with query parameters such as dataset, symbols, symbology type, schema, and time range to prepare for a data cost request.

```python
params = {
    "dataset": "GLBX.MDP3",
    "symbols": "ES.FUT",
    "stype_in": "parent",
    "schema": "mbo",
    "start": "2022-06-10T14:30",
    "end": "2022-06-11",
}
```

--------------------------------

### Get Batch Job Details

Source: https://github.com/databento/databento-python/blob/main/_autodocs/endpoints.md

Retrieve detailed information for a specific batch job using its unique identifier.

```APIDOC
## GET /batch.get_job_details

### Description
Get details for a specific batch job.

### Method
GET

### Endpoint
/batch.get_job_details

### Parameters
#### Query Parameters
- **job_id** (string) - Yes - The job identifier

### Response
#### Success Response (200)
- Content-Type: application/json
- Body: Job details dictionary

### Response Example
```json
{
  "id": "job_12345",
  "state": "done",
  "created_at": "2023-10-27T10:00:00Z"
}
```

### Request Example
```python
details = client.batch.get_job_details('job_12345')
print(f"State: {details['state']}")
```
```

--------------------------------

### Initialize Historical Client with Minimal Configuration

Source: https://github.com/databento/databento-python/blob/main/_autodocs/configuration.md

Initialize the Historical client using default settings, relying on the DATABENTO_API_KEY environment variable for authentication. The default gateway is HistoricalGateway.BO1.

```python
import databento as db

# Minimal configuration (uses environment variable)
client = db.Historical()
```

--------------------------------

### Get API Version - Python

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/utility-functions.md

Retrieve the API version number used by the Databento client library. This is useful for compatibility checks.

```python
import databento as db

print(f"Using API version: {db.API_VERSION}")
```

--------------------------------

### Live Client Constructor

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/live.md

Initializes a managed TCP connection to the Databento Live Subscription Gateway. Allows configuration of API key, gateway, port, timestamping, heartbeat, reconnection, slow reader behavior, and compression.

```APIDOC
## Live Client Constructor

### Description
Initializes a managed TCP connection to the Databento Live Subscription Gateway. Allows configuration of API key, gateway, port, timestamping, heartbeat, reconnection, slow reader behavior, and compression.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **key** (str) - Optional - None - The user API key for authentication. If None, uses `DATABENTO_API_KEY` environment variable.
- **gateway** (str) - Optional - None - The remote gateway to connect to; for advanced use.
- **port** (int) - Optional - 13000 - The remote port to connect to; for advanced use.
- **ts_out** (bool) - Optional - False - If set, DBN records will be timestamped when sent by the gateway.
- **heartbeat_interval_s** (int) - Optional - None - The interval in seconds at which gateway sends heartbeats if no other data. Minimum 5 seconds.
- **reconnect_policy** (ReconnectPolicy or str) - Optional - ReconnectPolicy.NONE - Reconnection policy: 'none' (default) or 'reconnect' for automatic reconnection.
- **slow_reader_behavior** (SlowReaderBehavior or str) - Optional - None - Gateway behavior when client falls behind: 'skip' (skip records) or 'warn' (send warning).
- **compression** (Compression) - Optional - Compression.NONE - Compression format: 'none' (default) or 'zstd' for Zstandard compression.

### Request Example
```python
import databento as db

# Initialize live client
client = db.Live('YOUR_API_KEY')

# Initialize with reconnect enabled
client = db.Live(
    key='YOUR_API_KEY',
    reconnect_policy='reconnect',
    compression='zstd'
)
```

### Response
#### Success Response (200)
None

#### Response Example
None

### Raises
- `ValueError` — If API key is invalid or not provided
```

--------------------------------

### Standard Import of Databento

Source: https://github.com/databento/databento-python/blob/main/_autodocs/module-structure.md

Use this method for a straightforward import where all public APIs are accessed via the 'db' prefix. Instantiate the Historical client with your API key.

```python
import databento as db

# All public APIs accessible via db prefix
client = db.Historical('YOUR_API_KEY')
```

--------------------------------

### MappingIntervalDict TypedDict

Source: https://github.com/databento/databento-python/blob/main/_autodocs/types.md

Defines the structure for a dictionary representing a symbol mapping over a date range. Includes start date, end date, and the symbol.

```python
class MappingIntervalDict(TypedDict):
    """Represents a symbol mapping over a start and end date range interval.
    
    Parameters
    ----------
    start_date : dt.date
        The start of the mapping period.
    end_date : dt.date
        The end of the mapping period.
    symbol : str
        The symbol value.
    """
    start_date: dt.date
    end_date: dt.date
    symbol: str
```

--------------------------------

### MappingInterval Class

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/instrument-map.md

Represents a symbol mapping that is valid during a specific date range. It includes the start date, end date (exclusive), and the symbol string.

```APIDOC
## MappingInterval Class

### Description
Represents a symbol mapping that is valid during a specific date range.

### Attributes
- **start_date** (dt.date) - The start time of the interval.
- **end_date** (dt.date) - The end time of the interval (exclusive).
- **symbol** (str) - The string symbol.

### Example
```python
from databento.common.symbology import MappingInterval
import datetime as dt

mapping = MappingInterval(
    start_date=dt.date(2022, 1, 1),
    end_date=dt.date(2022, 12, 31),
    symbol='ES.FUT'
)

print(f"Valid from {mapping.start_date} to {mapping.end_date}: {mapping.symbol}")
```
```

--------------------------------

### Initialize Databento Historical Client and Fetch Data

Source: https://github.com/databento/databento-python/blob/main/README.md

Instantiate the historical client with an API key and retrieve a range of time series data. The data can then be replayed using a callback function.

```python
import databento as db

client = db.Historical('YOUR_API_KEY')
data = client.timeseries.get_range(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    stype_in='parent',
    start='2022-06-10T14:30',
    end='2022-06-10T14:40',
)

data.replay(callback=print)  # market replay, with `print` as event handler
```

--------------------------------

### Reference Client Constructor

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/reference.md

Initializes the Reference client. It can be initialized with an explicit API key or by using the DATABENTO_API_KEY environment variable. It also allows specifying the API gateway.

```APIDOC
## Initialize Reference Client

### Description
Initializes the Reference client with optional API key and gateway.

### Method
`Reference(key: str | None = None, gateway: HistoricalGateway | str = HistoricalGateway.BO1)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import databento as db

# Initialize with explicit API key
client = db.Reference('YOUR_API_KEY')

# Or use DATABENTO_API_KEY environment variable
client = db.Reference()
```

### Response
#### Success Response (200)
Reference client instance with access to security master, corporate actions, and adjustment factors APIs.

#### Response Example
None

### Raises
- `ValueError` — If API key is invalid or not provided
```

--------------------------------

### Handle BentoDeprecationWarning

Source: https://github.com/databento/databento-python/blob/main/_autodocs/errors.md

Example of how to capture and handle `BentoDeprecationWarning` by setting the warnings filter to 'error'. This is useful for testing or ensuring that deprecated features are not accidentally used.

```python
import warnings
import databento as db

# Capture deprecation warnings
warnings.filterwarnings('error', category=db.BentoDeprecationWarning)

try:
    client = db.Historical('YOUR_API_KEY')
    # Some deprecated method call
except db.BentoDeprecationWarning as w:
    print(f"Deprecated: {w}")
```

--------------------------------

### Initialize Databento Client with Environment Variable

Source: https://github.com/databento/databento-python/blob/main/README.md

Configure the Databento client by omitting the API key parameter to use the DATABENTO_API_KEY environment variable. This is the recommended approach for production applications.

```python
import databento as db

# Pass as parameter
client = db.Historical('YOUR_API_KEY')

# Or, pass as `DATABENTO_API_KEY` environment variable
client = db.Historical()
```

--------------------------------

### Initialize Historical Client

Source: https://github.com/databento/databento-python/blob/main/_autodocs/configuration.md

Initialize the Historical client with optional API key and gateway. Defaults to BO1 gateway.

```python
Reference(
    key: str | None = None,
    gateway: HistoricalGateway | str = HistoricalGateway.BO1,
)
```

--------------------------------

### Get Instrument Details

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/metadata.md

Retrieve instrument definitions for a specific symbol on a given date. Requires specifying the dataset, symbol, input symbology type, and date.

```python
client.metadata.get_instrument(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    stype_in='parent',
    date='2022-06-10'
)
```

--------------------------------

### Historical Client Constructor

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/historical.md

Initializes the Historical client. It can be configured with an explicit API key and gateway, or by using environment variables.

```APIDOC
## Historical Client Constructor

### Description
Initializes the Historical client, providing access to historical market data and metadata. It can be configured with an explicit API key and gateway, or by using environment variables.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Constructor Signature
```python
Historical(
    key: str | None = None,
    gateway: HistoricalGateway | str = HistoricalGateway.BO1,
)
```

### Parameters
#### Parameters
- **key** (str) - Optional - None - The user API key for authentication. If None, uses `DATABENTO_API_KEY` environment variable.
- **gateway** (HistoricalGateway or str) - Optional - HistoricalGateway.BO1 - The API server gateway. Options: `HistoricalGateway.BO1` or string URL.

### Returns
Historical client instance with access to timeseries, batch, metadata, and symbology APIs.

### Raises
- `ValueError` — If API key is invalid or not provided

### Example
```python
import databento as db

# Initialize with explicit API key
client = db.Historical('YOUR_API_KEY')

# Or use DATABENTO_API_KEY environment variable
client = db.Historical()

# Access sub-APIs
data = client.timeseries.get_range(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    start='2022-06-10'
)
```
```

--------------------------------

### Get Schema Specification

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/metadata.md

Request detailed schema encoding specification from Databento for a given dataset and schema name. You can specify the encoding format, such as JSON or DBN.

```python
# Get trades schema in JSON format
schema = client.metadata.get_schema('GLBX.MDP3', 'trades', 'json')

# Get MBO schema in DBN encoding
schema = client.metadata.get_schema('XNAS.ITCH', 'mbo', 'dbn')
```

--------------------------------

### List Fields for a Schema

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Use `list_fields` to get detailed information about the fields within a specific data schema and encoding. This helps in understanding the structure of the data.

```python
client.metadata.list_fields(schema="mbo", encoding="dbn")
```

--------------------------------

### Initialize Historical Client

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/historical.md

Initialize the Historical client with an explicit API key or by relying on the DATABENTO_API_KEY environment variable. Access sub-APIs like timeseries for data retrieval.

```python
import databento as db

# Initialize with explicit API key
client = db.Historical('YOUR_API_KEY')

# Or use DATABENTO_API_KEY environment variable
client = db.Historical()

# Access sub-APIs
data = client.timeseries.get_range(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    start='2022-06-10'
)
```

--------------------------------

### Stream Live Data with Databento

Source: https://github.com/databento/databento-python/blob/main/_autodocs/00_START_HERE.md

Utilize the Live client to subscribe to and stream real-time market data. A handler function is required to process incoming records, such as printing the price.

```python
live = db.Live()
live.subscribe(dataset='GLBX.MDP3', symbols='ES.FUT')
live.start(handler=lambda record: print(record.price))
```

--------------------------------

### Handle BentoHttpError in Python

Source: https://github.com/databento/databento-python/blob/main/_autodocs/errors.md

Catch and handle HTTP-related errors from Databento API calls. This example demonstrates how to access the HTTP status, message, and request ID from a BentoHttpError.

```python
import databento as db

try:
    client = db.Historical('INVALID_KEY')
    data = client.timeseries.get_range(
        dataset='GLBX.MDP3',
        symbols='ES.FUT',
        start='2022-06-10'
    )
except db.BentoHttpError as e:
    print(f"HTTP Status: {e.http_status}")
    print(f"Message: {e.message}")
    print(f"Request ID: {e.request_id}")
```

--------------------------------

### Initialize Historical Client with Custom Gateway

Source: https://github.com/databento/databento-python/blob/main/_autodocs/configuration.md

Initialize the Historical client with a custom gateway URL. This is an advanced configuration option, typically used for specific network or testing scenarios.

```python
import databento as db

# Custom gateway (advanced)
client = db.Historical(
    key='db-...',
    gateway='https://hist.databento.com'
)
```

--------------------------------

### Map Symbols in CSV Files

Source: https://github.com/databento/databento-python/blob/main/_autodocs/QUICKSTART.md

Map symbols in a CSV file using a symbology mapping file. The output is written to a new CSV file. Requires 'databento' to be installed.

```python
import databento as db

# Map symbols in CSV file
output = db.map_symbols_csv(
    symbology_file='symbology.json',
    csv_file='data.csv',
    out_file='data_mapped.csv'
)
```

--------------------------------

### Initialize Historical Client with Explicit API Key

Source: https://github.com/databento/databento-python/blob/main/_autodocs/configuration.md

Initialize the Historical client by providing the API key directly as a constructor parameter. This overrides any value set in the DATABENTO_API_KEY environment variable.

```python
import databento as db

# Explicit key
client = db.Historical('db-...')
```

--------------------------------

### Create DBNStore from File

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/dbnstore.md

Load DBN data from a file on disk. Ensure the file exists and is readable. The data can then be converted to a DataFrame.

```python
import databento as db

# Load from a .dbn file
store = db.DBNStore.from_file('market_data.dbn.zst')

# Convert to DataFrame
df = store.to_df()
```

--------------------------------

### Handle BentoServerError for Server Errors

Source: https://github.com/databento/databento-python/blob/main/_autodocs/errors.md

Catch BentoServerError to handle server-side 5xx HTTP errors. This example shows how to implement a retry mechanism with a delay when a service is temporarily unavailable.

```python
import time

try:
    client = db.Historical('YOUR_API_KEY')
    data = client.timeseries.get_range(
        dataset='GLBX.MDP3',
        symbols='ES.FUT',
        start='2022-06-10'
    )
except db.BentoServerError as e:
    if e.http_status == 503:
        print("Service unavailable, retrying in 5 seconds...")
        time.sleep(5)
```

--------------------------------

### Set Databento API Key

Source: https://github.com/databento/databento-python/blob/main/_autodocs/QUICKSTART.md

Configure your Databento API key. Use an environment variable for production or pass it directly for development.

```bash
export DATABENTO_API_KEY=db-...
```

```python
import databento as db

client = db.Historical('db-...')
```

--------------------------------

### Fetch Historical Data Asynchronously

Source: https://github.com/databento/databento-python/blob/main/_autodocs/QUICKSTART.md

Use this snippet to fetch historical time-series data asynchronously. Ensure you have the 'asyncio' library and 'databento' installed. The client is initialized within the async function.

```python
import asyncio
import databento as db

async def fetch_data():
    client = db.Historical()
    
    # Async request
    data = await client.timeseries.get_range_async(
        dataset='GLBX.MDP3',
        symbols='ES.FUT',
        start='2022-06-10'
    )
    
    return data

# Run async
data = asyncio.run(fetch_data())
```

--------------------------------

### Live Data Performance Configuration

Source: https://github.com/databento/databento-python/blob/main/_autodocs/configuration.md

Optimize live data client configuration for high-throughput scenarios. Options include reducing bandwidth usage with compression, adjusting heartbeat intervals, and configuring behavior for slow readers.

```python
import databento as db

# Optimize for high-throughput scenarios
client = db.Live(
    compression='zstd',           # Reduce bandwidth
    heartbeat_interval_s=30,      # Longer heartbeat interval
    slow_reader_behavior='skip'   # Skip records if behind
)
```

--------------------------------

### Get Batch Job Details

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/batch.md

Retrieve the full details of a submitted batch job using its unique identifier. This is useful for monitoring job status and accessing file information once the job is complete.

```python
job_details = client.batch.get_job_details('job_123')
print(job_details['state'])  # 'done', 'processing', etc.
```

--------------------------------

### download

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/batch.md

Download a batch job or a specific file to {output_dir}/{job_id}/. Automatically generates necessary directories if they do not already exist.

```APIDOC
## download

### Description
Download a batch job or a specific file to `{output_dir}/{job_id}/`. Automatically generates necessary directories if they do not already exist.

### Method
GET

### Endpoint
/batch.download

### Parameters
#### Query Parameters
- **job_id** (str) - Required - The batch job identifier.
- **output_dir** (PathLike[str] or str) - Optional - The directory to download files to. Defaults to current working directory. Default: None
- **filename_to_download** (str) - Optional - Specific file to download. If None, downloads all files. Default: None
- **keep_zip** (bool) - Optional - If True, saves files as .zip archive. Cannot be used with `filename_to_download`. Default: False

### Response
#### Success Response (200)
- **list[Path]** — List of paths to downloaded files

### Raises
- **RuntimeError** — If no files found for the batch job
- **ValueError** — If file download fails or invalid parameter combination
```

--------------------------------

### DBNStore.from_file

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/dbnstore.md

Creates a DBNStore instance from a DBN-encoded file on disk. Supports compressed files (e.g., .dbn.zst).

```APIDOC
## DBNStore.from_file

### Description
Creates a DBNStore from a file on disk.

### Method
`classmethod`

### Signature
`from_file(path: PathLike[str] | str) -> DBNStore`

### Parameters
#### Path Parameters
- **path** (PathLike[str] or str) - Required - Path to a DBN-encoded file.

### Returns
- `DBNStore` — Instance backed by the file data

### Raises
- `ValueError` — If the file does not exist or is not readable

### Example
```python
import databento as db

# Load from a .dbn file
store = db.DBNStore.from_file('market_data.dbn.zst')

# Convert to DataFrame
df = store.to_df()
```
```

--------------------------------

### List Available Datasets

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Use `client.metadata.list_datasets()` to retrieve a list of all available datasets. This helps in identifying specific datasets for data retrieval.

```python
client.metadata.list_datasets()
```

--------------------------------

### Set API Key via Environment Variable

Source: https://github.com/databento/databento-python/blob/main/_autodocs/README.md

Configures the Databento client by setting the DATABENTO_API_KEY environment variable. This is the recommended method for API key management.

```bash
export DATABENTO_API_KEY=db-...
```

--------------------------------

### Submit Batch Download Job

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

The client library can initiate batch download requests to the Databento API. Specify dataset, symbols, schema, time range, and delivery options. The `limit` parameter restricts the number of records requested.

```python
new_job = client.batch.submit_job(
    dataset="GLBX.MDP3",
    symbols=["ESH1"],
    schema="trades",
    start="2020-12-27T12:00",
    end="2020-12-29",
    encoding="dbn",
    delivery="download",
    limit=1000,  # <-- request limited to 1000 records
)
new_job_id = new_job["id"]

new_job
```

--------------------------------

### List Unit Prices for a Dataset

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Use `list_unit_prices` to find the cost per gigabyte for different data schemas and modes (historical, live, etc.) for a given dataset. This is essential for cost estimation.

```python
client.metadata.list_unit_prices(dataset="GLBX.MDP3")
```

--------------------------------

### Write DBN data to CSV

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/dbnstore.md

Export DBN data to a CSV file or as a CSV string. This method supports pretty printing for prices and timestamps, and inclusion of symbols. Specify a path to write to a file, or omit it to get a string.

```python
# Write to file
path = store.to_csv('output.csv', pretty_px=True, map_symbols=True)

# Get CSV as string
csv_str = store.to_csv(pretty_px=True)
```

--------------------------------

### List Schemas for a Dataset

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/metadata.md

Request all available data schemas from Databento for a specific dataset. This helps in understanding the different data formats available for a given dataset.

```python
# Get schemas for a specific dataset
schemas = client.metadata.list_schemas('GLBX.MDP3')

for schema in schemas:
    print(schema)  # e.g., 'mbo', 'mbp-1', 'trades', 'ohlcv-1m'
```

--------------------------------

### Get Historical Data Range

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/timeseries.md

Use `get_range` to request historical time series data for a specified dataset, symbol, and time range. This method is synchronous and will block until the data is retrieved. The data can be processed directly or saved to disk.

```python
import databento as db

client = db.Historical('YOUR_API_KEY')

# Get ES futures data for a specific time range
data = client.timeseries.get_range(
    dataset='GLBX.MDP3',
    symbols='ES.FUT',
    stype_in='parent',
    start='2022-06-10T14:30',
    end='2022-06-10T14:40',
    schema='trades'
)

# Iterate over records
data.replay(callback=print)

# Convert to DataFrame
df = data.to_df()

# Convert to numpy array
array = data.to_ndarray()
```

--------------------------------

### Get Historical Data Range Asynchronously

Source: https://github.com/databento/databento-python/blob/main/_autodocs/api-reference/timeseries.md

Use `get_range_async` for non-blocking retrieval of historical time series data. This is useful in asynchronous applications where you don't want to halt execution while waiting for data. The method returns a `DBNStore` object upon completion.

```python
import asyncio
import databento as db

async def fetch_data():
    client = db.Historical('YOUR_API_KEY')
    data = await client.timeseries.get_range_async(
        dataset='GLBX.MDP3',
        symbols='ES.FUT',
        start='2022-06-10T14:30',
        end='2022-06-10T14:40'
    )
    return data

# Run async operation
data = asyncio.run(fetch_data())
```

--------------------------------

### Write Data to DBN File

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Use the `.to_file()` method to save raw DBN (Databento Binary) data directly to disk. This is efficient for storing large datasets in Databento's native format.

```python
data.to_file("test.dbn")
```

--------------------------------

### Get Historical Data with Databento

Source: https://github.com/databento/databento-python/blob/main/_autodocs/QUICKSTART.md

Fetch historical time-series data using the `timeseries.get_range` method. The client automatically uses the `DATABENTO_API_KEY` environment variable if not provided directly. Data can be converted to pandas DataFrames, NumPy arrays, or saved to CSV, JSON, or Parquet files.

```python
import databento as db

client = db.Historical()  # Uses DATABENTO_API_KEY

# Fetch trades data
data = client.timeseries.get_range(
    dataset='GLBX.MDP3',      # CME Globex
    symbols='ES.FUT',          # S&P 500 E-mini futures
    start='2022-06-10',
    end='2022-06-11'
)

# Convert to pandas DataFrame
df = data.to_df(pretty_px=True, map_symbols=True)
print(df.head())

# Convert to numpy array
array = data.to_ndarray()

# Write to CSV
data.to_csv('trades.csv', pretty_px=True)

# Write to JSON
data.to_json('trades.json')

# Write to Parquet
data.to_parquet('trades.parquet')
```

--------------------------------

### List Available Publishers

Source: https://github.com/databento/databento-python/blob/main/notebooks/quickstart.ipynb

Use `client.metadata.list_publishers()` to retrieve a list of all available data publishers. This is useful for understanding the sources of data.

```python
client.metadata.list_publishers()
```