pyapp-org · timsavage · Jul 27, 2022 · Jul 27, 2022 · Jul 27, 2022 · Jul 27, 2022
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -8,7 +8,7 @@ sphinx:
   configuration: docs/conf.py
 
 python:
-  version: 3.6
+  version: 3.8
   install:
     - method: pip
       path: .
diff --git a/HISTORY b/HISTORY
@@ -1,3 +1,17 @@
+4.9.0
+=====
+
+Changes
+--------
+
+- Redesign of the init process. Mostly moved into the `pyapp.init` module to allow
+  for init of applications that are not using the CliApplication mechanism. The init
+  methods also provide an easy location for initialisation of testing.
+
+- Creation of the `pytest-pyapp` package, a PyTest plugin with helper methods and
+  fixtures for simplifying the testing of pyApp applications.
+
+
 4.8.2
 =====
 

diff --git a/README.rst b/README.rst
@@ -2,17 +2,13 @@
 pyApp - A python application framework
 ######################################
 
-*Let us handle the boring stuff!*
+*Let pyApp handle the boring stuff!*
 
 +---------+------------------------------------------------------------------------------------------------------------+
 | Docs    | .. 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                                                                                   |
@@ -38,35 +34,39 @@ pyApp - A python application framework
 |         |    :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 application logic.
+pyApp takes care of the boilerplate code for building an modern application with a CLI, managing
+settings and much more so you can focus on the business logic.
+
 
 So what does pyApp handle?
 ==========================
 
-- **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.
 
-- **Instance Factories** - Configuration of plugins, database connections, or just
+- 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
+  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
+- User Interface - 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.
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -35,9 +35,9 @@
 master_doc = "index"
 
 # General information about the project.
-project = u"pyApp"
-copyright = u"2017, Tim Savage"
-author = u"Tim Savage"
+project = "pyApp"
+copyright = "2017, Tim Savage"
+author = "Tim Savage"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -208,7 +208,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, "PyApp.tex", u"pyApp Documentation", u"Tim Savage", "manual")
+    (master_doc, "PyApp.tex", "pyApp Documentation", "Tim Savage", "manual")
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -236,7 +236,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "pyapp", u"pyApp Documentation", [author], 1)]
+man_pages = [(master_doc, "pyapp", "pyApp Documentation", [author], 1)]
 
 # If true, show URL addresses after external links.
 # man_show_urls = False
