sessions

When a tick may be a real trading tick, by exchange and kind of instrument.

Brokers keep their sockets open outside trading hours and send what they have: a reconnect on a Sunday replays Friday's last state, and the exchanges' Saturday mock sessions stream prices that never traded. Stored as live ticks those would be wrong twice over - wrong prices, and stamped with a time at which nothing traded - so the unified service drops any tick received outside its instrument's window.

The window is wider than the trading session on both sides. It opens at 09:00 India time to keep the pre-open auction, and closes after the session to keep the closing prices brokers publish in the minutes after it. trading_close is the session's own end, which a policy that trusts a broker's close only while the session is running needs separately.

Which days trade comes from the exchanges' own calendars, one YAML file a year in calendars/, generated from each exchange's publication. They are kept per exchange and per calendar, because the segments of one exchange do not close together: currency derivatives also close on bank holidays the equity segment trades through, and the commodity segments close their 09:00-17:00 morning session and their 17:00 evening session separately - on most equity holidays the evening session still trades. Special sessions, such as Muhurat trading on Diwali, open a window on a day that is otherwise closed.

A day missing from a calendar - a year whose file has not been added yet, or a closure announced later by circular - is treated as a trading day. That costs at most one duplicate snapshot row per instrument when a feed reconnects, because an unchanged tick is dropped by the pipeline's de-duplication, whereas a trading day wrongly marked closed would lose a session.

Times are compared as seconds after midnight India time, computed from the epoch with a fixed offset: India has no daylight saving, so the arithmetic is exact and costs nothing per tick.

Classes:

Name	Description
TradingCalendar	The exchanges' holidays and special sessions, by exchange and calendar.
SessionGate	Answers "is this instant inside this instrument's window", fast enough to ask on every tick.

Functions:

Name	Description
session_for	The session window an instrument's ticks are accepted in.
india_day_number	The India trading day an instant falls on, as whole days since 1970-01-01.
india_date	The India calendar date an instant falls on.
day_start_epoch	The instant India midnight begins a day.
default_calendar	The calendar loaded from calendars/, read once per process.

TradingCalendar

TradingCalendar(closures=None, special_sessions=None, years=())

The exchanges' holidays and special sessions, by exchange and calendar.

Attributes:

Name	Type	Description
closures	dict	(exchange, calendar) to {date: "all" | "morning" | "evening"}.
special_sessions	dict	(exchange, calendar) to {date: (opens, closes)} in seconds after midnight.
years	list[int]	The years loaded.

Build a calendar from its tables.

Parameters:

Name	Type	Description	Default
closures	dict | None	(exchange, calendar) to {date: "all" | "morning" | "evening"}.	None
special_sessions	dict | None	(exchange, calendar) to {date: (opens, closes)}.	None
years	tuple[int]	The years the tables cover.	()

Returns:

Type	Description
None	This function returns nothing.

Example programs

Holidays in the 2026 fileBuilding and checking a calendar

examples/stock_brokers/instruments/ticks/utilities/sessions/TradingCalendar/example_1_holidays_in_the_2026_file.py

"""Loads the exchanges' 2026 calendar and asks what is closed on a few dates.

`TradingCalendar.load` reads every `<year>.yaml` file in `stock_brokers/instruments/ticks/utilities/calendars/`, which were generated from each exchange's own publication. Holidays are kept per exchange and per calendar, because one exchange's segments do not close together: on Ganesh Chaturthi (Monday 2026-09-14) NSE equities are closed all day while MCX commodities close only their morning session, and on New Year's Day MCX closes only its evening. A currency-only bank holiday closes the currency calendar while equities trade.

`closure` answers "all", "morning", "evening" or None for a date that is not listed. `special_session` answers the window of a special session, such as the Diwali Muhurat session on Sunday 2026-11-08, as seconds after midnight India time; the program also prints it as clock times. The Muhurat timings had not been notified when the file was written, so it holds the whole day open, 09:00 to 23:59:59, on every exchange and calendar. The files are part of the repository, so the program reads nothing outside it and needs no data store.

Run it from the project root:

    python examples/stock_brokers/instruments/ticks/utilities/sessions/TradingCalendar/example_1_holidays_in_the_2026_file.py
"""

import datetime

from stock_brokers.instruments.ticks.utilities.sessions import (
    TradingCalendar,
)


