[GRASS-SVN] r46363 - grass/branches/develbranch_6

svn_grass at osgeo.org svn_grass at osgeo.org
Sun May 22 09:18:47 EDT 2011


Author: martinl
Date: 2011-05-22 06:18:47 -0700 (Sun, 22 May 2011)
New Revision: 46363

Modified:
   grass/branches/develbranch_6/SUBMITTING_PYTHON
Log:
sync SUBMITTING_PYTHON with trunk


Modified: grass/branches/develbranch_6/SUBMITTING_PYTHON
===================================================================
--- grass/branches/develbranch_6/SUBMITTING_PYTHON	2011-05-22 13:11:18 UTC (rev 46362)
+++ grass/branches/develbranch_6/SUBMITTING_PYTHON	2011-05-22 13:18:47 UTC (rev 46363)
@@ -1,114 +1,203 @@
-$Date$
-
 NOTE: Please improve this list!
 
-Dear (new) GRASS Developer,
+Dear (new) GRASS developer,
 
-When submitting Python code to GRASS SVN repository, please take
+when submitting Python code to GRASS SVN repository, please take
 care of following rules:
 
-[ see SUBMITTING for C hints ]
+[ see SUBMITTING      for C hints ]
+[ see SUBMITTING_DOCS for documentation ]
 [ see SUBMITTING_SCRIPTS for shell script hints ]
 [ see SUBMITTING_TCLTK for tcl and tk hints ]
-[ see SUBMITTING_DOCS for documentation ]
 
+0.  Indentation
 
-1.  Indentation
+    As Python determines nesting based upon indentation, it isn't just
+    a stylistic issue.
 
-    As Python determines nesting based upon indentation, it
-    isn't just a stylistic issue.
-
     Please use 4-space indentation (GNU Emacs python-mode default).
 
     See also "Python Style Guide" by Guido van Rossum
     http://www.python.org/doc/essays/styleguide.html
 
+1.  Instructions for the GRASS script parser can be found in the g.parser 
+    module's help page.
+    http://grass.osgeo.org/grass70/manuals/html70_user/g.parser.html
 
-2.  Add a header section to the script you submit and make sure you
+2.  Use the directory structure to place your script appropriately into
+    the source tree
+    	- scripts go into scripts/
+
+    Also add a Makefile and a <module>.html file into this directory.
+    See existing Python scripts for examples.
+
+3.  Add a header section to the script you submit and make sure you
     include the copyright. The purpose section is meant to contain a
     general over view of the code in the file to assist other
     programmers that will need to make changes to your code. For this
     purpose use Python Docstring, see
     http://epydoc.sourceforge.net/docstrings.html
 
-    Example (fictitious header for a script called r.myscript):
+    Example (fictitious header for a script called g.myscript):
 
 """
-MODULE:    r.myscript
+MODULE:    g.myscript
 
-AUTHOR(S): Me <email AT some domain>
+AUTHOR(S): John Doe <email AT some domain>
 
-PURPOSE:   Calculates univariate statistics from a GRASS raster map
+PURPOSE:   Describe your script here...
 
-COPYRIGHT: (C) 2007 by the GRASS Development Team
+COPYRIGHT: (C) 2007 John Doe, and by the GRASS Development Team
 
            This program is free software under the GNU General Public
            License (>=v2). Read the file COPYING that comes with GRASS
            for details.
 """
 
-   The copyright protects your rights according to GNU General Public
-   License (www.gnu.org).
+    The copyright protects your rights according to GNU General Public
+    License (www.gnu.org).
 
+    You can easily autogenerate the header and parameters from an existing
+    module using the --script flag. Example:
 
-3.  - deleted.
-    We don't want the $ ID $ in source code any more as it causes problems
+     d.rast --script
+
+    Just select an existing module which is close to your application to save
+    efforts.
+
+4.  We don't want the $ ID $ in source code any more as it causes problems
     for the branches.
 
+5.  Create and use secure temporary files and directories. Use the
+    grass.tempfile() or grass.tempdir() functions to do this. e.g.
 
