Permalink
Browse files

some docstring cleanup

  • Loading branch information...
minrk committed Jan 23, 2011
1 parent b0d94c7 commit 689bb475cc6ae618cabf87917ad0eaaa61ebb50c
Showing with 89 additions and 18 deletions.
  1. +21 −8 IPython/zmq/parallel/client.py
  2. +19 −5 IPython/zmq/parallel/streamsession.py
  3. +49 −5 IPython/zmq/parallel/view.py
@@ -29,10 +29,16 @@
from dependency import Dependency, depend, require
import error
+#--------------------------------------------------------------------------
+# helpers for implementing old MEC API via client.apply
+#--------------------------------------------------------------------------
+
def _push(ns):
+ """helper method for implementing `client.push` via `client.apply`"""
globals().update(ns)
def _pull(keys):
+ """helper method for implementing `client.pull` via `client.apply`"""
g = globals()
if isinstance(keys, (list,tuple, set)):
for key in keys:
@@ -45,10 +51,13 @@ def _pull(keys):
return g.get(keys)
def _clear():
+ """helper method for implementing `client.clear` via `client.apply`"""
globals().clear()
def execute(code):
+ """helper method for implementing `client.execute` via `client.apply`"""
exec code in globals()
+
#--------------------------------------------------------------------------
# Decorators for Client methods
@@ -613,7 +622,7 @@ def shutdown(self, targets=None, restart=False, controller=False, block=None):
error = ss.unwrap_exception(msg['content'])
if error:
- return error
+ raise error
#--------------------------------------------------------------------------
# Execution methods
@@ -623,6 +632,8 @@ def shutdown(self, targets=None, restart=False, controller=False, block=None):
def execute(self, code, targets='all', block=None):
"""Executes `code` on `targets` in blocking or nonblocking manner.
+ ``execute`` is always `bound` (affects engine namespace)
+
Parameters
----------
code : str
@@ -634,18 +645,16 @@ def execute(self, code, targets='all', block=None):
whether or not to wait until done to return
default: self.block
"""
- # block = self.block if block is None else block
- # saveblock = self.block
- # self.block = block
result = self.apply(execute, (code,), targets=targets, block=block, bound=True)
- # self.block = saveblock
return result
def run(self, code, block=None):
"""Runs `code` on an engine.
Calls to this are load-balanced.
+ ``run`` is never `bound` (no effect on engine namespace)
+
Parameters
----------
code : str
@@ -908,7 +917,7 @@ def queue_status(self, targets=None, verbose=False):
the engines on which to execute
default : all
verbose : bool
- whether to return lengths only, or lists of ids for each element
+ Whether to return lengths only, or lists of ids for each element
"""
targets = self._build_targets(targets)[1]
content = dict(targets=targets, verbose=verbose)
@@ -927,12 +936,16 @@ def purge_results(self, msg_ids=[], targets=[]):
"""Tell the controller to forget results.
Individual results can be purged by msg_id, or the entire
- history of specific targets can
+ history of specific targets can be purged.
Parameters
----------
+ msg_ids : str or list of strs
+ the msg_ids whose results should be forgotten.
targets : int/str/list of ints/strs
- the targets
+ The targets, by uuid or int_id, whose entire history is to be purged.
+ Use `targets='all'` to scrub everything from the controller's memory.
+
default : None
"""
if not targets and not msg_ids:
@@ -201,7 +201,7 @@ def serialize_object(obj, threshold=64e-6):
def unserialize_object(bufs):
- """reconstruct an object serialized by serialize_object from data buffers"""
+ """reconstruct an object serialized by serialize_object from data buffers."""
bufs = list(bufs)
sobj = pickle.loads(bufs.pop(0))
if isinstance(sobj, (list, tuple)):
@@ -402,7 +402,7 @@ def send(self, stream, msg_type, content=None, buffers=None, parent=None, subhea
return omsg
def send_raw(self, stream, msg, flags=0, copy=True, ident=None):
- """Send a raw message via idents.
+ """Send a raw message via ident path.
Parameters
----------
@@ -444,9 +444,23 @@ def recv(self, socket, mode=zmq.NOBLOCK, content=True, copy=True):
raise e
def feed_identities(self, msg, copy=True):
- """This is a completely horrible thing, but it strips the zmq
- ident prefixes off of a message. It will break if any identities
- are unpackable by self.unpack."""
+ """feed until DELIM is reached, then return the prefix as idents and remainder as
+ msg. This is easily broken by setting an IDENT to DELIM, but that would be silly.
+
+ Parameters
+ ----------
+ msg : a list of Message or bytes objects
+ the message to be split
+ copy : bool
+ flag determining whether the arguments are bytes or Messages
+
+ Returns
+ -------
+ (idents,msg) : two lists
+ idents will always be a list of bytes - the indentity prefix
+ msg will be a list of bytes or Messages, unchanged from input
+ msg should be unpackable via self.unpack_message at this point.
+ """
msg = list(msg)
idents = []
while len(msg) > 3:
@@ -1,11 +1,24 @@
-#!/usr/bin/env python
-"""Views"""
+"""Views of remote engines"""
+#-----------------------------------------------------------------------------
+# Copyright (C) 2010 The IPython Development Team
+#
+# Distributed under the terms of the BSD License. The full license is in
+# the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
from IPython.external.decorator import decorator
+#-----------------------------------------------------------------------------
+# Decorators
+#-----------------------------------------------------------------------------
@decorator
def myblock(f, self, *args, **kwargs):
+ """override client.block with self.block during a call"""
block = self.client.block
self.client.block = self.block
ret = f(self, *args, **kwargs)
@@ -14,6 +27,7 @@ def myblock(f, self, *args, **kwargs):
@decorator
def save_ids(f, self, *args, **kwargs):
+ """Keep our history and outstanding attributes up to date after a method call."""
ret = f(self, *args, **kwargs)
msg_ids = self.client.history[-self._ntargets:]
self.history.extend(msg_ids)
@@ -22,6 +36,7 @@ def save_ids(f, self, *args, **kwargs):
@decorator
def sync_results(f, self, *args, **kwargs):
+ """sync relevant results from self.client to our results attribute."""
ret = f(self, *args, **kwargs)
delta = self.outstanding.difference(self.client.outstanding)
completed = self.outstanding.intersection(delta)
@@ -32,13 +47,20 @@ def sync_results(f, self, *args, **kwargs):
@decorator
def spin_after(f, self, *args, **kwargs):
+ """call spin after the method."""
ret = f(self, *args, **kwargs)
self.spin()
return ret
+#-----------------------------------------------------------------------------
+# Classes
+#-----------------------------------------------------------------------------
class View(object):
- """Base View class"""
+ """Base View class for more convenint apply(f,*args,**kwargs) syntax via attributes.
+
+ Don't use this class, use subclasses.
+ """
_targets = None
_ntargets = None
block=None
@@ -67,7 +89,7 @@ def targets(self):
@targets.setter
def targets(self, value):
- raise TypeError("Cannot set my targets argument after construction!")
+ raise AttributeError("Cannot set my targets argument after construction!")
@sync_results
def spin(self):
@@ -175,7 +197,16 @@ def purge_results(self, msg_ids=[],targets=[]):
class DirectView(View):
- """Direct Multiplexer View"""
+ """Direct Multiplexer View of one or more engines.
+
+ These are created via indexed access to a client:
+
+ >>> dv_1 = client[1]
+ >>> dv_all = client[:]
+ >>> dv_even = client[::2]
+ >>> dv_some = client[1:3]
+
+ """
def update(self, ns):
"""update remote namespace with dict `ns`"""
@@ -214,6 +245,19 @@ def kill(self, block=True):
return self.client.kill(targets=self.targets, block=block)
class LoadBalancedView(View):
+ """An engine-agnostic View that only executes via the Task queue.
+
+ Typically created via:
+
+ >>> lbv = client[None]
+ <LoadBalancedView tcp://127.0.0.1:12345>
+
+ but can also be created with:
+
+ >>> lbc = LoadBalancedView(client)
+
+ TODO: allow subset of engines across which to balance.
+ """
def __repr__(self):
return "<%s %s>"%(self.__class__.__name__, self.client._addr)

0 comments on commit 689bb47

Please sign in to comment.