From 4f87b4e98aeb30c9844c0e6f7cbab2af04f06707 Mon Sep 17 00:00:00 2001 From: fawce Date: Wed, 21 Mar 2012 00:55:35 -0400 Subject: [PATCH] documentation fixes and tweaks. --- etc/jenkins.sh | 7 +- etc/pycco.css | 186 +++++++++++++++++++++++++++++++++ zipline/finance/performance.py | 15 ++- zipline/lines.py | 79 +++++++------- zipline/protocol.py | 153 ++++++++++++++++----------- 5 files changed, 330 insertions(+), 110 deletions(-) create mode 100644 etc/pycco.css diff --git a/etc/jenkins.sh b/etc/jenkins.sh index 489bf7a6..2f3ff5f9 100755 --- a/etc/jenkins.sh +++ b/etc/jenkins.sh @@ -31,6 +31,11 @@ pycco ./zipline/*.py -d ./docs/_build/html/pycco/ pycco ./zipline/finance/*.py -d ./docs/_build/html/pycco/finance pycco ./zipline/test/*.py -d ./docs/_build/html/pycco/test pycco ./zipline/transforms/*.py -d ./docs/_build/html/pycco/transforms +# use our custom css +cp ./etc/pycco.css ./docs/_build/html/pycco/ +cp ./etc/pycco.css ./docs/_build/html/pycco/finance +cp ./etc/pycco.css ./docs/_build/html/pycco/test +cp ./etc/pycco.css ./docs/_build/html/pycco/transforms #run all the tests in test. see setup.cfg for flags. nosetests --config=jenkins_setup.cfg @@ -40,6 +45,6 @@ cp ./pylint.rcfile /mnt/jenkins/.pylintrc #default location for config file... pylint -f parseable zipline > pylint.out #run sloccount analysis -sloccount --wide --details ./ > sloccount.sc +sloccount --wide --details ./zipline > sloccount.sc deactivate diff --git a/etc/pycco.css b/etc/pycco.css new file mode 100644 index 00000000..152370c4 --- /dev/null +++ b/etc/pycco.css @@ -0,0 +1,186 @@ +/*--------------------- Layout and Typography ----------------------------*/ +body { + font-family: 'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif; + font-size: 16px; + line-height: 24px; + color: #252519; + margin: 0; padding: 0; +} +a { + color: #261a3b; +} + a:visited { + color: #261a3b; + } +p { + margin: 0 0 15px 0; +} +h1, h2, h3, h4, h5, h6 { + margin: 40px 0 15px 0; +} +h2, h3, h4, h5, h6 { + margin-top: 0; + } +#container, div.section { + position: relative; +} +#background { + position: fixed; + top: 0; left: 790px; right: 0; bottom: 0; + background: #f5f5ff; + border-left: 1px solid #e5e5ee; + z-index: -1; +} +#jump_to, #jump_page { + background: white; + -webkit-box-shadow: 0 0 25px #777; -moz-box-shadow: 0 0 25px #777; + -webkit-border-bottom-left-radius: 5px; -moz-border-radius-bottomleft: 5px; + font: 10px Arial; + text-transform: uppercase; + cursor: pointer; + text-align: right; +} +#jump_to, #jump_wrapper { + position: fixed; + right: 0; top: 0; + padding: 5px 10px; +} + #jump_wrapper { + padding: 0; + display: none; + } + #jump_to:hover #jump_wrapper { + display: block; + } + #jump_page { + padding: 5px 0 3px; + margin: 0 0 25px 25px; + } + #jump_page .source { + display: block; + padding: 5px 10px; + text-decoration: none; + border-top: 1px solid #eee; + } + #jump_page .source:hover { + background: #f5f5ff; + } + #jump_page .source:first-child { + } +div.docs { + float: left; + max-width: 710px; + min-width: 710px; + min-height: 5px; + padding: 10px 25px 1px 50px; + vertical-align: top; + text-align: left; +} + .docs pre { + margin: 15px 0 15px; + padding-left: 15px; + } + .docs p tt, .docs p code { + background: #f8f8ff; + border: 1px solid #dedede; + font-size: 12px; + padding: 0 0.2em; + } + .octowrap { + position: relative; + } + .octothorpe { + font: 12px Arial; + text-decoration: none; + color: #454545; + position: absolute; + top: 3px; left: -20px; + padding: 1px 2px; + opacity: 0; + -webkit-transition: opacity 0.2s linear; + } + div.docs:hover .octothorpe { + opacity: 1; + } +div.code { + margin-left: 790px; + padding: 14px 15px 16px 50px; + vertical-align: top; +} + .code pre, .docs p code { + font-size: 12px; + } + pre, tt, code { + line-height: 18px; + font-family: Monaco, Consolas, "Lucida Console", monospace; + margin: 0; padding: 0; + } +div.clearall { + clear: both; +} + + +/*---------------------- Syntax Highlighting -----------------------------*/ +td.linenos { background-color: #f0f0f0; padding-right: 10px; } +span.lineno { background-color: #f0f0f0; padding: 0 5px 0 5px; } +body .hll { background-color: #ffffcc } +body .c { color: #408080; font-style: italic } /* Comment */ +body .err { border: 1px solid #FF0000 } /* Error */ +body .k { color: #954121 } /* Keyword */ +body .o { color: #666666 } /* Operator */ +body .cm { color: #408080; font-style: italic } /* Comment.Multiline */ +body .cp { color: #BC7A00 } /* Comment.Preproc */ +body .c1 { color: #408080; font-style: italic } /* Comment.Single */ +body .cs { color: #408080; font-style: italic } /* Comment.Special */ +body .gd { color: #A00000 } /* Generic.Deleted */ +body .ge { font-style: italic } /* Generic.Emph */ +body .gr { color: #FF0000 } /* Generic.Error */ +body .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +body .gi { color: #00A000 } /* Generic.Inserted */ +body .go { color: #808080 } /* Generic.Output */ +body .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +body .gs { font-weight: bold } /* Generic.Strong */ +body .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +body .gt { color: #0040D0 } /* Generic.Traceback */ +body .kc { color: #954121 } /* Keyword.Constant */ +body .kd { color: #954121; font-weight: bold } /* Keyword.Declaration */ +body .kn { color: #954121; font-weight: bold } /* Keyword.Namespace */ +body .kp { color: #954121 } /* Keyword.Pseudo */ +body .kr { color: #954121; font-weight: bold } /* Keyword.Reserved */ +body .kt { color: #B00040 } /* Keyword.Type */ +body .m { color: #666666 } /* Literal.Number */ +body .s { color: #219161 } /* Literal.String */ +body .na { color: #7D9029 } /* Name.Attribute */ +body .nb { color: #954121 } /* Name.Builtin */ +body .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +body .no { color: #880000 } /* Name.Constant */ +body .nd { color: #AA22FF } /* Name.Decorator */ +body .ni { color: #999999; font-weight: bold } /* Name.Entity */ +body .ne { color: #D2413A; font-weight: bold } /* Name.Exception */ +body .nf { color: #0000FF } /* Name.Function */ +body .nl { color: #A0A000 } /* Name.Label */ +body .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +body .nt { color: #954121; font-weight: bold } /* Name.Tag */ +body .nv { color: #19469D } /* Name.Variable */ +body .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +body .w { color: #bbbbbb } /* Text.Whitespace */ +body .mf { color: #666666 } /* Literal.Number.Float */ +body .mh { color: #666666 } /* Literal.Number.Hex */ +body .mi { color: #666666 } /* Literal.Number.Integer */ +body .mo { color: #666666 } /* Literal.Number.Oct */ +body .sb { color: #219161 } /* Literal.String.Backtick */ +body .sc { color: #219161 } /* Literal.String.Char */ +body .sd { color: #219161; font-style: italic } /* Literal.String.Doc */ +body .s2 { color: #219161 } /* Literal.String.Double */ +body .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ +body .sh { color: #219161 } /* Literal.String.Heredoc */ +body .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ +body .sx { color: #954121 } /* Literal.String.Other */ +body .sr { color: #BB6688 } /* Literal.String.Regex */ +body .s1 { color: #219161 } /* Literal.String.Single */ +body .ss { color: #19469D } /* Literal.String.Symbol */ +body .bp { color: #954121 } /* Name.Builtin.Pseudo */ +body .vc { color: #19469D } /* Name.Variable.Class */ +body .vg { color: #19469D } /* Name.Variable.Global */ +body .vi { color: #19469D } /* Name.Variable.Instance */ +body .il { color: #666666 } /* Literal.Number.Integer.Long */ diff --git a/zipline/finance/performance.py b/zipline/finance/performance.py index f8659f2f..ac459697 100644 --- a/zipline/finance/performance.py +++ b/zipline/finance/performance.py @@ -122,14 +122,13 @@ import zipline.finance.risk as risk class PerformanceTracker(): """ - - Tracks the performance of the zipstream as it is running in - the simulotr, relays this out to the Deluge broker and then - to the client. - - +--------------------+ Result Stream +--------+ - | PerformanceTracker | ----------------> | Deluge | - +--------------------+ +--------+ + Tracks the performance of the zipline as it is running in + the simulator, relays this out to the Deluge broker and then + to the client. Visually: + + +--------------------+ Result Stream +--------+ + | PerformanceTracker | ----------------> | Deluge | + +--------------------+ +--------+ """ diff --git a/zipline/lines.py b/zipline/lines.py index 640885d4..c23f9a78 100644 --- a/zipline/lines.py +++ b/zipline/lines.py @@ -95,34 +95,36 @@ from zipline.monitor import Controller class SimulatedTrading(object): """ - Zipline with:: - - _no_ data sources. - - Trade simulation client, which is available to send callbacks on - events and also accept orders to be simulated. - - An order data source, which will receive orders from the trade - simulation client, and feed them into the event stream to be - serialized and order alongside all other data source events. - - transaction simulation transformation, which receives the order - events and estimates a theoretical execution price and volume. - - All components in this zipline are subject to heartbeat checks and - a control monitor, which can kill the entire zipline in the event of - exceptions in one of the components or an external request to end the - simulation. + Zipline with:: + + - _no_ data sources. + - Trade simulation client, which is available to send callbacks on + events and also accept orders to be simulated. + - An order data source, which will receive orders from the trade + simulation client, and feed them into the event stream to be + serialized and order alongside all other data source events. + - transaction simulation transformation, which receives the order + events and estimates a theoretical execution price and volume. + + All components in this zipline are subject to heartbeat checks and + a control monitor, which can kill the entire zipline in the event of + exceptions in one of the components or an external request to end the + simulation. """ def __init__(self, **config): """ :param config: a dict with the following required properties:: - - algorithm: a class that follows the algorithm protocol. See - :py:meth:`zipline.finance.trading.TradingSimulationClient.add_algorithm` - for details. - - trading_environment: an instance of - :py:class:`zipline.trading.TradingEnvironment` - - allocator: an instance of - :py:class:`zipline.simulator.AddressAllocator` - - simulator_class: a :py:class:`zipline.messaging.ComponentHost` - subclass (not an instance) + + - algorithm: a class that follows the algorithm protocol. See + :py:meth:`zipline.finance.trading.TradingSimulationClient.add_algorithm` + for details. + - trading_environment: an instance of + :py:class:`zipline.trading.TradingEnvironment` + - allocator: an instance of + :py:class:`zipline.simulator.AddressAllocator` + - simulator_class: a :py:class:`zipline.messaging.ComponentHost` + subclass (not an instance) """ assert isinstance(config, dict) self.algorithm = config['algorithm'] @@ -176,18 +178,19 @@ class SimulatedTrading(object): def create_test_zipline(**config): """ :param config: A configuration object that is a dict with:: - - environment - a \ - :py:class:`zipline.finance.trading.TradingEnvironment` - - allocator - a :py:class:`zipline.simulator.AddressAllocator` - - sid - an integer, which will be used as the security ID. - - order_count - the number of orders the test algo will place, - defaults to 100 - - trade_count - the number of trades to simulate, defaults to 100 - - simulator_class - optional parameter that provides an alternative - subclass of ComponentHost to hold the whole zipline. Defaults to - :py:class:`zipline.simulator.Simulator` - - algorithm - optional parameter providing an algorithm. defaults - to :py:class:`zipline.test.algorithms.TestAlgorithm` + + - environment - a \ + :py:class:`zipline.finance.trading.TradingEnvironment` + - allocator - a :py:class:`zipline.simulator.AddressAllocator` + - sid - an integer, which will be used as the security ID. + - order_count - the number of orders the test algo will place, + defaults to 100 + - trade_count - the number of trades to simulate, defaults to 100 + - simulator_class - optional parameter that provides an alternative + subclass of ComponentHost to hold the whole zipline. Defaults to + :py:class:`zipline.simulator.Simulator` + - algorithm - optional parameter providing an algorithm. defaults + to :py:class:`zipline.test.algorithms.TestAlgorithm` """ assert isinstance(config, dict) @@ -308,9 +311,9 @@ class SimulatedTrading(object): def shutdown(self): self.allocator.reaquire(*self.leased_sockets) - #--------------------------------# - # Component property accessors # - #--------------------------------# + #-------------------------------- + # Component property accessors + #-------------------------------- def get_positions(self): """ diff --git a/zipline/protocol.py b/zipline/protocol.py index e60177aa..fb5cb5e8 100644 --- a/zipline/protocol.py +++ b/zipline/protocol.py @@ -126,9 +126,9 @@ from protocol_utils import Enum, FrameExceptionFactory, namedict #import ujson #import ultrajson_numpy -# ================ +# ----------------------- # Control Protocol -# ================ +# ----------------------- INVALID_CONTROL_FRAME = FrameExceptionFactory('CONTROL') @@ -166,9 +166,9 @@ def CONTORL_UNFRAME(msg): #except AssertionError: #raise INVALID_CONTROL_FRAME(msg) -# ================== +# ----------------------- # Heartbeat Protocol -# ================== +# ----------------------- # These encode the msgpack equivelant of 1 and 2. The heartbeat # frame should only be 1 byte on the wire. @@ -178,9 +178,9 @@ HEARTBEAT_PROTOCOL = namedict({ 'REP' : b'\x02', }) -# ================== +# ----------------------- # Component State -# ================== +# ----------------------- COMPONENT_TYPE = Enum( 'SOURCE' , # 0 @@ -215,9 +215,9 @@ BACKTEST_STATE = Enum( 'DONE' , # done ( naturally completed ) ) -# ================== +# ----------------------- # Datasource Protocol -# ================== +# ----------------------- INVALID_DATASOURCE_FRAME = FrameExceptionFactory('DATASOURCE') @@ -225,13 +225,16 @@ def DATASOURCE_FRAME(event): """ Wraps any datasource payload with id and type, so that unpacking may choose the write UNFRAME for the payload. + + :param event: namedict with following properties - ::ds_id:: an identifier that is unique to the datasource in the context of - a component host (e.g. Simulator - ::ds_type:: a string denoting the datasource type. Must be on of:: - TRADE - (others to follow soon) - ::payload:: a msgpack string carrying the payload for the frame + - *ds_id* an identifier that is unique to the datasource in the context of a component host (e.g. Simulator) + - *ds_type* a string denoting the datasource type. Must be on of: + + - TRADE + - (others to follow soon) + + - *payload* a msgpack string carrying the payload for the frame """ assert isinstance(event.source_id, basestring) @@ -262,19 +265,24 @@ def DATASOURCE_FRAME(event): def DATASOURCE_UNFRAME(msg): """ - Extracts payload, and calls correct UNFRAME method based on the datasource - type passed along. + + Extracts payload, and calls correct UNFRAME method based on the \ +datasource type passed along. + + Returns a dict containing at least: + + - source_id + - type - returns a dict containing at least:: - - source_id - - type - - other properties are added based on the datasource type:: - - TRADE:: - - sid - int security identifier - - price - float - - volume - int - - dt - a datetime object + other properties are added based on the datasource type: + + - TRADE + + - sid - int security identifier + - price - float + - volume - int + - dt - a datetime object + """ try: @@ -298,14 +306,16 @@ def DATASOURCE_UNFRAME(msg): except ValueError: raise INVALID_DATASOURCE_FRAME(msg) -# ================== +# ----------------------- # Feed Protocol -# ================== +# ----------------------- + INVALID_FEED_FRAME = FrameExceptionFactory('FEED') def FEED_FRAME(event): """ - :event: a nameddict with at least:: + :param event: a nameddict with at least + - source_id - type """ @@ -329,9 +339,10 @@ def FEED_UNFRAME(msg): except ValueError: raise INVALID_FEED_FRAME(msg) -# ================== +# ----------------------- # Transform Protocol -# ================== +# ----------------------- + INVALID_TRANSFORM_FRAME = FrameExceptionFactory('TRANSFORM') def TRANSFORM_FRAME(name, value): @@ -364,14 +375,15 @@ def TRANSFORM_UNFRAME(msg): except ValueError: raise INVALID_TRANSFORM_FRAME(msg) -# ================== +# ----------------------- # Merge Protocol -# ================== +# ----------------------- INVALID_MERGE_FRAME = FrameExceptionFactory('MERGE') def MERGE_FRAME(event): """ - :event: a nameddict with at least:: + :param event: a nameddict with at least: + - source_id - type """ @@ -404,23 +416,27 @@ def MERGE_UNFRAME(msg): raise INVALID_MERGE_FRAME(msg) -# ================== +# ----------------------- # Finance Protocol -# ================== +# ----------------------- INVALID_ORDER_FRAME = FrameExceptionFactory('ORDER') INVALID_TRADE_FRAME = FrameExceptionFactory('TRADE') -# ================== -# Trades - Should only be called from inside DATASOURCE_ (UN)FRAME. -# ================== +# ----------------------- +# Trades +# ----------------------- +# +# - Should only be called from inside DATASOURCE_ (UN)FRAME. def TRADE_FRAME(event): - """:event: should be a namedict with:: - - ds_id -- the datasource id sending this trade out - - sid -- the security id - - price -- float of the price printed for the trade - - volume -- int for shares in the trade - - dt -- datetime for the trade + """ + :param event: should be a namedict with: + + - ds_id -- the datasource id sending this trade out + - sid -- the security id + - price -- float of the price printed for the trade + - volume -- int for shares in the trade + - dt -- datetime for the trade """ assert isinstance(event, namedict) @@ -459,9 +475,10 @@ def TRADE_UNFRAME(msg): except ValueError: raise INVALID_TRADE_FRAME(msg) -# ========= -# Orders - from client to order source -# ========= +# ----------------------- +# Orders +# ----------------------- +# - from client to order source def ORDER_FRAME(order): assert isinstance(order.sid, int) @@ -491,10 +508,14 @@ def ORDER_UNFRAME(msg): except ValueError: raise INVALID_ORDER_FRAME(msg) -# -# ================== -# TRANSACTIONS - Should only be called from inside TRANSFORM_(UN)FRAME. -# ================== + +# ----------------------- +# TRANSACTIONS +# ----------------------- +# +# - Should only be called from inside TRANSFORM_(UN)FRAME. + + def TRANSACTION_FRAME(event): assert isinstance(event, namedict) @@ -535,10 +556,13 @@ def TRANSACTION_UNFRAME(msg): raise INVALID_TRADE_FRAME(msg) -# ========= -# Orders - from order source to feed -# - should only be called from inside DATASOURCE_(UN)FRAME -# ========= +# ----------------------- +# ORDERS +# ----------------------- +# +# - from order source to feed +# - should only be called from inside DATASOURCE_(UN)FRAME + def ORDER_SOURCE_FRAME(event): assert isinstance(event.sid, int) @@ -576,15 +600,16 @@ def ORDER_SOURCE_UNFRAME(msg): except ValueError: raise INVALID_ORDER_FRAME(msg) -# ================= +# ----------------------- # Date Helpers -# ================= +# ----------------------- def PACK_DATE(event): """ Packs the datetime property of event into msgpack'able longs. This function should be called purely for its side effects. - The event's 'dt' property is replaced by a tuple of integers:: + The event's 'dt' property is replaced by a tuple of integers + - year, month, day, hour, minute, second, microsecond PACK_DATE and UNPACK_DATE are inverse operations. @@ -607,10 +632,12 @@ def UNPACK_DATE(event): UNPACK_DATE and PACK_DATE are inverse operations. - :param tuple event: event must a namedict with:: - - a property named 'dt_tuple' that is a tuple of integers - representing the date and time in UTC. dt_tumple must have year, - month, day, hour, minute, second, and microsecond + :param tuple event: event must a namedict with: + + - a property named 'dt_tuple' that is a tuple of integers \ + representing the date and time in UTC. + - dt_tuple must have year, month, day, hour, minute, second, and microsecond + :rtype: None """ assert isinstance(event.dt, tuple)