[SAGA-RG] SAGA Python language binding naming.

[Andre Merzky]

Beste Paul, 


Quoting [PFA van Zoolingen] (Aug 08 2008):
> 
> 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.

I am very likely much less of a python programmer than you,
thus please excuse the potential ignortance of my anwer! :-)


> 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)

Less keystrokes sound great :-)  But is that a scalable
approach?  Saga is organized into packages, with the
rationale that additional packages can be defined later on.

For example, the job package has the classes description,
job, service, and self.  We are in the process on adding a
checkpoint and recovery package, which kind of extends the
core job package, and has the same classes.  We would then
end up with

  saga.job_job, saga.job_service, ...
  saga.cpr_job, saga.cpr_service, ...

same amount of typing really.  Well, you probably would
leave off the prefix for the core package (saga.job,
saga.service, ...), but still.


Also, several classes/types would sound strange  without package
as qualifiers:

  saga.state   - state of SAGA?
  saga.service - what does it do?
  saga.entry   - entry of what?


> 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()

These are certainly things which should follow the typical language conventions...


> 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)

same here: if that is the way to go in python...


> 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)

That is certainly an option.  Just to give you some trouble,
here are some others:

  len_out = f.read      (len, buffer, sync);  // thats your version
  task    = f.read      (len, buffer, task);

  len_out = f.read_sync (len, buffer);
  task    = f.read_task (len, buffer);

  len_out = f.read      (sync, len, buffer);
  task    = f.read      (task, len, buffer);

  len_out = sync_f.read (len, buffer);
  task    = task_f.read (len, buffer);

And there are more...  All options have pro and cons.  We
had that discussion for a long time as we designed the task
model.  If you are interested in gazillions of mails running
circles, I can dig them out of the archive ;-)

Your model is nice, as it is simple.  The only drawback are
optional arguments:

  dir.copy (src, target, Overwrite, sync);

What happens without flags, e.g. no Overwrite is wanted:

  dir.copy (src, target, 0, sync);

Basically, you cannot have default args anymore, and always
have to specify all arguments.  Thats tedious to the
programmer. 

No idea if python provides some clever way to solve this -
most other languages don't.  Thus, please do also consider
to put the flag in the first place, or to use some other
qualifiers (method name, etc).  Can't recall at the moment
what way Hartmut chose in his Python implementation, sorry.

Cheers, Andre.


> 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.
-- 
Nothing is ever easy.