modules.asciidoc 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. [[module]]
  2. == Modules
  3. You have seen how you can reuse code in your program by defining functions once. What if you wanted
  4. to reuse a number of functions in other programs that you write? As you might have guessed, the
  5. answer is modules.
  6. There are various methods of writing modules, but the simplest way is to create a file with a `.py`
  7. extension that contains functions and variables.
  8. Another method is to write the modules in the native language in which the Python interpreter
  9. itself was written. For example, you can write modules in the http://docs.python.org/2/extending/[C
  10. programming language] and when compiled, they can be used from your Python code when using the
  11. standard Python interpreter.
  12. A module can be *imported* by another program to make use of its functionality. This is how we can
  13. use the Python standard library as well. First, we will see how to use the standard library
  14. modules.
  15. Example (save as `module_using_sys.py`):
  16. [source,python]
  17. --------------------------------------------------
  18. include::programs/module_using_sys.py[]
  19. --------------------------------------------------
  20. Output:
  21. --------------------------------------------------
  22. include::programs/module_using_sys.txt[]
  23. --------------------------------------------------
  24. .How It Works
  25. First, we *import* the `sys` module using the `import` statement. Basically, this translates to us
  26. telling Python that we want to use this module. The `sys` module contains functionality related to
  27. the Python interpreter and its environment i.e. the **sys**tem.
  28. When Python executes the `import sys` statement, it looks for the `sys` module. In this case, it is
  29. one of the built-in modules, and hence Python knows where to find it.
  30. If it was not a compiled module i.e. a module written in Python, then the Python interpreter will
  31. search for it in the directories listed in its `sys.path` variable. If the module is found, then
  32. the statements in the body of that module are run and the module is made *available* for you
  33. to use. Note that the initialization is done only the *first* time that we import a module.
  34. The `argv` variable in the `sys` module is accessed using the dotted notation i.e. `sys.argv`. It
  35. clearly indicates that this name is part of the `sys` module. Another advantage of this approach is
  36. that the name does not clash with any `argv` variable used in your program.
  37. The `sys.argv` variable is a *list* of strings (lists are explained in detail in a
  38. <<data_structures,later chapter>>. Specifically, the `sys.argv` contains the list of *command line
  39. arguments* i.e. the arguments passed to your program using the command line.
  40. If you are using an IDE to write and run these programs, look for a way to specify command line
  41. arguments to the program in the menus.
  42. Here, when we execute `python module_using_sys.py we are arguments`, we run the module
  43. `module_using_sys.py` with the `python` command and the other things that follow are arguments
  44. passed to the program. Python stores the command line arguments in the `sys.argv` variable for us
  45. to use.
  46. Remember, the name of the script running is always the first argument in the `sys.argv` list. So,
  47. in this case we will have `'module_using_sys.py'` as `sys.argv[0]`, `'we'` as `sys.argv[1]`,
  48. `'are'` as `sys.argv[2]` and `'arguments'` as `sys.argv[3]`. Notice that Python starts counting
  49. from 0 and not 1.
  50. The `sys.path` contains the list of directory names where modules are imported from. Observe that
  51. the first string in `sys.path` is empty - this empty string indicates that the current directory is
  52. also part of the `sys.path` which is same as the `PYTHONPATH` environment variable. This means that
  53. you can directly import modules located in the current directory. Otherwise, you will have to place
  54. your module in one of the directories listed in `sys.path`.
  55. Note that the current directory is the directory from which the program is launched. Run `import
  56. os; print os.getcwd()` to find out the current directory of your program.
  57. [[pyc]]
  58. === Byte-compiled .pyc files
  59. Importing a module is a relatively costly affair, so Python does some tricks to make it faster. One
  60. way is to create *byte-compiled* files with the extension `.pyc` which is an intermediate form that
  61. Python transforms the program into (remember the <<interpreted,introduction section>> on how Python
  62. works?). This `.pyc` file is useful when you import the module the next time from a different
  63. program - it will be much faster since a portion of the processing required in importing a module
  64. is already done. Also, these byte-compiled files are platform-independent.
  65. NOTE: These `.pyc` files are usually created in the same directory as the corresponding `.py`
  66. files. If Python does not have permission to write to files in that directory, then the `.pyc`
  67. files will _not_ be created.
  68. [[the_from_import_statement]]
  69. === The from ... import statement
  70. If you want to directly import the `argv` variable into your program (to avoid typing the `sys.`
  71. everytime for it), then you can use the `from sys import argv` statement.
  72. In general, you *should avoid* using this statement and use the `import` statement instead since
  73. your program will avoid name clashes and will be more readable.
  74. Example:
  75. [source,python]
  76. --------------------------------------------------
  77. from math import sqrt
  78. print "Square root of 16 is", sqrt(16)
  79. --------------------------------------------------
  80. [[module_name]]
  81. === A module's `__name__`
  82. Every module has a name and statements in a module can find out the name of their module. This is
  83. handy for the particular purpose of figuring out whether the module is being run standalone or
  84. being imported. As mentioned previously, when a module is imported for the first time, the code it
  85. contains gets executed. We can use this to make the module behave in different ways depending on
  86. whether it is being used by itself or being imported from another module. This can be achieved
  87. using the `__name__` attribute of the module.
  88. Example (save as `module_using_name.py`):
  89. [source,python]
  90. --------------------------------------------------
  91. include::programs/module_using_name.py[]
  92. --------------------------------------------------
  93. Output:
  94. --------------------------------------------------
  95. include::programs/module_using_name.txt[]
  96. --------------------------------------------------
  97. .How It Works
  98. Every Python module has its `__name__` defined. If this is `'__main__'`, that implies that the
  99. module is being run standalone by the user and we can take appropriate actions.
  100. === Making Your Own Modules
  101. Creating your own modules is easy, you've been doing it all along! This is because every Python
  102. program is also a module. You just have to make sure it has a `.py` extension. The following
  103. example should make it clear.
  104. Example (save as `mymodule.py`):
  105. [source,python]
  106. --------------------------------------------------
  107. include::programs/mymodule.py[]
  108. --------------------------------------------------
  109. The above was a sample *module*. As you can see, there is nothing particularly special about it
  110. compared to our usual Python program. We will next see how to use this module in our other Python
  111. programs.
  112. Remember that the module should be placed either in the same directory as the program from which we
  113. import it, or in one of the directories listed in `sys.path`.
  114. Another module (save as `mymodule_demo.py`):
  115. [source,python]
  116. --------------------------------------------------
  117. include::programs/mymodule_demo.py[]
  118. --------------------------------------------------
  119. Output:
  120. --------------------------------------------------
  121. include::programs/mymodule_demo.txt[]
  122. --------------------------------------------------
  123. .How It Works
  124. Notice that we use the same dotted notation to access members of the module. Python makes good
  125. reuse of the same notation to give the distinctive 'Pythonic' feel to it so that we don't have to
  126. keep learning new ways to do things.
  127. Here is a version utilising the `from..import` syntax (save as `mymodule_demo2.py`):
  128. [source,python]
  129. --------------------------------------------------
  130. include::programs/mymodule_demo2.py[]
  131. --------------------------------------------------
  132. The output of `mymodule_demo2.py` is same as the output of `mymodule_demo.py`.
  133. Notice that if there was already a `__version__` name declared in the module that imports mymodule,
  134. there would be a clash. This is also likely because it is common practice for each module to
  135. declare it's version number using this name. Hence, it is always recommended to prefer the `import`
  136. statement even though it might make your program a little longer.
  137. You could also use:
  138. [source,python]
  139. --------------------------------------------------
  140. from mymodule import *
  141. --------------------------------------------------
  142. This will import all public names such as `say_hi` but would not import `__version__` because it
  143. starts with double underscores.
  144. WARNING: Remember that you should avoid using import-star, i.e. `from mymodule import *`.
  145. .Zen of Python
  146. **************************************************
  147. One of Python's guiding principles is that "Explicit is better than Implicit". Run `import this` in
  148. Python to learn more.
  149. **************************************************
  150. [[the_dir_function]]
  151. === The +dir+ function
  152. You can use the built-in `dir` function to list the identifiers that an object defines. For
  153. example, for a module, the identifiers include the functions, classes and variables defined in that
  154. module.
  155. When you supply a module name to the`dir()` function, it returns the list of the names defined in
  156. that module. When no argument is applied to it, it returns the list of names defined in the current
  157. module.
  158. Example:
  159. --------------------------------------------------
  160. $ python
  161. >>> import sys
  162. # get names of attributes in sys module
  163. >>> dir(sys)
  164. ['__displayhook__', '__doc__',
  165. 'argv', 'builtin_module_names',
  166. 'version', 'version_info']
  167. # only few entries shown here
  168. # get names of attributes for current module
  169. >>> dir()
  170. ['__builtins__', '__doc__',
  171. '__name__', '__package__']
  172. # create a new variable 'a'
  173. >>> a = 5
  174. >>> dir()
  175. ['__builtins__', '__doc__', '__name__', '__package__', 'a']
  176. # delete/remove a name
  177. >>> del a
  178. >>> dir()
  179. ['__builtins__', '__doc__', '__name__', '__package__']
  180. --------------------------------------------------
  181. .How It Works
  182. First, we see the usage of `dir` on the imported `sys` module. We can see the huge list of
  183. attributes that it contains.
  184. Next, we use the `dir` function without passing parameters to it. By default, it returns the list
  185. of attributes for the current module. Notice that the list of imported modules is also part of this
  186. list.
  187. In order to observe the `dir` in action, we define a new variable `a` and assign it a value and
  188. then check `dir` and we observe that there is an additional value in the list of the same name. We
  189. remove the variable/attribute of the current module using the `del` statement and the change is
  190. reflected again in the output of the `dir` function.
  191. A note on `del` - this statement is used to *delete* a variable/name and after the statement has
  192. run, in this case `del a`, you can no longer access the variable `a` - it is as if it never existed
  193. before at all.
  194. Note that the `dir()` function works on *any* object. For example, run `dir(str)` for the
  195. attributes of the `str` (string) class.
  196. There is also a http://docs.python.org/2/library/functions.html#vars[`vars()`] function which can
  197. potentially give you the attributes and their values, but it will not work for all cases.
  198. [[packages]]
  199. === Packages
  200. By now, you must have started observing the hierarchy of organizing your programs. Variables
  201. usually go inside functions. Functions and global variables usually go inside modules. What if you
  202. wanted to organize modules? That's where packages come into the picture.
  203. Packages are just folders of modules with a special `__init__.py` file that indicates to Python
  204. that this folder is special because it contains Python modules.
  205. Let's say you want to create a package called 'world' with subpackages 'asia', 'africa', etc. and
  206. these subpackages in turn contain modules like 'india', 'madagascar', etc.
  207. This is how you would structure the folders:
  208. --------------------------------------------------
  209. - <some folder present in the sys.path>/
  210. - world/
  211. - __init__.py
  212. - asia/
  213. - __init__.py
  214. - india/
  215. - __init__.py
  216. - foo.py
  217. - africa/
  218. - __init__.py
  219. - madagascar/
  220. - __init__.py
  221. - bar.py
  222. --------------------------------------------------
  223. Packages are just a convenience to hierarchically organize modules. You will see many instances of
  224. this in the <<stdlib,standard library>>.
  225. === Summary
  226. Just like functions are reusable parts of programs, modules are reusable programs. Packages are
  227. another hierarchy to organize modules. The standard library that comes with Python is an example of
  228. such a set of packages and modules.
  229. We have seen how to use these modules and create our own modules.
  230. Next, we will learn about some interesting concepts called data structures.