root/trac/hacks/marketplugin/0.9/doc/api-notes

from trac.core import *



# XXX order matching is generic and can be done by generic auctioneer; order
# expiration, fills, and cancellation are specific to the contract
# type, and need to be handled by pit class;  make Pit a component;
# Book, Order, and Trade can be inherited from common
#
# how to abstract web vs xmlrpc:  different frontends, same
# backend



------------ common.py ---------------
class Specialist(Component):

    def order(self,req,size,symbol,currency,limit_price=None,stop_price=None):
        """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.  Limit_price == None and
        stop_price == None means market order.  If single auction, use
        sell for reserve price, buy for bids.  Returns order id."""

    def cancel(self,req,order_id):
        """Cancel an order.  Returns number of items not traded."""
        # called by WikiMarket._cancel_order
        # XXX replace with order.cancel()

------------ wiki.py ---------------
from tracmarket.common import Specialist, Book, Order, Pit, Trade

class WikiSpecialist(Specialist):

    def 


    
class ISpecialist(Interface):
    

    def match_symbol(req,symbol,currency):
        """Returns True if this component can handle orders and market
        data requests for symbol by current user, 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
        type of instrument being traded.  Returns order object."""

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

    def open_orders(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 common.py for definition of
        Quote, Book, Order, and Trade objects."""

    def _match_orders(symbol):
        """Fill orders for symbol, posting deals to ILedger component.
        Returns list of transaction IDs."""
        # calls MarketDataConsumer.trade for each transaction
        # XXX replace with book.match()



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 True if amount is 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


'''

class IQuartermaster(Interface):
    """Extension point interface for components that can store
    physical inventory location, manifests, ownership, and bills of
    materials, and report movement and assembly progress.
    """

class IPortfolio(Interface):
    """Extension point interface for components that can provide a
    consolidated view of currency, inventory, and orders for a given
    user.
    """


class OrderClerk(Interface):
    """Accept, store, and report orders.  Orders are opaque objects;
    the clerk knows nothing about their contents.  Does no matching,
    accounting, valuations, or anything else which would require
    looking inside the order."""

    def post(req,order):
        """Post order.  Returns order id string."""

    def cancel(order_id):
        """Cancel order.  Returns order object -- caller must inspect
        the order object to see if the cancel was successful."""




'''