pkglts¶

Building packages with long term support

The rationale behind the creation of this ‘package builder’ is to keep the life of a python programmer as easy as possible by providing three core functions:

A way to add more functionality to an existing package.

A way to keep the package structure up to date with currently known best practices.

Remove repetitive tasks that can be automated from the list of things to do.

Quick start¶

Create a virtual environment for development:

$ virtualenv dvlpt

Activate it:

$ (on windows)dvlpt\Scripts\activate
$ (on linux)dvlpt/bin/activate

Install pkglts:

(dvlpt)$ pip install pkglts

Create a directory for your package:

(dvlpt)$ mkdir toto

Run ‘manage’ inside this directory:

(dvlpt)$ cd toto
(dvlpt)toto$ pmg init
(dvlpt)toto$ pmg add base
(dvlpt)toto$ pmg regenerate

This will create the bare basic minimum for a python package. Add more options (see the add_option for more options) afterward. Especially, since in the example above we just added the ‘base’ option that will create a ‘src’ directory to put your code in it.

Documentation¶

More documentation can be found on readthedocs_pkglts. If you just intend to use this package you can start with some tutorials. However, if the core functionality are not sufficient and you want to be part of the development you might be interested with the developer section of the doc.

Upgrade Package Structure¶

Packages generated with pkglts contains three different types of files:

Configuration files for pkglts, which are all located inside a ‘.pkglts’ directory at the root of your package. This directory especially contains a ‘pkg_cfg.json’ resource file that contains all the information necessary to regenerate your package in order to take into account new developments in the way of packaging or new options you added to your package.

Files that contain at least one ‘pkglts’ tag that have been automatically generated by pkglts. Everything inside a pkglts section is regenerated every time the user call ‘regenerate’ on his package and are not meant to be modified. Between pkglts sections the user is free to add his own code that won’t be touched in the regenerate process.

developer data and modules edited by hand which contains the actual python code of the package independently of the structure of the package. pkglts will never touch them. If they conflict with some files used by a newly added option, the user will be prompted and will have to solve the conflict in order to install the option.

Every time you make changes to the structure of your package by adding a new option for example, a call to ‘pmg regenerate’ is mandatory to rebuilt the package structural files:

(dvlpt)toto$ pmg regenerate

This phase will never overwrite any files you modified or created. You’ll be prompted in case of conflicts but it is your responsibility to solve them and relaunch the command.

It is also good practice to regenerate your package from time to time to take into account the latest version of pkglts which will reflect the latest development in the way to package things.

Add Package Structure Functionality¶

Pkglts provides a set of options to introduce new functionality to an already existing package:

base: base option, basic package management

license: will help the developer to choose a license and add the relevant files

doc: Add some documentation to your package

test: basic unitests using Nose

coverage: add code coverage to the basic test configuration

pysetup: make your package distributable with setuptools (i.e. setup.py)

data: will guide through all the steps to add non python files to a package

github: will guide through all the step to safely store the package on Github

gitlab: will guide through all the step to safely store the package on a Gitlab repo

readthedocs: step by step guide to have your documentation on ReadTheDocs

travis: will guide through all the steps to use Travis-CI for continuous integration of your package

tox: defines config files to use multi environment testing, Tox

flake8: install and config Flake8 tools to check for code compliance to PEP8 guidelines.

pypi: step by step guide and configuration to upload package on PyPi.

Install a new option¶

To install a new option call the ‘add’ action:

(dvlpt)toto$ pmg add license

The script will perform different tasks sequentially:

Check if this option requires other options in order to be installed: e.g. the ‘pysetup’ option requires all ‘base, ‘doc’, ‘test’, ‘license’ and ‘version’ in order to run properly.

Check if this option requires some extra packages in order to setup: e.g. the ‘test’ option depends on the Nose package to function properly.

Note

Nothing will be installed without your consent

Multiple call to add options can be serialized but you explicitly needs to call regenerate to see the action of the new options on your package:

(dvlpt)toto$ pmg regenerate

Before calling ‘regenerate’ however, take the time to browse through ‘pkg_cfg.json’ in the ‘.pkglts’ directory to edit the parameters relevant for your option.

Install example files¶

Some options come with example files that can be installed with the special directive:

(dvlpt)toto$ pmg example test

The files will be directly installed without the need to a regenerate call. You can reinstall them at any time (you’ll be prompted for action if conflicts occur).

Extra services¶

Warning

Work In Progress

Package Builder also provides a few useful services to check that the python modules follow code best practices:

‘add_object’: will create a new python module with the proper headers and a skeleton of a python class.

‘add_plugin’: will wrap a given python class into a usable plugin.

‘add_script’: will wrap a given python functionality into a command line script.

‘reset_file_header’: will loop through all python modules and try to rewrite file header to match current best practices.

fmt_doc: check code documentation and format it according to given standard if possible. Requires some already good documentation, just a quick fix to pass from one style to another (e.g. google to numpy).

Contributing¶

You can contribute to this package by:

improving the documentation

correcting some bugs

closing a few issues

implementing a new option to add a new functionality to package structures