segments ¶

Canonical segment vocabulary for the instrument mapping layer.

The vocabulary declares every segment that a broker adapter may classify a raw row into, in the order that segments must appear in each broker's rules file under stock_brokers/instruments/mapping/utilities/rules/. The order is by asset class first — fixed income, equities, currencies, commodities — and within each asset class by instrument kind: simple instruments, futures, options, indices, index futures, index options. The catch-all segments come last: mutual funds, exchange traded funds, investment trusts, and the uncategorised buckets.

Segment values stored in unified.instruments are exchange-prefixed, for example nse_equities and bse_equity_options, produced by segment_value.

MAPPED_BROKERS lives here too, because the order the brokers are mapped in is a fact about mapping rather than about downloading, and several modules of this package import it.

Functions:

Name	Description
`segment_value`	Build the exchange-prefixed segment value stored in the mapped tables.
`segment_shape`	Look up the shape declared for a bare segment name.
`segment_rank`	Compute the ordering rank of one configured segment.
`split_segment_value`	Split an exchange-prefixed segment value into its exchange and bare name.
`segments_of`	Build the prefixed segment values for every combination of exchange and bare segment.
`is_adjustable`	Whether an exchange-prefixed segment is one whose prices are stored unadjusted with factors.

segment_value ¶

segment_value(exchange, bare_segment)

Build the exchange-prefixed segment value stored in the mapped tables.

Parameters:

Name	Type	Description	Default
`exchange`	`str`	Canonical lowercase exchange name, for example "nse".	required
`bare_segment`	`str`	Bare segment name from CANONICAL_SEGMENTS, for example "equities".	required

Returns:

Type	Description
`str`	The prefixed segment value, for example "nse_equities".

Source code in stock_brokers/instruments/mapping/utilities/segments.py

def segment_value(exchange, bare_segment):
    """
    Build the exchange-prefixed segment value stored in the mapped tables.

    Args:
        exchange (str): Canonical lowercase exchange name, for example "nse".
        bare_segment (str): Bare segment name from CANONICAL_SEGMENTS, for example "equities".

    Returns:
        str: The prefixed segment value, for example "nse_equities".
    """
    return f"{exchange}_{bare_segment}"

segment_shape ¶

segment_shape(bare_segment)

Look up the shape declared for a bare segment name.

Parameters:

Name	Type	Description	Default
`bare_segment`	`str`	Bare segment name from CANONICAL_SEGMENTS.	required

Returns:

Type	Description
`str`	The segment's shape, one of "security", "future", or "option".

Raises:

Type	Description
`ValueError`	If bare_segment is not part of the canonical vocabulary.

Source code in stock_brokers/instruments/mapping/utilities/segments.py

def segment_shape(bare_segment):
    """
    Look up the shape declared for a bare segment name.

    Args:
        bare_segment (str): Bare segment name from CANONICAL_SEGMENTS.

    Returns:
        str: The segment's shape, one of "security", "future", or "option".

    Raises:
        ValueError: If bare_segment is not part of the canonical vocabulary.
    """
    if bare_segment not in _SEGMENT_SHAPES:
        raise ValueError(f"{bare_segment!r} is not a canonical segment name")
    return _SEGMENT_SHAPES[bare_segment]

segment_rank ¶

segment_rank(exchange, bare_segment)

Compute the ordering rank of one configured segment.

The rank pairs the segment's position in the canonical vocabulary with the exchange's position in the canonical exchange list, so that a rules file listing segments in canonical order yields non-decreasing ranks. Config validation uses this to reject a rules file whose segments are out of order.

Parameters:

Name	Type	Description	Default
`exchange`	`str`	Canonical lowercase exchange name.	required
`bare_segment`	`str`	Bare segment name from CANONICAL_SEGMENTS.	required

Returns:

Type	Description
`tuple`	A (segment_position, exchange_position) pair of ints.

Source code in stock_brokers/instruments/mapping/utilities/segments.py

def segment_rank(exchange, bare_segment):
    """
    Compute the ordering rank of one configured segment.

    The rank pairs the segment's position in the canonical vocabulary with the exchange's position in the canonical exchange list, so that a rules file listing segments in canonical order yields non-decreasing ranks. Config validation uses this to reject a rules file whose segments are out of order.

    Args:
        exchange (str): Canonical lowercase exchange name.
        bare_segment (str): Bare segment name from CANONICAL_SEGMENTS.

    Returns:
        tuple: A (segment_position, exchange_position) pair of ints.
    """
    return (_SEGMENT_ORDER[bare_segment], _EXCHANGE_ORDER[exchange])

split_segment_value ¶

split_segment_value(value)

Split an exchange-prefixed segment value into its exchange and bare name.

Parameters:

Name	Type	Description	Default
`value`	`str`	Prefixed segment value, for example "nse_equities".	required

Returns:

Type	Description
`tuple`	An (exchange, bare_segment) pair, for example ("nse", "equities").

Source code in stock_brokers/instruments/mapping/utilities/segments.py

def split_segment_value(value):
    """
    Split an exchange-prefixed segment value into its exchange and bare name.

    Args:
        value (str): Prefixed segment value, for example "nse_equities".

    Returns:
        tuple: An (exchange, bare_segment) pair, for example ("nse", "equities").
    """
    exchange, _, bare_segment = value.partition("_")
    return exchange, bare_segment

segments_of ¶

segments_of(exchanges, bare_segments)

Build the prefixed segment values for every combination of exchange and bare segment.

Parameters:

Name	Type	Description	Default
`exchanges`	`str \| list[str]`	One canonical exchange name or several, for example "nse".	required
`bare_segments`	`tuple[str]`	Bare segment names, usually one of the families above.	required

Returns:

Type	Description
`list[str]`	The prefixed values, for example ["nse_equities", "nse_exchange_traded_funds"].

Source code in stock_brokers/instruments/mapping/utilities/segments.py

def segments_of(exchanges, bare_segments):
    """
    Build the prefixed segment values for every combination of exchange and bare segment.

    Args:
        exchanges (str | list[str]): One canonical exchange name or several, for example "nse".
        bare_segments (tuple[str]): Bare segment names, usually one of the families above.

    Returns:
        list[str]: The prefixed values, for example ["nse_equities", "nse_exchange_traded_funds"].
    """
    if isinstance(exchanges, str):
        exchanges = [exchanges]
    return [segment_value(exchange, bare) for exchange in exchanges for bare in bare_segments]

is_adjustable ¶

is_adjustable(segment)

Whether an exchange-prefixed segment is one whose prices are stored unadjusted with factors.

Parameters:

Name	Type	Description	Default
`segment`	`str`	A prefixed segment value, for example "nse_equities".	required

Returns:

Type	Description
`bool`	True for equities, exchange traded funds and investment trusts on any exchange.

Source code in stock_brokers/instruments/mapping/utilities/segments.py

def is_adjustable(segment):
    """
    Whether an exchange-prefixed segment is one whose prices are stored unadjusted with factors.

    Args:
        segment (str): A prefixed segment value, for example "nse_equities".

    Returns:
        bool: True for equities, exchange traded funds and investment trusts on any exchange.
    """
    return split_segment_value(segment)[1] in ADJUSTABLE_SEGMENTS