I recently created a small Python module called Backgroundr. Backgroundr allows for the simple creation of wallpaper images for your computer with custom colors and text. My plan, with Backgroundr, is to turn it into a web app, as well as the existing command line client. In order to do this I believe it is necessary to be able to reuse the core part of the module. The obvious solution to this is using pip, the go to Python package manager.

I have installed modules plenty of times using pip, but I have never thought about what is involved in submitting my own package to be used with this service. I initially opted to use the git+ssh protocol to attempt to install my module straight from my github repository. using this command: pip install git+ssh://git@github.com/smg247/backgroundr.git I was able to download some basic meta data about my module, but where was the module itself? It turns out that a fair amount more was involved in being able to actually package up my module to allow it to be installable with pip.

I began searching around and found a ton of documentation on what needed to be done to prepare a module for use with PYPI (the Python Package Index), which is exactly what I needed to do in order to be able to use pip on my module. The first thing I needed to do was create a setup.py; this is my current version along with useful comments:

from setuptools import setup, find_packages

setup(
    name="Backgroundr",
    keywords="Backgrounds Wallpapers Images",
    description="A simple way to create backgrounds for your computer with custom colors and text",
    version="1.0.0", # The version number needs to be bumped up each time a new submission is made to PYPI
    # The following modules will be installed upon installing this module, use this for necessary requirements
    install_requires=[
        "Pillow",
    ],
    # The find_packages function will find all python packages in the module
    # this is necessary or else no packages will actually be installed
    packages=find_packages(),
    # This will allow for non python files and folders to be installed along with your packages
    # The key is the package it belongs to and the value is a list of files, here I am including the 'fonts' folder
    package_data={
        "backgroundr": ["fonts/*"]
    },
    include_package_data=True,
    url="https://github.com/smg247/backgroundr",
    author="Stephen Goeddel",
    author_email="stephen@stephengoeddel.com"
)

When submitting a package to PYPI it is possible to upload both a source distribution and a built distribution or "wheel". The setup.cfg file is utilized in the creation of the wheel:

[bdist_wheel]
universal=1

This one simply says that the built "wheel" is universal, meaning it will work with Python 2 or 3. It was also necessary to install "wheel" and "twine" with pip in order to build my "wheel" and upload my module respectively. I then needed to setup a PYPI account and register my module on PYPI. From there it was as simple as creating a little bash script to create my dists and upload my module:

#!/bin/bash
python setup.py sdist
python setup.py bdist_wheel
twine upload dist/Backgroundr-$1.tar.gz
twine upload dist/Backgroundr-$1-py2.py3-none-any.whl

I was able to utilize this script to create my source and built distributions and upload them both by calling it with the current version number as an argument. Finally, Backgroundr is an official PYPI module and is available for installation by simply running:
pip install Backgroundr