auxilium 0.1.4

A Python project for an automated test and deploy toolkit - 100% reusable.

Python library auxilium

A Python project for an automated test and deploy toolkit - 100% reusable.

Code, Documentation and Tests

Modern software development comes as a triple of

• The code is the actual software program or library which can executed or invoked.

• The documentation should give an introducing the idea and mission, guide how to use it, describe functionality and features.

• Finally, intensive tests increases the confidence that the documented functionality is correctly implemented.

To support this auxilium is designed to build, to auto-doc, to test and to deploy small to medium size Python projects in 3 simple steps.

1. copy your source code into a boilerplate project structure

2. write useful documentation in your python source code doc strings

3. add as many as possible test cases in a designated test directory structure

Once setup up, auxilium provides - out of the box - tools to build a ci/cd (continuous integration/continuous deployment) framework with

• conventions on how the project is structured, i.e. where to find source, test and doc files

• provides useful template structure of files which can be easy modified and extended

• keeps always a single source of truth for project information (like version number)

• sets up a clear and straight structure of the project as well as the corresponding documentation

• minimises the places to edit, e.g. for the documentation there are by default only thre files to edit

• comes with a shell script to trigger plenty test and analysis routines incl. drafting releases on github.com and distribute on pypi.org

• uses standard community tools like unittest, pylint, coverage, sphinx and more

• no detailed configurations of any tools are needed, so you can focus completely on coding your project

• demo of how to use the framework and various services to build true ci/cd; a full automated test and deploy pineline.

Moreover, we recommend to use pyenv and virtualenv to test different python installations, too.

Quick Start a Project

Once installed simply invoke auxilium create and enter a few project details.

The whole project structure will be created. Full functioning incl. documentation gerneration, testing, etc..

$ auxilium create

*** create new project ***
Please enter project details.

Enter project name  : unicorn
Enter project slogan: Always be a unicorn.
Enter author name   : dreamer
Enter author email  : dreamer@ho

Created project unicorn with these files:

  unicorn/CHANGES.rst
  unicorn/dev.py
  unicorn/HOWTO.rst
  unicorn/LICENSE
  unicorn/MANIFEST.in
  unicorn/README.rst
  unicorn/requirements.txt
  unicorn/setup.py
  unicorn/upgrade_requirements.txt

  unicorn/doc/.DS_Store

  unicorn/doc/sphinx/.DS_Store
  unicorn/doc/sphinx/conf.py
  unicorn/doc/sphinx/doc.rst
  unicorn/doc/sphinx/index.rst
  unicorn/doc/sphinx/intro.rst
  unicorn/doc/sphinx/logo.png
  unicorn/doc/sphinx/releases.rst
  unicorn/doc/sphinx/tutorial.rst

  unicorn/test/__init__.py
  unicorn/test/unittests.py

  unicorn/unicorn/__init__.py

Consider a first full run via: 'cd unicorn; auxilium full;'

Default Structure of a Project

The top level of the directory structure consists of three sub-dirs for source, doc and test files and some more or less standard project files. Assume the project is called auxilium.

/unicorn (project root dir)

   /unicorn (python source files)
   /doc/sphinx (sphinx files)
   /test/unittests (unittest files)

   LICENSE (license to use)

   CHANGES.rst (change history)
   HOWTO.rst (user guide)
   README.rst (introduction)

   requirements.txt (pip dependencies)
   upgrade_requirements.txt (pip dependencies which always have to be upgraded)

   setup.py (configuration file to build a distribution)

Your python source files can be structured as you like. Only few information on your project is required and has to be found in

/unicorn/unicorn/__init__.py

Most of them are needed to setup the pip installation (using setuptools) as well as the sphinx configuration for generation a documentation. See here how unicorn/unicorn/__init__.py looks like.

# -*- coding: utf-8 -*-

# unicorn
# -------
# Always be a unicorn.
#
# Author:   dreamer
# Version:  0.1, copyright Thursday, 29 August 2019
# Website:  https://github.com/dreamer/unicorn
# License:  Apache License 2.0 (see LICENSE file)


import logging

logging.getLogger(__name__).addHandler(logging.NullHandler())

__doc__ = 'Always be a unicorn.'
__license__ = 'Apache License 2.0'

__author__ = 'dreamer'
__email__ = 'unicorn@home'
__url__ = 'https://github.com/' + __author__ + '/' + __name__

__date__ = 'Thursday, 29 August 2019'
__version__ = '0.1'
__dev_status__ = '3 - Alpha'

__dependencies__ = ()
__dependency_links__ = ()
__data__ = ()
__scripts__ = ()

On top level we have the following files

/auxilium (project root dir)

   LICENSE

   CHANGES.rst
   HOWTO.rst
   README.rst

   requirements.txt
   upgrade_requirements.txt

   setup.py

Which serve for

• LICENSE is the license how to use, change or distribute the project.

• CHANGES.rst will contain the whole change and release history

• HOWTO.rst gives a intro how to use your project. This will show up in your documentation as tutorial.

• README.rst is this page which show up on repository homepage at first. Moreover, this will show up in your documentation as introduction.

• requirements.txt are additional python packages, which are required for development and/or testing

• upgrade_requirements.txt are additional python packages (same as requirements.txt), which have to be upgraded, i.e. installed by pip with the –upgrade option. Usually used for dev repos.

• setup.py configs the installation procedure with pip and the meta keywords of your project on pypi.org. Most of the entries are found in the project __init__.py file.

The structure of

/auxilium (project root dir)

   /auxilium (python source files)
   /doc/sphinx (sphinx files)

Automated Documentation Generation

The documentation is located at

/auxilium (project root dir)

   /doc/sphinx (sphinx files)

auxilium extracts all docs from the source code file and links to some top level rst files. So usually no file under /doc/sphinx requires to be edited.

The site-map of a documentation will look like this

/index.rst
   /intro.rst     -> README.rst
   /tutorial.rst  -> HOWTO.rst
   /doc.rst       -> api/* (generated by *sphinx-apidoc* via :code:`auxilium api`)
   /releases.rst  -> CHANGES.rst

Sphinx has a configuration (conf.py) to build html and latex resp. pdf documentation. The later requires a latex installation to work.

And it can run code-blocks of code examples of your documentation. (But avoid .. doctest:: rst-directive and |something| links in README.rst. This would fail with setuptools to serve as long_description for pypi.org.

Since only doc.rst will not refer to a top level doc file of the project it is generated from the source code. So here the work starts to write good python doc strings.

But if a more sphinx specific file reps. documentation is preferred. May be in order to provide detailed insights into the project: Simply delete api/* (if existing) and replace the contents of doc.rst.

Automated Test and Test Coverage Framework

Test are invoked by using unittest discovery script which searches by default for files containing unittest.TestCase classes and process them.

Same for measuring the test coverage using coverage.py

/auxilium (project root dir)

   /test/unittests (unittest files)

Installation

The latest stable version can always be installed or updated via pip:

$ pip install auxilium

Development Version

The latest development version can be installed directly from GitHub:

$ pip install --upgrade git+https://github.com/sonntagsgesicht/auxilium.git

Contributions

Issues and Pull Requests are always welcome.

License

Code and documentation are available according to the Apache Software License (see LICENSE).