docs: remove obsolete comment about SubmittingPatches.rst
Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
This commit is contained in:
Nicolas Sebrecht
parent
4589cfeff2
commit
532278b4dd
|
|
@ -15,10 +15,9 @@ OfflineImap can be imported as::
|
|||
|
||||
from offlineimap import OfflineImap
|
||||
|
||||
The file ``SubmittingPatches.rst`` in the source distribution documents a
|
||||
number of resources and conventions you may find useful. It will eventually
|
||||
be merged into the main documentation.
|
||||
.. TODO: merge SubmittingPatches.rst to the main documentation
|
||||
The file ``HACKING.rst`` in the source distribution documents a
|
||||
number of resources and conventions you may find useful.
|
||||
|
||||
|
||||
:mod:`offlineimap` -- The OfflineImap module
|
||||
=============================================
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
Message filtering
|
||||
=================
|
||||
|
||||
There are two ways to selectively filter messages out of a folder, using `maxsize` and `maxage`. Setting each option will basically ignore all messages that are on the server by pretending they don't exist.
|
||||
There are two ways to selectively filter messages out of a folder, using
|
||||
`maxsize` and `maxage`. Setting each option will basically ignore all messages
|
||||
that are on the server by pretending they don't exist.
|
||||
|
||||
:todo: explain them and give tipps on how to use and not use them. Use cases!
|
||||
:todo: explain them and give tips on how to use and not use them. Use cases!
|
||||
|
||||
maxage
|
||||
------
|
||||
|
|
|
|||
|
|
@ -13,7 +13,10 @@ safely skip this section.
|
|||
folderfilter
|
||||
------------
|
||||
|
||||
If you do not want to synchronize all your folders, you can specify a `folderfilter`_ function that determines which folders to include in a sync and which to exclude. Typically, you would set a folderfilter option on the remote repository only, and it would be a lambda or any other python function.
|
||||
If you do not want to synchronize all your folders, you can specify a
|
||||
`folderfilter`_ function that determines which folders to include in a sync and
|
||||
which to exclude. Typically, you would set a folderfilter option on the remote
|
||||
repository only, and it would be a lambda or any other python function.
|
||||
|
||||
The only parameter to that function is the folder name. If the filter
|
||||
function returns True, the folder will be synced, if it returns False,
|
||||
|
|
@ -45,12 +48,18 @@ at the end when required by Python syntax) For instance::
|
|||
['INBOX', 'Sent Mail', 'Deleted Items',
|
||||
'Received']
|
||||
|
||||
Usually it suffices to put a `folderfilter`_ setting in the remote repository section. You might want to put a folderfilter option on the local repository if you want to prevent some folders on the local repository to be created on the remote one. (Even in this case, folder filters on the remote repository will prevent that)
|
||||
Usually it suffices to put a `folderfilter`_ setting in the remote repository
|
||||
section. You might want to put a folderfilter option on the local repository if
|
||||
you want to prevent some folders on the local repository to be created on the
|
||||
remote one. (Even in this case, folder filters on the remote repository will
|
||||
prevent that)
|
||||
|
||||
folderincludes
|
||||
--------------
|
||||
|
||||
You can specify `folderincludes`_ to manually include additional folders to be synced, even if they had been filtered out by a folderfilter setting. `folderincludes`_ should return a Python list.
|
||||
You can specify `folderincludes`_ to manually include additional folders to be
|
||||
synced, even if they had been filtered out by a folderfilter setting.
|
||||
`folderincludes`_ should return a Python list.
|
||||
|
||||
This can be used to 1) add a folder that was excluded by your
|
||||
folderfilter rule, 2) to include a folder that your server does not specify
|
||||
|
|
@ -84,11 +93,14 @@ nametrans`_ rules on the LOCAL repository.
|
|||
nametrans
|
||||
----------
|
||||
|
||||
Sometimes, folders need to have different names on the remote and the
|
||||
local repositories. To achieve this you can specify a folder name
|
||||
translator. This must be a eval-able Python expression that takes a
|
||||
foldername arg and returns the new value. We suggest a lambda function,
|
||||
but it could be any python function really. If you use nametrans rules, you will need to set them both on the remote and the local repository, see `Reverse nametrans`_ just below for details. The following examples are thought to be put in the remote repository section.
|
||||
Sometimes, folders need to have different names on the remote and the local
|
||||
repositories. To achieve this you can specify a folder name translator. This
|
||||
must be a eval-able Python expression that takes a foldername arg and returns
|
||||
the new value. We suggest a lambda function, but it could be any python
|
||||
function really. If you use nametrans rules, you will need to set them both on
|
||||
the remote and the local repository, see `Reverse nametrans`_ just below for
|
||||
details. The following examples are thought to be put in the remote repository
|
||||
section.
|
||||
|
||||
The below will remove "INBOX." from the leading edge of folders (great
|
||||
for Courier IMAP users)::
|
||||
|
|
@ -112,38 +124,59 @@ locally? Try this::
|
|||
Reverse nametrans
|
||||
+++++++++++++++++
|
||||
|
||||
Since 6.4.0, OfflineImap supports the creation of folders on the remote repository and that complicates things. Previously, only one nametrans setting on the remote repository was needed and that transformed a remote to a local name. However, nametrans transformations are one-way, and OfflineImap has no way using those rules on the remote repository to back local names to remote names.
|
||||
Since 6.4.0, OfflineImap supports the creation of folders on the remote
|
||||
repository and that complicates things. Previously, only one nametrans setting
|
||||
on the remote repository was needed and that transformed a remote to a local
|
||||
name. However, nametrans transformations are one-way, and OfflineImap has no way
|
||||
using those rules on the remote repository to back local names to remote names.
|
||||
|
||||
Take a remote nametrans rule `lambda f: re.sub('^INBOX/','',f)` which cuts off any existing INBOX prefix. Now, if we parse a list of local folders, finding e.g. a folder "Sent", is it supposed to map to "INBOX/Sent" or to "Sent"? We have no way of knowing. This is why **every nametrans setting on a remote repository requires an equivalent nametrans rule on the local repository that reverses the transformation**.
|
||||
Take a remote nametrans rule `lambda f: re.sub('^INBOX/','',f)` which cuts off
|
||||
any existing INBOX prefix. Now, if we parse a list of local folders, finding
|
||||
e.g. a folder "Sent", is it supposed to map to "INBOX/Sent" or to "Sent"? We
|
||||
have no way of knowing. This is why **every nametrans setting on a remote
|
||||
repository requires an equivalent nametrans rule on the local repository that
|
||||
reverses the transformation**.
|
||||
|
||||
Take the above examples. If your remote nametrans setting was::
|
||||
|
||||
nametrans = lambda folder: re.sub('^INBOX\.', '', folder)
|
||||
|
||||
then you will want to have this in your local repository, prepending "INBOX" to any local folder name::
|
||||
then you will want to have this in your local repository, prepending "INBOX" to
|
||||
any local folder name::
|
||||
|
||||
nametrans = lambda folder: 'INBOX.' + folder
|
||||
|
||||
Failure to set the local nametrans rule will lead to weird-looking error messages of -for instance- this type::
|
||||
Failure to set the local nametrans rule will lead to weird-looking error
|
||||
messages of -for instance- this type::
|
||||
|
||||
ERROR: Creating folder moo.foo on repository remote
|
||||
Folder 'moo.foo'[remote] could not be created. Server responded: ('NO', ['Unknown namespace.'])
|
||||
|
||||
(This indicates that you attempted to create a folder "Sent" when all remote folders needed to be under the prefix of "INBOX.").
|
||||
(This indicates that you attempted to create a folder "Sent" when all remote
|
||||
folders needed to be under the prefix of "INBOX.").
|
||||
|
||||
OfflineImap will make some sanity checks if it needs to create a new
|
||||
folder on the remote side and a back-and-forth nametrans-lation does not
|
||||
yield the original foldername (as that could potentially lead to
|
||||
infinite folder creation cycles).
|
||||
|
||||
You can probably already see now that creating nametrans rules can be a pretty daunting and complex endeavour. Check out the Use cases in the manual. If you have some interesting use cases that we can present as examples here, please let us know.
|
||||
You can probably already see now that creating nametrans rules can be a pretty
|
||||
daunting and complex endeavour. Check out the Use cases in the manual. If you
|
||||
have some interesting use cases that we can present as examples here, please let
|
||||
us know.
|
||||
|
||||
Debugging folderfilter and nametrans
|
||||
------------------------------------
|
||||
|
||||
Given the complexity of the functions and regexes involved, it is easy to misconfigure things. One way to test your configuration without danger to corrupt anything or to create unwanted folders is to invoke offlineimap with the `--info` option.
|
||||
Given the complexity of the functions and regexes involved, it is easy to
|
||||
misconfigure things. One way to test your configuration without danger to
|
||||
corrupt anything or to create unwanted folders is to invoke offlineimap with the
|
||||
`--info` option.
|
||||
|
||||
It will output a list of folders and their transformations on the screen (save them to a file with -l info.log), and will help you to tweak your rules as well as to understand your configuration. It also provides good output for bug reporting.
|
||||
It will output a list of folders and their transformations on the screen (save
|
||||
them to a file with -l info.log), and will help you to tweak your rules as well
|
||||
as to understand your configuration. It also provides good output for bug
|
||||
reporting.
|
||||
|
||||
FAQ on nametrans
|
||||
----------------
|
||||
|
|
|
|||
|
|
@ -3,7 +3,10 @@
|
|||
|
||||
.. currentmodule:: offlineimap.ui
|
||||
|
||||
OfflineImap has various ui systems, that can be selected. They offer various functionalities. They must implement all functions that the :class:`offlineimap.ui.UIBase` offers. Early on, the ui must be set using :meth:`getglobalui`
|
||||
OfflineImap has various ui systems, that can be selected. They offer various
|
||||
functionalities. They must implement all functions that the
|
||||
:class:`offlineimap.ui.UIBase` offers. Early on, the ui must be set using
|
||||
:meth:`getglobalui`
|
||||
|
||||
.. automethod:: offlineimap.ui.setglobalui
|
||||
.. automethod:: offlineimap.ui.getglobalui
|
||||
|
|
|
|||
Loading…
Reference in New Issue