Guides

Typed data migration

On this page8

FinLab trading payloads are moving from implicit dict/list structures to formal typed interfaces. This page lists the new schemas and APIs, how they stay compatible with existing code, and the deprecation policy. Legacy APIs keep working and typed and dict APIs can coexist, so you can migrate one piece at a time.

Migration steps

Move data models to `finlab.schemas` dataclasses

Use the new public schemas below for positions, orders and portfolios.

Switch to typed APIs incrementally

For example from_entries, generate_order_entries, get_data_typed, one call site at a time.

Keep the dict fallback

Keep the dict APIs until your UI, DB and scheduler layers finish migration.

New public schemas

Import these dataclasses from finlab.schemas. All of them provide from_dict() / to_dict():

from finlab.schemas import (
    OrderEntry,
    PortfolioConfigData,
    PortfolioData,
    PositionEntry,
    StrategyPositionData,
)

Positions: Position

Method	Description
`Position.from_entries(entries)`	Build a `Position` from a list of entries
`Position.to_entries()`	Convert to a list of entries

from finlab.online.order_executor import Position

position = Position({'AAPL': 10, 'MSFT': 5})

entries = position.to_entries()
position = Position.from_entries(entries)

rows = position.to_list()  # the legacy API still works

Legacy from_list() / to_list() are still supported, and typed and dict APIs can coexist during migration.

Orders: OrderExecutor

Method	Description
`OrderExecutor.generate_orders(..., as_entries=False, quantity_type='decimal')`	Default behavior is unchanged: still returns `list[dict]`
`OrderExecutor.generate_order_entries(..., quantity_type='decimal')`	Returns typed entries

quantity_type supports decimal (default), float and string.

Portfolio sync: PortfolioSyncManager

Method	Description
`get_data(typed=False)`	Read the data
`set_data(data, typed=False)`	Write the data
`get_data_typed()`	Read typed data
`set_data_typed(data)`	Write typed data

Internal storage (self.data) remains the same dict shape.
Typed conversion is done only at API boundaries, keeping to_path / to_local / to_cloud compatible.

Strategy reports: CloudReport and ReportExecution

CloudReport provides typed access to strategy reports:

Member	Description
`CloudReport.from_dict(report_dict, execution_dict)`	Construct from dicts
`CloudReport.position_info2()`	Get position info
`CloudReport.position_schedulers`	Schedulers and weights

ReportExecution wraps backtest execution config:

Member	Description
`ReportExecution.from_dict(d)` / `.to_dict()`	Convert from and to a dict
`.weights`	Current position weights (`pd.Series`)
`.next_weights`	Next-period position weights
`.actions`	Stop-loss / take-profit actions
`.config`	Backtest config (`resample`, `stopLoss`, `takeProfit`, etc.)
`.current_rebalance_date` / `.next_rebalance_date`	Rebalance dates

symbol and stock_id compatibility policy

Current policy:

symbol is canonical.
stock_id remains a backward-compatible alias.
Conflicting values in both keys raise an error.

Recommendations:

Prefer symbol in new code.
Keep stock_id read compatibility in third-party integrations until a major-version removal plan is announced.

Planned direction (tentative):

Version	Plan
`1.x`	`stock_id` stays fully supported as alias
`2.x` (not earlier than)	Re-evaluate warning-only mode or alias removal

Next steps

Orders: single strategy Send a strategy's positions to your broker with Position and OrderExecutor.
Orders: multiple strategies Manage a multi-strategy portfolio with PortfolioSyncManager.
finlab.online The full API of the order module.
finlab.portfolio The full API of the portfolio module.

Was this page helpful?