NOTE: Please improve this list! Dear (new) GRASS developer, when submitting Python code to GRASS SVN repository, please take care of following rules: [ 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 ] 0. Indentation 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. Use the directory structure to place your script appropriately into the source tree - scripts go into scripts/ Also add a Makefile and a .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 g.myscript): """ MODULE: g.myscript AUTHOR(S): John Doe PURPOSE: Describe your script here... 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). You can easily autogenerate the header and parameters from an existing module using the --script flag. Example: 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. # 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. 9. Make sure a new line is at the end of each file. 10. For consistency, use README rather than README.txt for any README files. 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. 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". 12. When submitting new files to the repository set SVN properties, usually for directory svn:ignore : *.pyc 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 13. wxGUI (gui/wxpython) See http://wiki.wxpython.org/wxPython_Style_Guide Major rules: - 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@lists.osgeo.org To subscribe to this mailing list, see http://lists.osgeo.org/mailman/listinfo/grass-dev 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."