Skip to content

Commit

Permalink
Review parameter documentation (initial commit)
Browse files Browse the repository at this point in the history
  • Loading branch information
@rafaduran
rafaduran committed Mar 15, 2014
1 parent dcf1b91 commit 23b8d7b
Show file tree
Hide file tree
Showing 3 changed files with 103 additions and 79 deletions.
59 changes: 38 additions & 21 deletions pymco/config.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@
def lookup_with_default(fnc):
"""
Wraps ConfigParser lookups, catching exceptions and providing defaults.
:param fnc: Function to be decorated.
"""
@functools.wraps(fnc)
def decorator(self, name, *args, **kwargs):
Expand Down Expand Up @@ -51,22 +53,34 @@ def __getitem__(self, key):

@lookup_with_default
def get(self, key):
"""Get option by key."""
"""Get option by key.
:param key: key to look for.
"""
return self.__getitem__(key)

@lookup_with_default
def getint(self, key):
"""Get int option by key."""
"""Get int option by key.
:param key: key to look for.
"""
return int(self.__getitem__(key))

@lookup_with_default
def getfloat(self, key):
"""Get float option by key."""
"""Get float option by key.
:param key: key to look for.
"""
return float(self.__getitem__(key))

@lookup_with_default
def getboolean(self, key):
"""Get bool option by key."""
"""Get bool option by key.
:param key: key to look for.
"""
value = self.__getitem__(key)
if isinstance(value, six.string_types):
if value.lower() in ('true', 'y', '1'):
Expand Down Expand Up @@ -96,8 +110,7 @@ def get_host_and_ports(self):
The result must follow the :py:class:`stomp.Connection`
``host_and_ports`` parameter.
Returns:
``host_and_ports``: Iterable of two-tuple where the first element
:returns: Iterable of two-tuple where the first element
is the host and the second is the port.
"""
if self.config['connector'] == 'stomp':
Expand All @@ -118,19 +131,16 @@ def get_host_and_ports(self):
def get_user_and_password(self, current_host_and_port=None):
"""Get the user and password for the current host and port.
Args:
``current_host_and_port`` (iterable): two-tuple where the first element is the
:param current_host_and_port: two-tuple iterable where the first element is the
host and second is the port. This parameter is not required for
``stomp`` connector.
:py:class:`pymco.connector.stomp.StompConnector` connector.
Returns:
Two-tuple where the first element is the user and the second is
:returns: Two-tuple where the first element is the user and the second is
the password for the given host and port.
Raises:
:py:exc:`ValueError`: if connector isn't ``stomp`` and
:raises: :py:exc:`ValueError` if connector isn't ``stomp`` and
``host_and_port`` is not provided.
:py:exc:`pymco.exc.ConfigLookupError`: if host and port are not
:raises: :py:exc:`pymco.exc.ConfigLookupError` if host and port are not
found into the connector list of host and ports.
"""
connector = self.config['connector']
Expand All @@ -156,8 +166,7 @@ def get_user_and_password(self, current_host_and_port=None):
def get_ssl_params(self):
"""Get SSL configuration for current connector
Returns:
``ssl_params``: An iterable of SSL configuration parameters to be
:returns: An iterable of SSL configuration parameters to be
used with :py:meth:`stomp.Transport.set_ssl`.
"""
connector = self.config['connector']
Expand Down Expand Up @@ -186,9 +195,7 @@ def get_ssl_params(self):
def get_conn_params(self):
"""Get STOMP connection parameters for current configuration.
Returns:
``params``: It will return a dictionary with stomp.py connection
like key/values.
:returns: Dictionary with stomp.py connection like key/values.
"""
connector = self.config['connector']
prefix = 'plugin.{0}.'.format(connector)
Expand All @@ -214,13 +221,23 @@ def get_conn_params(self):

@staticmethod
def from_configfile(configfile):
"""Reads configfile and returns a new :py:class:`Config` instance"""
"""Reads configfile and returns a new :py:class:`Config` instance
:param configfile: path to the configuration file to be parsed.
:returns: :py:class:`Config` instance.
"""
configstr = open(configfile, 'rt').read()
return Config.from_configstr(configstr)

@staticmethod
def from_configstr(configstr, section='default'):
"""Parses given string an returns a new :py:class:`Config` instance"""
"""Parses given string an returns a new :py:class:`Config` instance
:param configstr: configuration file content as string.
:param section: dummy section to be used for parsing configuration as
INI file.
:returns: :py:class:`Config` instance.
"""
config = six.StringIO()
config.write('[{0}]\n'.format(section))
config.write(configstr)
Expand Down
87 changes: 37 additions & 50 deletions pymco/connector/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ class BaseConnector(object):
id_generator = itertools.count()

def __init__(self, config, connection=None):
"""
:param config: :py:class:`pymco.Config`
"""
self.config = config
self._security = None
self._started = False
Expand All @@ -41,7 +44,11 @@ def __init__(self, config, connection=None):
self.set_ssl()

def connect(self, wait=None):
"""Connect to MCollective middleware."""
"""Connect to MCollective middleware.
:param wait: wait for connection to be established or not.
:returns: ``self``.
"""
if not self.connection.connected:
self.connection.start()
user, password = self.config.get_user_and_password(
Expand All @@ -53,7 +60,10 @@ def connect(self, wait=None):
return self

def disconnect(self):
"""Disconnet from MCollective middleware."""
"""Disconnet from MCollective middleware.
:returns: ``self``.
"""
if self.connection.is_connected():
self.connection.disconnect()

Expand All @@ -62,11 +72,8 @@ def disconnect(self):
def send(self, msg, destination, *args, **kwargs):
"""Send an MCollective message.
Args:
``msg``: message to be sent.
Returns:
``self``: so you can chain calls.
:param msg: message to be sent.
:returns: ``self``.
"""
self.connection.send(body=self.security.encode(msg),
destination=destination,
Expand All @@ -76,15 +83,10 @@ def send(self, msg, destination, *args, **kwargs):
def subscribe(self, destination, id=None, *args, **kwargs):
"""Subscribe to MCollective queue.
Args:
``destination``: Target to subscribe.
``args``: extra positional arguments.
``kwargs``: extra keyword arguments.
Returns:
``self``: so you can chain calls.
:param destination: Target to subscribe.
:param args: extra positional arguments.
:param kwargs: extra keyword arguments.
:returns: ``self``.
"""
if not id:
id = self.id
Expand All @@ -95,31 +97,21 @@ def subscribe(self, destination, id=None, *args, **kwargs):
def unsubscribe(self, destination, *args, **kwargs):
"""Unsubscribe to MCollective queue.
Args:
``destination``: Target to unsubscribe.
``args``: extra positional arguments.
``kwargs``: extra keyword arguments.
Returns:
``self``: so you can chain calls.
:param destination: Target to unsubscribe.
:param args: extra positional arguments.
:param kwargs: extra keyword arguments.
:returns: ``self``.
"""

def receive(self, timeout, *args, **kwargs):
"""Subscribe to MCollective topic queue and wait for just one message.
Args:
``timeout``: how long we should wait for the message.
``args``: extra positional arguments.
``kwargs``: extra keyword arguments.
Returns:
``message``: received message.
Raises: :py:exc:`pymco.exc.TimeoutError`
:param timeout: how long we should wait for the message.
:param args: extra positional arguments.
:param kwargs: extra keyword arguments.
:returns message``: received message.
:raises: :py:exc:`pymco.exc.TimeoutError` if expected messages doesn't
come in given ``timeout`` seconds.
"""
response_listener = listener.SingleResponseListener(timeout=timeout,
config=self.config)
Expand Down Expand Up @@ -155,9 +147,8 @@ def set_listeners(self):
def get_current_host_and_port(self):
"""Get the current host and port from the tracker listener.
Returns:
``current_host_and_port``: A two-tuple, where the first element is
the current host and the second the current port.
:returns: A two-tuple, where the first element is the current host and
the second the current port.
"""
tracker = self.connection.get_listener('tracker')
return tracker.get_host(), tracker.get_port()
Expand All @@ -180,24 +171,20 @@ def default_connection(cls, config):
def get_target(self, agent, collective, topciprefix=None):
"""Get the message target for the given agent and collective.
Args:
``agent``: MCollective target agent name.
``collective``: MCollective target collective.
``topicprefix``: Required for older versions of MCollective
Returns:
``target``: Message target string representation for given agent and
:param agent: MCollective target agent name.
:param collective: MCollective target collective.
:param topicprefix: Required for older versions of MCollective
:returns: Message target string representation for given agent and
collective.
"""


def get_reply_target(self, agent, collective):
"""Get the message target for the given agent and collective.
Args:
``agent``: MCollective target agent name.
``collective``: MCollective target collective.
Returns:
``reply_target``: Message reply target string representation for given
:param agent: MCollective target agent name.
:param collective: MCollective target collective.
:returns: Message reply target string representation for given
agent and collective.
"""

Expand Down
36 changes: 28 additions & 8 deletions pymco/listener.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,21 +22,40 @@ def __init__(self, *args, **kwargs):
self.curent_port = None

def on_connecting(self, host_and_port):
"""Track current host and port."""
"""Track current host and port.
:param host_and_port: A two-tuple with host as first element and port
as the second.
"""
self.current_host, self.current_port = host_and_port

def get_host(self):
"""Return current host."""
"""Return current host.
:returns: current host.
"""
return self.current_host

def get_port(self):
"""Return current host."""
"""Return current host.
:returns: current port.
"""
return self.current_port


class ResponseListener(listener.ConnectionListener):
"""Listener that waits for a message response."""
def __init__(self, config, count, timeout=30, condition=None):
"""
:param config: :py:class:`pymco.config.Config` instance.
:param count: nymber of expected messages.
:param timeout: seconds we should wait for messages.
:param condition: by default a :py:class:`threading.Condition` object
for synchronization purposes, but you can use any object
implementing the :py:meth:`wait` method and accepting a ``timeout``
argument.
"""
self.config = config
self._security = None
self.timeout = timeout
Expand All @@ -59,10 +78,8 @@ def security(self):
def on_message(self, headers, body):
"""Received messages hook.
Args:
`headers`: message headers.
`body`: message body.
:param headers: message headers.
:param body: message body.
"""
self.condition.acquire()
self.responses.append(self.security.deserialize(body))
Expand All @@ -71,7 +88,10 @@ def on_message(self, headers, body):
self.condition.release()

def wait_on_message(self):
"""Wait until we get a message."""
"""Wait until we get a message.
:returns: ``self``.
"""
self.condition.acquire()
self._wait_loop(self.timeout)
self.condition.release()
Expand Down

0 comments on commit 23b8d7b

Please sign in to comment.