Skip to content

Commit

Permalink
Prettified tox.ini and made docstrings and comments PEP 8 compliant
Browse files Browse the repository at this point in the history
  • Loading branch information
@agronholm
agronholm committed Nov 29, 2015
1 parent 4ecd2d6 commit 81d9a11
Show file tree
Hide file tree
Showing 8 changed files with 289 additions and 195 deletions.
10 changes: 7 additions & 3 deletions asphalt/core/command.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,11 @@


def quickstart_application():
"""Asks a few questions and builds a skeleton application directory structure."""
"""
Asks a few questions and builds a skeleton application directory
structure.
"""
current_version = pkg_resources.get_distribution('asphalt').parsed_version.public
next_major_version = '{}.0.0'.format(int(current_version.split('.')[0]) + 1)

Expand Down Expand Up @@ -103,12 +106,13 @@ def start(ctx: Context):

def run_from_config_file(config_file: Union[str, Path], runner: str='asyncio', unsafe: bool=False):
"""
Runs an application using configuration from the given configuration file.
Runs an application using configuration from the given
configuration file.
:param config_file: path to a YAML configuration file
:param unsafe: ``True`` to load the YAML file in unsafe mode
"""
"""
# Read the configuration from the supplied YAML file
with Path(config_file).open() as stream:
config = yaml.load(stream) if unsafe else yaml.safe_load(stream)
Expand Down
35 changes: 21 additions & 14 deletions asphalt/core/component.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,18 @@ class Component(metaclass=ABCMeta):
@abstractmethod
def start(self, ctx: Context):
"""
This method is the entry point to a component. It can be a coroutine.
This method is the entry point to a component.
It can be a coroutine.
The context can be used to:
* add context event listeners (:meth:`~Context.add_listener`)
* publish resources (:meth:`~Context.publish_resource` and
:meth:`~Context.publish_lazy_resource`)
* request resources (:meth:`~Context.request_resource`)
It is advisable for Components to first publish all the resources they can before
requesting any. This will speed up the dependency resolution and prevent deadlocks.
It is advisable for Components to first publish all the
resources they can before requesting any. This will speed up
the dependency resolution and prevent deadlocks.
:param ctx: the containing context for this component
"""
Expand All @@ -41,18 +43,22 @@ def __init__(self, components: Dict[str, Any]=None):

def add_component(self, alias: str, type: Union[str, type]=None, **kwargs):
"""
Instantiates a component using :func:`create_component` and adds it as a child component
of this container.
Instantiates a component using :func:`create_component` and
adds it as a child component of this container.
If the second argument is omitted, the value of ``alias`` is used as its value.
If the second argument is omitted, the value of ``alias`` is
used as its value.
The locally given configuration can be overridden by component configuration parameters
supplied to the constructor (the ``components`` argument).
The locally given configuration can be overridden by component
configuration parameters supplied to the constructor (the
``components`` argument).
:param alias: a name for the component instance, unique within this container
:param type: entry point name or :cls:`Component` subclass or a textual reference to one
"""
:param alias: a name for the component instance, unique within
this container
:param type: entry point name or :cls:`Component` subclass or a
textual reference to one
"""
if not isinstance(alias, str) or not alias:
raise TypeError('component_alias must be a nonempty string')
if alias in self.child_components:
Expand All @@ -67,10 +73,11 @@ def add_component(self, alias: str, type: Union[str, type]=None, **kwargs):
@asynchronous
def start(self, ctx: Context):
"""
Creates child components that have been configured but not yet created and then calls their
:meth:`Component.start` methods in separate tasks and waits until they have completed.
"""
Creates child components that have been configured but not yet
created and then calls their :meth:`Component.start` methods in
separate tasks and waits until they have completed.
"""
for alias in self.component_config:
if alias not in self.child_components:
self.add_component(alias)
Expand Down
92 changes: 54 additions & 38 deletions asphalt/core/connectors.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@

class ConnectorError(LookupError):
"""
Raised by :func:`create_connector` when the requested connector could not be created or
looked up.
Raised by :func:`create_connector` when the requested connector
could not be created orlooked up.
:ivar endpoint: the endpoint value
"""
Expand All @@ -33,8 +33,9 @@ def __str__(self):

class Connector(metaclass=ABCMeta):
"""
The base class for all connectors. Each connector class contains logic for making a connection
to some endpoint, usually over the network or inter-process communication channels.
The base class for all connectors. Each connector class contains
logic for making a connection to some endpoint, usually over the
network or inter-process communication channels.
"""

__slots__ = ()
Expand All @@ -51,15 +52,17 @@ def connect(self) -> Tuple[StreamReader, StreamWriter]:
@abstractmethod
def parse(cls, endpoint, defaults: Dict[str, Any]) -> Optional['Connector']:
"""
Returns an instance of this connector class if the type and value of ``endpoint`` are
compatible with this connector type.
Returns an instance of this connector class if the type and
value of ``endpoint`` are compatible with this connector type.
Subclasses should indicate what keys in ``defaults`` they can use.
Subclasses should indicate what keys in ``defaults`` they can
use.
:param endpoint: connector specific
:param defaults: a dictionary of default values, some specific to certain connector types
:return: an instance of this class or ``None`` if ``endpoint`` was not compatible with this
connector
:param defaults: a dictionary of default values, some specific
to certain connector types
:return: an instance of this class or ``None`` if ``endpoint``
was not compatible with this connector
"""

@abstractmethod
Expand All @@ -69,28 +72,35 @@ def __str__(self): # pragma: no cover

class TCPConnector(Connector):
"""
Connects to the specified host/port over TCP/IP, optionally using TLS.
Connects to the specified host/port over TCP/IP, optionally using
TLS.
The port can be omitted if one has been specified in the defaults.
The endpoint value can be one of the following:
* a string prefixed with ``tcp://`` or ``tcp+ssl://``
* an :class:`~ipaddress.IPv4Address` or :class:`~ipaddress.IPv6Address`
* an :class:`~ipaddress.IPv4Address` or
:class:`~ipaddress.IPv6Address`
* a dictionary containing the following keys:
* ``host``: string, :class:`~ipaddress.IPv4Address` or :class:`~ipaddress.IPv6Address`
* ``host``: string, :class:`~ipaddress.IPv4Address` or \
:class:`~ipaddress.IPv6Address`
* ``port`` (optional): an integer between 1 and 65535
* ``ssl`` (optional): either a boolean or an :class:`~ssl.SSLContext`
* ``timeout`` (optional): the number of seconds to wait for a connection to be established\
before raising :class:`~asyncio.TimeoutError`
* ``ssl`` (optional): either a boolean or an \
:class:`~ssl.SSLContext`
* ``timeout`` (optional): the number of seconds to wait for a \
connection to be established before raising \
:class:`~asyncio.TimeoutError`
TLS is enabled for this connection if any of these conditions are met:
#. The endpoint is a string that starts with ``tcp+ssl://``
#. The endpoint is a dict where ``ssl`` is set to a truthy value
#. ``ssl`` is ``True`` in ``defaults`` and ssl is not explicitly disabled for this connection
#. ``ssl`` is ``True`` in ``defaults`` and ssl is not explicitly \
disabled for this connection
For raw IPv6 address:port combinations, use the standard [...]:port format.
For example, ``[::1]:1234`` connects to localhost on port 1234 with IPv6.
For raw IPv6 address:port combinations, use the standard [...]:port
format. For example, ``[::1]:1234`` connects to localhost on port
1234 with IPv6.
"""

__slots__ = 'host', 'port', 'ssl', 'timeout'
Expand Down Expand Up @@ -163,20 +173,24 @@ def __str__(self):

class UnixSocketConnector(Connector):
"""
A connector that connects to a UNIX domain socket, optionally using TLS.
A connector that connects to a UNIX domain socket, optionally using
TLS.
The endpoint value can be one of the following:
* a string starting with either ``unix://`` or ``unix+ssl://`` followed by the socket
* a string starting with either ``unix://`` or ``unix+ssl://``
followed by the socket
pathname (absolute or relative to current working directory)
* a dictionary containing the following keys:
* ``path``: a string or :class:`~pathlib.Path`, specifying the target socket
* ``path``: a string or :class:`~pathlib.Path`, specifying the
target socket
* ``ssl``: either a boolean or an :class:`~ssl.SSLContext`
TLS is enabled for this connection if any of these conditions are met:
#. The endpoint is a string that starts with ``unix+ssl://``
#. The endpoint is a dict where ``ssl`` is set to a truthy value
#. ``ssl`` is ``True`` in ``defaults`` and ssl is not explicitly disabled for this connection
#. ``ssl`` is ``True`` in ``defaults`` and ssl is not explicitly
disabled for this connection
"""

__slots__ = 'path', 'ssl', 'timeout'
Expand Down Expand Up @@ -223,23 +237,25 @@ def create_connector(endpoint, defaults: Dict[str, Any]=None, ctx: Context=None,
timeout: int=None) -> Connector:
"""
Creates or looks up a connector from the given endpoint.
The endpoint is offered to each connector class in turn until one of them produces a connector
instance, which is then returned.
It is also possible to resolve named connectors by providing a context as the ``ctx`` argument.
Then supply an ``endpoint`` in the ``resource://<name>`` format (e.g. ``resource://foo`` to
get the connector resource named "foo").
:param endpoint: a connector specific value representing the endpoint of the connection
:param defaults: a dictionary of default values (see the documentation of each connector
type)
The endpoint is offered to each connector class in turn until one
of them produces a connector instance, which is then returned.
It is also possible to resolve named connectors by providing a
context as the ``ctx`` argument. Then supply an ``endpoint`` in
the ``resource://<name>`` format (e.g. ``resource://foo`` to get
the connector resource named "foo").
:param endpoint: a connector specific value representing the
endpoint of the connection
:param defaults: a dictionary of default values (see the
documentation of each connector type)
:param ctx: a context for resolving connector names
:param timeout: timeout for resource lookup (if endpoint refers to a resource; omit to use the
default timeout)
:raises ConnectorError: if all the connector types reject this endpoint or the named connector
resource could not be found
"""
:param timeout: timeout for resource lookup (if endpoint refers to
a resource; omit to use the default timeout)
:raises ConnectorError: if all the connector types reject this
endpoint or the named connector resource could not be found
"""
if isinstance(endpoint, str) and endpoint.startswith('resource://'):
if ctx is None:
raise ConnectorError(endpoint, 'named connector resource requested but no context '
Expand Down

0 comments on commit 81d9a11

Please sign in to comment.