busser-behave 0.1.3

data/vendor/behave/behave/_types.py

@@ -0,0 +1,134 @@
+# -*- coding: UTF-8 -*-
+"""Basic types (helper classes)."""
+
+import sys
+import six
+if six.PY2:
+    # -- USE PYTHON2 BACKPORT: With unicode support
+    import traceback2 as traceback
+else:
+    import traceback
+
+
+class Unknown(object):
+    """Placeholder for unknown/missing information, distinguishable from None.
+
+    .. code-block:: python
+
+        data = {}
+        value = data.get("name", Unknown)
+        if value is Unknown:
+            # -- DO SOMETHING
+            ...
+    """
+
+
+class ExceptionUtil(object):
+    """Provides a utility class for accessing/modifying exception information.
+
+    .. seealso:: PEP-3134 Chained excpetions
+    """
+    # pylint: disable=no-init
+
+    @staticmethod
+    def get_traceback(exception):
+        # -- ASSUMPTION: assert isinstance(exception, Exception)
+        return getattr(exception, "__traceback__", None)
+
+    @staticmethod
+    def set_traceback(exception, exc_traceback=Unknown):
+        assert isinstance(exception, Exception)
+        if exc_traceback is Unknown:
+            exc_traceback = sys.exc_info()[2]
+        exception.__traceback__ = exc_traceback
+
+    @classmethod
+    def has_traceback(cls, exception):
+        """Indicates if traceback information related to this exception
+        is stored with the exception object.
+
+        :param exception:   Exception object to check.
+        :return: True, if traceback info is stored. False, otherwise.
+        """
+        return cls.get_traceback(exception) is not None
+
+    @classmethod
+    def describe(cls, exception, use_traceback=False, prefix=""):
+        # -- NORMAL CASE:
+        text = u"{prefix}{0}: {1}\n".format(exception.__class__.__name__,
+                                            exception, prefix=prefix)
+        if use_traceback:
+            exc_traceback = cls.get_traceback(exception)
+            if exc_traceback:
+                # -- NOTE: Chained-exception cause (see: PEP-3134).
+                text += u"".join(traceback.format_tb(exc_traceback))
+        return text
+
+
+class ChainedExceptionUtil(ExceptionUtil):
+    """Provides a utility class for accessing/modifying exception information
+    related to chained exceptions.
+
+    .. seealso:: PEP-3134 Chained excpetions
+    """
+    # pylint: disable=no-init
+
+    @staticmethod
+    def get_cause(exception):
+        # -- ASSUMPTION: assert isinstance(exception, Exception)
+        return getattr(exception, "__cause__", None)
+
+    @staticmethod
+    def set_cause(exception, exc_cause):
+        assert isinstance(exception, Exception)
+        assert isinstance(exc_cause, Exception) or exc_cause is None
+        exception.__cause__ = exc_cause
+        if exc_cause and not hasattr(exc_cause, "__traceback__"):
+            # -- NEEDED-FOR: Python2
+            # Otherwise, traceback formatting tries to access missing attribute.
+            exc_cause.__traceback__ = None
+
+    # pylint: disable=arguments-differ
+    @classmethod
+    def describe(cls, exception, use_traceback=False, prefix="", style="reversed"):
+        """Describes an exception, optionally together with its traceback info.
+        Also shows information about exception cause (chained exceptions),
+        if exists.
+
+        :param exception:       Exception object to describe.
+        :param use_traceback:   Indicates if traceback info should be shown.
+        :param prefix:          Optional prefix for description text.
+        :param style:           Optional style indicator ("reversed", "normal")
+        :return: Exception description as text.
+        """
+        text = ExceptionUtil.describe(exception, use_traceback, prefix)
+
+        # -- STEP: Collect chained exceptions.
+        causes = []
+        exc_cause = cls.get_cause(exception)
+        while exc_cause:
+            causes.append(exc_cause)
+            exc_cause = cls.get_cause(exc_cause)
+
+        # -- STEP: Describe causes for chained exceptions.
+        parts = []
+        if style == "normal":
+            prefix = "CAUSE: "
+            for exc_cause in reversed(causes):
+                cause_text = ExceptionUtil.describe(exc_cause, use_traceback,
+                                                    prefix)
+                parts.append(cause_text)
+                if len(parts) == 1:
+                    prefix = "CAUSES: "
+            parts.append(text)
+        else:
+            parts.append(text)
+            for exc_cause in causes:
+                cause_text = ExceptionUtil.describe(exc_cause, use_traceback,
+                                                    prefix="CAUSED-BY: ")
+                parts.append(cause_text)
+        return u"\n".join(parts)
+        # if exc_cause:
+        #     cause_text =
+        #     text += u"\n" + cause_text
+        # return text

