Moving Up to the Module

00:00 In this lesson, we will be talking about internal modules. So in this table, we are on the second row and the example will be example number three,

00:11 _utils.py. In the previous examples, we had internal constants, variables, and functions. They were internal to a module. Remember how this table works?

00:23 The highest level is the package. A package can have several modules. A module can have several objects such as constants, variables, functions, and classes.

00:33 So, so far we’ve seen the constants, variables, and the functions that were internal to a module. Now we are seeing a module _utils that is internal to the package.

00:45 So we are moving up one level if you like. Just keep that in mind when we look at the example. So if we switch back to your favorite code editor,

00:57 this is where we left off. So create another module called _ utils.py.

01:09 In this module, we’ll have two functions: one public function and a non-public function. The public function is a function that allows you to save text to a file.

01:21 And the idea of this non-public module is that within your package, because remember it is internal to the package, but it is non-public for users of the package so outside of the package.

01:34 So whereas you had helper functions before in classes or modules, you can actually have helper modules if you like. So a module that holds all sorts of functions that you would then be using elsewhere in your code.

01:49 So one of the things I usually have set aside is a function that saves text to file. So let’s create that. We’ve created our _utils.py module.

02:01 I’m just going to put that in here just so you remember that this is a non-public module.

02:09 Let’s create our first function, which is a public function so no underscores here. It’s called save_text_to_file. And we are going to take, well, text as an input of course, because we want to save it to a file.

02:24 And then we open up a text file, which is called saved_text with a fixed name just to keep it simple for this example. I’m going to open that as a writable file clearly because I want to write to it.

02:39 And that will be captured in an object call, output_file.

02:45 And then all I do is output_file.write( ) and then I’m going to write the text to this file.

02:53 This just to give a bit more space. So that is our public function. Let’s now create an internal function and that will therefore start with an underscore.

03:04 And I’m just going to call it some_internal_function.

03:09 Doesn’t really matter what that is, this is just to show you that you can have a public and a non-public function in a non-public module. So this is an interesting example of again, how to see what is internal to what and non-public to what.

03:24 So we have a non-public module starting with an underscore, _utils. That means it’s internal to the package. Because the next level up from module is package, and it is non-public outside of the package.

03:40 Then we have a public function, saved to text, so that is public, that can be used anywhere. And then we have an internal function, some_internal_function that is internal to the _utils module.

03:53 So it can be used freely within the utils module, but it shouldn’t be used outside of the utils or the _utils module.

04:03 So what does that mean for our main file? Let’s move to main.py and create a bit more space. So what can we and can we not do here? Well, we are still within our package and the utils function is internal to the package so I can, from utils import, well from utils, I could import all the functions that don’t start with an underscore, all the ones that aren’t internal.

04:33 So I could import save_text_to_file.

04:37 So that is fine. What I shouldn’t do is from utils import the non-public function, which is some_internal_function.

04:51 Now what I can’t show you here is that you shouldn’t be using _utils outside of the package because I am within the package.

04:59 In the next lesson, you’ll create a package which will then finish off our single leading underscore examples. See you then.