Skip to content

feat(context): order convenience functions (#440)#555

Merged
MDUYN merged 1 commit into
devfrom
feat/440-order-convenience-functions
May 21, 2026
Merged

feat(context): order convenience functions (#440)#555
MDUYN merged 1 commit into
devfrom
feat/440-order-convenience-functions

Conversation

@MDUYN

@MDUYN MDUYN commented May 21, 2026

Copy link
Copy Markdown
Collaborator

Closes #440.

Summary

Adds five high-level ordering convenience functions on Context that simplify portfolio management and rebalancing. The framework previously required users to manually compute order amounts from target values/percentages — these helpers do it.

New API

Method Behavior
order_value(symbol, value, side, price) LIMIT order, amount = value / price
order_percent(symbol, percent, side, price) LIMIT order for percent of portfolio net size
order_target(symbol, target_amount, price) Rebalance to exactly target_amount units (BUY/SELL diff, no-op if equal)
order_target_value(symbol, target_value, price) Rebalance so position value at price equals target_value
order_target_percent(symbol, target_percent, price) Rebalance to target_percent of portfolio net size

All helpers produce LIMIT orders (require price) and validate inputs (positive value/percent/price, non-negative targets). Internally they delegate to create_limit_order; the target_* family looks up the current position and submits the BUY/SELL difference, or no order when already on target.

Example

class MyStrategy(TradingStrategy):
    def run_strategy(self, context, data):
        price = data["btc_ticker"]["price"]

        # Rebalance BTC to 10% of portfolio
        context.order_target_percent(
            target_symbol="BTC", target_percent=10.0, price=price
        )

        # Buy 500 EUR worth of ETH
        context.order_value(
            target_symbol="ETH", value=500.0,
            order_side=OrderSide.BUY, price=price
        )

        # End up with exactly 1.5 BTC
        context.order_target(
            target_symbol="BTC", target_amount=1.5, price=price
        )

Tests

14 new tests in tests/app/algorithm/test_order_convenience_functions.py covering buy paths, target-down rebalancing, no-op when already on target, and input validation errors.

============= 96 passed, 1 skipped, 2 warnings in 67.99s =============  (full tests/app/algorithm/ suite)
======================== 14 passed in 29.53s ========================= (new file only)

Add five high-level ordering helpers on Context that simplify
portfolio management and rebalancing by removing manual amount
calculations:

- order_value(symbol, value, side, price): place a LIMIT order for
  a fixed currency amount (amount = value / price).
- order_percent(symbol, percent, side, price): place a LIMIT order
  for a percentage of the portfolio's net size.
- order_target(symbol, target_amount, price): adjust the position
  to exactly target_amount units; submits BUY/SELL for the
  difference, or no order when already on target.
- order_target_value(symbol, target_value, price): adjust the
  position so its market value at price equals target_value.
- order_target_percent(symbol, target_percent, price): adjust the
  position so its market value equals target_percent of the
  portfolio's net size (rebalancing).

All helpers produce LIMIT orders by default and validate inputs
(positive value/percent/price, non-negative targets). Implemented
as thin wrappers around create_limit_order; target_* helpers
compute the current position size and place a BUY or SELL for the
difference.

Tests: 14 new tests in test_order_convenience_functions.py covering
buy paths, target-down rebalancing, no-op when already on target,
and validation errors.

Closes #440
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant