Chapter 3. Modularize, Package, Deploy!

In the past few chapters, you wrote a simple application, added new features to it, and made sure that some commonly encountered bugs were fixed. Now, it is time to make it available to a broader audience. In this chapter, you will learn the following topics:

• Modularizing and packaging the code written in earlier chapters

• Preparing and deploying a source distribution

• Setting up a private Python package repository

• Making incremental releases

• Bringing your code under version control

Thanks to word of mouth publicity, the high fantasy game application is gaining further attention. More and more people are requesting access to the code, either to use the functionality in their own application or to simply play the game. So far, you have sent the complete source code to the users requesting it. But, it is silly to continue doing that because you have made quite a few frequent upgrades.

There are several ways to handle this. The most basic option is to host the...

Selecting a versioning convention

How do we name new versions of the code? There are several versioning schemes in use. Let's quickly review a few popular ones.

Serial increments

In this scheme, you just increment the version number in a serial manner for each upgrade, for example, v1, v2, v3, and so on. However, this does not give any information on what a particular release is about. Just by looking at the version number, it is tough to tell whether a particular version introduces a revolutionary feature or just fixes a minor bug. It does not give any information on API compatibility. You can choose this simple versioning scheme if it is a small application with a small user base and a very limited scope.

Note

API compatibility

An Application Programming Interface (API), in simple terms, enables a piece of a program, say a library or an application, to talk to another one using a standard set of functions, methods, or objects.

Imagine a software library car that stores some data on a fancy...

Modularizing the code

We have been referring to modules in the earlier chapters. An explanation is in order. A single Python file with a .py extension is a module. You can use this module in some other source code using an import statement. The module name is the same as the file name, except the .py extension. For example, if the file name is knight.py, then import knight will import the module into your source file.

In this section, we will split the code in the attackoftheorcs_v1_1.py file into individual modules. You can find this file in the supporting code bundle for the previous chapter.

Attack of the Orcs v2.0.0

We will name this version 2.0.0. The major version is incremented to 2 as we are about to make some API level changes. The way we access functionality from the code will change after introduction of the new modules. Let's review the source file, attackoftheorcs_v1_1.py, from Chapter 2, Dealing with Exceptions. The first step is to create a module (a new file) for each of the...

Creating a package

Now that we have modularized the code, let's create a Python package. What is a package? It is a kind of fancy name for a directory where Python modules are located. However, there is more to it than that. For such a directory to be called a package, it must also contain an __init__.py file. This file can be kept empty or you can put some initialization code in this file. To transform the wargame directory as a Python package, we will create an empty __init__ .py file in this directory. The new directory structure is shown in the following screenshot:

Importing from the package

Let's see how to use the functionality from this newly created package. To test this out, create a new file, run_game.py, at the same directory level as the wargame package. The directory structure will appear as follows. Here, mydir is the top-level directory (it can be any name):

Add the following code to the run_game.py file:

The first line is the new import statement. Here, we are importing the...

Releasing the package on PyPI

