Merge pull request #215 from pyapp-org/development

Release 4.13

Author: timsavage

.github/workflows/default.yml

@@ -14,7 +14,7 @@ jobs:
 
     name: Test Python ${{ matrix.python-version }}
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3.5.2
       with:
           fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
 

HISTORY

@@ -1,3 +1,19 @@
+4.13
+====
+
+Changes
+-------
+
+- Added ext_block_list to allow for blocking of extensions to CliApplication.
+
+- Allow ext_allow_list and ext_block_list to include glob patterns.
+
+Pending Deprecations
+--------------------
+
+- Deprecated the use of ``ext_white_list`` in favour of ``ext_allow_list``.
+
+
 4.12
 ====
 

docs/developers.rst

@@ -1,5 +1,5 @@
-Developers
-==========
+Contribution Guide
+==================
 
 We welcome contributions to the pyApp project (and sub projects).
 
@@ -16,8 +16,8 @@ met:
 
 - Update the docs with the details if required.
 
-- The API matters, ensure any features provide a nice API for end users.
-
+- The API matters, ensure any features provide a nice API for both developers and
+  end-users.
 
 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

docs/extensions.rst

@@ -2,6 +2,9 @@
 Extensions
 ##########
 
+Extensions are features that are not part of the core pyApp framework but extend
+it's functionality.
+
 
 Available Extensions
 ====================
@@ -75,12 +78,11 @@ A Basic Project
 
 An extensions consists of a standard Python project structure eg::
 
-    ├┬ my_extension
-    │└ __init__.py
-    ├ README.rst
-    ├ pyproject.toml
-    ├ setup.cfg
-    └ setup.py
+    ├📁 src
+    │ └📁 my_extension
+    │   └📄 __init__.py
+    ├📄 README.md
+    └📄 pyproject.toml
 
 
 
@@ -93,46 +95,42 @@ The contents of which are:
     .. code-block:: python
 
         class Extension:
-            """
-            My pyApp Extension
-            """
+            """My pyApp Extension."""
 
             default_settings = ".default_settings"
             checks = ".checks"
 
             @staticmethod
             def register_commands(root):
-                """
-                Register custom commands with pyApp.
-                """
+                """Register custom commands with pyApp."""
 
             @staticmethod
             def ready():
-                """
-                Method called once pyApp has configured environment
-                """
+                """Method called once pyApp has configured environment."""
 
 
 .. 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.
 
-``README.rst``
+``README.md``
     While not strictly necessary a README document is *highly recommended* and is
     included in the package as the long description.
 
-    .. code-block:: rst
+    .. code-block:: md
 
-        ##################
-        My pyApp Extension
-        ##################
+        # My pyApp Extension
 
         Information about my extension
 
 
-Using Setuptools
-~~~~~~~~~~~~~~~~
+Using Setuptools with ``pyproject.toml``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Using Setuptools with ``setup.cfg``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``setup.cfg``
     Defines the metadata and configuration used to build a package, this is also

docs/getting-started.rst

@@ -5,8 +5,8 @@ Getting Started
 In this section we will run through the processes of building an application with
 ``pyApp``.
 
-App Layout
-==========
+Application Layout
+==================
 
 We'll start with a simple application that accepts input from the command line
 and combines it with a value from configuration.
@@ -28,12 +28,12 @@ Project Structure
 
 The basic structure of a ``pyApp`` application package consists of the following::
 
-    - myapp
-      |- __init__.py          Python package initialisation
-      |- __main__.py          Python main entry point
-      |- cli.py               The CLI (referenced from __main__)
-      |- default_settings.py  Definition of default runtime configuration
-      |- checks.py            Application specific checks
+    📁 myapp
+     ├📄 __init__.py          Python package initialisation
+     ├📄 __main__.py          Python main entry point
+     ├📄 cli.py               The CLI (referenced from __main__)
+     ├📄 default_settings.py  Definition of default runtime configuration
+     └📄 checks.py            Application specific checks
 
 
 ``__init__.py``
@@ -45,9 +45,11 @@ uses this file to find information for the application.
 
 ``__version__``
     The version number of the application, it is recommended that this be a
-    semantic version. ``pyApp`` also provides tools for this to be fetched from
+    `semantic version`_. ``pyApp`` also provides tools for this to be fetched from
     the installed package list.
 
+.. _semantic version: https://semver.org/
+
 
 ``__main__.py``
 ---------------

docs/index.rst

@@ -1,26 +1,18 @@
-.. PyApp documentation master file, created by
-   sphinx-quickstart on Thu Jan 12 12:26:34 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-
-
 Welcome to PyApp's documentation!
 =================================
 
-*Let us handle the boring stuff!*
+A simple python application framework *let pyApp handle the boring stuff!*
 
