Learning to Program With Python

Learning to ProgramWith Python Advanced Class 7

Topics • modules and the import statement • the standard library

What is a module? • It’s a .py file. • There’s nothing else to it. A python file and its contents are referred to as a python module.

The import statement • If you have a module named stuff.py, and another module named main.py, and you want to use the contents of stuff.py inside main.py, then you simply write this at the top of main.py: import stuff • That will give you access to all the variables, functions, and classes defined in stuff.py.

The import statement • In order for ‘import stuff’ to work, both files will have to be stored in the same place on your computer--- inside the same directory. If you place one in “My documents” and another in “My pictures”, they won’t be able to see each other, and you’ll get an ImportError. • ImportError is what you get whenever the import statement fails.

ImportError >>> import doesnt_exist >>> Traceback (most recent call last): File "<pyshell#0>", line 1, in <module> import doesnt_exist ImportError: No module named 'doesnt_exist'

Placement of the import statement • The import statement can go anywhere….even inside an if statement, if you only want to import something under certain circumstances. • But in general, good practice is to always place all your import statements at the top of your file, before any other code.

Importing multiple modules If you wanted to import stuff.py AND morestuff.py, you could write either of the following. They are identical. import stuff, morestuff OR: import stuff import morestuff

What happens when a module is imported? • All the code in that file is run, just as if it were being executed on its own. • After which all the variables, functions, and classes in that file become defined, and can now be used.

Using code from imported modules • Let’s imagine we had defined the function calculateOdds(percent, rate) inside of our module stuff.py, which we’ve now imported into main.py. • To use it in main.py, we write: stuff.calculateOdds(.4, 22)

Using code from imported modules • To access any functions or variables defined inside an imported module, you must write: newClassInstance = importedModuleName.className() or… importedModuleName.variableName or… importedModuleName.functionName(arguments)

if __name__ == “__main__” • This is something you’ll see often in python: if __name__ == “__main__”: #do something

What that means • __name__ is a variable defined automatically in all python scripts at the top level, meaning it can be accessed anywhere, in any scope. • If the module is being executed on its own, __name__ is set to the string “__main__”. • If the module is being imported, __name__ is set to the string “__nameOfModule__”.

__name__ • So when we imported stuff.py to main.py, if stuff.py had this line: print(__name__) …then in that case, it would print “__stuff__”, which is the name of the module. • If, on the other hand, we ran stuff.py on its own, that line would print “__main__”.

__name__ • So when you see « if __name__ == “__main__”: », what it’s doing is saying “Only execute the following code if this module is being run on its own, and not imported.” • That way, a module can be standalone, OR be useful as an import. This allows you to control how your module behaves in different circumstances.

from [module] import [something] • This is another way of importing things which you’ll often see, although people are often unsure of how this is any different from the other syntax. • They are NOT the same.

How are they different? • If stuff.py contains the single line ‘x = 5’, and I run ‘import stuff’ in our main.py, then to access x I have to type stuff.x. • Simply typing ‘x’ after the import will result in a NameError, because x is not defined. Only stuff.x is defined.

How are they different? • However, assuming again that stuff.py contains the line ‘x = 5’, and in main.py I write ‘from stuff import x’, then I can simply type x to access x. There is no stuff.x, because we didn’t import stuff. We only imported x. • If stuff.py had ‘x = 5’ and ‘y = 7’ and ‘z = 10’, you could import however many you wanted by separating the items with commas: from stuff import x, y, z

from [module] import * • The * character means ‘everything’. So this will take every single variable, function, and class in [module], and import it to your code, all directly. This is BAD. • It’s bad because if you have x = 20 in your code, and you import x from somewhere else without importing the module name to keep it separate, it will OVERWRITE your x, or else you will overwrite the imported x, depending which comes first.

( import stuff ) vs.( from stuff import * ) • You should essentially always use the first method. • That way, all the variables are stuff.variableName, and all the functions are stuff.functionName(), and the classes are stuff.className, and there is absolutely no possibility of any of them conflicting with anything in your code or any other imported module. • The second method is dangerous and discouraged.

Clarity of code with importing • It’s also bad to use ‘from [module] import *’ because if someone else is reading your code, they wouldn’t know that a variable, function, or class came from a particular module. They would have no idea where it was defined without searching around. • When you simply ‘import stuff’ and make everything stuff.whatever, then it’s crystal clear where it came from.

What if the module name is long? • Say the full module name is “IndustrialLightsAndMagic.SpecialEffects.DigitalLights.Ambient”…….obviously you don’t want to write that every time you call a function defined in that module. • So you think, I know, I’ll use ‘from IndustrialLightsAndMagic.SpecialEffects.DigitalLights.Ambient import *’ and that way I’ll never have to type it!

import [module] as [name] • While that would work, it’s still a bad idea, for the aforementioned reasons. The more intelligent solution is to give the module a shorter local name, like this: import IndustrialLightsAndMagic.etc.etcas ambient

import [module] as [name] • You’ve still imported the module, just the same as if you had only written ‘import [module]’, but you gave it a different name. Whatever name you want! And then you use it the same way. import IndustrialLightsAndMagic.etc.etcas ambient ambient.generateAmbiance() ambient.activateFloodLight()

import [module] as [name] • This way, you’ve shortened what you have to write every time, without reducing the clarity of your code, and without creating the danger of naming conflicts. • This is a great way to do things! But make sure the names you choose are clear and informative, or at least are an acronym of the full name or something.