The Python Package Index (PyPI) ( https://pypi.python.org/pypi) is a package distribution mechanism for the Python community. It is the official repository for the third-party packages. By default, the Python package manager, pip, searches this repository to install the packages.

This is the place where we will upload our source distribution and make it generally available to the Python community. The PyPI repository has a devoted test server (https://testpypi.python.org/pypi) for developers who are just learning to package their code. As this is a learning activity, we will first deploy our package on the test server.

Prepare the distribution

Let's start by laying out the ground work for the release. We first need to prepare the distribution to be released. The following steps provide a minimal set of instructions to prepare the distribution.

Step 1 – Setting up the package directory

Make a new directory, and call it testgamepkg or give it any name you like. In...

Using a private PyPI repository

This section will briefly cover how to setup a private PyPI repository. The discussion will be limited to creating a simple HTTP-based local server. There are several packages that can help you do this. Let's use a popular package called pypiserver (https://pypi.python.org/pypi/pypiserver). Let's open a terminal window and get ready for action.

Step 1 – Installing pypiserver

First, install the required package:

$ pip install pypiserver 

The pypi-server executable sits at the same location that you have the Python executable. For example, if you have /usr/bin/python, pypi-server will be available as /usr/bin/pypi-server.

Step 2 – Building a new source distribution

Go to the directory where you have setup.py and all other files. In the discussion earlier, we named it testgamepkg:

$ cd /path/to/testgamepkg

We have already installed testgamepkg in an earlier section. To simplify things, in setup.py let's change the name field to something else. While you are at it...

Making an incremental release

The package is released but that is not the end of the story. Very soon, you will need to make changes to the code and make the newer version available again. In this section, we will learn how to submit incremental patches to an already deployed distribution.

Packaging and uploading the new version

Preparing for the new release is pretty simple. Just update the version number to, for instance, 2.0.1 in the setup.py file. After making this change, run the earlier command that creates a source distribution and uploads the package in one go:

$ python setup.py sdist upload -r pypitest

The incremental release of v2.0.1 will now be available on the PyPI test repository.

Upgrading the installed version

If the previous version of the package is already installed on your computer, use the --upgrade option to update to the latest release version. This step is optional, but it is always good practice to verify the released version is working as expected:

$ pip install -i...

Version controlling the code

Let's recap what we have done so far. We started application development with a simple script. Gradually, we redesigned the application, added new features and fixed bugs to transform it into its current state. What if you want to go back to an earlier state of the code, say the code you wrote two days ago? You may want to do this for various reasons. For instance, the latest code might have some bugs that you didn't see two days ago. Imagine another scenario where you are collaborating with your colleagues on a project and you all need to work on the same set of files. How do we accomplish that?

In such situations, a version control system (VCS) comes to our rescue. It maintains a record of changes you make to the code. The files and directories now have a version associated with them. The VCS enables you to pull a specific version of any file.

There are several version control systems in use. Git, SVN, CVS, and Mercurial are some of the most popular open source...

Using GUI clients for Git

The earlier section exclusively discussed how to use Git from the command line. These commands can also be accessed through a graphical user interface (GUI). There are many GUI clients available for Git, for instance, gitk on Linux (http://gitk.sourceforge.net/) or Github Desktop, available for Mac and Windows 7 or later (https://desktop.github.com/). The free Python IDEs, such as the community edition of PyCharm, provide an easy-to-use GUI integration for Git and other version control systems. PyCharm provides a context menu integration for Git commands. For example, right-clicking on a file in the IDE will give you a context menu option to add or commit the file to a repository.

Exercise

We released the distribution to the PyPI test repository as it was just a toy problem. For more serious stuff, you should deploy the package to the PyPI main repository, https://pypi.python.org/pypi. As an exercise, deploy a package on the main PyPI server. The process is similar to what we discussed earlier.

• Create a new account on the PyPI website. Note that you need to create a separate account; the test PyPI account won't work here.

• In the .pypirc file, create a new profile to store credentials for the main server. See the following illustration for an inspiration:

  [distutils] 
  index-servers= 
  pypitest 
  pypimain
  
  [pypimain]
  repository = https://pypi.python.org/pypi
  username=<add PyPI main username>
  password=<add PyPI main password>
  
  [pypitest] 
  repository = https://testpypi.python.org/pypi 
  username=<add username>
  password=<add password>

• Appropriately, update the url field in setup.py.

• Follow the other steps in package creation and release. Remember to specify...

Summary

This chapter introduced you to some key aspects of application development in general and Python application development in particular. The chapter started with an introduction to different versioning conventions. It demonstrated how to create Python modules and packages.

With step-by-step instructions, the chapter demonstrated how to prepare a distribution (also called a package), deploy it on the PyPI test server, and install this deployed package using pip. Additionally, it also showed you how to make incremental releases and set up a private Python distribution. Finally, the chapter provided an overview of version control using Git.

Coding standards are a set of guidelines that you should follow while developing the code. Complying with these standards can have a significant impact on the code readability and the life of the code. In the next chapter, you will learn another important aspect of software development, code documentation, and best practices.