From f05bad383937c5601823439b50851d94d1526739 Mon Sep 17 00:00:00 2001 From: Estevan Pequeno Date: Tue, 3 Jul 2012 21:08:42 -0500 Subject: [PATCH] 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 6765f18..61d83ab 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 -- 1.8.0.2