-4. PLEASE take the time to add comments throughout your code explaining what
+	# setup temporary file
+	TMP = grass.tempfile()
+	if TMP is None:
+	    grass.fatal("Unable to create temporary files")
+	    
+6.  Use grass.findfile() when there is a need to test if a map exists.
+
+	# test for input raster map
+	result = grass.find_file(name = map_name, element = 'cell', quiet = True)
+	if not result['file']
+	  grass.fatal("Raster map <%s> not found" % map_name)
+
+	# test for input vector map
+	result = grass.find_file(name = map_name, element = 'vector', quiet = True)
+	if not result['file']
+	  grass.fatal("Vector map <%s> not found" % map_name)
+
+     ... and so forth. See 'g.manual g.findfile' for details.
+
+7.  For any informational output, use the grass.message()
+    function. For error messages should be used grass.fatal_error() or
+    grass.error() and for warnings grass.warning(). For debugging
+    purposes grass.debug().
+
+	#normal message:
+	grass.message("Done")
+
+	# warning:
+        grass.warning("No input values found, using default values")
+
+	# error:
+        grass.error("No map found")
+
+	# fatal error:
+	grass.fatal_error("No map found, exiting")
+
+	# debug output (use g.gisenv to enable/disable)
+        grass.debug("Our calculated value is: %d" % value)
+
+    Try to omit any usage of the 'print' command for informational output.
+
+8.  PLEASE take the time to add comments throughout your code explaining what
     the code is doing. It will save a HUGE amount of time and frustration for
     other programmers that may have to change your code in the future.
 
 
-5. Make sure a new line is at the end of each file.
+9.  Make sure a new line is at the end of each file.
 
 
-6. For consistency, use README rather than README.txt for any README files.
+10. For consistency, use README rather than README.txt for any README files.
 
 
-7. Be sure to develop on top of the LATEST GRASS code (which is in SVN repository).
-   You can re-check before submission with 'svn diff':
+11. Be sure to develop on top of the LATEST GRASS code (which is in SVN repository).
+    You can re-check before submission with 'svn diff':
 
-   Be sure to create unified ("diff -u") format. "Plain" diffs (the default
-   format) are risky, because they will apply without warning to code which
-   has been substantially changed; they are also harder to read than unified.
+    Be sure to create unified ("diff -u") format. "Plain" diffs (the default
+    format) are risky, because they will apply without warning to code which
+    has been substantially changed; they are also harder to read than unified.
 
-   Such diffs should be made from the top-level directory, e.g.
-   "svn diff gui/wxpython/wxgui.py"; that way, the diff will
-   include the pathname rather than just "wxgui.py".
+    Such diffs should be made from the top-level directory, e.g.
+    "svn diff gui/wxpython/wxgui.py"; that way, the diff will
+    include the pathname rather than just "wxgui.py".
 
 
-8. When submitting new files to the repository set SVN properties,
-   usually for directory
+12. When submitting new files to the repository set SVN properties,
+    usually for directory
 
       svn:ignore : *.pyc
 
-   or e.g. for Python file
+    or e.g. for Python file
     
       svn:mime-type : text/python
       svn:keywords : Author Date Id
       svn:eol-style : native
 
-   See
-   http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+    See
+    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
 
 
-9. wxGUI (gui/wxpython)
+13. wxGUI (gui/wxpython)
 
-   See http://wiki.wxpython.org/wxPython_Style_Guide
+    See http://wiki.wxpython.org/wxPython_Style_Guide
 
+    Major rules:
 
-10. Tell the other developers about the new code using the following e-mail:
-   grass-dev at lists.osgeo.org
+    - use named parameters in functions, e.g. 
+
+    dlg = wx.FileDialog(parent = self, message = _("Choose file to save current workspace"),
+                        wildcard = _("GRASS Workspace File (*.gxw)|*.gxw"), style = wx.FD_SAVE)
+
+    instead of
+
+    dlg = wx.FileDialog(self, _("Choose file to save current workspace"),
+                        _("GRASS Workspace File (*.gxw)|*.gxw"), wx.FD_SAVE)
+
+    - use wx.ID_ANY instead of `-1`
+
+    - use gcmd.GError(), gcmd.GWarning and gcmd.GMessage instead of wx.MessageBox()
+
+    - use gcmd.RunCommand() instead of grass.run_command() or grass.read_command() 
+
+    - use full strings, eg.
+
+      if ...:
+          win.SetLabel(_('Name for new 3D raster map to create'))
+      else:
+          win.SetLabel(_('Name for new raster map to create'))
+
+      instead of
+
+      _('Name for new %s to create') % maplabel
+
+      where `maplabel` can be 'raster map' or '3D raster map'
+
+14. Tell the other developers about the new code using the following e-mail:
+    grass-dev at lists.osgeo.org
  
-   To subscribe to this mailing list, see
-   http://lists.osgeo.org/mailman/listinfo/grass-dev
+    To subscribe to this mailing list, see
+    http://lists.osgeo.org/mailman/listinfo/grass-dev
 
 
-11. In case of questions feel free to contact the developers at the above
-   mailing list.
-   http://www.grass-gis.org/devel/index.php#submission
+15. In case of questions feel free to contact the developers at the above
+    mailing list.
+    http://grass.osgeo.org/devel/index.php#submission
 
 ...
 [please add further hints if required]
+
+
+"Your attention to detail is appreciated."



More information about the grass-commit mailing list