class HolidaysIn2026Example:
    """Asks the loaded 2026 calendar about closures and special sessions.

    Attributes:
        calendar (TradingCalendar): The calendar loaded from the repository's files.
    """

    def __init__(self):
        """Loads the calendar.

        Returns:
            None: This method returns nothing.
        """
        self.calendar = TradingCalendar.load()

    def clock(self, seconds):
        """Formats seconds after midnight as a clock time.

        Args:
            seconds (int): Seconds after midnight.

        Returns:
            str: The time as HH:MM.
        """
        hours = seconds // 3600
        minutes = seconds % 3600 // 60
        return f'{hours:02d}:{minutes:02d}'

    def print_closure(self, exchange, calendar_name, day):
        """Prints what of a day is closed for one exchange's calendar.

        Args:
            exchange (str): The canonical exchange.
            calendar_name (str): "equity", "currency" or "commodity".
            day (datetime.date): The date.

        Returns:
            None: This method returns nothing.
        """
        closed = self.calendar.closure(exchange, calendar_name, day)
        print(f'{day} {exchange} {calendar_name}: closed {closed}')

    def print_special_session(self, exchange, calendar_name, day):
        """Prints the special session held on a day, if any.

        Args:
            exchange (str): The canonical exchange.
            calendar_name (str): "equity", "currency" or "commodity".
            day (datetime.date): The date.

        Returns:
            None: This method returns nothing.
        """
        window = self.calendar.special_session(exchange, calendar_name, day)
        if window is None:
            print(f'{day} {exchange} {calendar_name}: no special session')
            return
        print(f'{day} {exchange} {calendar_name}: special session {window}, {self.clock(window[0])} to {self.clock(window[1])}')

    def run(self):
        """Prints closures and special sessions for chosen dates.

        Returns:
            None: This method returns nothing.
        """
        print(f'Years loaded: {self.calendar.years}')
        ganesh_chaturthi = datetime.date(2026, 9, 14)
        self.print_closure('nse', 'equity', ganesh_chaturthi)
        self.print_closure('mcx', 'commodity', ganesh_chaturthi)
        self.print_closure('ncdex', 'commodity', ganesh_chaturthi)
        self.print_closure('mcx', 'commodity', datetime.date(2026, 1, 1))
        bank_holiday = datetime.date(2026, 8, 26)
        self.print_closure('nse', 'currency', bank_holiday)
        self.print_closure('nse', 'equity', bank_holiday)
        self.print_closure('nse', 'equity', datetime.date(2026, 9, 15))
        muhurat = datetime.date(2026, 11, 8)
        self.print_special_session('nse', 'equity', muhurat)
        self.print_special_session('mcx', 'commodity', muhurat)
        self.print_special_session('nse', 'currency', muhurat)


if __name__ == '__main__':
    HolidaysIn2026Example().run()

It prints:

Years loaded: [2026]
2026-09-14 nse equity: closed all
2026-09-14 mcx commodity: closed morning
2026-09-14 ncdex commodity: closed all
2026-01-01 mcx commodity: closed evening
2026-08-26 nse currency: closed all
2026-08-26 nse equity: closed None
2026-09-15 nse equity: closed None
2026-11-08 nse equity: special session (32400, 86399), 09:00 to 23:59
2026-11-08 mcx commodity: special session (32400, 86399), 09:00 to 23:59
2026-11-08 nse currency: special session (32400, 86399), 09:00 to 23:59

examples/stock_brokers/instruments/ticks/utilities/sessions/TradingCalendar/example_2_building_and_checking_a_calendar.py

"""Builds calendars without the repository's files: an empty one, one from tables, and one from a file with a mistake.

`TradingCalendar.empty` gives a calendar with no holidays at all, which is what the offline suites use when a real calendar would get in the way; every weekday then trades. A calendar can also be built directly from its two tables, which is how a test pins down one closure without a file.

`TradingCalendar.load` checks the files it reads: a closure must be "all", "morning" or "evening". The program writes a one-holiday calendar file for an imaginary year into a temporary folder with the closure kind misspelt, and shows the `ValueError` naming the file, exchange, calendar and date. Only the file's name is printed, never the temporary path, so the output is the same on every run. No data store is involved.

Run it from the project root:

    python examples/stock_brokers/instruments/ticks/utilities/sessions/TradingCalendar/example_2_building_and_checking_a_calendar.py
"""

import datetime
import pathlib
import tempfile

from stock_brokers.instruments.ticks.utilities.sessions import (
    TradingCalendar,
)

BAD_FILE = """year: 2027
holidays:
  nse:
    equity:
      - {date: 2027-01-26, closed: allday, name: "Republic Day"}
"""


