### Navigation

- index
- next |
- previous |
- OfflineImap 6.5.4 documentation »

# `offlineimap.repository` – Email repositories

A derivative of class `Base.BaseRepository` represents an email repository depending on the type of storage, possible options are:

> - `IMAPRepository`,
> - `MappedIMAPRepository`
> - `GmailRepository`,
> - `MaildirRepository`, or
> - `LocalStatusRepository`.

Which class you need depends on your account configuration. The helper class `offlineimap.repository.Repository` is an autoloader, that returns the correct class depending on your configuration. So when you want to instanciate a new `offlineimap.repository`, you will mostly do it through this class.

class `Repository`(account, reqtype)

  Abstract class that returns the correct Repository type instance based on ‘account’ and ‘reqtype’, e.g. a class:ImapRepository instance.

  Load the correct Repository type and return that. The __init__ of the corresponding Repository class will be executed instead of this stub

  Parameters:

  - account – `Account`
  - regtype – ‘remote’, ‘local’, or ‘status’

# `offlineimap.repository.Base.BaseRepository` – Representation of a mail repository

class `BaseRepository`(reposname, account)
  `accountname`

    Account name as string

  `connect`()

    Establish a connection to the remote, if necessary. This exists so that IMAP connections can all be established up front, gathering passwords as needed. It was added in order to support the error recovery – we need to connect first outside of the error trap in order to validate the password, and that’s the point of this function.

  `deletefolder`(foldername)
  `dropconnections`()
  `forgetfolders`()

    Forgets the cached list of folders, if any. Useful to run after a sync run.

  `get_create_folders`()

    Is folder creation enabled on this repository?

    It is disabled by either setting the whole repository ‘readonly’ or by using the ‘createfolders’ setting.

  `getaccount`()
  `getconf`(option, default=<function CustomConfigDefault at 0x936f2cc>)
  `getconfboolean`(option, default=<function CustomConfigDefault at 0x936f2cc>)
  `getconffloat`(option, default=<function CustomConfigDefault at 0x936f2cc>)
  `getconfig`()
  `getconfint`(option, default=<function CustomConfigDefault at 0x936f2cc>)
  `getfolder`(foldername)
  `getfolders`()

    Returns a list of ALL folders on this server.

  `getlocaleval`()
  `getmapdir`()
  `getname`()
  `getsection`()
  `getsep`()
  `getuiddir`()
  `holdordropconnections`()
  `makefolder`(foldername)

    Create a new folder

  `readonly`

    Is the repository readonly?

  `restore_atime`()

    Sets folders’ atime back to their values after a sync

    Controlled by the ‘restoreatime’ config parameter (default False), applies only to local Maildir mailboxes and does nothing on all other repository types.

  `startkeepalive`()

    The default implementation will do nothing.

  `stopkeepalive`()

    Stop keep alive, but don’t bother waiting for the threads to terminate.

  `sync_folder_structure`(dst_repo, status_repo)

    Syncs the folders in this repository to those in dest.

    It does NOT sync the contents of those folders. nametrans rules in both directions will be honored, but there are NO checks yet that forward and backward nametrans actually match up! Configuring nametrans on BOTH repositories therefore could lead to infinite folder creation cycles.

class `IMAPRepository`(reposname, account)

  Initialize an IMAPRepository object.

class `MappedIMAPRepository`(reposname, account)

  Initialize an IMAPRepository object.

class `GmailRepository`(reposname, account)

  Gmail IMAP repository.

  Falls back to hard-coded gmail host name and port, if none were specified: http://mail.google.com/support/bin/answer.py?answer=78799&topic=12814

  Initialize a GmailRepository object.

class `MaildirRepository`(reposname, account)

  Initialize a MaildirRepository object. Takes a path name to the directory holding all the Maildir directories.

class `LocalStatusRepository`(reposname, account)

# `offlineimap.folder` – Basic representation of a local or remote Mail folder

