Package: auxilium
A Python project for an automated test and deploy toolkit - 100% reusable.Code, Documentation and TestsModern software development comes as a triple ofThecodeis the actual software program or library which can executed or
invoked.Thedocumentationshould give an introducing the idea and mission,
guide how to use it, describe functionality and features.Finally, intensivetestsincreases the confidence that the documented
functionality is correctly implemented.To support thisauxiliumis designed to build, to auto-doc, to test and
to deploy small to medium size Python projects in3 simple steps.copy yoursource codeinto a boilerplate project structurewrite usefuldocumentationin your python source code doc stringsadd as many as possibletest casesin a designated test directory structureWhat’s in the box?Once setup up,auxiliumserves as a development and integration
workflow manager. It provides tools to run a ci/cd
(continuous integration/continuous deployment) framework with state-of-art
development and integration tools likesource code management withgitpython environment virtualization withvenvintegrated dependency management withpipsource code quality and style validation withflake8source code security checks withbanditautomated software testing withunittestandregtesttest coverage measurement withcoverageautomated documentation generation withsphinxdocumentation templates base onrestructuredtextmarkup languagedesigned to work even at online sites likePyPi.comandGitHubstandard python distribution packaging withbuildandtwineremotegitrepo management forBitBucket,GitHub,GitLabsingle command software release deployment toPyPithe Python Package Index databaseHow does it work?conventions on how the project is structured,
i.e. where to find source, test and doc filesprovides useful template structure of files
which can be easy modified and extendedkeeps 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 documentationminimises the places to edit,
by default there are only three documentation files to be editedcomes with a shell script to trigger plenty test and analysis routines
incl. drafting pushing on git remotes and distribute on pypi.orguses standard community tools
likeunittest,flake8,coverage,sphinxand moreno detailed configurations of any tools are needed,
so you can focus completely on coding your projectdemo of how to use the framework and various services to build trueci/cd;
a full automated test and deploy pipeline for the rest of us.creates and usesvenvvirtual environment to test
on clean python installationMoreover, we recommend to usepyenvandvirtualenvto test different python installations, too.Quick Start a ProjectOnce installed simply invokeauxilium createand enter a few project details.The whole project structure will be created.
Full functioning incl. documentation generation, testing, etc..$auxiliumcreatePleaseenterprojectdetails.Enterprojectname:unicornEnterprojectslogan:Alwaysbeaunicorn.Enterprojectauthor:dreamerEnterprojectemail:dreamer@homeEnterprojecturl:www.dreamer.home/unicornCreatedprojectunicornwiththesefiles:unicorn/CHANGES.rstunicorn/HOWTO.rstunicorn/LICENSEunicorn/MANIFEST.inunicorn/README.rstunicorn/requirements.txtunicorn/setup.pyunicorn/upgrade_requirements.txtunicorn/doc/sphinx/conf.pyunicorn/doc/sphinx/doc.rstunicorn/doc/sphinx/index.rstunicorn/doc/sphinx/intro.rstunicorn/doc/sphinx/logo.pngunicorn/doc/sphinx/releases.rstunicorn/doc/sphinx/tutorial.rstunicorn/test/__init__.pyunicorn/test/unittests.pyunicorn/unicorn/__init__.pyDefault Structure of a ProjectThe 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 calledunicorn./unicorn(projectrootdir)/.aux/venv(virtualpythonenvironment)/unicorn(pythonsourcefiles)/doc/sphinx(sphinxfiles)/test/unittests(unittestfiles)LICENSE(licensetouse)CHANGES.rst(changehistory)HOWTO.rst(userguide)README.rst(introduction)requirements.txt(pipdependencies)upgrade_requirements.txt(pipdependencieswhichalwayshavetobeupgraded)setup.py(configurationfiletobuildadistribution)MANIFEST.in(configurationfiletobuildadistribution).gitignore(configurationfile-filesandfolderwhichgitshouldignore)On top level there ate the following filesLICENSEis the license how to use, change or distribute the project.CHANGES.rstwill contain the whole change and release historyHOWTO.rstgives a intro how to use your project.
This will show up in your documentation as tutorial.README.rstis this page which
shows up on repository homepage at first.
Moreover, this will show up in your documentation as introduction, too.requirements.txtare additional python packages,
which are required for development and/or testingupgrade_requirements.txtare additional python packages
(same asrequirements.txt), which have to be upgraded,
i.e. installed bypipwith the–upgradeoption.
Usually used for dev repos.setup.pyconfigs 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__.pyfile.MANIFEST.inconfigs the files
which will be part of the final distribution..gitignoreconfigs git which files and folder to ignoreand subdirectories.aux/venvwhich contains the virtual python environmentunicorn/as the actual python source directory
(place to put the python scripts)Note, project root dir and python source dir must have the same name!doc/sphinx/file read by sphinx to build documentation sites
which can be extended, e.g. byauxilium doc --api,
but also manually.test/to contain all test scripts and data
(by default there will be two:unittests.pyandregtests.py)As the actual python source files can be structured as you like insideunicorn/unicorn/only few information on your project are required and should be found inunicorn/unicorn/__init__.pyMost of them are needed to setup thepipinstallation (usingsetuptools),
deployment toPyPi.orgas well as the sphinx configuration for generation a documentation.
See here howunicorn/unicorn/__init__.pylooks 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)importlogginglogging.getLogger(__name__).addHandler(logging.NullHandler())__doc__='Always be a unicorn.'__license__='Apache License 2.0'__author__='dreamer'__email__='unicorn@home'__url__='https://www.dreamer.home/unicorn'__date__='Thursday, 29 August 2019'__version__='0.1'__dev_status__='3 - Alpha'__dependencies__=()__dependency_links__=()__data__=()__scripts__=()__theme__=''Once setup up, update file headers of all new and modified files
and adding them to the project source code repository simply byauxilium update.Automated Documentation GenerationThe documentation is generated bysphinxand the main documentation files is located at/auxilium(projectrootdir)/doc/sphinx(sphinxfiles)auxiliumextracts all docs from the source code file and links
to some top levelrstfiles.So usually no file under/doc/sphinxrequires 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/*(generatedby*sphinx-apidoc*via:code:`auxiliumdoc--api`)/releases.rst->CHANGES.rstThe project has a configuration (conf.py) to buildhtmlandlatexresp.pdfdocumentation. The later requires a latex installation to work.Andauxiliumwill run and checkcode-blocksof code examples
of your documentation during doc build (doctest).All this is executed by just one commandauxilium doc.Since onlydoc.rstwill 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
in your source code files.But if a moresphinxspecific file reps. documentation is preferred.
May be in order to provide detailed insights into the project:
Simply deleteapi/*(if existing) and replace the contents
ofdoc.rst.More on documentation can be found in thedocumentation.Automated Test and Test Coverage FrameworkTest are invoked byunittest discoverywhich searches by default for files
containingunittest.TestCaseclasses and process them.Same for measuring the test coverage
usingcoveragesource code security and quality
usingbanditandflake8./unicorn(projectrootdir)/test/unittests(unittestfiles)Run all tests and checks withauxilium test.More on testing can be found in thedocumentation.Automated Build and Deployment FrameworkOnce a project milestone is reached, docs are written
and all tests are successfully passed,
it is ready for deployment.The default deployment platform isPyPi.org.
Before deploying a distribution package is build.
Moreover, it’s time to update (pushto) the project state to
a git remote repo like onGitHub,GitLabanfBitBucketInvoke this withauxilium build.
Topushanddeployadd options--pushand--deploy.More on build and deployment can be found in thedocumentation.InstallationThe latest stable version can always be installed or updated via pip:$pipinstallauxiliumDevelopment VersionThe latest development version can be installed directly from GitHub:$pipinstall--upgradegit+https://github.com/sonntagsgesicht/auxilium.gitContributionsIssuesandPull Requestsare always welcome.LicenseCode and documentation are available according
to the Apache Software License (seeLICENSE).