class BuildingCalendarsExample:
    """Builds an empty calendar, a calendar from tables, and tries to load a bad file.

    Attributes:
        republic_day (datetime.date): The holiday used throughout.
    """

    def __init__(self):
        """Fixes the date asked about.

        Returns:
            None: This method returns nothing.
        """
        self.republic_day = datetime.date(2027, 1, 26)

    def run(self):
        """Prints what each calendar says about the date.

        Returns:
            None: This method returns nothing.
        """
        empty = TradingCalendar.empty()
        print(f'Empty calendar: closure {empty.closure("nse", "equity", self.republic_day)}, special session {empty.special_session("nse", "equity", self.republic_day)}, years {empty.years}')
        closures = {
            (
                'nse',
                'equity',
            ): {
                self.republic_day: 'all',
            },
        }
        special_sessions = {
            (
                'nse',
                'equity',
            ): {
                datetime.date(2027, 10, 31): (
                    18 * 3600,
                    19 * 3600 + 15 * 60,
                ),
            },
        }
        years = (
            2027,
        )
        built = TradingCalendar(closures, special_sessions, years)
        print(f'Built calendar: nse equity on {self.republic_day} closed {built.closure("nse", "equity", self.republic_day)}')
        print(f'Built calendar: nse currency on {self.republic_day} closed {built.closure("nse", "currency", self.republic_day)}')
        print(f'Built calendar: special session on 2027-10-31 {built.special_session("nse", "equity", datetime.date(2027, 10, 31))}')
        with tempfile.TemporaryDirectory() as directory:
            path = pathlib.Path(directory) / '2027.yaml'
            path.write_text(BAD_FILE)
            try:
                TradingCalendar.load(directory)
            except ValueError as error:
                print(f'Loading the misspelt file refused: {error}')


if __name__ == '__main__':
    BuildingCalendarsExample().run()

It prints:

Empty calendar: closure None, special session None, years []
Built calendar: nse equity on 2027-01-26 closed all
Built calendar: nse currency on 2027-01-26 closed None
Built calendar: special session on 2027-10-31 (64800, 69300)
Loading the misspelt file refused: 2027.yaml: nse equity 2027-01-26 closed is 'allday'

Methods:

Name	Description
load	Load every year's calendar file from a directory.
empty	A calendar with no holidays and no special sessions: every weekday trades.
closure	What of a day is closed.
special_session	A special session held on a day, if any.

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def __init__(self, closures=None, special_sessions=None, years=()):
    """
    Build a calendar from its tables.

    Args:
        closures (dict | None): (exchange, calendar) to {date: "all" | "morning" | "evening"}.
        special_sessions (dict | None): (exchange, calendar) to {date: (opens, closes)}.
        years (tuple[int]): The years the tables cover.

    Returns:
        None: This function returns nothing.
    """
    self.closures = closures or {}
    self.special_sessions = special_sessions or {}
    self.years = sorted(years)

load classmethod

load(directory=CALENDAR_DIRECTORY)

Load every year's calendar file from a directory.

Parameters:

Name	Type	Description	Default
directory	Path	The folder holding one <year>.yaml per year.	CALENDAR_DIRECTORY

Returns:

Type	Description
TradingCalendar	The calendar.

Raises:

Type	Description
ValueError	If a file names a closure kind other than all, morning or evening.

Example usage

From example_1_holidays_in_the_2026_file.py

self.calendar = TradingCalendar.load()

From example_2_building_and_checking_a_calendar.py

TradingCalendar.load(directory)

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

@classmethod
def load(cls, directory=CALENDAR_DIRECTORY):
    """
    Load every year's calendar file from a directory.

    Args:
        directory (pathlib.Path): The folder holding one `<year>.yaml` per year.

    Returns:
        TradingCalendar: The calendar.

    Raises:
        ValueError: If a file names a closure kind other than all, morning or evening.
    """
    closures, special_sessions, years = {}, {}, []
    for path in sorted(Path(directory).glob("*.yaml")):
        document = yaml.safe_load(path.read_text()) or {}
        years.append(document.get("year"))
        for exchange, calendars in (document.get("holidays") or {}).items():
            for calendar, entries in calendars.items():
                for entry in entries or []:
                    if entry["closed"] not in ("all", "morning", "evening"):
                        raise ValueError(f"{path.name}: {exchange} {calendar} {entry['date']} closed is {entry['closed']!r}")
                    closures.setdefault((exchange, calendar), {})[entry["date"]] = entry["closed"]
        for entry in document.get("special_sessions") or []:
            window = (_seconds(entry["opens"]), _seconds(entry["closes"]))
            for exchange in entry["exchanges"]:
                for calendar in entry["calendars"]:
                    special_sessions.setdefault((exchange, calendar), {})[entry["date"]] = window
    return cls(closures, special_sessions, years)