data/vendor/behave/behave/api/__init__.py

@@ -0,0 +1,7 @@
+"""
+Provides/defines stable APIs for behave users:
+
+* step writer(s): features/steps/*.py
+* environment writers: features/environment.py
+* ...
+"""

data/vendor/behave/behave/api/async_step.py

@@ -0,0 +1,283 @@
+# -*- coding: UTF-8 -*-
+# pylint: disable=line-too-long
+"""
+This module provides functionality to support "async steps" (coroutines)
+in a step-module with behave. This functionality simplifies to test
+frameworks and protocols that make use of `asyncio.coroutines`_ or
+provide `asyncio.coroutines`_.
+
+EXAMPLE:
+
+.. code-block:: python
+
+    # -- FILE: features/steps/my_async_steps.py
+    # EXAMPLE REQUIRES: Python >= 3.5
+    from behave import step
+    from behave.api.async_step import async_run_until_complete
+
+    @step('an async coroutine step waits {duration:f} seconds')
+    @async_run_until_complete
+    async def step_async_step_waits_seconds(context, duration):
+        await asyncio.sleep(duration)
+
+.. code-block:: python
+
+    # -- FILE: features/steps/my_async_steps2.py
+    # EXAMPLE REQUIRES: Python >= 3.4
+    from behave import step
+    from behave.api.async_step import async_run_until_complete
+    import asyncio
+
+    @step('a tagged-coroutine async step waits {duration:f} seconds')
+    @async_run_until_complete
+    @asyncio.coroutine
+    def step_async_step_waits_seconds2(context, duration):
+        yield from asyncio.sleep(duration)
+
+
+.. requires:: Python 3.5 (or 3.4) or :mod:`asyncio` backport (like :pypi:`trollius`)
+.. seealso::
+    https://docs.python.org/3/library/asyncio.html
+
+.. _asyncio.coroutines: https://docs.python.org/3/library/asyncio-task.html#coroutines
+"""
+# pylint: enable=line-too-long
+
+from __future__ import print_function
+# -- REQUIRES: Python >= 3.4
+# MAYBE BACKPORT: trollius
+import functools
+from six import string_types
+try:
+    import asyncio
+    has_asyncio = True
+except ImportError:
+    has_asyncio = False
+
+# -----------------------------------------------------------------------------
+# ASYNC STEP DECORATORS:
+# -----------------------------------------------------------------------------
+def async_run_until_complete(astep_func=None, loop=None, timeout=None,
+                             async_context=None, should_close=False):
+    """Provides a function decorator for async-steps (coroutines).
+    Provides an async event loop and runs the async-step until completion
+    (or timeout, if specified).
+
+    .. code-block:: python
+
+        from behave import step
+        from behave.api.async_step import async_run_until_complete
+        import asyncio
+
+        @step("an async step is executed")
+        @async_run_until_complete
+        async def astep_impl(context)
+            await asycio.sleep(0.1)
+
+        @step("an async step is executed")
+        @async_run_until_complete(timeout=1.2)
+        async def astep_impl2(context)
+            # -- NOTE: Wrapped event loop waits with timeout=1.2 seconds.
+            await asycio.sleep(0.3)
+
+    Parameters:
+        astep_func: Async step function (coroutine)
+        loop (asyncio.EventLoop):   Event loop to use or None.
+        timeout (int, float):       Timeout to wait for async-step completion.
+        async_context (name):       Async_context name or object to use.
+        should_close (bool):        Indicates if event lopp should be closed.
+
+    .. note::
+
+        * If :param:`loop` is None, the default event loop will be used
+          or a new event loop is created.
+        * If :param:`timeout` is provided, the event loop waits only the
+          specified time.
+        * :param:`async_context` is only used, if :param:`loop` is None.
+        * If :param:`async_context` is a name, it will be used to retrieve
+          the real async_context object from the context.
+
+    """
+    @functools.wraps(astep_func)
+    def step_decorator(astep_func, context, *args, **kwargs):
+        loop = kwargs.pop("_loop", None)
+        timeout = kwargs.pop("_timeout", None)
+        async_context = kwargs.pop("_async_context", None)
+        should_close = kwargs.pop("_should_close", None)
+
+        if isinstance(loop, string_types):
+            loop = getattr(context, loop, None)
+        elif async_context:
+            if isinstance(async_context, string_types):
+                name = async_context
+                async_context = use_or_create_async_context(context, name)
+                loop = async_context.loop
+            else:
+                assert isinstance(async_context, AsyncContext)
+                loop = async_context.loop
+        if loop is None:
+            loop = asyncio.get_event_loop() or asyncio.new_event_loop()
+
+        # -- WORKHORSE:
+        try:
+            if timeout is None:
+                loop.run_until_complete(astep_func(context, *args, **kwargs))
+            else:
+                # MAYBE: loop = asyncio.new_event_loop()
+                # MAYBE: should_close = True
+                task = loop.create_task(astep_func(context, *args, **kwargs))
+                done, pending = loop.run_until_complete(
+                    asyncio.wait([task], timeout=timeout))
+                assert not pending, "TIMEOUT-OCCURED: timeout=%s" % timeout
+        finally:
+            if loop and should_close:
+                # -- MAYBE-AVOID:
+                loop.close()
+
+    if astep_func is None:
+        # -- CASE: @decorator(timeout=1.2, ...)
+        # MAYBE: return functools.partial(step_decorator,
+        def wrapped_decorator1(astep_func):
+            @functools.wraps(astep_func)
+            def wrapped_decorator2(context, *args, **kwargs):
+                return step_decorator(astep_func, context, *args,
+                                      _loop=loop,
+                                      _timeout=timeout,
+                                      _async_context=async_context,
+                                      _should_close=should_close, **kwargs)
+            assert callable(astep_func)
+            return wrapped_decorator2
+        return wrapped_decorator1
+    else:
+        # -- CASE: @decorator ... or astep = decorator(astep)
+        # MAYBE: return functools.partial(step_decorator, astep_func=astep_func)
+        assert callable(astep_func)
+        @functools.wraps(astep_func)
+        def wrapped_decorator(context, *args, **kwargs):
+            return step_decorator(astep_func, context, *args, **kwargs)
+        return wrapped_decorator
+
+# -- ALIAS:
+run_until_complete = async_run_until_complete
+
+# -----------------------------------------------------------------------------
+# ASYNC STEP UTILITY CLASSES:
+# -----------------------------------------------------------------------------
+class AsyncContext(object):
+    # pylint: disable=line-too-long
+    """Provides a context object for "async steps" to keep track:
+
+    * which event loop is used
+    * which (asyncio) tasks are used or of interest
+
+    .. attribute:: loop
+        Event loop object to use.
+        If none is provided, the current event-loop is used
+        (or a new one is created).
+
+    .. attribute:: tasks
+        List of started :mod:`asyncio` tasks (of interest).
+
+    .. attribute:: name
+
+        Optional name of this object (in the behave context).
+        If none is provided, :attr:`AsyncContext.default_name` is used.
+
+    .. attribute:: should_close
+        Indicates if the :attr:`loop` (event-loop) should be closed or not.
+
+    EXAMPLE:
+
+    .. code-block:: python
+
+        # -- FILE: features/steps/my_async_steps.py
+        # REQUIRES: Python 3.5
+        from behave import given, when, then, step
+        from behave.api.async_step import AsyncContext
+
+        @when('I dispatch an async-call with param "{param}"')
+        def step_impl(context, param):
+            async_context = getattr(context, "async_context", None)
+            if async_context is None:
+                async_context = context.async_context = AsyncContext()
+            task = async_context.loop.create_task(my_async_func(param))
+            async_context.tasks.append(task)
+
+        @then('I wait at most {duration:f} seconds until all async-calls are completed')
+        def step_impl(context, duration):
+            async_context = context.async_context
+            assert async_context.tasks
+            done, pending = async_context.loop.run_until_complete(asyncio.wait(
+                async_context.tasks, loop=async_context.loop, timeout=duration))
+            assert len(pending) == 0
+
+        # -- COROUTINE:
+        async def my_async_func(param):
+            await asyncio.sleep(0.5)
+            return param.upper()
+    """
+    # pylint: enable=line-too-long
+    default_name = "async_context"
+
+    def __init__(self, loop=None, name=None, should_close=False, tasks=None):
+        self.loop = loop or asyncio.get_event_loop() or asyncio.new_event_loop()
+        self.tasks = tasks or []
+        self.name = name or self.default_name
+        self.should_close = should_close
+
+    def __del__(self):
+        if self.loop and self.should_close:
+            self.close()
+
+    def close(self):
+        if self.loop and not self.loop.is_closed():
+            self.loop.close()
+            self.loop = None
+
+
+# -----------------------------------------------------------------------------
+# ASYNC STEP UTILITY FUNCTIONS:
+# -----------------------------------------------------------------------------
+def use_or_create_async_context(context, name=None, loop=None, **kwargs):
+    """Utility function to be used in step implementations to ensure that an
+    :class:`AsyncContext` object is stored in the :param:`context` object.
+
+    If no such attribute exists (under the given name),
+    a new :class:`AsyncContext` object is created with the provided args.
+    Otherwise, the existing context attribute is used.
+
+    EXAMPLE:
+
+    .. code-block:: python
+
+        # -- FILE: features/steps/my_async_steps.py
+        # EXAMPLE REQUIRES: Python 3.5
+        from behave import when
+        from behave.api.async_step import use_or_create_async_context
+
+        @when('I dispatch an async-call with param "{param}"')
+        def step_impl(context, param):
+            async_context = use_or_create_async_context(context, "async_context")
+            task = async_context.loop.create_task(my_async_func(param))
+            async_context.tasks.append(task)
+
+        # -- COROUTINE:
+        async def my_async_func(param):
+            await asyncio.sleep(0.5)
+            return param.upper()
+
+    :param context:     Behave context object to use.
+    :param name:        Optional name of async-context object (as string or None).
+    :param loop:        Optional event_loop object to use for create call.
+    :param kwargs:      Optional :class:`AsyncContext` params for create call.
+    :return: :class:`AsyncContext` object from the param:`context`.
+    """
+    if name is None:
+        name = AsyncContext.default_name
+    async_context = getattr(context, name, None)
+    if async_context is None:
+        async_context = AsyncContext(loop=loop, name=name, **kwargs)
+        setattr(context, async_context.name, async_context)
+    assert isinstance(async_context, AsyncContext)
+    assert getattr(context, async_context.name) is async_context
+    return async_context

