1. Writing Your First Package
Up to this point, we've covered some important topics for Software Engineering in Python. Now we're going to get our hands dirty and put these ideas into practice by building a python package from the ground up.
We've seen how useful packages can be for easily importing functionality into a workflow, but what is under the covers? How do we make one ourselves?
2. Package structure
A minimal python package consists of 2 elements: a directory and a python file. You can see the basic structure here.
The name of the directory will be the name of the package, but how should you name it? We can turn to PEP 8 again for some guidance.
3. Package structure
To paraphrase, PEP 8 states that packages should have short, all-lowercase names. The use of underscores in a package name is discouraged, but you can and should use them if it improves readability.
Outside of this, you have the freedom to brand as you'd like. I'd suggest picking a name that conveys the functionality of the package.
4. Package structure
The file in our newly branded directory doesn't have any flexibility in naming. We must name it underscore underscore init underscore underscore dot py. This file lets python know that the directory we created is a package.
And that's it! With this structure we've created a package that we can import just like we would import numpy or any other package.
Note that as of Python version 3-point-3 any directory can be imported as if it were a package without error even if it doesn't follow this structure. Earlier versions of Python would throw an error if you tried to import an improperly formatted package. Even though a directory might import without error, you will run into issues if you do not follow this structure.
5. Importing a local package
So how do we import our package? Before we look at some code let's establish where our script is relative to our new package. We'll be working in the my_script dot py file that's in the same location as our package directory.
6. Importing a local package
With all the setup we've done so far, importing the package is a breeze. At the top of our script, we can use import my_package.
Just for an added bonus, let's check out what happens if we try to call help on our package.
We get some minimal information with python letting us know that it is indeed a package and additionally we see the location of our __init__ dot py file.
As we previously covered, it's up to the developer to add in useful documentation to be printed whenever a user calls help. Later we will be going over how we can add this documentation as well as implementing some functionality to make our package more useful.
7. Let's Practice
We just covered how to make a python package skeleton. This is an important concept that will serve as a foundation for all the useful packages you'll be writing in the future.
Before that, let's review with some exercises.