(01:Introduction)=

Introduction


Python packages are a core element of the Python programming language and are how you write reuseable and shareable code in Python. If you’re reading this book, chances are you already know how to use packages with the help of the import statement in Python. For example, importing and using the numpy package to round pi to 3 decimal places is as simple as:

In [1]:
import numpy as np

np.round(np.pi, decimals=3)
Out[1]:
3.142

At a minimum, a package simply bundles together code (such as functions, classes, variables, or scripts) so that it can be easily reused across different projects. However, packages may also include things like documentation and tests, which become exponentially more important if you wish to share your package with others.

As of January 2021, there are over 280,000 packages available on the Python Package Index (PyPI). Packages are a key reason why Python is such a powerful and widely used programming language. The chances are that someone has already solved a problem that you’re working on, and you can benefit from their work by downloading and installing their package (which they have kindly developed and shared) by, for example, using Python's native package manager pip and a simple pip install <package-name> at the command line. Put simply, packages are how you make it as easy as possible to share, maintain and collaborate on Python code with others; whether they be your friends, work colleagues, or the world!

Even if you never intend to share your code with others, making packages will ultimately save you time. Creating Python packages will make it significantly easier for you to access, reuse and maintain your code within a project and across different projects. At some point, all of us have wanted to reuse code from one project in another; this is something often accomplished through the reprehensible method of copy-and-pasting your existing code into the new project. Despite being obviously inefficient, this practice also makes it difficult to improve and maintain your code and its dependenices across projects. Creating a simple Python package will solve these problems.

Regardless of your motivation, the goal of this book is to show you how to easily develop Python packages. The focus is overwhelmingly practical - we will leverage modern methods and tools to develop and maintain packages efficiently, reproducibly, and with as much automation as possible; so you can focus on writing and sharing code. Along the way, we'll also enlighten some of the lower-level details of Python packaging and the Python programming language.

```{figure} images/packaging-flowchart.png

width: 75% name: 01-package-flowchart

alt: The Python packaging workflow.

The Python packaging workflow. ```

Why you should create packages

As discussed above, there are many reasons why you should develop Python packages! Let's summarise the key reasons below:

  • To effectively share your code with others.
  • They save you time. Even if you don't intend to share your code, packages help you easily reuse and maintain your code across multiple projects.
  • They force you to organise and document your code, such that it can be more easily understood and used at a later time.
  • They isolate dependencies for your code and improve its reproducibility.
  • They are a good way to practice writing good code.
  • Finally, developing and distributing packages supports the Python ecosystem and other Python users who can benefit from your work.