Shadow Ingest Discoverability¶

shadow-ingest keeps the public SDK intentionally small, but users still need a reliable way to discover valid inputs.

These helper APIs exist so users do not have to guess:

which trading dates are valid
which stock identifiers are valid on a date
which daily price fields are supported
which industry standards are available
how to map stock codes to industry rows
how to expand an industry into member stock rows

Core Discovery APIs¶

list_fields — get the documented fields values for gather_daily_price(...)
list_market_calendar — get valid trading dates
list_universe — get valid tradable stock codes for a required date

Industry Lookup APIs¶

get_industry_standards — list available taxonomy names
get_industry_mapping — map stock codes to industry hierarchy rows
get_industry_members — map an industry to member stock rows

Recommended Workflow¶

import shadow_ingest as si

trade_dates = si.list_market_calendar(year=2024)
trade_date = trade_dates[-1].isoformat()
stock_codes = si.list_universe(date=trade_date)
price_fields = si.list_fields(si.gather_daily_price)
industry_standards = si.get_industry_standards()
industry_df = si.get_industry_mapping(
    stock_codes=stock_codes[:10],
    standard=industry_standards[0],
    trade_date=trade_date,
)

print(price_fields)
print(industry_standards)
print(industry_df.head())

Why This Matters¶

The goal is a stable user mental model:

discover with helper APIs
fetch with dataframe APIs
work with the final table

Most users should only need these nine public Python APIs.

Field Discovery Rule¶

list_fields(...) is intentionally narrow.

Today it documents the supported public fields values for:

gather_daily_price(...)

For APIs that do not expose a stable public fields parameter, the docs should tell users to inspect df.columns from a small sample query instead of guessing.