@@ -251,7 +251,7 @@
     (
         master_doc,
         "pyApp",
-        u"pyApp Documentation",
+        "pyApp Documentation",
         author,
         "pyApp",
         "One line description of project.",

diff --git a/docs/developers.rst b/docs/developers.rst
@@ -1,27 +1,29 @@
 Developers
 ==========
 
-We welcome contributions to the pyApp project (and sub projects).
+Contributions to the pyApp project (and sub projects) are welcome.
 
-To get our PR accepted quickly please ensure the following requirements are
+To get a PR accepted quickly please ensure the following requirements are
 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:
 
-- Ensure your code has unit test coverage (using pyTest). Unittests should be
-  designed to be as fast as possible.
+  - All code is formatted by `black <https://github.com/ambv/black>`_
+  - Code passes PyLint checks (this is part of the automated build)
 
-- Ensure your code passes the pyLint checks (this is part of the automated build).
+- Ensure code has unit test coverage (using pyTest). Unittests should be
+  designed to be as fast as possible.
 
-- Update the docs with the details if required.
+- Documentation has been updated to reflect the change
 
 - The API matters, ensure any features provide a nice API for end users.
 
+The core pyApp package is intended to be light and primarily made up of plumbing
+code. To add support for a particular service or server a new pyApp extension is
+the way to achieve this.
 
-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 a new extension.
 
-See the *Developing an Extension* section of the extensions doc for guidance on
-building your own extension.
+.. _Developing an Extension:
diff --git a/docs/extensions.rst b/docs/extensions.rst
@@ -2,93 +2,41 @@
 Extensions
 ##########
 
-
-Available Extensions
-====================
-
-pyApp Developed
----------------
-
-🔌 SQLAlchemy - `pyapp.sqlalchemy`_
-
-🔌 Redis - `pyapp.redis`_
-
-In Beta
-~~~~~~~
-
-🐛 Rollbar - `pyapp.rollbar`_
-
-📧 AIO SMTPlib - `pyapp.aiosmtplib`_ Extension for aiosmtplib
-
-☁ Boto3 - `pyapp.boto3`_
-
-☁ AIOBotocore - `pyapp.aiobotocore`_
-
-📨 Messaging - `pyapp.messaging`_ - Extension to provide abstract interfaces for Message Queues.
-
-- 📨 AWS Messaging - `pyapp.messaging-aws`_ - Messaging extension for AWS (SQS/SNS)
-
-In development
-~~~~~~~~~~~~~~
-
-📧 SMTP - `pyapp.SMTP`_
-
-📨 Aio-Pika - `pyapp.aiopika`_ - Messaging extension for pika (RabbitMQ/AMQP)
-
-🔌 PySpark - `pyapp.pyspark`_ - Extension for PySpark
-
-🔎 Elastic Search - `pyapp.elasticsearch`_ - Extension for Elasticsearch
-
-Coming soon
------------
-
-📨 AMQP Messaging - Messaging extension for AMQP (RabbitMQ)
-
-.. _pyapp.sqlalchemy: https://www.github.com/pyapp-org/pyapp.sqlalchemy
-.. _pyapp.redis: https://www.github.com/pyapp-org/pyapp.redis
-.. _pyapp.aiobotocore: https://www.github.com/pyapp-org/pyapp.aiobotocore
-.. _pyapp.SMTP: https://www.github.com/pyapp-org/pyapp.SMTP
-.. _pyapp.boto3: https://www.github.com/pyapp-org/pyapp.boto3
-.. _pyapp.rollbar: https://www.github.com/pyapp-org/pyapp.rollbar
-.. _pyapp.aiosmtplib: https://www.github.com/pyapp-org/pyapp.aiosmtplib
-.. _pyapp.messaging: https://www.github.com/pyapp-org/pyapp-messaging
-.. _pyapp.messaging-aws: https://www.github.com/pyapp-org/pyapp-messaging-aws
-.. _pyapp.aiopika: https://www.github.com/pyapp-org/pyapp.aiopika
-.. _pyapp.pyspark: https://www.github.com/pyapp-org/pyapp.pyspark
-.. _pyapp.elasticsearch: https://www.github.com/pyapp-org/pyapp.elasticsearch
-
-.. 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 pyApp extension is a standard Python package that exports an entry point that
+pyApp utilises to load/activate the code.  The entry point will reference a class
+with attributes that pyApp recognises.
 
 A Basic Project
 ---------------
 
-An extensions consists of a standard Python project structure eg::
+The structure of an extension is similar to any other Python package.
+
+With Setuptools::
 
     ├┬ my_extension
     │└ __init__.py
     ├ README.rst
-    ├ pyproject.toml
     ├ setup.cfg
     └ setup.py
 
 
+With Poetry::
+
+    ├┬ my_extension
+    │└ __init__.py
+    ├ README.rst
+    ├ pyproject.toml
+    ├ poetry.lock
+
 
-The contents of which are:
+The contents of each file:
 
 ``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.
+    package must contain an Extension class every attribute on the class is optional.
 
     .. code-block:: python
 
@@ -114,11 +62,13 @@ The contents of which are:
 
 
 .. 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.
+    One gotcha when building extensions is attempting to access settings too early
+    before they have been loaded by pyApp, this is the use of the ``ready`` event
+    on the Extension class. The ``ready`` method will be called once all initialisation
+    activities have been completed and settings etc are ready for use.
+
 
-``README.rst``
+``README.rst`` or ``README.md``
     While not strictly necessary a README document is *highly recommended* and is
     included in the package as the long description.
 
@@ -211,3 +161,63 @@ Using poetry
 
         [tool.poetry.plugins."pyapp.extensions"]
         "my-extension" = "my_extension:Extension"
+
+
+Available Extensions
+====================
+
+pyApp Developed
+---------------
+
+🔌 SQLAlchemy - `pyapp.sqlalchemy`_
+
+🔌 Redis - `pyapp.redis`_
+
+In Beta
+~~~~~~~
+
+🐛 Rollbar - `pyapp.rollbar`_
+
+📧 AIO SMTPlib - `pyapp.aiosmtplib`_ Extension for aiosmtplib
+
+☁ Boto3 - `pyapp.boto3`_
+
+☁ AIOBotocore - `pyapp.aiobotocore`_
+
+📨 Messaging - `pyapp.messaging`_ - Extension to provide abstract interfaces for Message Queues.
+
+- 📨 AWS Messaging - `pyapp.messaging-aws`_ - Messaging extension for AWS (SQS/SNS)
+
+In development
+~~~~~~~~~~~~~~
+
+📧 SMTP - `pyapp.SMTP`_
+
+📨 Aio-Pika - `pyapp.aiopika`_ - Messaging extension for pika (RabbitMQ/AMQP)
+
+🔌 PySpark - `pyapp.pyspark`_ - Extension for PySpark
+
+🔎 Elastic Search - `pyapp.elasticsearch`_ - Extension for Elasticsearch
+
+Coming soon
+-----------
+
+📨 AMQP Messaging - Messaging extension for AMQP (RabbitMQ)
+
+.. _pyapp.sqlalchemy: https://www.github.com/pyapp-org/pyapp.sqlalchemy
+.. _pyapp.redis: https://www.github.com/pyapp-org/pyapp.redis
+.. _pyapp.aiobotocore: https://www.github.com/pyapp-org/pyapp.aiobotocore
+.. _pyapp.SMTP: https://www.github.com/pyapp-org/pyapp.SMTP
+.. _pyapp.boto3: https://www.github.com/pyapp-org/pyapp.boto3
+.. _pyapp.rollbar: https://www.github.com/pyapp-org/pyapp.rollbar
+.. _pyapp.aiosmtplib: https://www.github.com/pyapp-org/pyapp.aiosmtplib
+.. _pyapp.messaging: https://www.github.com/pyapp-org/pyapp-messaging
+.. _pyapp.messaging-aws: https://www.github.com/pyapp-org/pyapp-messaging-aws
+.. _pyapp.aiopika: https://www.github.com/pyapp-org/pyapp.aiopika
+.. _pyapp.pyspark: https://www.github.com/pyapp-org/pyapp.pyspark
+.. _pyapp.elasticsearch: https://www.github.com/pyapp-org/pyapp.elasticsearch
+
+.. 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.