07-09, 13:30–17:30 (US/Pacific), Ballroom B/C
Creating code that can be shared and reused is the pinnacle of open science. But tools and skills to share your code can be tricky to learn. In this hands-on tutorial, you’ll learn how to turn your pure Python code into an installable Python module that can be shared with others. To get the most out of this tutorial, you should be familiar with writing Python code, Python environments and functions.
You will leave this tutorial understanding how to:
- Create code that can be installed into different environments
- Use Hatch as a workflow tool, making setup and installation of your code easier
- Use Hatch to publish your package to (test) PyPI
Creating code that can be shared and reused is the gold-standard of open science. But tools and skills to share your code can be tricky to learn. In this hands-on tutorial, you’ll learn how to turn your code into an installable pure Python module ( a file containing Python code that defines functions, classes, and variables), that can be shared with others. We will provide pre-built code and module examples for each step of the tutorial to make it more beginner-friendly. However, to get the most out of this tutorial, you should be familiar with writing Python code, writing and using functions and you should understand the concept of Python environments. You should also have Python and Hatch installed on your computer prior to attending. If you are newer to environments and don’t have a preferred tool, then we recommend that you use conda. However, any environment tool that you prefer works well.
Tutorial Outline - 4 hour session
In each of the hour segments below, you can either opt to use the pre-built materials and code to follow along. Or, if you are more comfortable with the steps, you can bring your own code to the workshop and focus on learning Hatch, documenting your code and learning how to make it installable.
Hour One -The structure of an installable module
**0-15 minutes: ** Here we will get to know each other. I’ll also briefly introduce pyOpenSci and the work that we are doing in open science education and training space.
15-30 minutes Interactive discussion: Here, we’ll discuss why shareable code is important. And we’ll explore some best practices for making code easier to work with. I’ll also introduce Hatch as a workflow tool that streamlines tasks.
30-60 minutes hands-on: You will take an existing script and turn it into an installable module. You are welcome to use the provided scripts for this. If you are more comfortable with Python, then you can also bring your own script with you and work on it during the workshop.
Key Takeaways: After this hour you will have an understanding of:
- the purpose of the init.py file and
- how workflow tools such as Hatch can be useful when making code installable.
Hour Two - Everything you need to know about the pyproject.toml file & project metadata.
0-15 Interactive Discussion: Here you’ll learn about the pyproject.toml and how it’s used to document dependencies, and metadata for your project.
15-30: Short Break. Stretch your legs, get a drink.
30-60 Hands-on: In the hands-on part of this hour, you will modify your pyproject.toml file with required dependencies needed to run your code. You will also learn how to install your code in interactive or development mode using both pip and Hatch. Interactive mode will allow you to dynamically update your code and test it locally without reinstalling it. Finally, you will take your shiny new Python module for a test drive in your favorite Python environment.
Hour Three - The power of metadata and instructions for you, your future self & your colleagues
0-15 Interactive discussion: In this part of the tutorial we’ll discuss the power of documentation when sharing code and also for you when you have to update things in the future. **
15-50 Hands-on:** Here you will create a README file that helps users of your module understand how to install it and how to get started using it. You will also add docstrings to your code. See how docstrings are useful as “hints” when coding real time. Optional: if you are speedy, you can also delve into typing your code on your own. However, we won’t directly cover typing in this tutorial.
50-60: Break
Hour Four - Publishing and Sharing your code
0-15 minutes Interactive discussion: Here we will discuss what it means to “publish” code. We will also discuss other important elements such as license files and codes of conduct if you intend to turn your code into a published package.
15-45 minutes Hands-on: Publishing to PyPI vs. installing from Github. Those who’d like to follow along interactively can do so here. However, if your brain is tired, sit back and learn how to build your module into a package distribution using Hatch. And then we will give you all of the tools needed to publish to (test) PyPI.
45-60 minutes: wrap up, questions. Feedback.
To be successful in this tutorial you should:
- Be familiar with writing Python code,
- Be familiar with functions in Python
- Know how to import packages and functions in Python scripts.
Please arrive at the workshop with Hatch and Python already installed on your computer. You can follow the instructions here: https://github.com/pyOpenSci/code-to-module-workshop
I am the Executive Director and Founder of pyOpenSci - a non profit organization that is devoted to helping scientists tackle the world's greatest challenges by empowering them with the skills and tools needed to make their science more open and collaborative. We run an open peer review process for scientific Python software and also develop training resources around open science topics. We have been doing significant work in the Python ecosystem to bridge the technical understanding gap between the broader packaging community and what scientists need.
I've been teaching data-intensive topics for almost 20 years and am passionate about translating technical topics to beginners. I'm also a maintainer of the package stravalib. When i'm not working on all things Python, i'm outside on the trails, climbing mountains with my rescue pup or at the gym doing cross fit.
Isabel Zimmerman is a software engineer at Posit, PBC where she works primarily on building open-source Python tools for MLOps tasks. She also serves as an Editor at pyOpenSci, where she helps facilitate reviewing open scientific software in the Python ecosystem. Outside of computers, Isabel spends most of her time teaching her dogs new tricks or trying to learn how to sew.