class `BaseFolder`(name, repository)

  Para name: | Path & name of folder minus root or reference
  Para repository:
  | Repository() in which the folder is.

  `accountname`

    Account name as string

  `addmessageflags`(uid, flags)

    Adds the specified flags to the message’s flag set. If a given flag is already present, it will not be duplicated.

    Note that this function does not check against dryrun settings, so you need to ensure that it is never called in a dryrun mode.

    Parameters: | flags – A set() of flags

  `addmessagesflags`(uidlist, flags)

    Note that this function does not check against dryrun settings, so you need to ensure that it is never called in a dryrun mode.

  `cachemessagelist`()

    Reads the message list from disk or network and stores it in memory for later use. This list will not be re-read from disk or memory unless this function is called again.

  `change_message_uid`(uid, new_uid)

    Change the message from existing uid to new_uid

    If the backend supports it (IMAP does not).

    Parameters: | new_uid – (optional) If given, the old UID will be changed to a new UID. This allows backends efficient renaming of messages if the UID has changed.

  `check_uidvalidity`()

    Tests if the cached UIDVALIDITY match the real current one

    If required it saves the UIDVALIDITY value. In this case the function is not threadsafe. So don’t attempt to call it from concurrent threads.

    Returns: | Boolean indicating the match. Returns True in case it implicitely saved the UIDVALIDITY.

  `copymessageto`(uid, dstfolder, statusfolder, register=1)

    Copies a message from self to dst if needed, updating the status

    Note that this function does not check against dryrun settings, so you need to ensure that it is never called in a dryrun mode.

    Parameters:

    - uid – uid of the message to be copied.
    - dstfolder – A BaseFolder-derived instance
    - statusfolder – A LocalStatusFolder instance
    - register – whether we should register a new thread.”

    Returns: | Nothing on success, or raises an Exception.

  `deletemessage`(uid)

    Note that this function does not check against dryrun settings, so you need to ensure that it is never called in a dryrun mode.

  `deletemessageflags`(uid, flags)

    Removes each flag given from the message’s flag set. If a given flag is already removed, no action will be taken for that flag.

    Note that this function does not check against dryrun settings, so you need to ensure that it is never called in a dryrun mode.

  `deletemessages`(uidlist)

    Note that this function does not check against dryrun settings, so you need to ensure that it is never called in a dryrun mode.

  `deletemessagesflags`(uidlist, flags)

    Note that this function does not check against dryrun settings, so you need to ensure that it is never called in a dryrun mode.

  `get_saveduidvalidity`()

    Return the previously cached UIDVALIDITY value

    Returns: | UIDVALIDITY as (long) number or None, if None had been saved yet.

  `get_uidvalidity`()

    Retrieve the current connections UIDVALIDITY value

    This function needs to be implemented by each Backend :returns: UIDVALIDITY as a (long) number

  `getcopyinstancelimit`()

    For threading folders, returns the instancelimitname for InstanceLimitedThreads.

  `getfolderbasename`()

    Return base file name of file to store Status/UID info in

  `getfullname`()
  `getmessage`(uid)

    Returns the content of the specified message.

  `getmessagecount`()

    Gets the number of messages.

  `getmessageflags`(uid)

    Returns the flags for the specified message.

  `getmessagelist`()

    Gets the current message list. You must call cachemessagelist() before calling this function!

  `getmessagetime`(uid)

    Return the received time for the specified message.

  `getmessageuidlist`()

    Gets a list of UIDs. You may have to call cachemessagelist() before calling this function!

  `getname`()

    Returns name

  `getrepository`()

    Returns the repository object that this folder is within.

  `getroot`()

    Returns the root of the folder, in a folder-specific fashion.

  `getsep`()

    Returns the separator for this folder type.

  `getvisiblename`()

    The nametrans-transposed name of the folder’s name

  `save_uidvalidity`()

    Save the UIDVALIDITY value of the folder to the cache

    This function is not threadsafe, so don’t attempt to call it from concurrent threads.

  `savemessage`(uid, content, flags, rtime)

    Writes a new message, with the specified uid.

    If the uid is < 0: The backend should assign a new uid and

      return it. In case it cannot assign a new uid, it returns the negative uid passed in WITHOUT saving the message.

      If the backend CAN assign a new uid, but cannot find out what this UID is (as is the case with some IMAP servers), it returns 0 but DOES save the message.

      IMAP backend should be the only one that can assign a new uid.

    If the uid is > 0, the backend should set the uid to this, if it can.
      If it cannot set the uid to that, it will save it anyway. It will return the uid assigned in any case.

    Note that savemessage() does not check against dryrun settings, so you need to ensure that savemessage is never called in a dryrun mode.

  `savemessageflags`(uid, flags)

    Sets the specified message’s flags to the given set.

    Note that this function does not check against dryrun settings, so you need to ensure that it is never called in a dryrun mode.

  `storesmessages`()

    Should be true for any backend that actually saves message bodies. (Almost all of them). False for the LocalStatus backend. Saves us from having to slurp up messages just for localstatus purposes.

  `suggeststhreads`()

    Returns true if this folder suggests using threads for actions; false otherwise. Probably only IMAP will return true.

  `sync_this` = None

    Should this folder be included in syncing?

  `syncmessagesto`(dstfolder, statusfolder)

    Syncs messages in this folder to the destination dstfolder.

    This is the high level entry for syncing messages in one direction. Syncsteps are:

    Pass1: Copy locally existing messages
      Copy messages in self, but not statusfolder to dstfolder if not already in dstfolder. dstfolder might assign a new UID (e.g. if uploading to IMAP). Update statusfolder.
    Pass2: Remove locally deleted messages

      Get all UIDS in statusfolder but not self. These are messages that were deleted in ‘self’. Delete those from dstfolder and statusfolder.

      After this pass, the message lists should be identical wrt the uids present (except for potential negative uids that couldn’t be placed anywhere).

    Pass3: Synchronize flag changes
      Compare flag mismatches in self with those in statusfolder. If msg has a valid UID and exists on dstfolder (has not e.g. been deleted there), sync the flag change to both dstfolder and statusfolder.

    Parameters:

    - dstfolder – Folderinstance to sync the msgs to.
    - statusfolder – LocalStatus instance to sync against.

  `syncmessagesto_copy`(dstfolder, statusfolder)

    Pass1: Copy locally existing messages not on the other side

    This will copy messages to dstfolder that exist locally but are not in the statusfolder yet. The strategy is:

    1. Look for messages present in self but not in statusfolder.
    2. invoke copymessageto() on those which: - If dstfolder doesn’t have it yet, add them to dstfolder. - Update statusfolder

    This function checks and protects us from action in ryrun mode.

  `syncmessagesto_delete`(dstfolder, statusfolder)

    Pass 2: Remove locally deleted messages on dst

    Get all UIDS in statusfolder but not self. These are messages that were deleted in ‘self’. Delete those from dstfolder and statusfolder.

    This function checks and protects us from action in ryrun mode.

  `syncmessagesto_flags`(dstfolder, statusfolder)

    Pass 3: Flag synchronization

    Compare flag mismatches in self with those in statusfolder. If msg has a valid UID and exists on dstfolder (has not e.g. been deleted there), sync the flag change to both dstfolder and statusfolder.

    This function checks and protects us from action in ryrun mode.

  `uidexists`(uid)

    Returns True if uid exists

### Navigation

- index
- next |
- previous |
- OfflineImap 6.5.4 documentation »