Python-EFL: more docs for ecore

SVN revision: 84350

doc/ecore/class-filedownload.rst

@@ -0,0 +1,4 @@
+:class:`efl.ecore.FileDownload` Class
+==============================
+
+.. autoclass:: efl.ecore.FileDownload

doc/ecore/ecore.rst

@@ -68,6 +68,7 @@ Reference
    class-idleexiter
    class-exe
    class-fdhandler
+   class-filedownload
 
 
 Inheritance diagram

efl/ecore/efl.ecore_animator.pxi

@@ -17,6 +17,30 @@
 
 
 cdef class Animator(Eo):
+    """Creates an animator to tick off at every animaton tick during main loop
+       execution.
+
+       This class represents an animator that will call the given ``func``
+       every N seconds where N is the frametime interval set by
+       animator_frametime_set(). The function will be passed any extra
+       parameters given to constructor.
+
+       When the animator ``func`` is called, it must return a value of either
+       *True* or *False* (remember that Python returns *None* if no value is
+       explicitly returned and *None* evaluates to *False*). If it returns
+       *True*, it will be called again at the next tick, or if it returns
+       *False* it will be deleted automatically making any references/handles
+       for it invalid.
+
+       Animators should be stopped/deleted by means delete() or
+       returning *False* from ``func``, otherwise they'll continue alive, even
+       if the current python context delete it's reference to it.
+
+       :param func: function to call every frame.
+                    Expected signature::
+                        func(*args, **kargs): bool
+
+    """
     def __init__(self, func, *args, **kargs):
         if not callable(func):
             raise TypeError("Parameter 'func' must be callable")
@@ -37,13 +61,26 @@ cdef class Animator(Eo):
         return self.func(*self.args, **self.kargs)
 
     def delete(self):
+        "Stop callback emission and free internal resources."
         ecore_animator_del(self.obj)
 
     def stop(self):
+        "Alias for delete()."
         self.delete()
 
 
 def animator_add(func, *args, **kargs):
+    """Animator factory, for C-api compatibility.
+
+       func signature::
+         func(*args, **kargs): bool
+
+       :param func: function to call every frame.
+
+       :return: a new Animator instance
+       :rtype: ``efl.ecore.Animator``
+
+    """
     return Animator(func, *args, **kargs)
 
 

efl/ecore/efl.ecore_file_download.pxi