-As of pyApp 4.0, Python < 3.6 is no longer supported.
+As of pyApp 4.3, Python < 3.8 is no longer supported.
 
 +---------+------------------------------------------------------------------------------------------------------------+
-| Docs    | .. image:: https://readthedocs.org/projects/pyapp/badge/?version=latest                                    |
+| Code    | .. image:: https://img.shields.io/badge/GitHub-code-brightgreen                                            |
+|         |    :target: https://github.com/pyapp-org/pyapp                                                             |
+|         |    :alt: GitHub                                                                                            |
+|         | .. image:: https://readthedocs.org/projects/pyapp/badge/?version=latest                                    |
 |         |    :target: https://docs.pyapp.info/                                                                       |
 |         |    :alt: ReadTheDocs                                                                                       |
 +---------+------------------------------------------------------------------------------------------------------------+
-| Build   | .. image:: https://api.dependabot.com/badges/status?host=github&repo=pyapp-org/pyapp                       |
-|         |    :target: https://dependabot.com                                                                         |
-|         |    :alt: Dependabot Status                                                                                 |
-+---------+------------------------------------------------------------------------------------------------------------+
 | Quality | .. image:: https://sonarcloud.io/api/project_badges/measure?project=pyapp-org_pyapp&metric=sqale_rating    |
 |         |    :target: https://sonarcloud.io/dashboard?id=pyapp-org_pyapp                                             |
 |         |    :alt: Maintainability                                                                                   |
@@ -46,41 +38,41 @@ As of pyApp 4.0, Python < 3.6 is no longer supported.
 |         |    :target: https://pypi.io/pypi/pyapp/                                                                    |
 +---------+------------------------------------------------------------------------------------------------------------+
 
-pyApp takes care of the boring boilerplate code for building a CLI, managing
-settings and much more so you can focus on your business logic.
+pyApp takes care of the application framework code, managing settings and much
+more so you can focus on your business logic.
 
 
-So what do we handle?
-=====================
+Features
+========
 
-- Configuration - Loading, merging your settings from different sources
+* Configuration - Loading, merging your settings from different sources
 
-  + Python modules
-  + File and HTTP(S) endpoints for JSON and YAML files.
+  * Python modules
+  * File and HTTP(S) endpoints for JSON and YAML files.
 
-- Instance Factories - Configuration of plugins, database connections, or just
-  implementations of an ``ABC``.
-  Leveraging settings to make setup of your application easy and reduce coupling.
+* Instance Factories - Configuration of plugins, database connections, or just
+   implementations of an ``ABC``. Leveraging settings to make setup of your
+   application easy and reduce coupling.
 
-- Dependency Injection - Easy to use dependency injection without complicated setup.
+* Dependency Injection - Easy to use dependency injection without complicated setup.
 
-- Feature Flags - Simple methods to enable and disable features in your application
+* Feature Flags - Simple methods to enable and disable features in your application
   at runtime.
 
-- Checks - A framework for checking settings are correct and environment is
+* Checks - A framework for checking settings are correct and environment is
   operating correctly (your ops team will love you)?
 
-- Extensions - Extend the basic framework with extensions. Provides deterministic
+* Extensions - Extend the basic framework with extensions. Provides deterministic
   startup, extension of the CLI and the ability to register checks and extension
   specific default settings.
 
-- Application - Provides a extensible and simple CLI interface for running
+* Application - Provides a extensible and simple CLI interface for running
   commands (including async), comes with built-in commands to execute check, setting
   and extension reports.
 
-- Logging - Initialise and apply sane logging defaults.
+* Logging - Initialise and apply sane logging defaults.
 
-- Highly tested and ready for production use.
+* Highly tested and ready for production use.
 
 
 Installation

docs/recipes/index.rst

@@ -1,6 +1,13 @@
 Recipes
 =======
 
+Recipes are code snippets that show how to use the library in specific use cases.
+
+.. tip:: Found a good use case that is not covered by the recipes? Suggest a new
+  recipy or request one by opening an issue on the `pyApp issue tracker`_.
+
+.. _pyApp issue tracker: https://github.com/pyapp-org/pyapp/issues/new
+
 .. toctree::
    :maxdepth: 1
 

docs/recipes/integration-with-django.rst

@@ -24,4 +24,4 @@ Add to the ``ready`` method of your *App* class:
             pyapp_settings.load(ObjectLoader(django_settings))
 
 ``ObjectLoader`` is a special loader that reads configuration variable from an
-existing object or in this case a Django settings object.
+existing object; in this case the Django settings object.

docs/recipes/single-script.rst

@@ -14,9 +14,7 @@ Example:
 
     @app.command
     def adduser(username: str, *, email: str = None, is_admin: bool = False):
-        """
-        Add a user
-        """
+        """Add a user"""
         ...
 
     if __name__ == "__main__":