Merge branch 'release/4.3.0'

Author: timsavage

.gitignore

@@ -13,6 +13,7 @@ build
 _build
 .tox
 .eggs
+.nox
 
 # IDE cruft
 .idea

HISTORY

@@ -1,3 +1,16 @@
+4.3.0
+=====
+
+Features
+--------
+
+- Async commands, ``app.command`` can not be applied to async functions and
+  handle the event loop.
+
+- ``app.default`` now returns a Command Proxy supporting async and additional
+  command line arguments.
+
+
 4.2.0
 =====
 

README.rst

@@ -62,8 +62,8 @@ So what do we handle?
   specific default settings.
 
 - Application - Provides a extensible and simple CLI interface for running
-  commands, comes with built-in commands to execute check, setting and extension
-  reports.
+  commands (including async), comes with built-in commands to execute check, setting
+  and extension reports.
 
 - Logging - Initialise and apply sane logging defaults.
 

docs/developers.rst

@@ -9,14 +9,19 @@ met:
 - Install the `pre-commit <https://github.com/pre-commit/pre-commit>`_ hooks to
   ensure you code is formatted by `black <https://github.com/ambv/black>`_.
 
-- Ensure your code has unit test coverage (we use pytest). Unit tests should be
+- Ensure your code has unit test coverage (using pyTest). Unittests should be
   designed to be as fast as possible.
 
+- Ensure your code passes the pyLint checks (this is part of the travis build).
+
 - Update the docs with the details if required.
 
 - The API matters, ensure any features provide a nice API for end users.
 
 
-The core pyApp package is intended to be fairly light and mainly made up of 
-plumbing code. If you want to add support for a particular service or server
-an extension is the best way to do that.
+The core pyApp package is intended to be light and mainly made up of plumbing
+code. If you want to add support for a particular service or server an extension
+is the way to do this.
+
+See the *Developing an Extension* section of the extensions doc for guidance on
+building your own extension.

docs/extensions.rst

@@ -6,10 +6,10 @@ Extensions
 Available Extensions
 ====================
 
-pyApp.org Supplied
-------------------
+pyApp Developed
+---------------
 
-These are extensions supplied by `pyApp`.
+Extensions available for use:
 
 - `pyapp.aiobotocore <https://github.com/pyapp-org/pyapp.aiobotocore>`_ -
   Factory for `Async AWS client library <https://github.com/aio-libs/aiobotocore>`_
@@ -21,12 +21,147 @@ These are extensions supplied by `pyApp`.
   Factory for `SQLALchemy <https://www.sqlalchemy.org>`_
 
 
-These extensions are in development.
+Extensions in beta:
 
 - `pyapp-messaging <https://github.com/pyapp-org/pyapp-messaging>`_ -
   Abstract messaging framework for interacting with Pub/Sub and Message Queues.
 
+Extensions in development:
+
 - `pyapp.boto3 <https://github.com/pyapp-org/pyapp.boto3>`_ -
   Factory for `AWS client library <https://boto3.amazonaws.com/v1/documentation/api/latest/index.html>`_
 - `pyapp.smtp <https://github.com/pyapp-org/pyapp.SMTP>`_ -
   Interface to `smtplib <https://docs.python.org/3/library/smtplib.html>`_
