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.
- copy your source code into a boilerplate project structure
- write useful documentation in your python source code doc strings
- 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
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
pipwith 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.
.. 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:
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
unittest.TestCase classes and process them.
Same for measuring the test coverage using coverage.py
/auxilium (project root dir) /test/unittests (unittest files)
The latest stable version can always be installed or updated via pip:
$ pip install auxilium
The latest development version can be installed directly from GitHub:
$ pip install --upgrade git+https://github.com/sonntagsgesicht/auxilium.git
Code and documentation are available according to the Apache Software License (see LICENSE).
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size auxilium-0.1.4-py3-none-any.whl (53.6 kB)||File type Wheel||Python version py3||Upload date||Hashes View|
|Filename, size auxilium-0.1.4.tar.gz (52.1 kB)||File type Source||Python version None||Upload date||Hashes View|