empty classmethod

empty()

A calendar with no holidays and no special sessions: every weekday trades.

Returns:

Type	Description
TradingCalendar	The calendar.

Example usage

From example_2_building_and_checking_a_calendar.py

empty = TradingCalendar.empty()

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

@classmethod
def empty(cls):
    """
    A calendar with no holidays and no special sessions: every weekday trades.

    Returns:
        TradingCalendar: The calendar.
    """
    return cls()

closure

closure(exchange, calendar, day)

What of a day is closed.

Parameters:

Name	Type	Description	Default
exchange	str	Canonical exchange.	required
calendar	str	EQUITY, CURRENCY or COMMODITY.	required
day	date	The date.	required

Returns:

Type	Description
str | None	"all", "morning" or "evening", or None when the day is not a listed holiday.

Example usage

From example_1_holidays_in_the_2026_file.py

closed = self.calendar.closure(exchange, calendar_name, day)

From example_2_building_and_checking_a_calendar.py

print(f'Empty calendar: closure {empty.closure("nse", "equity", self.republic_day)}, special session {empty.special_session("nse", "equity", self.republic_day)}, years {empty.years}')

From example_2_building_and_checking_a_calendar.py

print(f'Built calendar: nse equity on {self.republic_day} closed {built.closure("nse", "equity", self.republic_day)}')

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def closure(self, exchange, calendar, day):
    """
    What of a day is closed.

    Args:
        exchange (str): Canonical exchange.
        calendar (str): EQUITY, CURRENCY or COMMODITY.
        day (datetime.date): The date.

    Returns:
        str | None: "all", "morning" or "evening", or None when the day is not a listed holiday.
    """
    return self.closures.get((exchange, calendar), {}).get(day)

special_session

special_session(exchange, calendar, day)

A special session held on a day, if any.

Parameters:

Name	Type	Description	Default
exchange	str	Canonical exchange.	required
calendar	str	EQUITY, CURRENCY or COMMODITY.	required
day	date	The date.	required

Returns:

Type	Description
tuple[int, int] | None	The window's opening and closing seconds after midnight, or None.

Example usage

From example_1_holidays_in_the_2026_file.py

window = self.calendar.special_session(exchange, calendar_name, day)

From example_2_building_and_checking_a_calendar.py

print(f'Empty calendar: closure {empty.closure("nse", "equity", self.republic_day)}, special session {empty.special_session("nse", "equity", self.republic_day)}, years {empty.years}')

From example_2_building_and_checking_a_calendar.py

print(f'Built calendar: special session on 2027-10-31 {built.special_session("nse", "equity", datetime.date(2027, 10, 31))}')

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def special_session(self, exchange, calendar, day):
    """
    A special session held on a day, if any.

    Args:
        exchange (str): Canonical exchange.
        calendar (str): EQUITY, CURRENCY or COMMODITY.
        day (datetime.date): The date.

    Returns:
        tuple[int, int] | None: The window's opening and closing seconds after midnight, or None.
    """
    return self.special_sessions.get((exchange, calendar), {}).get(day)

SessionGate

SessionGate(calendar=None)

Answers "is this instant inside this instrument's window", fast enough to ask on every tick.

What a day allows - closed, a whole session, only a morning or evening, or a special session's hours - is worked out once per exchange, session and India day and remembered, so the per-tick cost is one division, one modulo, a dictionary look-up and two comparisons.

Build the gate.

Parameters:

Name	Type	Description	Default
calendar	TradingCalendar | None	Holidays and special sessions, defaulting to the files in calendars/.	None

Returns:

Type	Description
None	This function returns nothing.

Example programs

An ordinary tuesdayHoliday windows

examples/stock_brokers/instruments/ticks/utilities/sessions/SessionGate/example_1_an_ordinary_tuesday.py