+
+.. note::
+    The development status of these projects may have changed from when this
+    documentation was generated, see the repository (or PyPi) of the extension
+    package for up to date status.
+
+Developing an Extension
+=======================
+
+An extension is a standard Python package that exports a known entry point that
+pyApp uses to identify extensions.  This entry point will reference a class with
+known attributes that pyApp recognises.
+
+A Basic Project
+---------------
+
+An extensions consists of a standard Python project structure eg::
+
+    ├┬ my_extension
+    │├ __init__.py
+    │└ __version__.py
+    ├ README.rst
+    ├ setup.cfg
+    └ setup.py
+
+
+The contents of which are:
+
+``my_extension/__init__.py``
+    The package init file, this file contains the extension entry point. While a
+    package must container an Extension class every attribute on the class is optional.
+
+    .. code-block:: python
+
+        # Pull in the version
+        from .__version__ import __version__
+
+
+        class Extension:
+            """
+            My pyApp Extension
+            """
+
+            default_settings = ".default_settings"
+            checks = ".checks"
+
+            @staticmethod
+            def register_commands(root):
+                """
+                Register custom commands with pyApp.
+                """
+
+            @staticmethod
+            def ready():
+                """
+                Method called once pyApp has configured environment
+                """
+
+
+``my_extension/__version__.py``
+    The package version; defining the version in a separate file simplifies the
+    process of obtaining the version during the package build process.
+
+    .. code-block:: python
+
+        __version__ = "1.0"
+
+
+``README.rst``
+    While not strictly necessary a README document is *highly recommended* and is
+    included in the package as the long description.
+
+    .. code-block:: rst
+
+        ##################
+        My pyApp Extension
+        ##################
+
+        Information about my extension
+
+
+``setup.cfg``
+    Defines the metadata and configuration used to build a package, this is also
+    where the entry point used identify you extension is defined.
+
+    .. code-block:: ini
+
+        [metadata]
+        name = my-extension
+        author = Author
+        author-email = [email protected]
+        description = Blurb about my extension
+        long-description = file: README.rst
+        url = https://github.com/author/my-extension
+        platforms = any
+        license = BSD-3-Clause
+
+        [options]
+        python_requires = >=3.6
+        packages = find:
+        setup_requires =
+            setuptools >=38.3
+        install_requires =
+            pyapp >=4.3.0
+
+        [options.entry_points]
+        # Used by pyApp to recognise my_extension
+        pyapp.extensions =
+            my-extension = my_extension:Extension
+
+
+``setup.py``
+    Script that trigger ``setuptools`` to build a package. This example takes
+    advantage of the version in a separate file to extract the version number.
+
+    .. code-block:: python
+
+        from pathlib import Path
+        from setuptools import setup
+
+        HERE = Path(__file__).parent
+
+        about = {}
+        with (HERE / "my_extension/__version__.py").open() as f:
+            exec(f.read(), about)
+
+        setup(version=about["__version__"])
+
+
+.. tip::
+    A gotcha when building extensions is attempting to access settings to early
+    this is the reason for the ``ready`` event on the Extension class. Once ready
+    has been called settings are setup and ready for use.

docs/index.rst

@@ -67,8 +67,8 @@ So what do we handle?
   specific default settings.
 
 - Application - Provides a extensible and simple CLI interface for running
-  commands, comes with built-in commands to execute check, setting and extension
-  reports.
+  commands (including Async), comes with built-in commands to execute check, setting
+  and extension reports.
 
 - Logging - Initialise and apply sane logging defaults.
 

docs/recipes/index.rst

@@ -5,3 +5,4 @@ Recipes
    :maxdepth: 1
 
    integration_with_django
+   using_async_commands

docs/recipes/using_async_commands.rst

@@ -0,0 +1,16 @@
+Using Async Commands
+====================
+
+As of pyApp 4.3 command handlers can be defined as Async functions and pyApp will
+take care of setting up an event loop call the handler.
+
+.. code-block:: python
+
+    app = CliApplication()
+
+    @app.command
+    async def my_command(args):
+        pass
+
+
+This feature is also available to the default handler.

noxfile.py

@@ -0,0 +1,7 @@
+import nox
+from nox.sessions import Session
+
+
+@nox.session(python=("3.6", "3.7", "3.8"))
+def tests(session: Session):
+    session.run("python", "setup.py", "test")

pyapp/__version__.py

@@ -1,2 +1,2 @@
 # pylint: disable=missing-module-docstring
-__version__ = "4.2.0"
+__version__ = "4.3.0"