Dates and Datetimes

xbbg accepts native Python date and datetime types on every API surface that takes a date or datetime. You no longer need to pre-format values to strings before calling bdh, bdib, bdtick, or any of the xbbg.ext helpers — pass a datetime.date, datetime.datetime, or a pandas.Timestamp directly.

Accepted types

For any parameter named start_date, end_date, dt, start_datetime, end_datetime, settle_dt, expiry_dt, or asof:

Type	Example	Notes
`str` (ISO 8601)	`"2023-01-17"`, `"2023-01-17T10:30:00"`, `"2023-01-17T10:30:00-05:00"`	Year-leading. Tz suffix preserved.
`str` (Bloomberg-native)	`"20230117"`	Compact form, no separators.
`str` (“today”)	`"today"`	Case-insensitive. Resolves to today’s date.
`datetime.date`	`date(2023, 1, 17)`	Date portion only.
`datetime.datetime` (naive)	`datetime(2023, 1, 17, 10, 30)`	For datetime params, naive values are interpreted via `request_tz`.
`datetime.datetime` (aware)	`datetime(2023, 1, 17, tzinfo=ZoneInfo("America/New_York"))`	Timezone preserved end-to-end.
`pandas.Timestamp`	`pd.Timestamp("2023-01-17")`	Detected via duck-typing — pandas is not a hard dependency.

Rejected formats

xbbg rejects ambiguous month/day strings instead of guessing:

blp.bdh("AAPL US Equity", "PX_LAST", start_date="01/17/2023")
# ValueError: Ambiguous date format '01/17/2023': month/day order cannot be inferred.
# Use ISO 8601 (YYYY-MM-DD), Bloomberg-native (YYYYMMDD), or pass a
# datetime.date / datetime.datetime object.

Examples

Historical data

from datetime import date

import pandas as pd
from xbbg import blp

# String, date, datetime, and pd.Timestamp all work interchangeably.
df = blp.bdh("AAPL US Equity", "PX_LAST", start_date="2023-01-01", end_date="today")
df = blp.bdh("AAPL US Equity", "PX_LAST", start_date=date(2023, 1, 1))
df = blp.bdh("AAPL US Equity", "PX_LAST", start_date=pd.Timestamp("2023-01-01"))

Intraday bars and ticks

from datetime import datetime
from zoneinfo import ZoneInfo

# Naive datetimes are interpreted using request_tz (default UTC).
df = blp.bdtick(
    "AAPL US Equity",
    start_datetime=datetime(2024, 12, 1, 9, 30),
    end_datetime=datetime(2024, 12, 1, 16, 0),
    request_tz="exchange",
)

# Tz-aware datetimes preserve their own zone — request_tz is ignored.
df = blp.bdtick(
    "AAPL US Equity",
    start_datetime=datetime(2024, 12, 1, 9, 30, tzinfo=ZoneInfo("America/New_York")),
    end_datetime=datetime(2024, 12, 1, 16, 0, tzinfo=ZoneInfo("America/New_York")),
)

Override-path date values

Bloomberg field overrides (passed as **kwargs) also accept native types. Date-typed values are normalized to YYYYMMDD automatically:

from datetime import date

# USER_LOCAL_TRADE_DATE is a Bloomberg date-typed override.
df = blp.bdp(
    "AAPL US Equity",
    "PX_LAST",
    USER_LOCAL_TRADE_DATE=date(2023, 1, 17),  # -> "20230117"
)

Bond and option settlement / expiry

from datetime import date

from xbbg.ext.bonds import bond_risk
from xbbg.ext.fixed_income import yas
from xbbg.ext.options import option_chain

bond_risk("T 4.5 05/15/38 Govt", settle_dt=date(2024, 6, 15))
yas("US912810TM69 Govt", "YAS_BOND_YLD", settle_dt=date(2024, 6, 15))
option_chain("AAPL US Equity", expiry_dt=date(2025, 1, 17))

Timezone semantics for intraday requests

Input shape	Interpretation
`datetime` naive + `request_tz=None` (default)	Treated as UTC.
`datetime` naive + `request_tz="exchange"`	Treated as the security’s exchange timezone.
`datetime` naive + `request_tz="America/New_York"` (any IANA zone)	Treated in that zone.
`datetime` aware	Tz preserved; `request_tz` is ignored.
`pd.Timestamp` (with `tz`)	Same as aware datetime.
`pd.Timestamp` (without `tz`)	Same as naive datetime.