"""Asks the session gate which ticks of an ordinary Tuesday would be kept, for each kind of session.

The unified tick service drops any tick received outside its instrument's window, because brokers keep streaming outside trading hours: a Sunday reconnect replays Friday's prices and the Saturday mock sessions stream prices that never traded. `SessionGate.in_window` answers that question for one instant. The window is wider than trading hours on both sides: it opens at 09:00 for the pre-open auction and closes after the session to keep the closing prices, so an equity tick at 15:45 is kept although trading ended at 15:30.

`before_trading_close` is a separate question: whether an instant is before the session's own close, which decides whether a broker's `close` may be taken as the previous close. The program uses an empty calendar, so the answer depends only on the clock and the weekday, and it builds each instant from a fixed India time. No data store is involved.

Run it from the project root:

    python examples/stock_brokers/instruments/ticks/utilities/sessions/SessionGate/example_1_an_ordinary_tuesday.py
"""

import datetime
import zoneinfo

from stock_brokers.instruments.ticks.utilities import sessions
from stock_brokers.instruments.ticks.utilities.sessions import (
    SessionGate,
    TradingCalendar,
)

INDIA = zoneinfo.ZoneInfo('Asia/Kolkata')


class OrdinaryTuesdayExample:
    """Checks a series of instants on Tuesday 2026-09-15 against three sessions.

    Attributes:
        gate (SessionGate): The gate being shown, over an empty calendar.
    """

    def __init__(self):
        """Builds the gate over a calendar with no holidays.

        Returns:
            None: This method returns nothing.
        """
        self.gate = SessionGate(TradingCalendar.empty())

    def check(self, exchange, segment, hour, minute):
        """Prints whether a tick at a time on the Tuesday is kept, and whether it is before the close.

        Args:
            exchange (str): The canonical exchange.
            segment (str): The instrument's canonical segment.
            hour (int): The hour, India time.
            minute (int): The minute.

        Returns:
            None: This method returns nothing.
        """
        session = sessions.session_for(segment)
        moment = datetime.datetime(2026, 9, 15, hour, minute, tzinfo=INDIA)
        epoch = moment.timestamp()
        kept = self.gate.in_window(exchange, session, epoch)
        before_close = self.gate.before_trading_close(session, epoch)
        print(f'{segment} at {hour:02d}:{minute:02d}: kept {kept}, before the close {before_close}')

    def run(self):
        """Prints the answers for an equity, a currency and a commodity instrument.

        Returns:
            None: This method returns nothing.
        """
        self.check('nse', 'nse_equities', 8, 55)
        self.check('nse', 'nse_equities', 9, 5)
        self.check('nse', 'nse_equities', 15, 45)
        self.check('nse', 'nse_equities', 16, 5)
        self.check('nse', 'nse_currency_futures', 16, 45)
        self.check('nse', 'nse_currency_futures', 17, 40)
        self.check('mcx', 'mcx_commodity_futures', 17, 40)
        self.check('mcx', 'mcx_commodity_futures', 23, 58)
        sunday = datetime.datetime(2026, 9, 13, 11, 0, tzinfo=INDIA)
        kept = self.gate.in_window('nse', sessions.EQUITY_SESSION, sunday.timestamp())
        print(f'nse_equities on Sunday 2026-09-13 at 11:00: kept {kept}')


if __name__ == '__main__':
    OrdinaryTuesdayExample().run()

It prints:

nse_equities at 08:55: kept False, before the close True
nse_equities at 09:05: kept True, before the close True
nse_equities at 15:45: kept True, before the close False
nse_equities at 16:05: kept False, before the close False
nse_currency_futures at 16:45: kept True, before the close True
nse_currency_futures at 17:40: kept False, before the close False
mcx_commodity_futures at 17:40: kept True, before the close True
mcx_commodity_futures at 23:58: kept True, before the close False
nse_equities on Sunday 2026-09-13 at 11:00: kept False

examples/stock_brokers/instruments/ticks/utilities/sessions/SessionGate/example_2_holiday_windows.py

"""Shows how holidays that close only part of a day change a session's window, using the exchanges' real 2026 calendar.

`SessionGate.window` works out, once per exchange, session and India day, which seconds after midnight accept ticks, and remembers it. A full holiday or a weekend has no window. A commodity day whose morning is closed opens at 17:00 for the evening session. A commodity day whose evening is closed keeps the morning session and stays open 30 minutes past 17:00 for the morning's closing prices. `is_trading_day` asks only whether a day has any window, and `window_end_epoch` gives the instant the window around a moment closes, which the ownership rules use to know how long an owner's claim lasts.

The program loads the calendar files in the repository and asks about Ganesh Chaturthi (Monday 2026-09-14), New Year's Day and an ordinary Tuesday. Day numbers are whole days since 1970-01-01 in India time, computed from fixed dates. No data store is involved.

Run it from the project root:

    python examples/stock_brokers/instruments/ticks/utilities/sessions/SessionGate/example_2_holiday_windows.py
"""