data/vendor/behave/behave/capture.py

@@ -0,0 +1,227 @@
+# -*- coding: UTF-8 -*-
+"""
+Capture output (stdout, stderr), logs, etc.
+"""
+
+from __future__ import absolute_import
+from contextlib import contextmanager
+import sys
+from six import StringIO, PY2
+from behave.log_capture import LoggingCapture
+from behave.textutil import text as _text
+
+def add_text_to(value, more_text, separator="\n"):
+    if more_text:
+        if value:
+            if separator and not value.endswith(separator):
+                value += separator
+            value += more_text
+        else:
+            value = more_text
+    return value
+
+
+class Captured(object):
+    """Stores and aggregates captured output data."""
+    empty = u""
+    linesep = u"\n"
+
+    def __init__(self, stdout=None, stderr=None, log_output=None):
+        self.stdout = stdout or self.empty
+        self.stderr = stderr or self.empty
+        self.log_output = log_output or self.empty
+
+    def reset(self):
+        self.stdout = self.empty
+        self.stderr = self.empty
+        self.log_output = self.empty
+
+    # -- PYTHON2:
+    if PY2:
+        def __nonzero__(self):
+            return bool(self.stdout or self.stderr or self.log_output)
+    else:
+        def __bool__(self):
+            return bool(self.stdout or self.stderr or self.log_output)
+
+    @property
+    def output(self):
+        """Makes a simple report of the captured data by concatenating
+        all parts.
+        """
+        output_text = self.stdout
+        output_text = add_text_to(output_text, self.stderr)
+        output_text = add_text_to(output_text, self.log_output)
+        return output_text
+
+    def add(self, captured):
+        """Adds/appends captured output data to this object.
+
+        :param captured:    Captured object whose data should be added.
+        :return: self, to allow daisy-chaining (if needed).
+        """
+        assert isinstance(captured, Captured)
+        self.stdout = add_text_to(self.stdout, captured.stdout, self.linesep)
+        self.stderr = add_text_to(self.stderr, captured.stderr, self.linesep)
+        self.log_output = add_text_to(self.log_output, captured.log_output,
+                                      self.linesep)
+        return self
+
+    def make_report(self):
+        """Makes a detailled report of the captured output data.
+
+        :returns: Report as string.
+        """
+        report_parts = []
+        if self.stdout:
+            parts = ["Captured stdout:", _text(self.stdout).rstrip(), ""]
+            report_parts.extend(parts)
+        if self.stderr:
+            parts = ["Captured stderr:", _text(self.stderr).rstrip(), ""]
+            report_parts.extend(parts)
+        if self.log_output:
+            parts = ["Captured logging:", _text(self.log_output)]
+            report_parts.extend(parts)
+        return self.linesep.join(report_parts).strip()
+
+    def __add__(self, other):
+        """Supports incremental add::
+
+            captured1 = Captured("Hello")
+            captured2 = Captured("World")
+            captured3 = captured1 + captured2
+            assert captured3.stdout == "Hello\nWorld"
+        """
+        new_data = Captured(self.stdout, self.stderr, self.log_output)
+        return new_data.add(other)
+
+    def __iadd__(self, other):
+        """Supports incremental add::
+
+            captured1 = Captured("Hello")
+            captured2 = Captured("World")
+            captured1 += captured2
+            assert captured1.stdout == "Hello\nWorld"
+        """
+        return self.add(other)
+
+
+class CaptureController(object):
+    """Simplifies the lifecycle to capture output from various sources."""
+    def __init__(self, config):
+        self.config = config
+        self.stdout_capture = None
+        self.stderr_capture = None
+        self.log_capture = None
+        self.old_stdout = None
+        self.old_stderr = None
+
+    @property
+    def captured(self):
+        """Provides access of the captured output data.
+
+        :return: Object that stores the captured output parts (as Captured).
+        """
+        stdout = None
+        stderr = None
+        log_out = None
+        if self.config.stdout_capture and self.stdout_capture:
+            stdout = _text(self.stdout_capture.getvalue())
+        if self.config.stderr_capture and self.stderr_capture:
+            stderr = _text(self.stderr_capture.getvalue())
+        if self.config.log_capture and self.log_capture:
+            log_out = _text(self.log_capture.getvalue())
+        return Captured(stdout, stderr, log_out)
+
+    def setup_capture(self, context):
+        assert context is not None
+        if self.config.stdout_capture:
+            self.stdout_capture = StringIO()
+            context.stdout_capture = self.stdout_capture
+
+        if self.config.stderr_capture:
+            self.stderr_capture = StringIO()
+            context.stderr_capture = self.stderr_capture
+
+        if self.config.log_capture:
+            self.log_capture = LoggingCapture(self.config)
+            self.log_capture.inveigle()
+            context.log_capture = self.log_capture
+
+    def start_capture(self):
+        if self.config.stdout_capture:
+            # -- REPLACE ONLY: In non-capturing mode.
+            if not self.old_stdout:
+                self.old_stdout = sys.stdout
+                sys.stdout = self.stdout_capture
+            assert sys.stdout is self.stdout_capture
+
+        if self.config.stderr_capture:
+            # -- REPLACE ONLY: In non-capturing mode.
+            if not self.old_stderr:
+                self.old_stderr = sys.stderr
+                sys.stderr = self.stderr_capture
+            assert sys.stderr is self.stderr_capture
+
+    def stop_capture(self):
+        if self.config.stdout_capture:
+            # -- RESTORE ONLY: In capturing mode.
+            if self.old_stdout:
+                sys.stdout = self.old_stdout
+                self.old_stdout = None
+            assert sys.stdout is not self.stdout_capture
+
+        if self.config.stderr_capture:
+            # -- RESTORE ONLY: In capturing mode.
+            if self.old_stderr:
+                sys.stderr = self.old_stderr
+                self.old_stderr = None
+            assert sys.stderr is not self.stderr_capture
+
+    def teardown_capture(self):
+        if self.config.log_capture:
+            self.log_capture.abandon()
+
+    def make_capture_report(self):
+        """Combine collected output and return as string."""
+        return self.captured.make_report()
+        # report = u""
+        # if self.config.stdout_capture and self.stdout_capture:
+        #     output = self.stdout_capture.getvalue()
+        #     if output:
+        #         output = _text(output)
+        #         report += u"\nCaptured stdout:\n" + output
+        # if self.config.stderr_capture and self.stderr_capture:
+        #     output = self.stderr_capture.getvalue()
+        #     if output:
+        #         output = _text(output)
+        #         report += u"\nCaptured stderr:\n" + output
+        # if self.config.log_capture and self.log_capture:
+        #     output = self.log_capture.getvalue()
+        #     if output:
+        #         output = _text(output)
+        #         report += u"\nCaptured logging:\n" + output
+        # return report
+
+# -----------------------------------------------------------------------------
+# UTILITY FUNCTIONS:
+# -----------------------------------------------------------------------------
+@contextmanager
+def capture_output(controller, enabled=True):
+    """Provides a context manager that starts capturing output
+
+    .. code-block::
+
+        with capture_output(capture_controller):
+            ... # Do something
+    """
+    if enabled:
+        try:
+            controller.start_capture()
+            yield
+        finally:
+            controller.stop_capture()
+    else:
+        # -- CAPTURING OUTPUT is disabled.
+        # Needed to prevent recursive captures with context.execute_steps()
+        yield