Never test with real money

# paper_broker.py
# A simulated broker for learning. It accepts orders, fills them, and tracks
# positions and funds. It touches NO real money and needs NO login. Every
# runnable example in this course drives this paper broker, so you can practise
# order handling and live-risk code with real output and zero risk.
#
# This is a teaching simulator, and it is deliberately simplified. A real broker
# models a full order book, margins, and network latency. Here a market order
# fills at the last known price and a limit order fills when the price reaches
# it. No specific broker is named or endorsed; the method names are the common
# shape a broker API tends to have (funds, positions, quotes, place an order).
#
# You do not need to understand every line before using it. You need to trust
# that it behaves roughly like a broker and that it cannot spend a rupee.

from dataclasses import dataclass
from itertools import count
from typing import Optional, List, Dict


@dataclass
class Order:
    order_id: int
    client_order_id: str
    symbol: str
    side: str                 # "BUY" or "SELL"
    quantity: int
    order_type: str           # "MARKET" or "LIMIT"
    price: Optional[float]    # limit price, or None for a market order
    status: str = "PENDING"   # PENDING, OPEN, PARTIALLY_FILLED, FILLED, REJECTED, CANCELLED
    filled_quantity: int = 0
    average_price: float = 0.0
    message: str = ""         # reason for a rejection, and so on

    @property
    def remaining(self) -> int:
        return self.quantity - self.filled_quantity


