Published in DevBae. Please read it here:

Imagine you are in a desert and you only have one bottle packed in a Japanese puzzle box with no documentation on how to open it.

Felt bad right? That exactly what happens when anyone looks at a poorly documented, badly written code and wants to work on it.

I recently worked on a code and it was a nightmare for me to appreciate what they did just by looking at the code. There was no good API Documentation, there were no examples, code was poorly linted and it’s was one big mess.

Over these 4 years, I have realized that everyone tells you how to publish your code, as in a previous article in DevBae, but no one tells you how to write it in a way that it’ll be usable and people will be able to read it/understand it/redistribute it.

There are some considerations when you write your code. These will be:

And the list goes on. I will try to answer most of these questions in this article. I will also add up a few extra things and some lifechanging tools which you can use to make your lives easier.

Package Template

The code that you have written in a file is not at all distribution friendly. You first need to work on creating all the meta files for your package. The package template suggested in a previous blog is a starting point. I hope you all have understood how to write tests, setup files, etc. We will still work on that but read the previous blog first if you haven’t.

Since past few years, Python packages have changed a lot. PEP 517 made pip change it’s definition completely. Earlier, it used to be very similar to python but nowadays, it doesn’t matter if you have a file in your Python Package or not. The most important file now is pyproject.toml. However, that’s a story of a different article. Through this article, we will understand how to first migrate from to something more recent. We will learn how to configure setup.cfg for our packages. setuptools documentation sheds an amazing amount of light on how to do that. But we will still have a look at an example. Before we start, I will start by suggesting a package template.

|  |--source/
|     |
|     |--index.rst
|     |--_static/
|  |
|  |
|  |
|  |
|  |

You can do this very easily on your own, or just use this awesome cookiecutter template developed by my friend and mentor Juan Luis Cano Rodríguez. But remember that the cookiecutter template is extremely modern and doesn’t include a at all. If you want a slow migration guide, keep reading.

What will go where?

Considering the fact that you already know how to write, we will now decide how to make the package more modern by moving everything to setup.cfg. One very heavy fact (not easily digestible) is that we no longer use requirements.txt for dependency management in a package. So all you have to first do it create a requirements.txt and leave it blank.

Now, you r setup.cfg has to be populated with (Remove all the comments):

name = packagename
version = 0.1.dev0  #Use Semantic Versioning
author = Shreyas Bapat
author_email =
license = MIT       #Whatever suits best               
description = A one liner about my package
keywords =
url = #Your personal/package website
download_url = #GitHub Repo
long_description = file: README.rst
classifiers =
        Development Status :: 4 - Beta
        Intended Audience :: Education
        Intended Audience :: Science/Research
        License :: OSI Approved :: MIT License
        Operating System :: OS Independent
        Programming Language :: Python
        Programming Language :: Python :: 3
        Programming Language :: Python :: 3.6
        Programming Language :: Python :: 3.7
        Programming Language :: Python :: 3.8
        Topic :: Scientific/Engineering
package_dir =
    = src
packages = find:
zip_safe = False
install_requires =
        numba >=0.46,!=0.49.0 ; implementation_name=='cpython'
include_package_data = True
python_requires = >=3.6
where = src
dev =
        black ; python_version>="3.6"
norecursedirs =
python_files =
doctest_plus = disabled
addopts = --strict
markers =
ignore = E203, E266, E501, W503
max-line-length = 80
max-complexity = 18
select = B,C,E,F,W,T4,B9

Your now will just look like:

#!/usr/bin/env python
from setuptools import setup

That’s it. This is all you have to do.

Now there are various parts of this file. Let’s look at some of them and understand what they do.

1) install_requires : The section of install requires in the setup.cfg is there to mention all the dependencies of the project. All this will be installed automatically when you will pip install packagename.

2) python_requires : It specifies the minimum Python version you support for the package.

3) options.extras_require : These are the dependencies that you don’t want your users to install but, they are essential for development. All this will be installed when you do pip install packagename/[dev].

You can ignore the rest for now. Now if you look closely, you will find three development dependencies you will not understand. Black, isort, and sphinx. I will try to explain what these are in the next sections.

Code linting

I will start by quoting the zen of Python :

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

This easter egg was introduced in PEP 20 and can be reproduced by writing :

>>> import this

One of Guido’s key insights is that code is read much more often than it is written. Code linting guidelines are intended to improve the readability of code and make it consistent across the wide spectrum of Python code. As PEP 20 says, “Readability counts”. A style guide is about consistency. Consistency within a project is more important. Consistency within one module or function is the most important.

However, know when to be inconsistent – sometimes style guide recommendations just aren’t applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best.

An excerpt from PEP 8:

