A Python project for an automated test and deploy toolkit - 100% reusable.
Project description
Python library auxilium
A Python project for an automated test and deploy toolkit which is 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
/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 doctests of code examples of your documentation.
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).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.