import datetime
import zoneinfo

from stock_brokers.instruments.ticks.utilities import sessions
from stock_brokers.instruments.ticks.utilities.sessions import (
    SessionGate,
    TradingCalendar,
)

INDIA = zoneinfo.ZoneInfo('Asia/Kolkata')


class HolidayWindowsExample:
    """Prints the windows of a few days, with the real 2026 calendar.

    Attributes:
        gate (SessionGate): The gate being shown.
    """

    def __init__(self):
        """Builds the gate over the calendar files in the repository.

        Returns:
            None: This method returns nothing.
        """
        self.gate = SessionGate(TradingCalendar.load())

    def clock(self, seconds):
        """Formats seconds after midnight as a clock time.

        Args:
            seconds (int): Seconds after midnight.

        Returns:
            str: The time as HH:MM:SS.
        """
        hours = seconds // 3600
        minutes = seconds % 3600 // 60
        remaining = seconds % 60
        return f'{hours:02d}:{minutes:02d}:{remaining:02d}'

    def describe(self, exchange, session, day):
        """Prints one day's window, whether it trades, and when a window around noon ends.

        Args:
            exchange (str): The canonical exchange.
            session (Session): The session, from `session_for`.
            day (datetime.date): The date.

        Returns:
            None: This method returns nothing.
        """
        noon = datetime.datetime(day.year, day.month, day.day, 12, 0, tzinfo=INDIA)
        day_number = sessions.india_day_number(noon.timestamp())
        window = self.gate.window(exchange, session, day_number)
        trades = self.gate.is_trading_day(exchange, session, day_number)
        if window is None:
            print(f'{day} {exchange} {session.calendar}: trades {trades}, no window')
            return
        print(f'{day} {exchange} {session.calendar}: trades {trades}, window {self.clock(window[0])} to {self.clock(window[1])}')
        ends = self.gate.window_end_epoch(exchange, session, noon.timestamp())
        ends_at = datetime.datetime.fromtimestamp(ends, INDIA)
        print(f'    a tick at noon belongs to a window ending {ends_at.isoformat()}')

    def run(self):
        """Prints the windows for the chosen days.

        Returns:
            None: This method returns nothing.
        """
        ganesh_chaturthi = datetime.date(2026, 9, 14)
        new_year = datetime.date(2026, 1, 1)
        tuesday = datetime.date(2026, 9, 15)
        self.describe('nse', sessions.EQUITY_SESSION, ganesh_chaturthi)
        self.describe('mcx', sessions.COMMODITY_SESSION, ganesh_chaturthi)
        self.describe('mcx', sessions.COMMODITY_SESSION, new_year)
        self.describe('nse', sessions.EQUITY_SESSION, new_year)
        self.describe('ncdex', sessions.NCDEX_SESSION, tuesday)
        self.describe('nse', sessions.CURRENCY_SESSION, tuesday)


if __name__ == '__main__':
    HolidayWindowsExample().run()

It prints:

2026-09-14 nse equity: trades False, no window
2026-09-14 mcx commodity: trades True, window 17:00:00 to 23:59:59
    a tick at noon belongs to a window ending 2026-09-14T23:59:59+05:30
2026-01-01 mcx commodity: trades True, window 09:00:00 to 17:30:00
    a tick at noon belongs to a window ending 2026-01-01T17:30:00+05:30
2026-01-01 nse equity: trades True, window 09:00:00 to 16:00:00
    a tick at noon belongs to a window ending 2026-01-01T16:00:00+05:30
2026-09-15 ncdex commodity: trades True, window 09:00:00 to 21:30:00
    a tick at noon belongs to a window ending 2026-09-15T21:30:00+05:30
2026-09-15 nse currency: trades True, window 09:00:00 to 17:30:00
    a tick at noon belongs to a window ending 2026-09-15T17:30:00+05:30

Methods:

Name	Description
window	The seconds after midnight a day accepts ticks between, for an exchange's session.
is_trading_day	Whether any part of a day trades for an exchange's session.
in_window	Whether an instant is inside an instrument's accepted window.
before_trading_close	Whether an instant is before the session's own close on its day.
window_end_epoch	The instant the window containing an instant closes.

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def __init__(self, calendar=None):
    """
    Build the gate.

    Args:
        calendar (TradingCalendar | None): Holidays and special sessions, defaulting to the files in `calendars/`.

    Returns:
        None: This function returns nothing.
    """
    self._calendar = calendar if calendar is not None else default_calendar()
    self._windows = {}