class PaperBroker:
    def __init__(self, cash: float = 1_000_000, prices: Optional[Dict[str, float]] = None,
                 cost_bps: float = 0.0, slippage_bps: float = 0.0,
                 liquidity: Optional[int] = None):
        # cash: starting funds in rupees.
        # prices: {symbol: last_price} the simulator knows about.
        # cost_bps, slippage_bps: illustrative costs in basis points (1 bp = 0.01%).
        #   Both default to 0 so the early examples are exact; later chapters
        #   turn them on to study slippage (chapter 19) and cost (chapter 21).
        # liquidity: shares fillable per price event (None means fill fully);
        #   later chapters use it to study partial fills (chapter 11).
        self.cash = float(cash)
        self.prices = dict(prices or {})
        self.cost_bps = cost_bps
        self.slippage_bps = slippage_bps
        self.liquidity = liquidity
        self.positions: Dict[str, Dict[str, float]] = {}  # symbol -> {quantity, avg_price}
        self.orders: Dict[int, Order] = {}
        self._ids = count(1)
        self._client_ids = count(1)

    # ----- reads (always safe to call) -----
    def get_funds(self) -> Dict[str, float]:
        return {"available_cash": round(self.cash, 2)}

    def get_positions(self) -> List[Dict]:
        return [{"symbol": s, "quantity": int(p["quantity"]),
                 "avg_price": round(p["avg_price"], 2)}
                for s, p in self.positions.items() if p["quantity"] != 0]

    def get_holdings(self) -> List[Dict]:
        # In this simulator, holdings mirror positions. A real broker separates
        # today's intraday positions from settled, delivered holdings.
        return self.get_positions()

    def get_quote(self, symbol: str) -> Optional[Dict]:
        last = self.prices.get(symbol)
        if last is None:
            return None
        half_spread = last * self.slippage_bps / 10_000 / 2  # a tiny illustrative spread
        return {"symbol": symbol, "last_price": round(last, 2),
                "bid": round(last - half_spread, 2), "ask": round(last + half_spread, 2)}

    def get_order(self, order_id: int) -> Optional[Order]:
        return self.orders.get(order_id)

    def get_orders(self) -> List[Order]:
        return list(self.orders.values())

    # ----- writes -----
    def place_order(self, symbol: str, side: str, quantity: int,
                    order_type: str = "MARKET", price: Optional[float] = None,
                    client_order_id: Optional[str] = None) -> Order:
        oid = next(self._ids)
        coid = client_order_id or f"c{next(self._client_ids)}"
        order = Order(oid, coid, symbol, side.upper(), int(quantity),
                      order_type.upper(), price)
        self.orders[oid] = order

        # validate the order before it can do anything
        if order.quantity <= 0:
            return self._reject(order, "quantity must be positive")
        if order.order_type == "LIMIT" and order.price is None:
            return self._reject(order, "a limit order needs a price")
        last = self.prices.get(symbol)
        if order.order_type == "MARKET":
            if last is None:
                return self._reject(order, "no price known for symbol")
            if order.side == "BUY" and last * order.quantity > self.cash:
                return self._reject(order, "insufficient funds")
            order.status = "OPEN"
            self._fill(order, last)
        else:  # LIMIT: rest until the price reaches it, or fill now if already there
            order.status = "OPEN"
            if last is not None and self._crosses(order, last):
                self._fill(order, order.price)
        return order

    def modify_order(self, order_id: int, price: Optional[float] = None,
                     quantity: Optional[int] = None) -> Optional[Order]:
        order = self.orders.get(order_id)
        if order is None or order.status in ("FILLED", "CANCELLED", "REJECTED"):
            return order
        if price is not None:
            order.price = price
        if quantity is not None:
            order.quantity = int(quantity)
        return order

    def cancel_order(self, order_id: int) -> Optional[Order]:
        order = self.orders.get(order_id)
        if order and order.status in ("OPEN", "PARTIALLY_FILLED"):
            order.status = "CANCELLED"
        return order

    def feed_price(self, symbol: str, price: float) -> List[Order]:
        # Move the market and try to fill any resting limit orders on this symbol.
        # Returns the orders that got a fill from this price.
        self.prices[symbol] = float(price)
        filled = []
        for order in self.orders.values():
            if (order.symbol == symbol and order.order_type == "LIMIT"
                    and order.status in ("OPEN", "PARTIALLY_FILLED")
                    and self._crosses(order, price)):
                if self._fill(order, order.price) > 0:
                    filled.append(order)
        return filled

    # ----- internals -----
    def _reject(self, order: Order, reason: str) -> Order:
        order.status = "REJECTED"
        order.message = reason
        return order

    def _crosses(self, order: Order, price: float) -> bool:
        # A buy limit fills when the price falls to it; a sell limit when it rises.
        return price <= order.price if order.side == "BUY" else price >= order.price

    def _fill(self, order: Order, price: float) -> int:
        qty = order.remaining
        # Limited liquidity fills a resting limit order a slice at a time; a
        # market order takes what it needs at once (this simulator has no book).
        if self.liquidity is not None and order.order_type == "LIMIT":
            qty = min(qty, self.liquidity)
        if qty <= 0:
            return 0
        # slippage moves the fill against whoever is taking liquidity
        slip = price * self.slippage_bps / 10_000
        fill_price = price + slip if order.side == "BUY" else price - slip

        # blend this fill into the order's running average fill price
        prev = order.filled_quantity
        order.filled_quantity += qty
        order.average_price = (order.average_price * prev + fill_price * qty) / order.filled_quantity
        order.status = "FILLED" if order.remaining == 0 else "PARTIALLY_FILLED"

        # update cash and the position
        signed = qty if order.side == "BUY" else -qty
        self.cash -= fill_price * signed                       # BUY spends cash, SELL adds
        self.cash -= abs(fill_price * qty) * self.cost_bps / 10_000
        self._apply_position(order.symbol, signed, fill_price)
        return qty

    def _apply_position(self, symbol: str, signed_qty: int, price: float):
        pos = self.positions.setdefault(symbol, {"quantity": 0, "avg_price": 0.0})
        old = pos["quantity"]
        new = old + signed_qty
        if old == 0 or (old > 0) == (signed_qty > 0):
            # opening, or adding in the same direction: blend the average price
            if new != 0:
                pos["avg_price"] = (pos["avg_price"] * old + price * signed_qty) / new
        elif abs(signed_qty) > abs(old):
            # sold or bought through flat into the other direction
            pos["avg_price"] = price
        # simply reducing toward flat keeps the existing average price
        if new == 0:
            pos["avg_price"] = 0.0
        pos["quantity"] = new

# A first run against the paper broker: check funds, buy, see the fill,
# see the position and the funds change. No login, no real money.
from paper_broker import PaperBroker

# Start with 10 lakh rupees and one price the simulator knows.
broker = PaperBroker(cash=1_000_000, prices={"RELIANCE": 1400.0})

print("Funds before:", broker.get_funds())

order = broker.place_order("RELIANCE", "BUY", 100, order_type="MARKET")
print(f"Order {order.order_id} [{order.client_order_id}]: {order.status}, "
      f"filled {order.filled_quantity} at avg {order.average_price:.2f}")

print("Positions:  ", broker.get_positions())
print("Funds after:", broker.get_funds())

# Read-only calls are always safe: ask the simulator for a quote.
print("Quote:      ", broker.get_quote("RELIANCE"))