Introduction

Pylease works on Python projects that are being managed by setuptools, i.e. have setup.py file in their root directory. This is enough to make Pylease get things done. Pylease is an extensible modular tool, which enables the developers to enhance it further. So let us start with the installation first.

Installation

Pylease is a regular Python package which comes with a command line tool, obviously called pylease. So to start:

$ pip install pylease

And then just check if everything went fine:

$ pylease --version
Pylease version 0.3

Workflow

The simplicity of Pylease is that it does not require any specific configuration or scripts, it accepts Python projects just as-is. Although, you can configure Pylease to fully use its features, it is not required and you can just start using Pylease on a project you were working on for years. So let us consider two scenarios.

Project from Scratch

So to start a new Python project, just create a new empty directory for your project and then use the init command to create a skeleton for your project:

$ mkdir my_project
$ cd my_project
$ pylease init my_project

Now you have the skeleton of your project ready to be used:

$ ls -LR
my_project setup.cfg  setup.py

./my_project:
__init__.py
$ cat setup.py
import my_project
from setuptools import setup

setup(name='my_project',
      version=my_project.__version__)
$ cat setup.cfg
[pylease]
version-files = my_project/__init__.py
$ cat my_project/__init__.py
__version__ = '0.0'

Existing Project

If you have an already initialised Python project, then the first thing you will want to do for feeling the presence of Pylease, is the following:

$ cd /path/to/your/project/root
$ ls
... setup.py ...
$ pylease status
Project Name: <your project>
Current Version: <project version>

Releasing a Project

The idea of Pylease came while doing some routine tasks during a release process of a Python project, thus the main focus of it is the release process itself. So Pylease provides the make command to perform an appropriate release. But before doing anything release related, first check out your current status as it is done for an Existing Project.

So while you are working on a project, the current version defined is the last version the project was released with. As you can see in initialising a Project from Scratch, the initial version is 0.0, i.e. no release is done yet.

You may ask a reasonable question, why does not the current version represent the version you want to release next? The reason for that is that it is possible that while working on the project, you might have a minor bug, small feature that will need a rapid release, so you will need to make a patch or minor level release.

As already mentioned, you perform a release with the help of the make command of Pylease. The main and required parameter of make command is the release level, which is passed as one of the following:

• --major
• --minor
• --patch
• --dev

For instance, executing pylease make --minor on a project with version 0.3 will update it to 0.4:

$ pylease status
Project Name: example
Current Version: 0.3
$ pylease make --minor
$ pylease status
Project Name: example
Current Version: 0.4

So this is pretty much all what the release is. As a result, you will have your setup.py updated to the new version. To customize the behaviour of the release process, you might want to take a look at Pylease configuration.

Moreover, if you wish to add your own custom actions to Pylease, you should definitely get into extending Pylease.

For a quick reference, always consider to take a look at --help messages for commands, e.g. pylease make --help.