python: fix the type nonsense of the first parameter of class Directory

[notmuch] / bindings / python / notmuch / database.py

diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py
index 3de0f2b8997a8dc04032c875e4bc2b592cbf44b0..504bb8804223fe94a502f9078eeee5dcaff01dae 100644 (file)
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -140,7 +140,7 @@ class Database(object):
         :param mode:   Mode to open a database in. Is always
                        :attr:`MODE`.READ_WRITE when creating a new one.
         :type mode:    :attr:`MODE`
         :param mode:   Mode to open a database in. Is always
                        :attr:`MODE`.READ_WRITE when creating a new one.
         :type mode:    :attr:`MODE`

-        :exception: :exc:`NotmuchError` or derived exception in case of
+        :raises: :exc:`NotmuchError` or derived exception in case of

             failure.
         """
         self._db = None
             failure.
         """
         self._db = None


@@ -176,8 +176,7 @@ class Database(object):
 
         :param path: A directory in which we should create the database.
         :type path: str
 
         :param path: A directory in which we should create the database.
         :type path: str

-        :returns: Nothing
-        :exception: :exc:`NotmuchError` in case of any failure
+        :raises: :exc:`NotmuchError` in case of any failure

                     (possibly after printing an error message on stderr).
         """
         if self._db is not None:
                     (possibly after printing an error message on stderr).
         """
         if self._db is not None:


@@ -200,8 +199,7 @@ class Database(object):
 
         :param status: Open the database in read-only or read-write mode
         :type status:  :attr:`MODE`
 
         :param status: Open the database in read-only or read-write mode
         :type status:  :attr:`MODE`

-        :returns: Nothing
-        :exception: Raises :exc:`NotmuchError` in case of any failure
+        :raises: Raises :exc:`NotmuchError` in case of any failure

                     (possibly after printing an error message on stderr).
         """
         res = Database._open(_str(path), mode)
                     (possibly after printing an error message on stderr).
         """
         res = Database._open(_str(path), mode)


@@ -296,7 +294,7 @@ class Database(object):
         neither begin nor end necessarily flush modifications to disk.
 
         :returns: :attr:`STATUS`.SUCCESS or raises
         neither begin nor end necessarily flush modifications to disk.
 
         :returns: :attr:`STATUS`.SUCCESS or raises

-        :exception: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION
+        :raises: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION

                     Xapian exception occurred; atomic section not entered.
 
         *Added in notmuch 0.9*"""
                     Xapian exception occurred; atomic section not entered.
 
         *Added in notmuch 0.9*"""


@@ -317,7 +315,7 @@ class Database(object):
 
         :returns: :attr:`STATUS`.SUCCESS or raises
 
 
         :returns: :attr:`STATUS`.SUCCESS or raises
 

-        :exception:
+        :raises:

             :exc:`NotmuchError`:
                 :attr:`STATUS`.XAPIAN_EXCEPTION
                     A Xapian exception occurred; atomic section not
             :exc:`NotmuchError`:
                 :attr:`STATUS`.XAPIAN_EXCEPTION
                     A Xapian exception occurred; atomic section not


@@ -346,14 +344,14 @@ class Database(object):
               of database (see :meth:`get_path`), or else should be an absolute
               path with initial components that match the path of 'database'.
         :returns: :class:`Directory` or raises an exception.
               of database (see :meth:`get_path`), or else should be an absolute
               path with initial components that match the path of 'database'.
         :returns: :class:`Directory` or raises an exception.

-        :exception:
+        :raises:

             :exc:`NotmuchError` with :attr:`STATUS`.FILE_ERROR
                     If path is not relative database or absolute with initial
                     components same as database.
         """
         self._assert_db_is_initialized()
         # sanity checking if path is valid, and make path absolute
             :exc:`NotmuchError` with :attr:`STATUS`.FILE_ERROR
                     If path is not relative database or absolute with initial
                     components same as database.
         """
         self._assert_db_is_initialized()
         # sanity checking if path is valid, and make path absolute

-        if path[0] == os.sep:
+        if path and path[0] == os.sep:

             # we got an absolute path
             if not path.startswith(self.get_path()):
                 # but its initial components are not equal to the db path
             # we got an absolute path
             if not path.startswith(self.get_path()):
                 # but its initial components are not equal to the db path


@@ -367,7 +365,7 @@ class Database(object):
         dir_p = Database._get_directory(self._db, _str(path))
 
         # return the Directory, init it with the absolute path
         dir_p = Database._get_directory(self._db, _str(path))
 
         # return the Directory, init it with the absolute path

