root/trac/hacks/marketplugin/0.9/tracmarket/api.py

import types
import time

from trac.core import *


# Symbol namespace is split into 'wiki', 'ticket', etc.  Symbol names
# are namespace.basket.{basket...}contract:
#
#   wiki.SandBox.7              -- "SandBox" page, version 7
#   ticket.43.priority.high     -- ticket #43, priority high

class InsufficientFunds(Exception): 
    def __str__(self):
        d = self.args[0]
        bal = d['balance']
        amt = d['amount']
        sym = d['symbol']
        account = d['account']
        out = "Insufficient Funds: "
        out += "attempted to withdraw, reserve, or spend %f %s, " % (amt, sym)
        out += "%s balance is only %f" % (account, bal)
        return out

class MissingAccount(Exception): pass
    
class IMarketController(Interface):
    '''Central controller for tracmarket plugin.  UI module(s) talk to
    the controller.  The controller sets up the per-query context (db,
    message bus, etc.), passes it to the command interpreter one or
    more times (once for each command), then does the db commit or
    rollback when UI calls close().'''

    def open(req, bus=None, db=None):
        '''Set up the tracmarket subsystem.  Returns the system's
        message bus object, which it creates if none is provided.
        Opens a db connection if none is provided.  The UI controls
        tracmarket by sending and receiving messages on the bus, and
        is then responsible for calling .close() at the end of the
        query.'''

    def run(bus, cmds):
        '''Return a generator which sends commands to bus and yields
        the resulting message stream.  Cmds is a list of command
        strings.'''

    def close(bus, commit=True):
        '''Do internal cleanup; call at end of HTTP or other query.
        If commit=True, then commit db.'''

    def run_cmd(req, cmd):
        '''Backward compatibility method.  Create bus, execute a
        single command, close and return internal context when done.
        Response can be found in ctx.res.  This api (and the whole
        ctx.res tree) is deprecated -- use run() instead.'''


# XXX deprecate
class ICommandInterpreter(Interface):
    """Extension point interface for components that can handle orders
    and market data requests for a given contract."""

    def match_symbol(symbol, currency):
        """Returns True if this component can handle orders and market
        data requests for symbol, denominated in currency."""

    def order(req, size, symbol, currency, **kwargs):
        """Create an order to buy or sell 'size' items.  Orders with
        different denominations go into different books; we don't
        perform automatic currency conversion.  Negative size means
        sell, positive size means buy.  Kwargs are specific to the
        instrument being traded.  Returns order object."""

    def cancel(req, order_id):
        """Cancel an order.  Returns order object -- check contents
        for status."""

    def open_orders(req, user):
        """Return a list of open order objects for user."""
        # called by WikiMarket._render_portfolio

    def quote(symbol, currency, last_count=1):
        """Return a consolidated quote containing order book and
        'last_count' number of trades.  See model.py for definition of
        Quote, Book, Order, and Trade objects."""


# XXX deprecate
class ILedger(Interface):
    """Extension point interface for components that can store 
    and report double-entry transactions for currency and inventory
    items.
    """
    
    def post(req, legs, memo=''):
        """Record a transaction; 'legs' is a list of transaction legs
        that have been created using mkleg().  Memo is a string.  Legs
        can be mixed-currency.  Ensures debits and credits are
        balanced within each currency.  Adds remote_user and
        timestamp.  Returns integer transaction id."""
        # called by Auctioneer._match_orders

    def mkleg(entity, account, symbol, amount, serial=None):
        """Convenience method to help create a proper transaction leg.
        Does no storage.  Returns an object suitable for sending to
        post().  Entity is an entity string.  Account is an account name
        string.  Symbol is a string, and can be any symbol previously
        defined by mksymbol().  Amount is a signed float, and will be
        converted to debit or credit depending on normal balance of
        account.  Serial is an optional string, and is used to
        designate a unique instance of symbol to be transferred, e.g.
        equipment, stock certificate, or banknote serial number.
        Returns None if insufficient funds available in account."""
        # called by Auctioneer._match_orders

    def mkentity(entity, description):
        """Create a legal entity to group accounts under -- person,
        corporation, etc.  Entity is a unique string.  Description is
        a string."""
        # called by WikiMarket._init_user

    def chentity(entity, description=None):
        """Change entity attributes."""

    def mkaccount(entity, account, description, normal_balance):
        """Create a currency or inventory account for entity.  Account
        is an account name string.  Description is a string.
        Normal_balance is a string: 'debit' or 'credit'."""
        # called by WikiMarket._init_user

    def chaccount(entity, account, description=None):
        """Change account attributes."""

    def mksymbol(symbol, description, divisible):
        """Create a currency or inventory item symbol for later use in
        transaction legs.  Symbol is a string (no spaces), and might
        be a currency symbol, part number, or similar.  Description is
        a string.  Divisible is a boolean; if false, it means that
        amounts must be equal to a round integer; for example, a
        dollar is divisible, but an inventory item might not be."""
        # called by WikiMarket._init_version

    def history(entity=None, account=None, symbol=None,
            start_date=None, end_date=None, count=None):
        """Return a list of transaction objects, sorted by
        date."""
        # called by WikiMarket._render_portfolio
        # called by WikiMarket._timeline_item

    def balance(entity, account, symbol, serial=None):
        """Return quantity of symbol in account."""
        # called by WikiMarket._render_portfolio