From BlenderWiki

Contents | Previous | Next

10 Module

Its pretty hard to miss the functionality of modules inside python. No module means no python program. Modules are the source of our technomagic its where everything resides.

10.1 Modules and Bytecode

We have met modules before, if you remember, modules are nothing more than text files which the python interpreter uses to produce python bytecode. The Python intepreter is nothing more than a program, an executable, like anything else and bytecode is the intermediate between source code (module) and machine code which is the only thing your computer can understand. Bytecode files come with the extension *.pyc and what makes them unique is that they are cross-platform (meaning they will run unchanged on many different OS), and they are actually faster to execute than modules. Actually to be even more precise they are the only thing that python executes.

Each time you run a module you basically run its bytecode file. Python checks its date/time signature: if no bytecode file exists, python compiles it and thus creates it; if it exists but has a different date/time signature (meaning it was created in a different date and time) then the module is recompiled, if it is of the same date and time module it is ignored and python uses the bytecode file. The big advantage here is that the only slow down you will experience with this method is when the module is compiled, each time you re-run it will start way faster because no compilation will be performed.

10.2 What is a module?

Sensible question my young apprentice. A module is a simple text file with a *.py extension. However a module can also be a python library

10.3 Python libraries

Python libraries are modules that can be imported using the import statement.

Let's put one of our previous examples in a file called <mylib.py>. How you name your module does not matter as long as you use the appropriate name to import it.

class x:
    def __init__(self):
        self.a = 10
        self.b = 20
 
    def add_together(self):
        print("a + b = ",(self.a + self.b))

in a file called <myapp.py> put the following

import mylib
 
y = mylib.x()
y.add_together()
 
n = x()
n.a = 20
n.add_together()

Yes its that easy. Importing is a bit like copy and paste, however as you can see it creates a scope for us, exactly like Objects. We did mylib.x(), if we wanted to just do a y = x() then our import should be like this.

from mylib import *

Again you see how much readable and simple python syntax is, isn't it a beauty. * here is use as "everything" (but is deprecated?!) you could as well have done this

or we could have imported only the x class

from mylib import x

you could even have done this

from mylib import x as myclass

here we import x from mylib but also rename it to mycalss so our instance creation will look like this

y = myclass()
y.add_together()
 
n = myclass()
n.a = 20
n.add_together()

So as you can see you can do some pretty nice tricks with import. One thing you need to remember is that you can import a module as many times inside your code as you want, but if it has been imported before, python does not import it again so that it does not waste time.

10.4 __main__

What import is doing is basically executing the module, so its like running the module in the first place. However that is not always desirable. Its possible to run a module in such that when is run from the python intepreter runs specific code and when import as module run different code. Here is how.

class x:
    def __init__(self):
        self.a = 10
        self.b = 20
 
    def add_together(self):
        print("a + b = ",(self.a + self.b))
 
if __name__ == "__main__":
    print("you run mylib module, which contains the class named x ")

the global variable here __name__ and its value string "__main__" informs us that the module is not imported but run from the python intepreter. If we did try to import mylib like we did in the previous section then the if would return False and the print would not execute.

This another technomagic spell for creating a module that can be both an application and a library at the same time, and behave differently when run as an app and differently when imported as a library.

10.5 Package

Putting every library feature in a single python module is perfectly possible, but from the first chapter I tried to teach you a single rule, a rule that I believe applies to every part of life and more in coding.

"DIVIDE AND CONQUER"

Or to put it more technically, divide your code into small manageable chunks that are easy to read, easy to understand and easy to relate with each other. So in this case we could divide a big library to several modules and import them. However there is a way to make all those modules group together with python packages.

A Python package is simple enough, it is basically a folder with __init__.py inside it and of course can contain many other modules too. That module works very similarly to __init__() function we used in the Object chapter and like __init__() __init__.py sets variables and even executes code that prepares our library for import. What that means differs from library to library and its completely up to the coder.

Packages are used by many addons that use several python modules, so its important to understand them.

You import the package like a module but not using the name __init__, instead __init__ takes the name of you folder, so if your folder is named mypackage,you will do a

import mypackage

by the way the above will import only __init__.py inside the mypackage folder. Again what name you choose for the folder is completely up to you. This WILL NOT import any other module inside your folder but you could make your __init__.py import other modules so each time you do the above you will also import other modules, some of them, all of them, again its up to you. Python never ties your hand, you are the boss.

10.6 Summary

• Modules are nothing more than text files
• Modules are compiled to python bytecode if they have not been compiled before
• Modules can be used as python libraries too
• We import modules with the import command
• We can check whether a module is run as a app or imported as a library with __name__
• Python packages can group multiple modules

10.7 End of PART I

YOU DID IT !!! you learned all the very basic of python language and you are ready to move to the next Part where we will finally start making some powerful addons. The knowledge you gained here is not useful just for making blender addons but for making any other python application. What we will learn from now on is only a variation of what we have learned so far. This is the source of your magic, before moving on make sure you understand and remember at least a substantial part.

So prepare your spell books, we go for a deep divide inside the magic of blender python....

Contents | Previous | Next