This lesson is being piloted (Beta version)


What is a package?

Why is packaging important in scientific research?

If you have used Python for scientific computation, you’ve likely encountered widely distributed open-source packages like NumPy, SciPy, or Pandas. However, it’s important to note that packages can exist at many scales and contexts, ranging from personal and organizational use to wide public distributions.

In this tutorial we’ll walk through methods and tools used to create and distribute your own Python packages.

Lesson Plan

We’re going to create a Python package from scratch, then publish it. Packages often include additional files for configuration, documentation, and automations. We’ll look at the following important groups of files:

├── src/                    ─┐
│   └── example_package_YOUR_USERNAME_HERE/
│   │   ├──      │
│   │   └──       ├─ Minimum to make the code
├── tests/                   │  work and be installable
│   └──      │
├── pyproject.toml          ─┘ ← Metadata and versioning
├── .git/                   ─┬─ Store the history of the code
├── .gitignore              ─┘
├── .venv/                  ─── Environment to run the code
├── README                  ─┐
├── CHANGELOG                ├─ Tell people browsing the code what it's for,
├── LICENSE                  │  how it's changed, under what conditions they
├── CITATION.cff            ─┘  can use it, and how they can cite it
├── docs/                   ─┐
│   ├──             ├─ Document the code in more detail
│   └──             ─┘
├── .pre-commit-config.yaml ─┐
├──               │
└── .github/                 ├─ Automate tasks which run _on_ the code
    └── workflows/           │  like style-checks, tests, and publishing
        ├── test.yaml        │
        └── publish.yaml    ─┘

See Also

This is a tutorial. For reference material, you should bookmark the following guides:


  • Basic Python


Setup Download files required for the lesson
00:00 1. Environments How do you install and manage packages?
00:20 2. Code to Package How do we take code and turn that into a package?
What are the minimum elements required for a Python package?
How do you set up tests?
00:45 3. Other files that belong with your package What other files are important parts of your software package?
01:00 4. Metadata What metadata is important to add to your package?
How to I add common functionality, like executable scripts?
01:15 5. Versioning How do you choose your versions?
How do you set version limits on dependencies?
How do you set a version?
01:30 6. Publishing package and citation How do I publish a package?
How do I make my work citable?
01:45 7. Documentation Overview How do I document my project?
01:45 8. Documentation with Sphinx How do I document my project?
02:05 9. Documentation with MkDocs Material How do I document my project?
02:25 10. Checks and tests How do you ensure your code will work well?
02:45 11. Task runners How can you ensure others run the same code you do?
02:55 12. Continuous Integration How do you ensure code keeps passing
03:15 Finish

The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.