@@ -33,6 +33,47 @@ cdef int _progress_cb(void *data, const_char_ptr file, long int dltotal,
 
 
 cdef class FileDownload(object):
+    """ Download the given url to destination.
+
+    You must provide the full url, including 'http://', 'ftp://' or 'file://'.
+    If ``dst`` already exist it will not be overwritten and the function will fail.
+    Ecore must be compiled with CURL to download using http and ftp protocols.
+    The ``status`` param in the ``completion_cb`` will be 0 if the download
+    end successfully or 1 in case of failure.
+    The ``progress_cb`` must return 0 to continue normally or 1 to abort
+    the download, note that no *completion_cb* will be called if you abort in
+    this way.
+    The constructor will raise a SystemError exception if the download don't
+    start, this can happen if you don't have CURL compiled, if the destination
+    exists or if the destination path don't exist or isn't writable.
+
+    The callback signatures are::
+
+        completion_cb(file, status, *args, **kargs)
+        progress_cb(file, dltotal, dlnow, uptotal, upnow, *args, **kargs): int
+
+    You can use the download feature as a class instance or you can use
+    the legacy API.
+
+    Instance example::
+    
+        from efl.ecore import FileDownload
+        dl = FileDownload("http://your_url", "/path/to/destination", None, None)
+        dl.abort()
+
+    Legacy example::
+
+        from efl import ecore
+        dl = ecore.file_download("http://your_url",
+                                 "/path/to/destination", None, None)
+        ecore.file_download_abort(dl)
+
+    :param url: The complete url to download
+    :param dst: Where to download the file
+    :param completion_cb: A callback called on download complete
+    :param progress_cb: A callback called during the download operation
+
+    """
     def __init__(self, url, dst, completion_cb, progress_cb, *args, **kargs):
         cdef Ecore_File_Download_Job *job
 
@@ -88,6 +129,7 @@ cdef class FileDownload(object):
         return 0
 
     def abort(self):
+        """Abort the download and free internal resources."""
         if self.job != NULL:
             ecore_file_download_abort(self.job)
             self.job = NULL
@@ -95,13 +137,45 @@ cdef class FileDownload(object):
 
 
 def file_download(url, dst, completion_cb, progress_cb, *args, **kargs):
+    """
+    efl.ecore.FileDownload} factory, for C-api compatibility.
+
+    :param url: The complete url to download
+    :param dst: Where to download the file
+    :param completion_cb: The function called when the download end
+                          Expected signature::
+                            completion_cb(file, status, *args, **kargs)
+    :param progress_cb: The function to called while the download progress
+                        advance. Ecpected signature::
+                            progress_cb(file, dltotal, dlnow, uptotal, upnow, *args, **kargs): int
+
+    :return: a new FileDownload instance
+    :rtype: `efl.ecore.Download`
+    """
     return FileDownload(url, dst, completion_cb, progress_cb, *args, **kargs)
 
 def file_download_abort(instance):
+    """
+    C-api compatibility
+    Abort the given download an free internal resources
+    """
     instance.abort()
 
 def file_download_abort_all():
+    """
+    This will abort all the download currently in progrss, use with caution.
+    """
     ecore_file_download_abort_all()
 
 def file_download_protocol_available(protocol):
+    """
+    Check if the given download protocol is available, available protocols
+    are: "http://", "ftp://" and "file://". Note that ecore can be
+    compiled without CURL support and thus http and ftp could not be available
+
+    :param protocol: The protocol to check, ex: "http://"
+    :type protocol: str
+    :return: True if the protocol is supported
+    :rtype: bool
+    """
     return bool(ecore_file_download_protocol_available(protocol))

efl/ecore/efl.ecore_idler.pxi

@@ -17,6 +17,30 @@
 
 
 cdef class Idler(Eo):
+    """Add an idler handler.
+
+    This class represents an idler on the event loop that will
+    call ``func`` when there is nothing more to do. The function will
+    be passed any extra parameters given to constructor.
+
+    When the idler ``func`` is called, it must return a value of either
+    True or False (remember that Python returns None if no value is
+    explicitly returned and None evaluates to False). If it returns
+    B{True}, it will be called again when system become idle, or if it
+    returns B{False} it will be deleted automatically making any
+    references/handles for it invalid.
+
+    Idlers should be stopped/deleted by means of delete()or
+    returning False from ``func``, otherwise they'll continue alive, even
+    if the current python context delete it's reference to it.
+
+    Idlers are useful for progressively prossessing data without blocking.
+
+    :param func: function to call when system is idle.
+                 Expected signature::
+                    func(*args, **kargs): bool
+
+    """
     def __init__(self, func, *args, **kargs):
         if not callable(func):
             raise TypeError("Parameter 'func' must be callable")
@@ -37,13 +61,40 @@ cdef class Idler(Eo):
         return self.func(*self.args, **self.kargs)
 
     def delete(self):
+        "Stop callback emission and free internal resources."
         ecore_idler_del(self.obj)
 
     def stop(self):
+        "Alias for stop()."
         self.delete()
 
 
 cdef class IdleEnterer(Idler):
+    """Add an idle enterer handler.
+
+    This class represents a function that will be called before systems
+    enter idle. The function will be passed any extra parameters given
+    to constructor.
+
+    When the idle enterer ``func`` is called, it must return a value of
+    either *True* or *False* (remember that Python returns *None* if no value
+    is explicitly returned and *None* evaluates to *False*). If it returns
+    *True*, it will be called again when system become idle, or if it
+    returns *False* it will be deleted automatically making any
+    references/handles for it invalid.
+
+    Idle enterers should be stopped/deleted by means of delete() or
+    returning *False* from ``func``, otherwise they'll continue alive, even
+    if the current python context delete it's reference to it.
+
+    Idle enterer are useful for post-work jobs, like garbage collection.
+
+
+    :param func: function to call when system enters idle.
+                Expected signature::
+                    func(*args, **kargs): bool
+   
+    """
     def __init__(self, func, *args, **kargs):
         if not callable(func):
             raise TypeError("Parameter 'func' must be callable")
@@ -53,10 +104,33 @@ cdef class IdleEnterer(Idler):
         self._set_obj(ecore_idle_enterer_add(_ecore_task_cb, <void *>self))
 
     def delete(self):
+        "Stop callback emission and free internal resources."
         ecore_idle_enterer_del(self.obj)
 
 
 cdef class IdleExiter(Idler):
+    """Add an idle exiter handler.
+
+    This class represents a function that will be called before systems
+    exits idle. The function will be passed any extra parameters given
+    to constructor.
+
+    When the idle exiter ``func`` is called, it must return a value of
+    either *True* or *False* (remember that Python returns *None* if no value
+    is explicitly returned and *None* evaluates to *False*). If it returns
+    *True*, it will be called again when system become idle, or if it
+    returns *False* it will be deleted automatically making any
+    references/handles for it invalid.
+
+    Idle exiters should be stopped/deleted by means of delete() or
+    returning *False* from ``func``, otherwise they'll continue alive, even
+    if the current python context delete it's reference to it.
+
+    :param func: function to call when system exits idle.
+                 Expected signature::
+                    func(*args, **kargs): bool
+
+    """
     def __init__(self, func, *args, **kargs):
         if not callable(func):
             raise TypeError("Parameter 'func' must be callable")
@@ -70,12 +144,40 @@ cdef class IdleExiter(Idler):
 
 
 def idler_add(func, *args, **kargs):
+    """efl.ecore.Idler factory, for C-api compatibility.
+
+    :param func: function to call when system is idle.
+                Expected signature::
+                    func(*args, **kargs): bool
+
+    :return: a new Idler instance
+    :rtype: efl.ecore.Idler
+
+    """
     return Idler(func, *args, **kargs)
 
 
 def idle_enterer_add(func, *args, **kargs):
+    """efl.ecore.IdleEnterer factory, for C-api compatibility.
+
+    :param func: function to call when system enters idle.
+                 Expected signature::
+                    func(*args, **kargs): bool
+
+    :return: a new IdleEnterer instance
+    :rtype: efl.ecore.IdleEnterer
+    """
     return IdleEnterer(func, *args, **kargs)
 
 
 def idle_exiter_add(func, *args, **kargs):
+    """efl.ecore.IdleExiter factory, for C-api compatibility.
+
+    :param func: function to call when system exits idle.
+                 Expected signature::
+                    func(*args, **kargs): bool
+
+    :return: a new IdleExiter instance
+    :rtype: efl.ecore.IdleExiter
+    """
     return IdleExiter(func, *args, **kargs)