window

window(exchange, session, day_number)

The seconds after midnight a day accepts ticks between, for an exchange's session.

Parameters:

Name	Type	Description	Default
exchange	str	Canonical exchange, for example "nse".	required
session	Session	The instrument's session, from session_for.	required
day_number	int	Whole days since 1970-01-01 in India time.	required

Returns:

Type	Description
tuple[int, int] | None	The first and last accepted second, or None when the day is closed.

Example usage

From example_2_holiday_windows.py

window = self.gate.window(exchange, session, day_number)

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def window(self, exchange, session, day_number):
    """
    The seconds after midnight a day accepts ticks between, for an exchange's session.

    Args:
        exchange (str): Canonical exchange, for example "nse".
        session (Session): The instrument's session, from session_for.
        day_number (int): Whole days since 1970-01-01 in India time.

    Returns:
        tuple[int, int] | None: The first and last accepted second, or None when the day is closed.
    """
    key = (exchange, session, day_number)
    if key in self._windows:
        return self._windows[key]

    day = date.fromordinal(date(1970, 1, 1).toordinal() + day_number)
    special = self._calendar.special_session(exchange, session.calendar, day)
    if special is not None:
        window = special
    elif (day_number + _EPOCH_WEEKDAY) % 7 >= 5:
        window = None
    else:
        closed = self._calendar.closure(exchange, session.calendar, day)
        if closed is None:
            window = (session.opens, session.window_close)
        elif closed == "morning" and session.evening_opens is not None:
            window = (session.evening_opens, session.window_close)
        elif closed == "evening" and session.evening_opens is not None:
            window = (session.opens, session.evening_opens + EVENING_CLOSED_GRACE_SECONDS)
        else:
            window = None

    if len(self._windows) > 4096:
        self._windows.clear()
    self._windows[key] = window
    return window

is_trading_day

is_trading_day(exchange, session, day_number)

Whether any part of a day trades for an exchange's session.

Parameters:

Name	Type	Description	Default
exchange	str	Canonical exchange.	required
session	Session	The instrument's session.	required
day_number	int	Whole days since 1970-01-01 in India time.	required

Returns:

Type	Description
bool	True when the day has a window.

Example usage

From example_2_holiday_windows.py

trades = self.gate.is_trading_day(exchange, session, day_number)

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def is_trading_day(self, exchange, session, day_number):
    """
    Whether any part of a day trades for an exchange's session.

    Args:
        exchange (str): Canonical exchange.
        session (Session): The instrument's session.
        day_number (int): Whole days since 1970-01-01 in India time.

    Returns:
        bool: True when the day has a window.
    """
    return self.window(exchange, session, day_number) is not None

in_window

in_window(exchange, session, epoch)

Whether an instant is inside an instrument's accepted window.

Parameters:

Name	Type	Description	Default
exchange	str	Canonical exchange.	required
session	Session	The instrument's session, from session_for.	required
epoch	float	Seconds since the Unix epoch.	required

Returns:

Type	Description
bool	True when a tick received then should be kept.

Example usage

From example_1_an_ordinary_tuesday.py

kept = self.gate.in_window(exchange, session, epoch)

From example_1_an_ordinary_tuesday.py