When applying the guideline would make the code less readable, even for someone who is used to reading code that follows this PEP. To be consistent with surrounding code that also breaks it (maybe for historic reasons) – although this is also an opportunity to clean up someone else’s mess (in true XP style). Because the code in question predates the introduction of the guideline and there is no other reason to be modifying that code. When the code needs to remain compatible with older versions of Python that don’t support the feature recommended by the style guide.

Keeping this in mind that using PEP 8 can actually hamper the readability of the code, many people stopped using PEP8, and maintainability of the public codes started to go down. You have to understand that while reviewing the submitted patches, you get to look at the diff. Sometimes the diff can be overwhelming. And when the diffs are ignored and few parts of the code are merged without a proper review as they are hard to read, a strong technical debt is introduced which continues for years and is difficult to resolve. That’s why we should always avoid Technical Debts. You must ask if PEP 8 can’t help, what can?

The same question came into the mind of a few developers who found simple PEP 8 as useless and difficult to maintain. They created Black. They found workarounds in PEP 8 and created a code formatter which complies with PEP8 while giving a maintainable code.

In their own words:

Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead. In this way, you can use Black to format your code and make the same compulsion on all the patches. This will increase readability and maintainability.

There’s isort as well. It does a magical thing of making all the imports in a consistent order. For example, for a file like this,

import numpy
from astropy import units
import scipy
import main
import matplotlib

it will analyze which are the core modules, which are your local modules and what kind of imports are there and then rearrange them to :

import matplotlib
import numpy
import scipy
from astropy import units
import main

Beautiful right? This is also intended to increase code readability and maintainability.


Modern projects use Sphinx for automatic documentation generation. Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages.

Some pointers on sphinx:

So all you have to do is write good docstrings, understand how sphinx works, and you are good to go. I suggest using numpy like docstrings for classes and methods. One example of the same would be:

def function(x, y):
   Some information about the function.
   x : type
      Description of parameter `x`.
   y : type, optional
      Description of parameter `y` (with type not specified)
      Description of the anonymous integer return value.
       If the matrix is not numerically invertible.

These docstrings are written in reStructuredText and are automatically picked up by sphinx if used.

You should also maintain a CHANGELOG for keeping a track of what changes every release, who are the people who contributed to the release, who amongst them are first time contributors, etc. This helps people understand what is changing in the software, what’s new and what’s deprecated without looking at the code.


There are typically 2 major modes if distribution in Python:

  1. PyPI
  2. conda

You can see how to publish/distribute packages on PyPI in the previous article. I will explain how you can do that for conda. You will have to use something called conda forge. You will have to add a recipe in conda first and let conda forge verify that your package is well maintained. Here’s how you do that:

Then you can happily do: conda install -c conda-forge packagename!

Cool right? But what if I told you, you can also publish it on things like apt. For that, you will have to contact someone in Debian Ecosystem(Also me :p). It’s not open access. You have to be authorized to create a repository in debian salsa. So, the best shot is to contact an existing maintainer. If you are developing a python package for astronomy, I can help you put that in Debian Astro very easily. For others, I will have to go through a process, but I can certainly help you.

In the end, you will have sudo apt install python3-packagename for your package.

Choosing a Licence for your package

You SHOULD ALWAYS NAME YOUR LICENCE FILE AS COPYING. Don’t ask why, just do it. The reasons for that are beyond the scope of this article.


Your source publication needs a license. In the US, if no license is specified, users have no legal right to download, modify, or distribute. Furthermore, people can’t contribute to your code unless you tell them what rules to play by. Choosing a license is complicated, so here are some pointers:

Open source. There are plenty of open source licenses available to choose from.

In general, these licenses tend to fall into one of two categories:

  1. licenses that focus more on the user’s freedom to do with the software as they please (these are the more permissive open source licenses such as the MIT, BSD, and Apache)

  2. licenses that focus more on making sure that the code itself — including any changes made to it and distributed along with it — always remains free (these are the less permissive free software licenses such as the GPL and LGPL)

The latter are less permissive in the sense that they don’t permit someone to add code to the software and distribute it without also including the source code for their changes.

To help you choose one for your project, there’s a license chooser; use it.

More Permissive

Less Permissive:

A good overview of licenses with explanations of what one can, cannot, and must do using a particular software can be found at tl;drLegal.

Choosing a license is one of the most important tasks as it defines how your software will be used, how it will be cited, how it will be redistributed.

I hope I explained most of the things very well, if you still have doubts, write a mail to me on I will be glad to have a discussion with you. Hope to see more and more Python Packages from the community. Remember, don’t think that your code is very basic and does not contribute anything to society. Every bit counts, every second you invest in making a code that does a small task counts. No code is useless.

Happy Coding!