-        return Directory(_str(abs_dirpath), dir_p, self)
+        return Directory(abs_dirpath, dir_p, self)

 
     _add_message = nmlib.notmuch_database_add_message
     _add_message.argtypes = [NotmuchDatabaseP, c_char_p,
 
     _add_message = nmlib.notmuch_database_add_message
     _add_message.argtypes = [NotmuchDatabaseP, c_char_p,


@@ -410,7 +408,7 @@ class Database(object):
 
         :rtype:   2-tuple(:class:`Message`, :attr:`STATUS`)
 
 
         :rtype:   2-tuple(:class:`Message`, :attr:`STATUS`)
 

-        :exception: Raises a :exc:`NotmuchError` with the following meaning.
+        :raises: Raises a :exc:`NotmuchError` with the following meaning.

               If such an exception occurs, nothing was added to the database.
 
               :attr:`STATUS`.FILE_ERROR
               If such an exception occurs, nothing was added to the database.
 
               :attr:`STATUS`.FILE_ERROR


@@ -460,7 +458,7 @@ class Database(object):
                This filename was removed but the message persists in the
                database with at least one other filename.
 
                This filename was removed but the message persists in the
                database with at least one other filename.
 

-        :exception: Raises a :exc:`NotmuchError` with the following meaning.
+        :raises: Raises a :exc:`NotmuchError` with the following meaning.

              If such an exception occurs, nothing was removed from the
              database.
 
              If such an exception occurs, nothing was removed from the
              database.
 


@@ -479,7 +477,7 @@ class Database(object):
         :param msgid: The message ID
         :type msgid: unicode or str
         :returns: :class:`Message` or `None` if no message is found.
         :param msgid: The message ID
         :type msgid: unicode or str
         :returns: :class:`Message` or `None` if no message is found.

-        :exception:
+        :raises:

             :exc:`OutOfMemoryError`
                   If an Out-of-memory occured while constructing the message.
             :exc:`XapianError`
             :exc:`OutOfMemoryError`
                   If an Out-of-memory occured while constructing the message.
             :exc:`XapianError`


@@ -512,7 +510,7 @@ class Database(object):
             function returns None if no message is found with the given
             filename.
 
             function returns None if no message is found with the given
             filename.
 

-        :exception:
+        :raises:

             :exc:`OutOfMemoryError`
                   If an Out-of-memory occured while constructing the message.
             :exc:`XapianError`
             :exc:`OutOfMemoryError`
                   If an Out-of-memory occured while constructing the message.
             :exc:`XapianError`


@@ -641,7 +639,7 @@ class Directory(object):
 
     def __init__(self, path, dir_p, parent):
         """
 
     def __init__(self, path, dir_p, parent):
         """

-        :param path:   The absolute path of the directory object as unicode.
+        :param path:   The absolute path of the directory object.

         :param dir_p:  The pointer to an internal notmuch_directory_t object.
         :param parent: The object this Directory is derived from
                        (usually a :class:`Database`). We do not directly use
         :param dir_p:  The pointer to an internal notmuch_directory_t object.
         :param parent: The object this Directory is derived from
                        (usually a :class:`Database`). We do not directly use


@@ -649,7 +647,6 @@ class Directory(object):
                        this Directory object lives. This keeps the
                        parent object alive.
         """
                        this Directory object lives. This keeps the
                        parent object alive.
         """

-        assert isinstance(path, unicode), "Path needs to be an UNICODE object"

         self._path = path
         self._dir_p = dir_p
         self._parent = parent
         self._path = path
         self._dir_p = dir_p
         self._parent = parent


@@ -679,27 +676,19 @@ class Directory(object):
                 don't store a timestamp of 0 unless you are comfortable with
                 that.
 
                 don't store a timestamp of 0 unless you are comfortable with
                 that.
 

-          :param mtime: A (time_t) timestamp
-          :returns: Nothing on success, raising an exception on failure.
-          :exception: :exc:`NotmuchError`:
-
-                        :attr:`STATUS`.XAPIAN_EXCEPTION
-                          A Xapian exception occurred, mtime not stored.
-                        :attr:`STATUS`.READ_ONLY_DATABASE
-                          Database was opened in read-only mode so directory
-                          mtime cannot be modified.
-                        :attr:`STATUS`.NOT_INITIALIZED
-                          The directory has not been initialized
+        :param mtime: A (time_t) timestamp
+        :raises: :exc:`XapianError` a Xapian exception occurred, mtime
+                 not stored
+        :raises: :exc:`ReadOnlyDatabaseError` the database was opened
+                 in read-only mode so directory mtime cannot be modified
+        :raises: :exc:`NotInitializedError` the directory object has not
+                 been initialized

         """
         self._assert_dir_is_initialized()
         """
         self._assert_dir_is_initialized()

-        #TODO: make sure, we convert the mtime parameter to a 'c_long'

         status = Directory._set_mtime(self._dir_p, mtime)
 
         status = Directory._set_mtime(self._dir_p, mtime)
 

-        #return on success
-        if status == STATUS.SUCCESS:
-            return
-        #fail with Exception otherwise
-        raise NotmuchError(status)
+        if status != STATUS.SUCCESS:
+            raise NotmuchError(status)

 
     def get_mtime(self):
         """Gets the mtime value of this directory in the database
 
     def get_mtime(self):
         """Gets the mtime value of this directory in the database


@@ -707,8 +696,7 @@ class Directory(object):
         Retrieves a previously stored mtime for this directory.
 
         :param mtime: A (time_t) timestamp
         Retrieves a previously stored mtime for this directory.
 
         :param mtime: A (time_t) timestamp

-        :returns: Nothing on success, raising an exception on failure.
-        :exception: :exc:`NotmuchError`:
+        :raises: :exc:`NotmuchError`:

 
                         :attr:`STATUS`.NOT_INITIALIZED
                           The directory has not been initialized
 
                         :attr:`STATUS`.NOT_INITIALIZED
                           The directory has not been initialized