Introduction to distutils (I)
Hey there! Have you ever wondered how to build and distribute a python module or library you have written to the public? If you have (if you haven't, that's cool anyway), then this might be interesting for you. Starting with this post, I'll write a tutorial divided in three parts that will hopefully serve as a simple and easy to understand introduction to Python's distutils: from writing the build script to sharing your library with the world.
First of all, please take into account that I will be referring to Python 2.7 in this tutorial, but it may not be that different for Python 3.
All right, let's get started with a bit of general information about what is distutils and how it works: imagine that you have written a Python module that you think might be useful to someone and want to share it online. You could always share your source code (free software!), but nowadays people prefer a simple and straight forward way of doing things, that's where distutils comes into play.
The distutils module makes building, distributing and installing modules easy: just write your setup script and you are ready to go. For this tutorial, I will be using a little project of mine called breezedb which you can find at GitHub, as I just recently went through all this process.
Project structure
As far as I know, there isn't a predefined structure for a Python project, so you can organize it the way you like. For instance, this is the structure I used for breezedb:
breezedb/ -- directory that contains the Python modules
doc/ -- directory that contains the documentation (I'll leave this for another time)
test/ -- directory that contains some test for the module
AUTHORS -- file that contains the name of the contributors
COPYING -- file that contains the complete license of the code
README -- well, everyone likes to have a README file with some information ;D
setup.py -- distutils setup script
For the time being, let's just work with setup.py, and we'll use the rest later on.
The setup script
Now for the interesting part, this is breezedb's setup script, which I will explain line by line with comments:
# -*- coding: utf-8 -*-
#
# This file is part of breezedb - https://github.com/rmed/breezedb_python
#
# Copyright (C) 2013 Rafael Medina García <rafamedgar@gmail.com>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published
# by the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
from distutils.core import setup
setup(
# Module name
name = 'breezedb',
# Version of the module
version = '1.0.1',
# A short description of your module. You may also want to add more information in a README file
description = 'A simple file-based database engine',
# Author of the module
author = 'Rafael Medina García',
# Contact email
author_email = '',
# Your personal website, support site, etc. I've written here the GitHub repository
url = 'https://github.com/rmed/breezedb_python',
# License of your code. It is important to include a file with the content of the license if required
license = 'LGPLv3',
# The packages to include in the build. The directories must have a __init__.py file for Python to recognize them as modules
packages = ['breezedb'],
# Distribution related categories
classifiers = [
'Development Status :: 5 - Production/Stable',
'Environment :: Console',
'Intended Audience :: Developers',
'License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)',
'Operating System :: OS Independent',
'Programming Language :: Python',
'Programming Language :: Python :: 2.7',
'Topic :: Database :: Database Engines/Servers',
'Topic :: Software Development :: Libraries :: Python Modules'
]
)
This is a rather simple setup script, so you might want to check the Python documentation for more advanced functionality.
I'll explain classifiers another time, as they are closely related to the distribution of the module and will make much more sense later on. Apart from that, that's basically it: you now have a setup script ready to go and in the next part of this tutorial we will see how to build the module and other interesting features that distutils offers.