Skip to content

Add stub, naming restrictions to structure #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kennethreitz merged 4 commits into from
Jul 4, 2012
Merged

Add stub, naming restrictions to structure #178

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f05bad3
module naming
epequeno Jul 4, 2012
fcefab9
minor editing
epequeno Jul 4, 2012
167d566
add stub
epequeno Jul 4, 2012
28d211f
edit stub
epequeno Jul 4, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 33 additions & 6 deletions docs/writing/structure.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
----------------
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 memoization or caching: you want to store the results of an
Expand Down