import [module] as [name] • This would be somewhat questionable: import IndustrialLightsAndMagic.etc.etc as z • This would be good: import IndustrialLightsAndMagic.etc.etc as ILM_ambient

Docstrings • I’ve been saving this for awhile, until just this moment. • Python has documentation built-in as part of the language. • Remember how we can make single-line comments with the hash tag in python: #This is a comment

Docstrings • Indeed, comments made with the hash tag are simply that. There’s nothing more to them. • But remember how we can also make multi-line comments by triple quoting? “ “ “ This is a multi-line comment “ “ “

Docstrings • Normally, there’s nothing more to them either. They are perfectly acceptable, normal comments with no special qualities. • However, if a triple-quoted string is the first thing in a module, or the first thing in a function definition, or the first thing in a class definition, then it becomes the docstring for that module, function, or class.

Docstrings • So if we start our module off with this: “ “ “ This is stuff.py, which contains all sorts of stuff. “ “ “ … and then we import stuff, we can print stuff.__doc__ to access that comment. It’s the documentation for the module.

Docstrings • If we write this function: def add(x, y): “ “ “ Adds two numbers and returns the result. “ “ “ return x + y …and then print add.__doc__, again we can access that comment as a string. It’s the documentation for the function!

Docstrings • And, in the exact same fashion, if we write: class Nothing: “ “ “ This class doesn’t do anything. “ “ “ pass ….and then print Nothing.__doc__, we can access that comment as a string. It’s the built-in description and explanation of the class!

Docstrings • So you could write a docstring for a module, a docstring for every class in that module, and another docstring for every method belonging to each of those classes. • When you use the built-in help() function in the interpreter, all it does it fetch the docstrings belonging to whatever you call it on.

Always write docstrings! • It is standard industry practice to always write docstrings. They explain what your classes, methods, and modules do. • This way, all your code comes with a built-in explanation of what it’s for. • Normal comments are good too, but docstrings allow for automation– since they’re always in the same place, a program can find them and assemble documentation that way automatically. Which is what the help() function does!

The standard library • The standard library is a set of modules that come with python by default. They provide a massive amount of built-in functionality. • There are dozens of modules in the standard library. We’re going to take a look at a bunch of them over the course of the rest of these slides and the next set.

The random module • The random module is just what it sounds like– it provides all sorts of functionality relating to randomness. • It can provide random numbers, randomly choose an element from a list, or shuffle the order of a list.

The random module • To gain access to the random module, we of course write: import random • After which, we can use any of its many functions. http://docs.python.org/3.3/library/random.html

The random module • One useful function is the randint(a, b) function, which returns a random integer between a and b. >>> import random >>> random.randint(3, 400) 17 >>> random.randint(3, 400) 286

The random module • Then there’s the choice(seq) function, which returns an element randomly selected from the sequence it is given as an argument. >>> import random >>> random.choice( [ 4, 5, 6 ] ) 5 >>> random.choice(“chimaera”) ‘e’

The random module • There’s the shuffle method, which speaks for itself and returns nothing. >>> import random >>> x = [1, 2, 3, 4, 5, 6] >>> random.shuffle(x) >>> x [4, 2, 6, 1, 5, 3]

The math module • This one is super important. It provides a ton of mathematical functionality. • First of all, it has two variables defined, e and pi. >>> import math >>> math.pi 3.141592653589793 >>> math.e 2.718281828459045

The math module • Here’s a link to all the stuff in the math module, by the way: http://docs.python.org/3.3/library/math.html

The math module Here’s some more stuff from the math module: >>> import math >>> math.cos(30) #cosine >>> math.atan(3) #arctangent

The math module • Here’s some more stuff from the math module: >>> math.degrees(3) #convert radians to degrees >>> math.radians(36) #convert degrees to radians >>> math.log(3, 5) #logarithm of 3 to base 5

The os module • This is for interacting with the operating system. Along with math, random, and sys (which we’ll talk about next), it’s one of the most commonly used modules. • It works the same on all major operating systems– using it adds some portability to your code. The same os API calls are used on Windows, Mac, or Linux to accomplish the same things.

The os module: a brief introduction • os.getcwd() ---> returns the current working directory as a string. • os.listdir() ---> returns a list of strings describing all the files and directories inside the current working directory. • os.chdir() ---> changes the current working directory. • os.mkdir(dirName) ---> creates a new directory/folder.

The sys module • To rehash, the os module allows you to navigate the filesystem, exploring and modifying directories, and to communicate with the computer and with other programs, even starting and stopping other programs. • The sys module, on the other hand, allows you to find out all sorts of information about the system the program is running on– how the system is environment is configured, and what kind of environment it is to begin with.

The sys module • Additionally, the sys module allows you to gain information about the shell from which the python program might be running. • If a program is started at the command line with some command line arguments, the sys module is the most basic option for retrieving those arguments.

sys.args • Once sys has been imported, you can access sys.args, which is a list containing all the command line arguments that were used to start the program. $ python alarmclock 3 hours • So here we’re imagining we’re starting a python program named ‘alarmclock.py’ with the arguments ‘3’ and ‘am’. And we could access those from within the program with sys.args.

Next class: • Going to look at a bunch of other modules! Some of but probably not all of the following… • re (regular expressions), pretty print, string, copy, decimal, collections, datetime, pickle, csv, hashlib, zipfile, time, urllib, glob.

Learning to Program With Python