kept = self.gate.in_window('nse', sessions.EQUITY_SESSION, sunday.timestamp())

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def in_window(self, exchange, session, epoch):
    """
    Whether an instant is inside an instrument's accepted window.

    Args:
        exchange (str): Canonical exchange.
        session (Session): The instrument's session, from session_for.
        epoch (float): Seconds since the Unix epoch.

    Returns:
        bool: True when a tick received then should be kept.
    """
    shifted = epoch + INDIA_OFFSET_SECONDS
    window = self.window(exchange, session, int(shifted // SECONDS_PER_DAY))
    if window is None:
        return False
    seconds = shifted % SECONDS_PER_DAY
    return window[0] <= seconds <= window[1]

before_trading_close

before_trading_close(session, epoch)

Whether an instant is before the session's own close on its day.

Parameters:

Name	Type	Description	Default
session	Session	The instrument's session.	required
epoch	float	Seconds since the Unix epoch.	required

Returns:

Type	Description
bool	True before the close.

Example usage

From example_1_an_ordinary_tuesday.py

before_close = self.gate.before_trading_close(session, epoch)

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def before_trading_close(self, session, epoch):
    """
    Whether an instant is before the session's own close on its day.

    Args:
        session (Session): The instrument's session.
        epoch (float): Seconds since the Unix epoch.

    Returns:
        bool: True before the close.
    """
    return (epoch + INDIA_OFFSET_SECONDS) % SECONDS_PER_DAY < session.trading_close

window_end_epoch

window_end_epoch(exchange, session, epoch)

The instant the window containing an instant closes.

Parameters:

Name	Type	Description	Default
exchange	str	Canonical exchange.	required
session	Session	The instrument's session.	required
epoch	float	Seconds since the Unix epoch.	required

Returns:

Type	Description
float	Seconds since the Unix epoch.

Example usage

From example_2_holiday_windows.py

ends = self.gate.window_end_epoch(exchange, session, noon.timestamp())

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def window_end_epoch(self, exchange, session, epoch):
    """
    The instant the window containing an instant closes.

    Args:
        exchange (str): Canonical exchange.
        session (Session): The instrument's session.
        epoch (float): Seconds since the Unix epoch.

    Returns:
        float: Seconds since the Unix epoch.
    """
    day_number = india_day_number(epoch)
    window = self.window(exchange, session, day_number)
    return day_start_epoch(day_number) + (window[1] if window else session.window_close)

session_for

session_for(segment)

The session window an instrument's ticks are accepted in.

Parameters:

Name	Type	Description	Default
segment	str	The instrument's exchange-prefixed segment, for example "nse_currency_futures".	required

Returns:

Type	Description
Session	The window, in seconds after midnight India time, and the calendar it follows.

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def session_for(segment):
    """
    The session window an instrument's ticks are accepted in.

    Args:
        segment (str): The instrument's exchange-prefixed segment, for example "nse_currency_futures".

    Returns:
        Session: The window, in seconds after midnight India time, and the calendar it follows.
    """
    exchange, bare = split_segment_value(segment)
    if exchange == "ncdex":
        return NCDEX_SESSION
    if exchange == "mcx" or bare.startswith("commodit"):
        return COMMODITY_SESSION
    if bare.startswith("currenc"):
        return CURRENCY_SESSION
    return EQUITY_SESSION

india_day_number

india_day_number(epoch)

The India trading day an instant falls on, as whole days since 1970-01-01.

Parameters:

Name	Type	Description	Default
epoch	float	Seconds since the Unix epoch.	required

Returns:

Type	Description
int	The day number.

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def india_day_number(epoch):
    """
    The India trading day an instant falls on, as whole days since 1970-01-01.

    Args:
        epoch (float): Seconds since the Unix epoch.

    Returns:
        int: The day number.
    """
    return int((epoch + INDIA_OFFSET_SECONDS) // SECONDS_PER_DAY)

india_date

india_date(epoch)

The India calendar date an instant falls on.

Parameters:

Name	Type	Description	Default
epoch	float	Seconds since the Unix epoch.	required

Returns:

Type	Description
date	The date.

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def india_date(epoch):
    """
    The India calendar date an instant falls on.

    Args:
        epoch (float): Seconds since the Unix epoch.

    Returns:
        datetime.date: The date.
    """
    return date.fromordinal(date(1970, 1, 1).toordinal() + india_day_number(epoch))

day_start_epoch

day_start_epoch(day_number)

The instant India midnight begins a day.

Parameters:

Name	Type	Description	Default
day_number	int	Whole days since 1970-01-01, as india_day_number returns.	required

Returns:

Type	Description
float	Seconds since the Unix epoch.

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def day_start_epoch(day_number):
    """
    The instant India midnight begins a day.

    Args:
        day_number (int): Whole days since 1970-01-01, as india_day_number returns.

    Returns:
        float: Seconds since the Unix epoch.
    """
    return day_number * SECONDS_PER_DAY - INDIA_OFFSET_SECONDS

_seconds

_seconds(text)

"HH:MM" or "HH:MM:SS" as seconds after midnight.

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def _seconds(text):
    """"HH:MM" or "HH:MM:SS" as seconds after midnight."""
    parts = [int(part) for part in str(text).split(":")]
    return _clock(*parts)

default_calendar

default_calendar()

The calendar loaded from calendars/, read once per process.

Returns:

Type	Description
TradingCalendar	The calendar.

Source code in stock_brokers/instruments/ticks/utilities/sessions.py

def default_calendar():
    """
    The calendar loaded from `calendars/`, read once per process.

    Returns:
        TradingCalendar: The calendar.
    """
    global _DEFAULT_CALENDAR
    if _DEFAULT_CALENDAR is None:
        _DEFAULT_CALENDAR = TradingCalendar.load()
    return _DEFAULT_CALENDAR