Objectives and Setup#

Python is a powerful programing language for getting things done, however, its very permissive acceptance of datum types to arguments and from data structures makes correctly programming around- and validating those data nebulous. This workshop is about annotating Python code to include information about data types for developers, users, and Integrated development Environments (IDEs) as well as validation of said data. You’ll learn about the built in Python type hints for non-enforceable annotation, wrapping data structures into programmable classes called a dataclass, manual validation of said data, and finally leveraging a powerful external library called pydantic to automatically validate arbitrarily complex data structures through native type hints.

In this workshop we will be using Jupyter notebooks, which you will be able to set up once you have installed Anaconda, however, this code is meant to be dynamically interacted with and run. So, feel free to follow along in your own editor or IDE.

Prerequisite Skills and Installs#

Before starting this workshop, you should be familiar with object oriented programming in Python. You can complete MolSSI’s Object Oriented Programming in Python workshop to get hands-on experience with object oriented programming.

You should also already have Python installed (or know how to), as well as install packages into Python. Ideally you should set up a separate conda environment or other environment (e.g. wheel). If you need a primer or refresher on this, please see the Setup page for MolSSI’s Best Practices Workshop.

You will need the following packages installed to run the material. We provide a conda environment file in the Lesson Materials (see below), or you can install the packages yourself through conda/mamba or pip

  • pydantic >=2.0

  • numpy

  • jupyter (if using a Jupyter Notebook. This lesson can be done fully with terminal and a text editor/IDE if you want.)

Obtain lesson materials#

  1. Download the files needed for these lessons here.

  2. Create a folder called types-and-pydantic on your Desktop.

  3. Move the downloaded materials to the new folder.

  4. Unzip the file.

Using the Lesson Materials: Code#

This is meant to be a dynamic, interactive workshop where you will be building, updating, and executing code in real time. Each chapter covers certain topics which are expanded and built upon in the next chapter. You will start with the molecule.py (which is a copy of the 00_base_molecule.py) in Type Hints in Python, and eventually construct the 01_typed_molecule.py file from the Lesson Materials, which you can use as reference and to see the end-goal. Dataclasses In Python will pick up from 01_typed_molecule.py as a base to eventually build 02_dataclass_molecule.py, and so on. We encourage you to use the included molecule.py to follow along with the chapters of this workshop and build up so you can see where we started.

Your files may look different depending on how you choose to approach the problems, and that’s okay! The lesson material files are meant to serve as guides, not the sole correct answers.

Using the Lesson Materials: Dependency Environment#

The Lesson Materials also include a Conda Environment file which all the dependencies ready to go. The file is the type_hints_pydantic_tut.yml file. You can run the following command to set up a Conda environment named “type-hint-pydantic” into a new clean environment.

If you have mamba installed:

mamba env create -n type-hint-pydantic -f type_hints_pydantic_tut.yml

If you only have conda installed

conda env create -n type-hint-pydantic -f type_hints_pydantic_tut.yml

Activate your environment

conda activate type-hint-pydantic

Start your Python editor of choice (the Jupyter notebook or your IDE) to complete the exercises.