20/35271cba1368ceb6670c5a50390a3feee7bf56

   1 Return-Path: <patricktotzke@googlemail.com>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id 8258A429E32\r
   6         for <notmuch@notmuchmail.org>; Mon,  5 Dec 2011 13:13:08 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -0.799\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-0.799 tagged_above=-999 required=5\r
  12         tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1,\r
  13         FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
  14 Received: from olra.theworths.org ([127.0.0.1])\r
  15         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  16         with ESMTP id tYnBGKjkRaIw for <notmuch@notmuchmail.org>;\r
  17         Mon,  5 Dec 2011 13:13:05 -0800 (PST)\r
  18 Received: from mail-ee0-f53.google.com (mail-ee0-f53.google.com\r
  19  [74.125.83.53])        (using TLSv1 with cipher RC4-SHA (128/128 bits))        (No client\r
  20  certificate requested) by olra.theworths.org (Postfix) with ESMTPS id\r
  21  51E8B429E36    for <notmuch@notmuchmail.org>; Mon,  5 Dec 2011 13:13:04 -0800\r
  22  (PST)\r
  23 Received: by mail-ee0-f53.google.com with SMTP id b57so1074011eek.26\r
  24         for <notmuch@notmuchmail.org>; Mon, 05 Dec 2011 13:13:04 -0800 (PST)\r
  25 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;\r
  26         d=googlemail.com; s=gamma;\r
  27         h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references;\r
  28         bh=RWIIiF5DuOor+mGKND/Dx+wgqr8PpPFctTNJ2oVtW1g=;\r
  29         b=Cf9sObHzx5wIxDD4LTH1N7xaTkMQtrn4jcwfm/+Syiuynn1b6o89VO0tBYrGyHv61D\r
  30         Hmk73omWMKUecRCGv6xVCqvWVzkvCFc6c/lXDzH7nlQ4Wsfz7/tXTT9vbU7vXaJdxZ+h\r
  31         y0BRsHz/i3QNsFJnTGAHYH+Ok+fnp6Nu9ccuM=\r
  32 Received: by 10.14.9.210 with SMTP id 58mr1484128eet.123.1323119583798;\r
  33         Mon, 05 Dec 2011 13:13:03 -0800 (PST)\r
  34 Received: from localhost (cpc1-sgyl2-0-0-cust548.18-2.cable.virginmedia.com.\r
  35         [82.41.10.37])\r
  36         by mx.google.com with ESMTPS id 65sm38883529eeg.8.2011.12.05.13.13.01\r
  37         (version=TLSv1/SSLv3 cipher=OTHER);\r
  38         Mon, 05 Dec 2011 13:13:02 -0800 (PST)\r
  39 From: Patrick Totzke <patricktotzke@googlemail.com>\r
  40 To: notmuch@notmuchmail.org\r
  41 Subject: [PATCH 3/3] fix sphinx compile-time warnings\r
  42 Date: Mon,  5 Dec 2011 21:12:35 +0000\r
  43 Message-Id: <1323119555-31416-4-git-send-email-patricktotzke@gmail.com>\r
  44 X-Mailer: git-send-email 1.7.4.1\r
  45 In-Reply-To: <1323119555-31416-1-git-send-email-patricktotzke@gmail.com>\r
  46 References: <1323119555-31416-1-git-send-email-patricktotzke@gmail.com>\r
  47 X-BeenThere: notmuch@notmuchmail.org\r
  48 X-Mailman-Version: 2.1.13\r
  49 Precedence: list\r
  50 List-Id: "Use and development of the notmuch mail system."\r
  51         <notmuch.notmuchmail.org>\r
  52 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  53         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  54 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  55 List-Post: <mailto:notmuch@notmuchmail.org>\r
  56 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  57 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  58         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  59 X-List-Received-Date: Mon, 05 Dec 2011 21:13:08 -0000\r
  60 \r
  61 no changes to the code, only makes compiling the docs smoother\r
  62 as some rsT syntax errors were fixed\r
  63 ---\r
  64  bindings/python/docs/source/index.rst |   17 ++++----\r
  65  bindings/python/notmuch/database.py   |   67 ++++++++++++++++++--------------\r
  66  bindings/python/notmuch/message.py    |   27 +++++++------\r
  67  bindings/python/notmuch/tag.py        |   11 +++--\r
  68  4 files changed, 68 insertions(+), 54 deletions(-)\r
  69 \r
  70 diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst\r
  71 index 73d2a3b..f7d3d60 100644\r
  72 --- a/bindings/python/docs/source/index.rst\r
  73 +++ b/bindings/python/docs/source/index.rst\r
  74 @@ -138,10 +138,10 @@ More information on specific topics can be found on the following pages:\r
  75  \r
  76     .. method:: __len__()\r
  77  \r
  78 -   .. warning:: :meth:`__len__` was removed in version 0.6 as it exhausted\r
  79 -       the iterator and broke list(Messages()). Use the\r
  80 -       :meth:`Query.count_messages` function or use\r
  81 -       `len(list(msgs))`.\r
  82 +   .. warning::\r
  83 +   \r
  84 +      :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke\r
  85 +      list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`.\r
  86  \r
  87  :class:`Message` -- A single message\r
  88  ----------------------------------------\r
  89 @@ -205,10 +205,11 @@ More information on specific topics can be found on the following pages:\r
  90  \r
  91     .. method:: __len__\r
  92  \r
  93 -       .. warning:: :meth:`__len__` was removed in version 0.6 as it\r
  94 -           exhausted the iterator and broke list(Tags()). Use\r
  95 -           :meth:`len(list(msgs))` instead if you need to know the\r
  96 -           number of tags.\r
  97 +       .. warning::\r
  98 +\r
  99 +            :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke\r
 100 +            list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of\r
 101 +            tags.\r
 102  \r
 103     .. automethod:: __str__\r
 104  \r
 105 diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py\r
 106 index 706e8c8..471adaa 100644\r
 107 --- a/bindings/python/notmuch/database.py\r
 108 +++ b/bindings/python/notmuch/database.py\r
 109 @@ -40,16 +40,19 @@ class Database(object):\r
 110      :exc:`XapianError` as the underlying database has been\r
 111      modified. Close and reopen the database to continue working with it.\r
 112  \r
 113 -    .. note:: Any function in this class can and will throw an\r
 114 -           :exc:`NotInitializedError` if the database was not\r
 115 -           intitialized properly.\r
 116 -\r
 117 -    .. note:: Do remember that as soon as we tear down (e.g. via `del\r
 118 -           db`) this object, all underlying derived objects such as\r
 119 -           queries, threads, messages, tags etc will be freed by the\r
 120 -           underlying library as well. Accessing these objects will lead\r
 121 -           to segfaults and other unexpected behavior. See above for\r
 122 -           more details.\r
 123 +    .. note::\r
 124 +\r
 125 +        Any function in this class can and will throw an\r
 126 +        :exc:`NotInitializedError` if the database was not intitialized\r
 127 +        properly.\r
 128 +\r
 129 +    .. note::\r
 130 +\r
 131 +        Do remember that as soon as we tear down (e.g. via `del db`) this\r
 132 +        object, all underlying derived objects such as queries, threads,\r
 133 +        messages, tags etc will be freed by the underlying library as well.\r
 134 +        Accessing these objects will lead to segfaults and other unexpected\r
 135 +        behavior. See above for more details.\r
 136      """\r
 137      _std_db_path = None\r
 138      """Class attribute to cache user's default database"""\r
 139 @@ -253,10 +256,8 @@ class Database(object):\r
 140          neither begin nor end necessarily flush modifications to disk.\r
 141  \r
 142          :returns: :attr:`STATUS`.SUCCESS or raises\r
 143 -\r
 144 -        :exception: :exc:`NotmuchError`:\r
 145 -            :attr:`STATUS`.XAPIAN_EXCEPTION\r
 146 -                Xapian exception occurred; atomic section not entered.\r
 147 +        :exception: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION\r
 148 +                    Xapian exception occurred; atomic section not entered.\r
 149  \r
 150          *Added in notmuch 0.9*"""\r
 151          self._assert_db_is_initialized()\r
 152 @@ -295,9 +296,11 @@ class Database(object):\r
 153          """Returns a :class:`Directory` of path,\r
 154          (creating it if it does not exist(?))\r
 155  \r
 156 -        .. warning:: This call needs a writeable database in\r
 157 -           :attr:`Database.MODE`.READ_WRITE mode. The underlying library will\r
 158 -           exit the program if this method is used on a read-only database!\r
 159 +        .. warning::\r
 160 +\r
 161 +            This call needs a writeable database in\r
 162 +            :attr:`Database.MODE`.READ_WRITE mode. The underlying library will\r
 163 +            exit the program if this method is used on a read-only database!\r
 164  \r
 165          :param path: An unicode string containing the path relative to the path\r
 166                of database (see :meth:`get_path`), or else should be an absolute\r
 167 @@ -459,10 +462,11 @@ class Database(object):\r
 168      def find_message_by_filename(self, filename):\r
 169          """Find a message with the given filename\r
 170  \r
 171 -        .. warning:: This call needs a writeable database in\r
 172 -           :attr:`Database.MODE`.READ_WRITE mode. The underlying library will\r
 173 -           exit the program if this method is used on a read-only\r
 174 -           database!\r
 175 +        .. warning::\r
 176 +\r
 177 +            This call needs a writeable database in\r
 178 +            :attr:`Database.MODE`.READ_WRITE mode. The underlying library will\r
 179 +            exit the program if this method is used on a read-only database!\r
 180  \r
 181          :returns: If the database contains a message with the given\r
 182              filename, then a class:`Message:` is returned.  This\r
 183 @@ -791,10 +795,12 @@ class Directory(object):\r
 184            and know that it only needs to add files if the mtime of the\r
 185            directory and files are newer than the stored timestamp.\r
 186  \r
 187 -          .. note:: :meth:`get_mtime` function does not allow the caller\r
 188 -                 to distinguish a timestamp of 0 from a non-existent\r
 189 -                 timestamp. So don't store a timestamp of 0 unless you are\r
 190 -                 comfortable with that.\r
 191 +          .. note::\r
 192 +\r
 193 +                :meth:`get_mtime` function does not allow the caller to\r
 194 +                distinguish a timestamp of 0 from a non-existent timestamp. So\r
 195 +                don't store a timestamp of 0 unless you are comfortable with\r
 196 +                that.\r
 197  \r
 198            :param mtime: A (time_t) timestamp\r
 199            :returns: Nothing on success, raising an exception on failure.\r
 200 @@ -928,13 +934,16 @@ class Filenames(object):\r
 201      def __len__(self):\r
 202          """len(:class:`Filenames`) returns the number of contained files\r
 203  \r
 204 -        .. note:: As this iterates over the files, we will not be able to\r
 205 -               iterate over them again! So this will fail::\r
 206 +        .. note::\r
 207 +\r
 208 +            As this iterates over the files, we will not be able to\r
 209 +            iterate over them again! So this will fail::\r
 210  \r
 211                   #THIS FAILS\r
 212                   files = Database().get_directory('').get_child_files()\r
 213 -                 if len(files) > 0:              #this 'exhausts' msgs\r
 214 -                     # next line raises NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)!!!\r
 215 +                 if len(files) > 0:  # this 'exhausts' msgs\r
 216 +                     # next line raises\r
 217 +                     # NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)\r
 218                       for file in files: print file\r
 219          """\r
 220          if self._files_p is None:\r
 221 diff --git a/bindings/python/notmuch/message.py b/bindings/python/notmuch/message.py\r
 222 index 2534742..2f0fd92 100644\r
 223 --- a/bindings/python/notmuch/message.py\r
 224 +++ b/bindings/python/notmuch/message.py\r
 225 @@ -127,10 +127,12 @@ class Messages(object):\r
 226          """Return the unique :class:`Tags` in the contained messages\r
 227  \r
 228          :returns: :class:`Tags`\r
 229 -        :exceptions: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if not inited\r
 230 +        :exceptions: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if not init'ed\r
 231  \r
 232 -        .. note:: :meth:`collect_tags` will iterate over the messages and\r
 233 -          therefore will not allow further iterations.\r
 234 +        .. note::\r
 235 +\r
 236 +            :meth:`collect_tags` will iterate over the messages and therefore\r
 237 +            will not allow further iterations.\r
 238          """\r
 239          if self._msgs is None:\r
 240              raise NotmuchError(STATUS.NOT_INITIALIZED)\r
 241 @@ -358,14 +360,15 @@ class Message(object):\r
 242          """Gets all direct replies to this message as :class:`Messages`\r
 243          iterator\r
 244  \r
 245 -        .. note:: This call only makes sense if 'message' was\r
 246 -          ultimately obtained from a :class:`Thread` object, (such as\r
 247 -          by coming directly from the result of calling\r
 248 -          :meth:`Thread.get_toplevel_messages` or by any number of\r
 249 -          subsequent calls to :meth:`get_replies`). If this message was\r
 250 -          obtained through some non-thread means, (such as by a call\r
 251 -          to :meth:`Query.search_messages`), then this function will\r
 252 -          return `None`.\r
 253 +        .. note::\r
 254 +\r
 255 +            This call only makes sense if 'message' was ultimately obtained from\r
 256 +            a :class:`Thread` object, (such as by coming directly from the\r
 257 +            result of calling :meth:`Thread.get_toplevel_messages` or by any\r
 258 +            number of subsequent calls to :meth:`get_replies`). If this message\r
 259 +            was obtained through some non-thread means, (such as by a call to\r
 260 +            :meth:`Query.search_messages`), then this function will return\r
 261 +            `None`.\r
 262  \r
 263          :returns: :class:`Messages` or `None` if there are no replies to\r
 264              this message.\r
 265 @@ -646,7 +649,7 @@ class Message(object):\r
 266  \r
 267          This means that changes to the message state, (via :meth:`add_tag`,\r
 268          :meth:`remove_tag`, and :meth:`remove_all_tags`), will not be\r
 269 -        committed to the database until the message is :meth:`thaw`ed.\r
 270 +        committed to the database until the message is :meth:`thaw` ed.\r
 271  \r
 272          Multiple calls to freeze/thaw are valid and these calls will\r
 273          "stack". That is there must be as many calls to thaw as to freeze\r
 274 diff --git a/bindings/python/notmuch/tag.py b/bindings/python/notmuch/tag.py\r
 275 index f3a3d27..a77b68d 100644\r
 276 --- a/bindings/python/notmuch/tag.py\r
 277 +++ b/bindings/python/notmuch/tag.py\r
 278 @@ -113,11 +113,12 @@ class Tags(object):\r
 279      def __str__(self):\r
 280          """The str() representation of Tags() is a space separated list of tags\r
 281  \r
 282 -        .. note:: As this iterates over the tags, we will not be able\r
 283 -               to iterate over them again (as in retrieve them)! If\r
 284 -               the tags have been exhausted already, this will raise a\r
 285 -               :exc:`NotmuchError` STATUS.NOT_INITIALIZED on\r
 286 -               subsequent attempts.\r
 287 +        .. note::\r
 288 +\r
 289 +            As this iterates over the tags, we will not be able to iterate over\r
 290 +            them again (as in retrieve them)! If the tags have been exhausted\r
 291 +            already, this will raise a :exc:`NotmuchError`\r
 292 +            STATUS.NOT_INITIALIZED on subsequent attempts.\r
 293          """\r
 294          return " ".join(self)\r
 295  \r
 296 -- \r
 297 1.7.4.1\r
 298 \r