kennethreitz/python-guide
1
0
Fork 0
mirror of https://github.com/kennethreitz/python-guide.git synced 2026-06-05 23:00:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #178 from epequeno/modulename

Browse Source 
Add stub, naming restrictions to structure
This commit is contained in:
Kenneth Reitz
2012-07-03 23:33:13 -07:00
parent d78b1a3e99 28d211f6f5
commit 4461f0ce8e
1 changed files with 33 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/writing/structure.rst
+33 -6
View File
@@ -1,9 +1,23 @@
Structuring Your Project
========================
Structuring your project properly is extremely important.
By "structure" we mean the decisions you make concerning
how your project best meets its objective. We need to consider how to
best leverage Python's features to create clean, effective code.
In practical terms, "structure" means making clean code whose logic and
dependencies are clear as well as how the files and folders are organized
in the filesystem.
Which functions should go into which modules? How does data flow through
the project? What features and functions can be grouped together and
isolated? By answering questions like these you can begin to plan, in
a broad sense, what your finished product will look like.
In this section we take a closer look at Python's module and import
systems as they are the central element to enforcing structure in your
project. We then discuss various perspectives on how to build code which
can be extended and tested reliably.
.. todo:: Fill in "Structuring Your Project" stub
Structure is Key
----------------
@@ -75,9 +89,22 @@ As soon as you use `import` statements you use modules. These can be either buil
modules such as `os` and `sys`, third-party modules you have installed in your
environment, or your project's internal modules.
Nothing special is required for a Python file to be a module, but the import
mechanism needs to be understood in order to use this concept properly and avoid
some issues.
To keep in line with the style guide, keep module names short, lowercase, and
be sure to avoid using special symbols like the dot (.) or question mark (?).
So a file name like `my.spam.py` is one you should try to avoid! Naming this way
will interfere with the way python looks for modules.
In this example python expects to find a "spam.py" file in a folder named "my"
which is not the case. There is an
`example <http://docs.python.org/tutorial/modules.html#packages>`_
of how the dot should be used available in the python docs.
If you'd like you could name it as `my_spam.py` but even our friend the
underscore should not be seen often in module names.
Aside for some naming restrictions, nothing special is required for a Python file
to be a module, but the import mechanism needs to be understood in order to use
this concept properly and avoid some issues.
Concretely, the `import modu` statement will look for the proper file, which is
`modu.py` in the same directory as the caller if it exists. If it is not
@@ -276,7 +303,7 @@ clearer and thus preferred.
# Do something
# bar() is decorated
Using this mechanism is useful for separating concerns and avoiding
This mechanism is useful for separating concerns and avoiding
external un-related logic 'polluting' the core logic of the function
or method. A good example of a piece of functionality that is better handled
with decoration is memorization or caching: you want to store the results of an