[SAGA-RG] SAGA Python language binding naming.

[PFA van Zoolingen]

All,

To agree on the naming convention for the (implementation independent) 
specification the Python to Saga language binding, I am starting this 
thread. I am not a long-time Python programmer so I would like some imput 
about the following.

All names are taken from the GFD-R-P.90 document, "A Simple API for Grid 
Applications (SAGA)". Most name rules are taken from the Python Style 
Guide: http://www.python.org/dev/peps/pep-0008/

Module name:
-saga
-Examples: saga.File, saga.Flags, saga.Object
-Rationale: 
Less keyboard strokes.
Different class names do not conflict. (File.Flags, Namespace.Flags and 
Replica.Flags are the same. Job.State and Task.State are the same. Only 
Stream.State conflicts. This could become Stream.StreamState)

This means only one saga module, and no specific packages. (Could this 
be a problem in the future?)

Class name:
-Uppercase letters or CapCase convention. Abbreviations in capitols
-Example: File(), TaskContainer(), URL(), SeekMode(), NSEntry()

Exception names:
-Same as for class names.
-Example: NotImplemented(), IncorrectURL(), AlreadyExists()

Enum types:
-GFD-R-P.90 specifies a number of enum types. (Standard) Python does not 
have enums. So just create classes with numbers within them.
-Example: 
The classes WaitMode, ObjectType, Permission, Flags, SeekMode, IOMode

class State(object):
     new      = 1
     running  = 2
     done     = 3
     canceled = 4
     failed   = 5

Function names:
-Lowercase with words separated by an underscore.
- Rationale: I know, seems strange, but it looks like its Python 
practice, in most cases. (Some Python modules like StringIO.py don't 
comply, but pickle.py does.) 
-Example: Attributes.set_attribute(self, key, value)
           Context.set_defaults(self)
 	  Object.get_session(self)

Variable names:
-Same as Function names.
-Example: State.done (see above), ObjectType().exception

Return types:
-All the methods used have a returntype. Most are easily converted from 
the pseudo-code to Python code, but there are some optimalisations 
numbers -> int, long, float.
boolean -> True, False,
String -> String

array <String> -> a List/Tuple (I.E. Attributes.get_vector_attribute())
array <byte>   -> String (Buffer.set_data())

I haven't found other cases yet, but the list is probably incomplete.

-Sychronous, Asynchonous, Task

In 3.10, page 142, GDF-R-P.90 states to use a template member method 
like: task.get_result <return_type> (void) to get a Sync, Async or Task 
as a return type. Since Python does not have templates (String templates 
are something else), I propose to add a jobType parameter to all the 
methods using this principle. jobType could be {sync=0, async=1, 
task=0}. jobType could be defaulted to jobType=sync, so:

f = saga.File(someURL)
len_out = f.read (len, buffer);
OR
task  =   f.read (len, buffer, jobType=sync)

Well, probably more to come but this is it for now.
Greetings,

Paul van Zoolingen.
Student Vrije Universiteit, Amsterdam, The Netherlands
===
Those who can, do. Those who can't, simulate.