Changes between Initial Version and Version 1 of DeveloperGuidelinesS3

Timestamp:

01/02/11 07:48:13 (14 years ago)

Author:

Dominic König

Comment:

--

DeveloperGuidelinesS3

@@ +1 @@
+[wiki:DeveloperGuidelines] | S3
+
+= S3 Framework Extensions for Web2py =
+
+All S3 framework extensions for web2py reside as a Python package in {{{modules/s3}}}:
+
+||'''Module'''||'''Functionality'''||
+||s3aaa||Authentication, Authorization, Accouting||
+||s3cfg||Deployment Settings||
+||s3gis||GIS Module||
+||s3msg||Messaging API||
+||s3test|| ||
+||s3tools||Tools||
+||s3utils||Utilities||
+||s3validators||Custom Validators||
+||s3vita||Person Finder Toolkit (VITA)||
+||s3widgets||Custom UI Widgets||
+||s3xrc||Extensible Resource Controller (S3XRC)||
+||s3rest||RESTful API (S3XRC)||
+||s3crud||RESTful CRUD Methods (S3XRC)||
+||s3search||RESTful Search Methods||
+||s3export||Resource Export Toolkit (S3XRC)||
+||s3import||Resource Import Toolkit (S3XRC)||
+||s3model||Data Model Extensions (S3XRC)||
+||s3xml||XML Toolkit (S3XML)||
+
+== The s3base Namespace ==
+
+The names of the S3 package (=classes, functions, constants) are defined in {{{modules/s3/__init__.py}}} - all names which are imported in this file are available under the {{{s3base}}} namespace. 
+
+This namespace is imported in {{{models/000_1st_run.py}}}, thus it is available to ''all'' models and controllers - you don't need to import any S3 names separately, and neither do you need to think under which namespace a S3 class or function is available: always simply use the {{{s3base}}} prefix:
+
+{{{
+gis = s3base.GIS(...)
+resource = s3base.S3Resource(...)
+}}}
+
+For convenience, the names of {{{s3utils}}}, {{{s3widgets}}} and {{{s3validators}}} are also imported into the global namespace, so you do not need a namesace prefix to access them:
+
+{{{
+mytable.myfield.requires = IS_UTC_DATETIME()
+mywidget = S3CheckboxWidget.widget()
+}}}
+
+== Extending S3 ==
+
+If you're going to add things to S3, please do it at the right place:
+
+  - Utility functions which are meant to be globally available belong into {{{modules/s3/s3utils.py}}}
+  - All other utility functions should either be class methods or should not be globally available
+  - New classes should be added to the respective modules
+  - New modules should be added as separate files
+
+To make a class, function or constant available in the {{{s3base}}} namespace, you should import it in {{{modules/s3/__init__.py}}}:
+
+{{{
+from s3xrc import S3ResourceController
+}}}
+
+Note that you need to use the {{{from s3xxx import yyy}}} notation (relative import).
+
+== Importing Modules ==
+
+Any submodule in modules/s3 can import names from any other submodule in modules/s3 by simply {{{from s3xxx import yyy}}}, by relative import:
+
+{{{
+from s3xrc import S3ResourceController
+}}}
+
+If you use the wildcard:
+
+{{{
+from s3xxx import *
+}}}
+
+then you have to ensure that the name you want to import is listed in the {{{__all__}}} variable inside the respective {{{s3xxx}}} submodule:
+
+{{{
+__all__ = ["MyClass", "MyOtherClass"]
+}}}
+
+If {{{__all___}}} is not declared inside a submodule, then all names are imported - but this should be avoided.
+
+You can also import names from other modules in the {{{modules}}} directory, by relative import:
+
+{{{
+from ..pyparsing import ParseBaseException
+}}}
+
+Note the {{{..}}} before the module path.
+
+== Coding Conventions ==
+
+Please consider our coding conventions when coding S3 extensions:
+
+  - names of top-level functions must be prefixed by {{{s3_}}}, must be all lowercase (no CamelCase!), with words separated by underscores, e.g. {{{s3_my_function}}}
+  - names of genuine S3 classes (even if based on web2py classes) must be prefixed by S3, and use CamelCase, e.g. {{{S3ResourceController}}}
+  - names of customized web2py classes (which are meant to be used instead of the native web2py class) are ''suffixed'' with S3, e.g. {{{AuthS3}}}
+  - constants must be prefixed by S3, all uppercase, with words separated by underscores, e.g. S3_MY_CONSTANT
+  - functions inside of classes can be named arbitrarily, however, their names should somehow indicate what they do
+
+  - all modules must have a docstring describing the module, the module author(s), the copyright and license
+  - the copyright statement must declare the SSF as copyright holder, and the license must be MIT
+  - dependencies can be declared with the {{{@requires:}}} statement
+
+{{{
+""" Utilities
+
+    @requires: U{B{I{gluon}} <http://web2py.com>}
+
+    @author: Fran Boon <fran[at]aidiq.com>
+    @author: Michael Howden <michael[at]aidiq.com>
+    @author: Pradnya Kulkarni
+
+    @copyright: (c) 2010 Sahana Software Foundation
+    @license: MIT
+
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use,
+    copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following
+    conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+    OTHER DEALINGS IN THE SOFTWARE.
+
+"""
+
+}}}
+
+
+  - all functions - in classes or top-level - must have docstrings explaining what they are supposed to do
+  - the docstring should contain an {{{@author: }}} tag if the author differs from the module author
+  - you should add your email address, if you want others to contact you with questions or suggestions
+
+{{{
+def shn_split_multi_value(value):
+    """
+    @author: Michael Howden <michael[at]aidiq.com>
+
+    Converts a series of numbers delimited by |, or already in a string into a list
+
+    If value = None, returns []
+
+    """
+
+}}}
+
+  - use {{{@status:}}} to indicate the current status of the implementation
+  - use {{{@see:}}} to refer to web pages (e.g. Eden wiki pages)
+  - see [http://epydoc.sourceforge.net/manual-fields.html] for more docstring tags