From f05bad383937c5601823439b50851d94d1526739 Mon Sep 17 00:00:00 2001 From: Estevan Pequeno Date: Tue, 3 Jul 2012 21:08:42 -0500 Subject: [PATCH 1/4] module naming --- docs/writing/structure.rst | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 6765f1848..61d83ab14 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -75,9 +75,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 `_ + 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 From fcefab992cdf699a9c84e9aa56c0c1ed609f01e6 Mon Sep 17 00:00:00 2001 From: Estevan Pequeno Date: Tue, 3 Jul 2012 21:24:08 -0500 Subject: [PATCH 2/4] minor editing --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 61d83ab14..0d2989b3e 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -289,7 +289,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 From 167d566650bcb2ca5156d7af2b69f7858bda3c80 Mon Sep 17 00:00:00 2001 From: Estevan Pequeno Date: Tue, 3 Jul 2012 22:19:31 -0500 Subject: [PATCH 3/4] add stub --- docs/writing/structure.rst | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 0d2989b3e..b1cc5de23 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -1,9 +1,22 @@ Structuring Your Project ======================== -Structuring your project properly is extremely important. +When we say 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 the actual files and folders that +comprise your project as well as the way dependencies are handled within +the code itself. + +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. -.. todo:: Fill in "Structuring Your Project" stub Structure is Key ---------------- From 28d211f6f52fe26332536761d669dae4eb704fdc Mon Sep 17 00:00:00 2001 From: Estevan Pequeno Date: Tue, 3 Jul 2012 22:36:07 -0500 Subject: [PATCH 4/4] edit stub --- docs/writing/structure.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index b1cc5de23..ee328ee92 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -1,21 +1,22 @@ Structuring Your Project ======================== -When we say structure we mean the decisions you make concerning +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 the actual files and folders that -comprise your project as well as the way dependencies are handled within -the code itself. +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. -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. +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. +project. We then discuss various perspectives on how to build code which +can be extended and tested reliably. Structure is Key