Creating modules and packages - Python Tutorial

- Modules, packages, libraries, oh my. We've been using them throughout the course with the import statement. But what are these things actually? And what's going on under the hood? Okay, let's get this out of the way right up front. There's no real formal definition of a library in python. It's more of a general computer science word. It just means imported files. Code that you're referencing that lives somewhere else. When people say Python libraries, they could either be talking about a module or a package, but usually they're talking about a package. So with that in mind, we're going to focus on modules and packages. Let's go to the code. A module is literally just a Python file. And here I've created a file or a module called primes.py and it has two functions in it. IsPrime, which takes in a number and returns whether or not that number is prime. And listPrimes, which returns a list of primes up to that number. I made a new Python file called use module, and it's currently blank. And I'm going to import primes. Then I'm going to print primes.isPrime. So here we're importing our primes module and using the isPrime function to decide whether or not five is prime. Python use module, and it looks like five is prime. I can also rewrite my import statement to import an individual function instead of the whole primes module. So from primes, import listPrimes. We're going to print listPrimes 100. And now I can call that function directly other than saying primes.listPrimes. So that lists all the prime numbers up to 100. So primes is a module. Then what's a package? Well, a package is simply a collection of modules. It's a collection of related Python files all bundled up into a single package. And here I've created a simple package called numbers. And this contains two modules. Factors, which contains a single function called getFactors. Just returns a list of all the factors of the number you pass in. And then primes, which is the same module that we used before, but inside this numbers package. There's also a very important file called init.py. If you look at it, it's completely blank. But it's required to tell Python, "Hey, this is a package, "not just a random collection of Python files in a folder." Note the init.py like the constructor or the initialization function of class has two dashes before and after the init. So when this init.py file is in this directory, it allows us to do imports like this. And I'm going to go to usepackage.py and do from numbers.factors import getFactors. And then I can print getFactors of 100. So numbers is the package, factors is the module, and I'm importing the function getFactors. Python usePackage.py, there you go. All the factors of 100. Now watch what happens when I delete the init.py file. Get out of there. Okay. Let's run this again. Uh-oh, module not found error. And it literally says numbers is not a package. So now it's just some random directory. So it's very important to have that init.py file there. So I'm going to add that init.py file back. Underscore underscore init underscore underscore dot py. Just add that back before I forget. So like I said before, the modules in these packages are generally closely related in functionality, so it can be useful to let them reference each other. Let's take this primes module here, and I can rewrite this isPrime function to use the getFactors function by importing the factors module from numbers.factors import getFactors. So I'm just going to return the length of getFactors of that number equals two. So we can take advantage of the fact that prime numbers have exactly two factors. And one last thing I want to show you is a built-in Python variable called name. Now, I'm going to go to the module primes.py. So this isn't in the package but the module. And I'm going to add this line. Print F primes.py module name is underscore underscore name underscore underscore. And now if I run primes.py directly from the command line, see what happens. Python, let me clear this. Primes.py. So I'm not running useModule, I'm running primes.py directly. And you see primes.py module name is underscore underscore main. Main is the default module name for the sort of main piece of code that you're running directly. Now let's go to use module.py, and you can see that it imports the primes module at the top. And when that module gets imported, in this import primes line, Python will actually run through and execute all of the code in this module. So when we run useModule.py, the name of that module will print out. Python useModule.py. And you can see that the module name is now primes. It's not main, it's primes. So this is the module name, and if I run it directly it's main. And we can see this at work in packages too. So if I go to my numbers package. And let's go to the init.py file. So often this file is blank, but we can still add code to it. For instance, name in init.py is underscore underscore name. There we go. And in factors.py I'm going to add this. Print name in factors.py is name. Now let's run usePackage.py. Python usePackage.py. So you can see that in init.py we get the package name. So this is the package file. And in factors.py we get numbers.factors. That's the module within the package. One common pattern in Python when writing modules and packages is to take advantage of this underscore underscore name variable by creating code that will only be run if your module is called directly, versus being imported. So, for instance, let's go back to the primes module. And note that this is the module, not the package. We can add some helper text if our users get confused by doing this. If name is equal to the string main, with two underscores, print this is a module, please import using new line import primes. Now you can see, if I run primes.py directly, we get some nice helper texts there. However, if I run useModule.py, that doesn't print out. By using what you've learned in this chapter, command line arguments, documentation, help text, modules and package organization, you can create code that's not usable just by you, but accessible to others. Whether those people are in your organization or across the globe. They can import it, use it, modify it, share it. And who knows, I might use one of your packages someday.