API Reference

ngv_reports_ibkr.config_helpers.get_config(file_name: str) → Dict

Returns file_name lines as Dict.

Uses dotenv

Parameters:: file_name (str) – env file name. Default = .env
Return type:: Dict

ngv_reports_ibkr.config_helpers.get_ib_json(configs: Dict) → Dict

Returns the json parsed value for the IB_JSON env var.

This should be a json string

Parameters:: configs (Dict) – env file contents
Returns:: IB_JSON parsed as json
Return type:: dict

class ngv_reports_ibkr.adapters.ReportOutputAdapterCSV(*, data_folder: str = 'data', report: CustomFlexReport)

Adapter responsible for writing Report Sections to disk.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ngv_reports_ibkr.adapters.ReportOutputAdapterPandas(*, report: CustomFlexReport)

Adapter responsible for returning Report Sections as dictionary of Panda DataFrames.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

process_accounts() → List[dict]

For each account, generate a dict of DataFrames for all sections.

Returns:: list of dicts of dfs (generated by put_all)
Return type:: List[dict]

put_all(aid: str) → dict

Generate a dict of DataFrames for all sections

Parameters:: aid (str) – account id
Returns:: dict of dfs
Return type:: dict

put_close_trades(aid: str) → DataFrame

Generate a DataFrame of closed trades for a given account id

Parameters:: aid (str) – account id
Returns:: df of close trades
Return type:: pd.DataFrame

put_open_positions(aid: str) → DataFrame

Generate a DataFrame of open positions for a given account id

Parameters:: aid (str) – account id
Returns:: df of trades
Return type:: pd.DataFrame

put_trades(aid: str) → DataFrame

Generate a DataFrame of trades for a given account id

Parameters:: aid (str) – account id
Returns:: df of trades
Return type:: pd.DataFrame

class ngv_reports_ibkr.custom_flex_report.CustomFlexReport(token=None, queryId=None, path=None)

trades_by_account_id(account_id: str) → DataFrame

Get trades for a specific account with schema validation.

Parameters:: account_id (str) – The account ID to filter trades for
Returns:: DataFrame of trades for the account, or None if no trades exist. Returns the DataFrame even if schema validation fails (with errors logged).
Return type:: pd.DataFrame or None

Notes

This method validates the returned DataFrame against the IBKR flex report trades schema to ensure data integrity. Validation failures are logged as errors but do not prevent the DataFrame from being returned. This allows analysis of potentially corrupted data while alerting to schema mismatches.

Schema validation errors are logged with: - Account ID context - Number of validation failures - Detailed error messages

If validation fails, check logs for specific column/type mismatches.

ngv_reports_ibkr.download_trades.execute_csv_for_accounts(report_name: str, cache: bool = False, file_name: str = '.env')

Execute the trades dowload process for accounts

Parameters:

report_name (str) – report name as it exists in the env file. Eg, report_name=xyz, in env file=IB_REPORT_ID_XYZ
cache (bool) – cache XML
file_name (str) – env file name. Defaults to “.env”.

ngv_reports_ibkr.download_trades.fetch_report(flex_token: int, query_id: int, cache_report_on_disk: bool = False) → CustomFlexReport

Fetch report. Optionally save to disk (helpful for debugging)

Parameters:

flex_token (int) – IB Flex Token
query_id (int) – IB Report Query Id
cache_report_on_disk (bool, optional) – Cache XML content on disk. Helpful for debugging. Defaults to False.

Returns:

[description]

Return type:

CustomFlexReport

ngv_reports_ibkr.download_trades.load_report(xml_file_path: str) → CustomFlexReport

Load CustomFlexReport from provided file path

Parameters:: xml_file_path (str) – file path to the cached XML file
Returns:: report
Return type:: CustomFlexReport

ngv_reports_ibkr.transforms.parse_datetime_series(raw_series: Series, target_tz: str = 'America/New_York') → Series

Parse IBKR datetime strings to timezone-aware pandas datetime.

Parameters:

raw_series – Series with IBKR datetime strings like “2026-01-15;10:30:00 EST”
target_tz – Target timezone for output (default: America/New_York)

Returns:

Timezone-aware datetime series in target_tz