#! /usr/bin/env python
# -*- coding: iso-8859-1 -*-

# Based on Id: sample.py,v 4.1.2.6 2006/04/14 13:59:26 cvs Exp

# Copyright 2005, 2006, 2007, 2009 Stefan Merten <smerten@oekonux.de>

# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

"""
Put pages to a MoinMoin Wiki from various sources.

Do

	perldoc moinupdate.py

for a man page.
"""

"""
=head1 NAME

moinupdate.py -- put pages to a MoinMoin Wiki from various sources

=head1 SYNOPSIS

B<moinupdate.py> I<source-option> [I<option>]... I<target-url> [I<page>]...

B<moinupdate.py> B<--help>

=head1 DESCRIPTION

Put pages to a MoinMoin Wiki at I<target-url> by the XML-RPC interface (V2).
The pages are taken from the source given by the I<source-option>.

=cut
"""

###############################################################################
###############################################################################
# Import

import sys
import os.path
import re

import smtplib
from email.MIMEMultipart import MIMEMultipart
from email.MIMEText import MIMEText

from optparse import OptionParser, OptionGroup, OptionValueError, Option
from copy import copy

import pwd
import os

import socket
import xmlrpclib
import codecs
import urllib
from sets import Set

import warnings
warnings.filterwarnings('ignore', "tempnam")

from xml.dom import minidom, Node

###############################################################################
###############################################################################
# Constants

global MergeModes
# First entry is used as default
MergeModes = ( 'clean', 'ignore', 'save', 'force', )

global AuthTypes
# First entry is used as default, last is used implicitly
AuthTypes = ( 'basic', 'moin', 'none', )

###############################################################################
###############################################################################
# Variables

"""
@var options: Options given on the command line
@type options: optparse.Values
"""
global options

###############################################################################
###############################################################################
# Classes

# MoinAuth support based on contribution from Markus Demleitner
class AuthServerProxy(object):
    """
    A wrapper around xmlrpclib.ServerProxy that adds xmlrpc auth to
    method calls.

    @ivar _proxy: The delegate to which all calls are given.
    @type _proxy: xmlrpclib.ServerProxy

    @ivar _authToken: The token used for authentication. Generated by the
                      server.
    @type _authToken: str?
    """

    def __init__(self, fullUrl, account, password):
        """
        Initialize the proxy connection.

        @param fullUrl: URL to the Wiki.
        @type fullUrl: str

        @param account: Account name to authenticate with.
        @type account: str

        @param password: Password to authenticate with.
        @type password: str

        @raise IOError: If authentication fails.
        """
        self._proxy = xmlrpclib.ServerProxy(fullUrl)
        self._authToken = self._proxy.getAuthToken(account, password)
        if not self._authToken:
            raise IOError(-1, ("Can not authenticate at Wiki %r using MoinAuth for account %r"
                               % ( fullUrl, account, )))

    def _wrapMethod(self, name):

        def wrapped(*args, **kwargs):
            multicall = xmlrpclib.MultiCall(self._proxy)
            multicall.applyAuthToken(self._authToken)
            getattr(multicall, name)(*args, **kwargs)
            results = multicall()
            if isinstance(results[0], xmlrpclib.Fault):
                raise IOError(-1, ("Can not re-authenticate using MoinAuth token %r"
                                   % ( self._authToken, )))
            return results[1]

        return wrapped

    def __getattr__(self, name):
        return self._wrapMethod(name)

###############################################################################

# TODO This is bad design because for a couple of fields the user of this type
#      needs to know how the `ChangeEntry` was created because filling of
#      certain values depends on the constructor currently. One solution would
#      be to create different subclasses which have a defined behavior. Another
#      solution would be to get the information dynamic which may be hard to do
#      sometimes.
class ChangeEntry(object):
    """
    Describes an entry in a RecentChanges list. This is for all practical
    purposes an immutable type.

    @ivar _pageName: Name of the changed page.
    @type _pageName: unicode

    @ivar _version: Version number this change created.
    @type _version: int

    @ivar _author: Account under which the change was made if available.
    @type _author: unicode

    @ivar _timestamp: Date and time the change took place.
    @type _timestamp: xmlrpclib.DateTime

    @ivar _comment: Comment for this change or C{None} if unknown.
    @type _comment: unicode | None

    @ivar _renameOrResurrect: Flag for rename or resurrection or C{None} if
                              unknown.
    @type _renameOrResurrect: bool | None

    @ivar _delete: Flag flagging deletion or C{None} if unknown.
    @type _delete: bool | None

    @ivar _renamedFrom: If this was a rename the name of the original page or
                        empty string for no rename of C{None} if unknown.
                        This field may be modified if queried.
    @type _renamedFrom: unicode | None
    """

    ##########################################################################

    def __init__(self, pageName, version, author, timestamp, comment=None, renameOrResurrect=None, delete=None, renamedFrom=None):
        if isinstance(pageName, unicode):
            self._pageName = pageName
        else:
            self._pageName = unicode(pageName, 'utf-8')
        self._version = int(version)
        if isinstance(author, unicode):
            self._author = author
        else:
            self._author = unicode(author, 'utf-8')
        self._timestamp = timestamp
        if isinstance(comment, str):
            self._comment = unicode(comment, 'utf-8')
        else:
            self._comment = comment
        self._renameOrResurrect = renameOrResurrect
        self._delete = delete
        if isinstance(renamedFrom, str):
            self._renamedFrom = unicode(renamedFrom, 'utf-8')
        else:
            self._renamedFrom = renamedFrom

    ##########################################################################

    def __str__(self):
        return ("%r changed by %r on %s to version %d"
                % ( self._pageName, self._author, self._timestamp,
                    self._version, ))

    ##########################################################################

    def __repr__(self):
        return ("ChangeEntry(%r, %r, %r, %r, comment=%r, renameOrResurrect=%r, delete=%r, renamedFrom=%r)"
                % ( self._pageName, self._version, self._author,
                    self._timestamp, self._comment, self._renameOrResurrect,
                    self._delete, self._renamedFrom, ))

    ##########################################################################

    def __eq__(self, other):
        return (self._timestamp == other._timestamp
                and self._version == other._version
                and self._pageName == other._pageName
                and self._author == other._author)

    ##########################################################################

    def __ne__(self, other):
        return not self.__eq__(other)

    ##########################################################################

    def __cmp__(self, other):
        # Define a total ordering so this is compatible with `__eq__'/`__ne__'
        return (self._timestamp.__cmp__(other._timestamp)
                or self._version.__cmp__(other._version)
                or self._pageName.__cmp__(other._pageName)
                or self._author.__cmp__(other._author))

    ##########################################################################

    def getPageName(self):
        return self._pageName

    ##########################################################################

    def getVersion(self):
        return self._version

    ##########################################################################

    def getAuthor(self):
        return self._author

    ##########################################################################

    def getComment(self, unknown):
        """
        @param unknown: Value to return for unknown values.
        @type unknown: any

        @return: Comment if known or C{unknown}
        @rtype: unicode | any
        """
        if self._comment is None:
            return unknown
        return self._comment

    ##########################################################################

    def getRenameOrResurrect(self, unknown):
        """
        @param unknown: Value to return for unknown values.
        @type unknown: any

        @return: Rename or resurrect flag if known or C{unknown}
        @rtype: bool | any
        """
        if self._renameOrResurrect is None:
            return unknown
        return self._renameOrResurrect

    ##########################################################################

    def getDelete(self, unknown):
        """
        @param unknown: Value to return for unknown values.
        @type unknown: any

        @return: Delete flag if known or C{unknown}
        @rtype: bool | any
        """
        if self._delete is None:
            return unknown
        return self._delete

    ##########################################################################

    def getRenamedFrom(self, wiki, currentPageName, unknown):
        """
        Tries to determine name of page this change was a rename from. CHANGES
        the object if necessary!

        @param wiki: Wiki to get more information from.
        @type wiki: Wiki

        @param currentPageName: Most recent name of the page in C{wiki} so more
                                information can be queried from this page.
        @type currentPageName: unicode

        @param unknown: Value to return for unknown values.
        @type unknown: any

        @return: If this was a rename the name of the original page, if this
                 was no rename the empty string or C{unknown} if not known.
        @rtype: unicode | any
        """
        if self._renamedFrom is None:
            if self._renameOrResurrect is None:
                # Nothing known about these things
                return unknown
            if not self._renameOrResurrect:
                self._renamedFrom = u""
            else:
                # Query Wiki for this page and use the result of the query
                # regardless of its outcome
                self._renamedFrom = wiki.getPageInfo(currentPageName,
                                                     self.getVersion())._renamedFrom
                # Yes, this may mean that the query is repeated later but that
                # would mean that `self._renameOrResurrect` is not C{None}
                # which is never the case if there can be a result at all
        return self._renamedFrom

###############################################################################

class NoSuchPage(Exception):
    """
    An exception to indicate a missing page.

    @ivar name: Name of the page.
    @type name: unicode

    @ivar version: Version of the page looked for. C{None} means most recent.
    @type version: int | None
    """

    ###########################################################################

    def __init__(self, name, version=None):
        Exception.__init__(self, name, version)
        self.name = name
        self.version = version

    ###########################################################################

    def __str__(self):
        return "No such page: %r V%s" % ( self.name, self.version, )

###############################################################################

class NotAllowed(Exception):
    """
    An exception to indicate some denied access.

    @ivar name: Name of the page.
    @type name: unicode

    @ivar version: Version of the page looked for. C{None} means most recent.
    @type version: int | None
    """

    ###########################################################################

    def __init__(self, name, version=None):
        Exception.__init__(self, name, version)
        self.name = name
        self.version = version

    ###########################################################################

    def __str__(self):
        return ("Access to page %r V%s not allowed"
                % ( self.name, self.version, ))

###############################################################################

class PageAlreadyExists(Exception):
    """
    An exception to indicate a already existing page.

    @ivar name: Name of the page.
    @type name: unicode
    """

    ###########################################################################

    def __init__(self, name):
        Exception.__init__(self, name)
        self.name = name

    ###########################################################################

    def __str__(self):
        return "Page already exists: %r" % ( self.name, )

###############################################################################

# TODO Support for unsupported or half-supported functionality makes code
#      difficult and error-prone; it would be easier to simply require a
#      certain set of functionality or at least either require standard
#      functionality or a certain version of `remoteMoin` plugins.
class NotSupported(Exception):
    """
    An exception to indicate some possible but missing functionality in a Wiki.

    @ivar operation: Name of the operation.
    @type operation: unicode
    """

    ###########################################################################

    def __init__(self, operation):
        Exception.__init__(self, operation)
        self.operation = operation

    ###########################################################################

    def __str__(self):
        return ("Operation %r not supported" % ( self.operation, ))

###############################################################################

class Wiki(object):
    """
    An interface to access a Wiki in a uniform way.
    """

    ###########################################################################

    def getPage(self, pageName, version=None):
        """
        Get a page from the Wiki.

        @param pageName: The name of the page in the Wiki.
        @type pageName: unicode

        @param version: Version to get or C{None} for most recent version.
                        Defaults to C{None}. First version is usually number 1,
                        second version number 2 and so on. Deletion of pages
                        doesn't reset the counter, however.
        @type version: int | None

        @return: The data of the page from the Wiki. It has always a trailing
                 linefeed regardless whether there was one.
        @rtype: unicode

        @raise IOError: When the connection doesn't work.
        @raise IOError: Unknown XML-RPC fault.
        @raise NoSuchPage: Page does not exist in this version.
        @raise NotAllowed: Read access is not allowed.
        """
        raise NotImplementedError

    ###########################################################################

    def getPageInfo(self, pageName, version=None):
        """
        Get information for a page from a Wiki.

        @param pageName: The name of the page in the Wiki.
        @type pageName: unicode

        @param version: Version to get or C{None} for most recent version.
                        Defaults to C{None}
        @type version: int | None

        @return: A change entry containing all the information or C{None} if
                 the page does not exist (in this version) or I{version} is
                 C{0}.
        @rtype: ChangeEntry | None

        @raise IOError: When the connection doesn't work.
        @raise IOError: Unknown XML-RPC fault.
        @raise NoSuchPage: Page does not exist in this version.
        @raise NotAllowed: Read access is not allowed.
        """
        raise NotImplementedError

    ###########################################################################

    def putPage(self, pageName, pageData, comment=None, minorEdit=None):
        """
        Put a page to this Wiki.

        @param pageName: The name of the page in the target Wiki.
        @type pageName: unicode

        @param pageData: The data of the page to put to the target Wiki.
        @type pageData: unicode

        @param comment: A comment for this change or C{None} for no comment.
                        Defaults to C{None}.
        @type comment: unicode | None

        @param minorEdit: A flag to mark this as minor edit or C{None} for no
                          flag. Defaults to C{None}.
        @type minorEdit: bool | None

        @raise IOError: When the connection doesn't work.
        @raise IOError: Unknown XML-RPC fault.
        @raise NotAllowed: Edit access is not allowed.
        """
        raise NotImplementedError

    ###########################################################################

    # TODO Getting all changes might be too much for an active Wiki
    def getRecentChanges(self, pages, sinceWhen="1970-01-01T00:00:00"):
        """
        @param pages: List of page names to consider. All pages are
                      considered if empty.
        @type pages: ( unicode, ..., )

        @param sinceWhen: Timestamp after which recent changes are fetched.
                          Must be given in ISO notation. Defaults to the
                          beginning of the era.
        @type sinceWhen: str

        @return: Recent changes with most recent change last.
        @rtype: [ ChangeEntry, ..., ]

        @raise IOError: When the connection doesn't work.
        @raise IOError: Unknown XML-RPC fault.
        """
        raise NotImplementedError

    ###########################################################################

    def deletePage(self, pageName, comment=u""):
        """
        Delete a page in this Wiki.

        @param pageName: The name of the page in the target Wiki.
        @type pageName: unicode

        @param comment: A comment for the deletion.
        @type comment: unicode

        @raise IOError: When the connection doesn't work.
        @raise IOError: Unknown XML-RPC fault.
        @raise NotAllowed: Deletion access is not allowed.
        @raise NotSupported: When the operation could be available in the
                             target Wiki but is not.
        """
        raise NotImplementedError

    ###########################################################################

    def renamePage(self, fromName, toName, comment=u""):
        """
        Rename a page in this Wiki.

        @param fromName: The name of the original page in the target Wiki.
        @type fromName: unicode

        @param toName: The name of the new page in the target Wiki.
        @type toName: unicode

        @param comment: A comment for the rename.
        @type comment: unicode

        @raise IOError: When the connection doesn't work.
        @raise IOError: Unknown XML-RPC fault.
        @raise NotAllowed: Rename access is not allowed.
        @raise PageAlreadyExists: Target page already exists.
        @raise NoSuchPage: Original page does not exist.
        @raise NotSupported: When the operation could be available in the
                             target Wiki but is not.
        """
        raise NotImplementedError

###############################################################################

class MoinWiki(Wiki):
    """
    A class for accessing a MoinMoin Wiki.

    @cvar _SPECIALCHANGE_VERSION: Version number used for special changes like
                                  attachments in the recent changes list.
    @type _SPECIALCHANGE_VERSION: int

    @ivar _connection: The connection to the Wiki.
    @type _connection: xmlrpclib.ServerProxy

    @ivar _sinceWhen2RecentChanges: Cache for recent changes. Maps a timestamp
                                    to a complete tuple of recent changes.
    @type _sinceWhen2RecentChanges: { str: ( ChangeEntry, ..., ), ..., }

    @ivar _baseUrl: Base URL to name the Wiki.
    @type _baseUrl: str

    @ivar _supported: Maps names of operation to a flag indicating whether
                      the operation is supported.
    @type _supported: { str: bool, ..., }
    """

    _SPECIALCHANGE_VERSION = 99999999
    
    ##########################################################################

    def __init__(self, baseUrl, authType=AuthTypes[-1], account="", password=""):
        """
        @param baseUrl: Base URL of the Wiki where XML-RPC access is possible.
        @type baseUrl: str

        @param authType: Authentication type to use. Must be one of
                         `AuthTypes'. Defaults to the implicitly used value
                         ('none').
        @type authType: str

        @param account: Account to use for authentication. Empty for no account
                        (probably for read access only). Defaults to
                        the empty string.
        @type account: str

        @param password: Password to use for BasicAuthentication. Only used
                         when C{account} is non-empty. Defaults to the empty
                         string.
        @type password: str

        @raise IOError: When connection doesn't work.
        @raise ValueError: When an unknown authentication type is given.
        """
        self._baseUrl = baseUrl
        fullUrl = "%s/?action=xmlrpc2" % ( baseUrl, )
        if authType == 'none':
            self._connection = xmlrpclib.ServerProxy(fullUrl)
        elif authType == 'basic':
            from MoinMoin.support.BasicAuthTransport import BasicAuthTransport

            transport = BasicAuthTransport(account, password)
	    transport._use_datetime = 0 # Needed for Python 2.5 `Transport`
            self._connection = xmlrpclib.ServerProxy(fullUrl,
                                                     transport=transport)
        elif authType == 'moin':
            try:
                self._connection = AuthServerProxy(fullUrl, account, password)
            except IOError:
                raise
        else:
            raise ValueError

        # Test connection before going on
        try:
            self._connection.getRPCVersionSupported()
        except Exception, exception:
            raise IOError(-1, ("No connection to Wiki %r: %s"
                               % ( baseUrl, str(exception), )))

        self._sinceWhen2RecentChanges = { }
        self._supported = { }

    ###########################################################################

    def getPage(self, pageName, version=None):
        try:
            if version is None:
                fault = self._connection.getPage(pageName)
            else:
                fault = self._connection.getPageVersion(pageName, version)
        except socket.error, exception:
            raise self.__socketError2IOError(exception)
        except xmlrpclib.Fault, fault:
            pass
        self.__raiseIfFault(fault, pageName, version)

        if isinstance(fault, unicode):
            # The page as Unicode string
            data = fault
        else:
            # The page as UTF-8
            data = unicode(fault, 'utf-8')
        if not data.endswith("\n"):
            data += "\n"
        return data

    ###########################################################################

    def getPageInfo(self, pageName, version=None):
        if version == 0:
            return None

        try:
            return self._getPageInfoVersionWithAttributes(pageName,
                                                          version or 0)
        except:
            # If this didn't work try the standard call
            pass

        if version is None:
            try:
                fault = self._connection.getPageInfo(pageName)
            except socket.error, exception:
                raise self.__socketError2IOError(exception)
            except xmlrpclib.Fault, fault:
                pass
            self.__raiseIfFault(fault, pageName, version)

            return ChangeEntry(fault['name'], fault['version'],
                               fault.get('author', u""), fault['lastModified'])
        else:
            # A specific version is wanted
            changes = self.getRecentChanges(( pageName, ))
            founds = [ entry
                       for entry in changes
                       if entry.getVersion() == version ]
            if not founds:
                # No such version
                # TODO This could try harder by getting a more recent version
                #      of recent changes if the required version is bigger than
                #      the biggest version seen; makes only sense if
                #      `getRecentChanges' uses cached data
                raise NoSuchPage(pageName, version)
            else:
                return founds[0]

    ###########################################################################

    def _getPageInfoVersionWithAttributes(self, pageName, version):
        """
        Tries to get page info with attributes.

        Parameters, exceptions and return value are as for C{getPageInfo}().

        @param version: Version to get or C{0} for the most recent version.
        @type version: int

        @raise NotSupported: If the operation is not supported by this Wiki.
        """
        operation = "getPageInfoVersionWithAttributes"
        if not self._getSupported(operation):
            raise NotSupported(operation)

        try:
            result = self._connection.getPageInfoVersionWithAttributes(pageName,
                                                                       version)
        except socket.error, exception:
            raise self.__socketError2IOError(exception)
        except xmlrpclib.Fault, result:
            pass
        self.__raiseIfFault(result, pageName, operation=operation)
        # TODO Could store `action` and `extra` if present
        # TODO Could store `extra` to `revertedFrom` if `action` is
        #      ``SAVE/REVERT``; `revertedFrom` could be used for real reverts
        #      in the target
        return ChangeEntry(result['name'], result['version'],
                           result.get('author', u""), result['lastModified'],
                           comment=result['comment'],
                           renameOrResurrect=result['renameOrResurrect'],
                           delete=result['delete'],
                           renamedFrom=result.get('renamedFrom', u""))

    ###########################################################################

    def getRecentChanges(self, pages, sinceWhen="1970-01-01T00:00:00"):
        """
        Caches full queries.
        """
        if self._sinceWhen2RecentChanges.has_key(sinceWhen):
            # This is an expensive operation so use a cache if possible
            changes = list(self._sinceWhen2RecentChanges[sinceWhen])
        else:
            try:
                return self._getRecentChangesWithAttributes(pages, sinceWhen)
            except:
                # If this didn't work try the standard call
                pass

            try:
                changesXmlRpc = self._connection.getRecentChanges(xmlrpclib.DateTime(sinceWhen))
            except socket.error, exception:
                raise self.__socketError2IOError(exception)
            except xmlrpclib.Fault, changesXmlRpc:
                pass
            self.__raiseIfFault(changesXmlRpc, u"")
            # TODO Special changes must be considered
            changes = [ ChangeEntry(entry['name'], entry['version'],
                                    entry.get('author', ""),
                                    entry['lastModified'])
                        for entry in changesXmlRpc
                        if entry['version'] != self._SPECIALCHANGE_VERSION ]
            changes.reverse()

            self._sinceWhen2RecentChanges[sinceWhen] = tuple(changes)
            verboseOut(( "%d total changes in Wiki `%s'"
                         % ( len(changes), self._baseUrl, ), ))
        if pages:
            changes = [ entry
                        for entry in changes
                        if entry.getPageName() in pages ]
        return changes

    ###########################################################################

    def _getRecentChangesWithAttributes(self, pages, sinceWhen):
        """
        Tries to get recent changes with attributes.

        Parameters, exceptions and return value are as for
        C{getRecentChanges}().

        @raise NotSupported: If the operation is not supported by this Wiki.
        """
        operation = "getRecentChangesWithAttributes"
        if not self._getSupported(operation):
            raise NotSupported(operation)

        try:
            results = self._connection.getRecentChangesWithAttributes(xmlrpclib.DateTime(sinceWhen), pages)
        except socket.error, exception:
            raise self.__socketError2IOError(exception)
        except xmlrpclib.Fault, results:
            pass
        self.__raiseIfFault(results, u"", operation=operation)

        changes = [ ]
        count = 0
        for changesXmlRpc in results:
            try:
                # Check for fault
                self.__raiseIfFault(changesXmlRpc, u"")
            except:
                # Explicitly requested page was not readable or
                # non-existant - make as if there were no changes to it
                continue
            # TODO Special changes must be considered
            changes += [ ChangeEntry(entry['name'], entry['version'],
                                     entry.get('author', ""),
                                     entry['lastModified'],
                                     comment=entry['comment'],
                                     renameOrResurrect=entry['renameOrResurrect'])
                         for entry in changesXmlRpc
                         if entry['version'] != self._SPECIALCHANGE_VERSION  ]
            count += 1

        if count > 1:
            # Multiple change results were concatenated
            changes.sort()
        else:
            # A single result is sorted reversed
            changes.reverse()

        if not pages:
            self._sinceWhen2RecentChanges[sinceWhen] = tuple(changes)
            verboseOut(( "%d total changes in Wiki `%s'"
                         % ( len(changes), self._baseUrl, ), ))
        return changes

    ###########################################################################

    def putPage(self, pageName, pageData, comment=None, minorEdit=None):
        if options.dry_run:
            errorOut(( "dry-run in effect: Not updating page %r[%d]"
                       % ( pageName, len(pageData), ), ))
            return

        if not pageData.endswith("\n"):
            # Missing final linfeeds seem to trigger a bug in the MoinMoin code
            # resulting in garbage characters at the beginning of the last line
            # - so better add one
            pageData += "\n"

        try:
            self._putPageWithAttributes(pageName, pageData, comment, minorEdit)
            return
        except:
            # If this didn't work try the standard call
            pass

        import xml.parsers.expat
        try:
            fault = self._connection.putPage(pageName, pageData)
        except xml.parsers.expat.ExpatError:
            # This seems to happen sometimes; reason is probably old,
            # unmaintained code containing a race condition; seems to be
            # harmless so ignore it
            errorOut(( "Ignoring empty response for page %r" % ( pageName, ), ))
            fault = None
        except socket.error, exception:
            raise self.__socketError2IOError(exception)
        except xmlrpclib.Fault, fault:
            pass
        self.__raiseIfFault(fault, pageName)

    ###########################################################################

    def _putPageWithAttributes(self, pageName, pageData, comment, minorEdit):
        """
        Tries to get put a page with attributes.

        Parameters, exceptions and return value are as for C{putPage}().

        @raise NotSupported: If the operation is not supported by this Wiki.
        """
        operation = "putPageWithAttributes"
        if not self._getSupported(operation):
            raise NotSupported(operation)

        attributes = self.__buildAttributes(comment=comment,
                                            minorEdit=minorEdit)
        try:
            fault = self._connection.putPageWithAttributes(pageName, pageData,
                                                           attributes)
        except socket.error, exception:
            raise self.__socketError2IOError(exception)
        except xmlrpclib.Fault, fault:
            pass
        self.__raiseIfFault(fault, pageName, operation=operation)

    ###########################################################################

    def deletePage(self, pageName, comment=u""):
        if options.dry_run:
            errorOut(( "dry-run in effect: Not deleting page %r"
                       % ( pageName, ), ))
            return

        operation = "deletePageWithAttributes"
        if not self._getSupported(operation):
            raise NotSupported(operation)

        import xml.parsers.expat
        try:
            fault = self._connection.deletePageWithAttributes(pageName,
                                                              self.__buildAttributes(comment=comment))
        except xml.parsers.expat.ExpatError:
            # This seems to happen sometimes; reason is probably old,
            # unmaintained code containing a race condition; seems to be
            # harmless so ignore it
            errorOut(( "Ignoring empty response for page %r" % ( pageName, ), ))
            fault = None
        except socket.error, exception:
            raise self.__socketError2IOError(exception)
        except xmlrpclib.Fault, fault:
            pass
        self.__raiseIfFault(fault, pageName, operation=operation)

    ###########################################################################

    def renamePage(self, fromName, toName, comment=u""):
        if options.dry_run:
            errorOut(( "dry-run in effect: Not renaming page %r to %r"
                       % ( fromName, toName, ), ))
            return

        operation = "renamePageWithAttributes"
        if not self._getSupported(operation):
            raise NotSupported(operation)

        import xml.parsers.expat
        try:
            fault = self._connection.renamePageWithAttributes(fromName, toName,
                                                              self.__buildAttributes(comment=comment))
        except xml.parsers.expat.ExpatError:
            # This seems to happen sometimes; reason is probably old,
            # unmaintained code containing a race condition; seems to be
            # harmless so ignore it
            errorOut(( "Ignoring empty response for page %r" % ( toName, ), ))
            fault = None
        except socket.error, exception:
            raise self.__socketError2IOError(exception)
        except xmlrpclib.Fault, fault:
            pass
        self.__raiseIfFault(fault, fromName, operation=operation,
                            targetName=toName)

    ###########################################################################

    def _setSupported(self, operation, flag):
        """
        Remembers whether a certain operation is supported by the referenced
        Wiki.

        @param operation: Name of the operation.
        @type operation: str

        @param flag: Support state.
        @type flag: bool
        """
        self._supported[operation] = flag

    ###########################################################################

    def _getSupported(self, operation):
        """
        @param operation: Name of the operation.
        @type operation: str

        @return: C{False} if this operation is known to be unsupported.
        @rtype: bool
        """
        return self._supported.get(operation, True)

    ###########################################################################

    def __socketError2IOError(self, exception):
        """
        Map a socket error to an IOError which can be raised.

        @param exception: The exception to map.
        @type exception: socket.error

        @return: The mapped exception.
        @rtype: IOError
        """
        if len(exception.args) == 1:
            return IOError(-1, ( "Connection to Wiki failed on socket level: %s"
                                 % ( exception.args[0], ), ))
        else:
            return IOError(exception.args[0],
                           ( "Connection to Wiki failed on socket level: %s"
                             % ( exception.args[1], ), ))

    ###########################################################################

    def __raiseIfFault(self, fault, pageName, version=None, operation="", targetName=u""):
        """
        Raise a useful exception if C{fault} is an XML-RPC fault.

        @param fault: The result of an XML-RPC call.
        @type fault: dict | any

        @param pageName: Name of the page for which the call was done.
        @type pageName: unicode

        @param version: Version of the page or C{None} for most recent.
        @type version: int | None

        @param operation: Name of the operation which may be not supported.
                          Defaults to the empty string. If this is given
                          C{_setSupported()} is called with the respective
                          outcome.
        @type operation: str

        @param targetName: Name of the target page in a two page operation for
                           which the call was done.
        @type targetName: unicode

        @raise NoSuchPage: If C{fault} is a no such page fault.
        @raise NotAllowed: If C{fault} indicates denied access.
        @raise PageAlreadyExists: If C{fault} indicates an already existing
                                  page.
        @raise NotSupported: If C{fault} indicated an unsupported operation.
        @raise IOError: If C{fault} is an unknown fault.
        """
        if operation:
            # Assume operation is supported
            self._setSupported(operation, True)

        locally = isinstance(fault, xmlrpclib.Fault)
        if locally:
            # An explicit fault thrown locally
            code = fault.faultCode
            message = fault.faultString
        else:
            # May be a result of a fault
            if not isinstance(fault, dict):
                # Not a dict - no fault
                return

            code = fault.get('faultCode', None)
            if code is None:
                # No `faultCode' entry - no fault
                return

            message = fault.get('faultString', "")

        if code == 1:
            # Probably a known fault
            if "No such page" in message:
                raise NoSuchPage(pageName, version)
            elif "not allowed" in message:
                raise NotAllowed(pageName, version)
            elif "already exists" in message:
                raise PageAlreadyExists(targetName)
            elif locally and "not callable" in message:
                # wikirpc.py:418 simply calls the assumed plugin even if it is
                # None meaning not found
                if operation:
                    self._setSupported(operation, False)
                raise NotSupported(operation)
        raise IOError(-1, ("Error while accessing page %r V%s: code: %d, message: %r"
                           % ( pageName, version, code, message, )))

    ###########################################################################

    def __buildAttributes(self, comment=None, minorEdit=None):
        """
        @param comment: Attribute for commenting changes in a Wiki.
        @type comment: unicode | None

        @param minorEdit: Attribute for marking minor changes as such.
        @type minorEdit: bool | None

        @return: An attribute structure compatible with C{putPage} on
                 http://www.jspwiki.org/Wiki.jsp?page=WikiRPCInterface2#section-WikiRPCInterface2-NewFunctionsInAPIV2.
                 An attribute is only set if given and not C{None}.
        @rtype: { 'comment': unicode, 'minoredit': xmlrpclib.Boolean, }
        """
        result = { }
        if comment is not None:
            result['comment'] = comment
        if minorEdit is not None:
            result['minoredit'] = xmlrpclib.Boolean(minorEdit)
        return result

###############################################################################

class MediaWiki(Wiki):
    # TODO
    """
    A class for accessing a MediaWiki Wiki. Does not yet implement the complete
    C{Wiki} interface.

    @ivar _baseUrl: Base URL to name the Wiki.
    @type _baseUrl: str
    """
    
    ##########################################################################

    def __init__(self, baseUrl):
        while baseUrl.endswith("/"):
            baseUrl = baseUrl[:-1]
        self._baseUrl = baseUrl

    ###########################################################################

    def getPage(self, pageName, version=None):
        if version is not None:
            # TODO
            raise NotImplementedError

        if isinstance(pageName, unicode):
            pageName = pageName.encode("utf-8")
        # See http://meta.wikimedia.org/wiki/Help:Export for documentation
        exportUrl = ("%s/Special:Export?action=submit&curonly=true&pages=%s"
                     % ( self._baseUrl, urllib.quote(pageName), ))
        connection = urllib.urlopen(exportUrl)
        export = connection.read()
        connection.close()
        if connection.info().getsubtype() != 'xml':
            raise IOError(-1, ( "Unexpected mime type `%s'"
                                % ( connection.info().gettype(), ), ))
        if connection.info().getparam('charset') != 'utf-8':
            raise IOError(-1, ( "Unexpected character encoding `%s'"
                                % ( connection.info().getparam('charset'), ), ))
        document = minidom.parseString(export)
        pages = document.documentElement.getElementsByTagName('page')
        if len(pages) != 1:
            raise NoSuchPage(pageName, version)
        page = pages[0]
        revisions = page.getElementsByTagName('revision')
        if len(revisions) != 1:
            raise IOError(-1, ( "Not exactly one <revision> element found", ))
        revision = revisions[0]
        texts = revision.getElementsByTagName('text')
        if len(texts) != 1:
            raise IOError(-1, ( "Not exactly one <text> element found", ))
        text = texts[0]
        if (len(text.childNodes) != 1
            or text.firstChild.nodeType != Node.TEXT_NODE):
            raise IOError(-1, ( "Not exactly one text node found", ))
        result = text.firstChild.data
        document.unlink()
        if not result.endswith("\n"):
            result += "\n"
        return result

###############################################################################

class ErrorMail(object):
    """
    A class for gathering information to send a mail.

    @ivar _mail: The mail itself or C{None} if no mail is wanted.
    @type _mail: MIMEMultipart | None

    @ivar _toAddress: Address to send the mail to if neccessary. Empty string
                      for no mail.
    @type _toAddress: str

    @ivar _fromName: Name for the C{From:} header.
    @type _fromName: str
    """

    ###########################################################################

    def __init__(self, toAddress):
        self._mail = None
        self._toAddress = toAddress
        self._fromName = pwd.getpwuid(os.getuid())[0]
        if toAddress:
            self._mail = MIMEMultipart()
            self._mail['Subject'] = ("%s[%s]: Overlap report"
                                     % ( os.path.basename(sys.argv[0]),
                                         options.merge_mode, ))
            self._mail['To'] = toAddress
            self._mail['From'] = self._fromName

    ###########################################################################

    def addMergeError(self, pageName, message, data):
        """
        Add a message about a merge error.

        @param pageName: Name of the overlapping page.
        @type pageName: unicode

        @param message: The error message.
        @type message: str

        @param data: Data to add to the error message encoded in UTF-8.
        @type data: str
        """
        if self._mail is None:
            return

        errorBody = u"\n%s: %s\n\n" % ( pageName, message, )
        errorPart = MIMEText(errorBody.encode("utf-8"), "plain", "utf-8")
        self._mail.attach(errorPart)
        dataPart = MIMEText(data, "plain", "utf-8")
        self._mail.attach(dataPart)

    ###########################################################################

    def send(self):
        """
        Send mail if mail is wanted and mail contains something.
        """
        if (self._mail is None or
            reduce(lambda last, current: last + 1, self._mail.walk(), 0) <= 1):
            return

        if options.dry_run:
            errorOut(( "dry-run in effect: Not sending mail to `%s'"
                       % ( self._toAddress, ), ))
            return

        # Error mail contains more than the (empty) top level message
        verboseOut(( "Sending mail to `%s'" % ( self._toAddress, ), ))
        smtp = smtplib.SMTP('localhost')
        smtp.sendmail(self._fromName, self._toAddress, self._mail.as_string())
        smtp.quit()

###############################################################################

class Changes(object):
    """
    A class for maintaining a set of changes.

    Each page in C{_changes} has an entry in C{_pageName2Current},
    C{_pageName2Original} and C{_pageName2OriginalVersion}. These are computed
    on demand or by C{evalRenames}.

    @ivar _wiki: The Wiki where the changes come from.
    @type _wiki: Wiki

    @ivar _changes: The list of changes. Most recent change is last
    @type _changes: [ ChangeEntry, ..., ]

    @ivar _renamedFrom2To: Maps a page name to the one it is renamed to most
                           recently by C{_changes}. No entry if page never has
                           been renamed.
    @type _renamedFrom2To: { unicode: unicode, ..., }

    @ivar _pageName2Current: Maps the name of a page to the name after all
                             renames in C{_changes} happened.
    @type _pageName2Current: { unicode: unicode, ..., }

    @ivar _pageName2Original: Maps the name of a page to the name before any
                              renames in C{_changes} happened.
    @type _pageName2Original: { unicode: unicode, ..., }

    @ivar _pageName2OriginalVersion: Maps the name of a page to the version
                                     before any change in C{_changes} happened.
    @type _pageName2OriginalVersion: { unicode: int, ..., }

    @ivar _pageName2Access: Maps the name of a page to the name after all
                            changes of access names happened.
    @type _pageName2Access: { unicode: unicode, ..., }

    """

    ###########################################################################

    def __init__(self, wiki, pages):
        """
        Initialize by getting the recent changes.

        @param pages: List of pages to get recent changes for. Empty for all.
        @type pages: [ unicode, ..., ]
        """
        self._wiki = wiki
        self._changes = self._wiki.getRecentChanges(pages)
        self._pageName2Current = None
        self._pageName2Original = None
        self._pageName2OriginalVersion = None
        self._renamedFrom2To = None
        self._pageName2Access = { }

    ###########################################################################

    def reduceToForked(self, other):
        """
        Finds the place where changes forked and reduces both changes lists.

        @param other: Other changes list which initially must be equal.
        @type other: Changes

        @raise ValueError: When changes do not overlap in at least first entry.
        """
        if self._changes[0] != other._changes[0]:
            # Very first entry must be equal or otherwise there may be
            # something badly wrong
            raise ValueError()

        for i in range(len(self._changes)):
            if (i >= len(other._changes)
                or self._changes[i] != other._changes[i]):
                break
        else:
            i = len(self._changes)

        # Remove equal change entries
        del self._changes[:i]
        del other._changes[:i]

        # Invalidate values computed on demand
        self._pageName2Current = None
        self._pageName2Original = None
        self._pageName2OriginalVersion = None
        self._renamedFrom2To = None

    ###########################################################################

    def getLength(self):
        """
        @return: Number of changes.
        @rtype: int
        """
        return len(self._changes)

    ###########################################################################

    def getPageSet(self):
        """
        @return: Set of page names.
        @rtype: Set(unicode)
        """
        return Set([ change.getPageName()
                     for change in self._changes ])

    ###########################################################################

    def evalRenames(self):
        """
        Evaluates the renames which are contained in the changes. Sets
        C{_pageName2Current}, C{_pageName2Original},
        C{_pageName2OriginalVersion} and C{_renamedFrom2To}.
        """
        self._pageName2Current = { }
        self._pageName2Original = { }
        self._pageName2OriginalVersion = { }
        self._renamedFrom2To = { }

        reverseChanges = self._changes[:]
        reverseChanges.reverse()
        # Compute most recent page names by stepping backward through changes
        for change in reverseChanges:
            pageName = change.getPageName()
            if not self._pageName2Current.has_key(pageName):
                # Has never been renamed
                self._pageName2Current[pageName] = pageName
            currentPageName = self._pageName2Current[pageName]
            renamedFrom = change.getRenamedFrom(self._wiki, currentPageName,
                                                u"")

            # Correct original information for all pages thinking they already
            # have this information
            originalName = renamedFrom or pageName
            originalVersion = change.getVersion() - 1
            for name in ([ pageName, ]
                         + [ name
                             for name in self._pageName2Original.keys()
                             if self._pageName2Original[name] == pageName ]):
                self._pageName2Original[name] = originalName
                self._pageName2OriginalVersion[name] = originalVersion

            if renamedFrom:
                # Change is a rename
                if self._renamedFrom2To.has_key(renamedFrom):
                    # A rename cycle happened - remember only latest rename
                    verboseOut(( "Page %r has been renamed to %r and later to %r"
                                 % ( renamedFrom, pageName,
                                     self._renamedFrom2To[renamedFrom],
                                     ), ))
                else:
                    self._renamedFrom2To[renamedFrom] = pageName
                # Source page of rename has not been touched at all (-1) or has
                # been recreated (version 0)
                assert (self._pageName2OriginalVersion.get(renamedFrom, -1)
                        in ( -1, 0, ))
                if self._pageName2OriginalVersion.get(renamedFrom, -1) == 0:
                    # Source page of rename has been recreated after the rename
                    # - real name is valid
                    pass
                else:
                    # Source page of rename has not been touched after the
                    # rename - current name is the rename destination
                    self._pageName2Current[renamedFrom] = currentPageName

    ###########################################################################

    def getChanges(self, pageName=None):
        """
        @param pageName: Name of a page to get changes for or C{None} for all
                         pages. Defaults to C{None}.
        @type pageName: unicode | None

        @return: All changes of the given page. Most recent change last.
        @rtype: [ ChangeEntry, ..., ]
        """
        return [ change
                 for change in self._changes
                 if pageName is None or change.getPageName() == pageName ]

    ###########################################################################

    def getLastChange(self, pageName=None):
        """
        @param pageName: Name of a page to get last change for or C{None} for
                         last change in all pages. Defaults to C{None}.
        @type pageName: unicode | None

        @return: Most recent change or C{None} if no such change.
        @rtype: ChangeEntry | None
        """
        for i in range(len(self._changes), 0, -1):
            change = self._changes[i - 1]
            if pageName is None or change.getPageName() == pageName:
                return change
        return None

    ###########################################################################

    def getCurrentPageName(self, pageName):
        """
        @param pageName: Name of a page.
        @type pageName: unicode

        @return: Name of given page after all renames happened.
        @rtype: unicode
        """
        if self._pageName2Current is None:
            self.evalRenames()
        return self._pageName2Current.get(pageName, pageName)

    ###########################################################################

    def getOriginalPageName(self, pageName):
        """
        @param pageName: Name of a page.
        @type pageName: unicode

        @return: Name of given page before any renames happened.
        @rtype: unicode
        """
        if self._pageName2Original is None:
            self.evalRenames()
        return self._pageName2Original.get(pageName, pageName)

    ###########################################################################

    def getOriginalVersion(self, pageName):
        """
        @param pageName: Name of a page.
        @type pageName: unicode

        @return: Version of given page before any changes happened. C{0} if the
                 page has been created by a change. C{None} if the page was
                 never changed.
        @rtype: int | None
        """
        if self._pageName2OriginalVersion is None:
            self.evalRenames()
        return self._pageName2OriginalVersion.get(pageName, None)

    ###########################################################################

    def setAccessPageName(self, fromName, toName):
        """
        Sets an access name for a page. This needs to be done if renames are
        executed.

        @page fromName: Former name of the page.
        @type fromName: unicode

        @page toName: Current name of the page.
        @type toName: unicode
        """
        for name in [ fromName, ] + [ name
                                      for name in self._pageName2Access.keys()
                                      if self._pageName2Access[name] == fromName ]:
            self._pageName2Access[name] = toName

    ###########################################################################

    def getAccessPageName(self, pageName):
        """
        @param pageName: Name of a page.
        @type pageName: unicode

        @return: Name of given page after all access changes happened.
        @rtype: unicode
        """
        if self._pageName2Current is None:
            self.evalRenames()
        currentName = self._pageName2Current.get(pageName, pageName)
        return self._pageName2Access.get(currentName, currentName)

###############################################################################
###############################################################################
# General functions

def pod2Head(pod):
    """
    @param pod: Snippet in POD format to be analyzed.
    @type pod: str

    @return: String of first `=headX' entry in POD snippet or empty string if
             none found.
    @rtype: str
    """
    for line in pod.split("\n"):
        if line.startswith("=head"):
            return line[len("=headX"):].strip()
    return ""

###############################################################################

def pod2Description(pod):
    """
    @param pod: Snippet in POD format to be analyzed.
    @type pod: str

    @return: Stripped text from all lines not being a POD line command.
    @rtype: str
    """
    result = ""
    for line in pod.split("\n"):
        if not line.startswith("="):
            result = result.strip() + " " + line.strip()
    return result.strip()

###############################################################################

def pod2OptionList(pod):
    """
    Return option names found in POD snippet. Option names are recognized in
    `=item B<option>' constructs.

    @param pod: Snippet in POD format to be analyzed.
    @type pod: str

    @return: All option names contained in POD snippet as a list.
    @rtype: [ str, ..., ]
    """
    result = [ ]
    for line in pod.split("\n"):
        found = re.search("^=item\s*B<(-[^>]+)>", line)
        if found:
            result.append(found.group(1))
    return result

###############################################################################

def pod2OptionKeywords(pod):
    """
    Return a dict mapping `OptionParser.add_option' keywords to values found in
    POD snippet.

    @param pod: Snippet in POD format to be analyzed.
    @type pod: str

    @return: Mapping for all values found. Currently `help' and `dest' are
             filled.
    @rtype: { keyword: value, ..., }
    """
    result = { 'help': "", }
    for line in pod.split("\n"):
        if line.startswith("=cut"):
            break
        found = re.search("^=item\s*B<--?([^>]+)>(?:=|\s*)", line)
        if found:
            result['help'] = ""
            optionName = found.group(1)
            found = re.search("I<([^>]+)>", line)
            if found:
                result['dest'] = found.group(1)
            elif len(optionName) > 1:
                result['dest'] = optionName
        else:
            result['help'] += line + "\n"
    result['help'] = result['help'].strip()
    if result.has_key('dest'):
        result['dest'] = result['dest'].replace("-", "_")
    else:
        errorExit(1, ( "Internal error: Missing `dest' in documentation string:",
                       pod, ))
    return result

###############################################################################

def pod2Argument(pod):
    """
    Return a list of two strings for `OptionGroup.__init__' describing the
    argument found in POD snippet.

    @param pod: Snippet in POD format to be analyzed.
    @type pod: str

    @return: Name of the argument and its description.
    @rtype: [ argument, description, ]
    """
    argument = ""
    description = ""
    for line in pod.split("\n"):
        if line.startswith("=cut"):
            break
        found = re.search("^=item\s*I<([^>]+)>", line)
        if found:
            description = ""
            argument = found.group(1)
        else:
            description += line + "\n"
    description = description.strip()
    return [ argument, description, ]

###############################################################################

def parseOptions():
    """
    Sets options and returns arguments.

    @return: Target URL and tuple with file names.
    @rtype: ( str, ( str, ..., ), )
    """
    global options
    pod = """

=head1 OPTIONS

=cut
    """
    optionParser = OptionParser("usage: %prog [option]... <target-url> [<page>]...")


    pod = """

=head2 Source options

These options define the source where to get pages from. Exactly one of them
needs to be given.

=over 4

=cut
    """
    sourceGroup = OptionGroup(optionParser, pod2Head(pod),
                              pod2Description(pod))
    optionParser.add_option_group(sourceGroup)

    pod = """

=item B<-d> I<source-directory>

=item B<--directory>=I<source-directory>

Page sources are to be found from I<source-directory>. The files must have
UTF-8 names and must have the extension given by the B<-x/--extension> option.
The content of the file must also use character set UTF-8.

For this source no merging is done. Instead the files are put to the target
Wiki unmodified.

=cut
    """
    sourceGroup.add_option(default="",
                           *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<--media-source>=I<media-url>

Use a MediaWiki Wiki as the source. I<media-url> is the base URL of the
MediaWiki Wiki. For this to work the target Wiki must have the MediaWiki parser
plugin.

Changes are merged as expected. For this to work option B<-U/--user> must be
given and used consistently. I.e. there should be a special user doing the
merges and nothing else. The last change done to a page in the target Wiki by
this special user is taken as the last synchronization point.

=cut
    """
    sourceGroup.add_option(default="",
                           *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<-s> I<source-url>

=item B<--source>=I<source-url>

Use another MoinMoin Wiki as the source.

This is the scenario for which this is designed:

=over 4

=item Master and slave Wiki

The Wiki at I<target-url> is the master Wiki. This is typically a public
available Wiki.

The Wiki at I<source-url> is a slave Wiki. The slave Wiki
is typically a local Wiki which is available while being offline.

=item Updating the slave Wiki

The slave Wiki is updated regularly by B<rsync> or similar means. I.e. the the
F<data> directory of the slave Wiki is made an exact copy of the F<data>
directory of the master Wiki including all log files.

=item Working with the slave Wiki

After the slave Wiki has been updates one may make changes in the slave Wiki
exactly as would have been done in the master Wiki.

=item Updating the master Wiki

After the master Wiki is available again B<moinupdate> is used to synchronize
the master with the slave Wiki. This is done by comparing the recent changes in
both Wikis. Since the slave Wiki started out as an exact copy of the master
there is a point in time where the changes fork. Changes which have been done
in the slave after this point are synchronized to the master by B<moinupdate>.

=back

=cut
    """
    sourceGroup.add_option(default="",
                           *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=back

=head2 Merge options

Options telling what to do when source and target versions need to be merged.
These options are ignored if the source doesn't permit merges.

=over 4

=cut
    """
    mergeGroup = OptionGroup(optionParser, pod2Head(pod),
                             pod2Description(pod))
    optionParser.add_option_group(mergeGroup)

    pod = """

=item B<-m> I<merge-mode>

=item B<--merge>=I<merge-mode>

Determines the merge mode used for a page which has been changed in source and
target Wiki. I<merge-mode> may be one of the following:

=over 4

=item B<ignore>

No merge is done and the page is not updated at all. An error message is output
for each such page.

=item B<clean>

A merge of source and target pages is attempted. If there are no overlapping
changes the page is updated. If there are overlapping changes an error message
is output and the page is not updated.

=item B<save>

A merge of source and target pages is attempted. If there are no overlapping
changes the page is updated. If there are overlapping changes an error message
is output, the merge result with the overlaps is written to directory
I<save-directory> given by B<-S/--save-directory> and the page is not updated.
This is useful to manually correct overlaps in the saved file and update the
target Wiki with the corrected file.

The option B<-S/--save-directory> is mandatory for this case.

=item B<force>

A merge of source and target pages is attempted and the page is always updated
with the result. An error message is output if there are overlapping changes.
Note that this may introduce merge markup into the page.

=back

Merges in content are done in the sequence they happened in the source.

If pages are renamed in source and target this is considered unresolvable and
an error message is output and the page is not renamed in the target.

Defaults to B<clean>.

=cut
    """
    mergeGroup.add_option(default=MergeModes[0],
                          *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<-M> I<mail-address>

=item B<--merge-errors-to>=I<mail-address>

Give an e-mail address where merge errors are send to in addition to the normal
handling. If an updated page is ignored without merging it is sent by mail. If
a merge took place with overlapping changes the page is sentwith overlaps. In
both cases the error messages are also sent.

This allows for catching errors even for non-supervised operation of the
program.

=cut
    """
    mergeGroup.add_option(default="",
                          *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<-S> I<save-directory>

=item B<--save-directory>=I<save-directory>

Gives the directory to save files when B<-m/--merge> is B<save>. In this case
this option is mandatory.

=cut
    """
    mergeGroup.add_option(default="",
                          *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<--append>=I<append>

Gives a string which is appended to every page retrieved from the source.

This must be a valid UTF8 string in the correct syntax for the target Wiki. For
MoinMoin target Wikis it may contain standard variables which are substituted
while saving. In addition C<\n> is replaced by a new line and C<@SOURCEPAGE@>
is replaced by the name of the source page in the source Wiki. Im most cases
there should be a trailing newline.

Currently only implemented for B<--media-source>.

=cut
    """
    mergeGroup.add_option(default="",
                          *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<--prepend>=I<prepend>

Gives a string which is prepended to every page retrieved from the source.
Refer to B<--append> for details.

Currently only implemented for B<--media-source>.

=cut
    """
    mergeGroup.add_option(default="",
                          *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=back

=head2 Target options

=over 4

=cut
    """
    targetGroup = OptionGroup(optionParser, pod2Head(pod),
                              pod2Description(pod))
    optionParser.add_option_group(targetGroup)

    pod = """

=item B<-a> I<auth-type>

=item B<--auth-type>=I<auth-type>

Gives the type of authorization to be used for the target Wiki.

These options exist:

=over 4

=item C<none>

Use no authorization.

=item C<basic>

Use basic authorization.

=item C<moin>

Use MoinAuth authorization.

=back

Defaults to C<basic>.

=cut
    """
    targetGroup.add_option(default=AuthTypes[0],
                           *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<-P> I<password>

=item B<--password>=I<password>

Gives the password to use to login with user I<account> on I<target-url> and
I<source-url>.

If this is not given no authentication is done and the target Wiki thus must be
completely open for XML-RPC I<putpage> access. Please note that it is crucial
that for B<-s/--source> the user accessing the Wikis has the same reading
rights in both Wikis.

=cut
    """
    targetGroup.add_option(*pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<-U> I<account>

=item B<--user>=I<account>

Gives the name of the user account in the target Wiki under which the pages are
written. All information such as recent changes is also read with this user
account in the target Wiki and for B<-s/--source> also in the source Wiki.

Defaults to the real name (gecos field) of the current user as retrieved from
the operating system. For this all whitespace is removed from the real name and
capitalization is kept.

If I<account> is an empty string B<--auth-type>=C<none> is implied.

This must be an UTF-8 string if it contains non-ASCII characters.

=cut
    """
    targetGroup.add_option(default=pwd.getpwuid(os.getuid())[4].replace(" ", ""),
                           *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=back

=head2 General options

=over 4

=cut
    """
    generalGroup = OptionGroup(optionParser, pod2Head(pod),
                               pod2Description(pod))
    optionParser.add_option_group(generalGroup)

    pod = """

=item B<-n>

=item B<--dry-run>

Do everything except really changing something in the target Wiki.

=cut
    """
    generalGroup.add_option(action="store_true",
                            *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<-p> I<page-dict>

=item B<--page-dict> I<page-dict>

I<page-dict> gives the name of a page in the target Wiki containing a MoinMoin
Dict. This Dict maps names of source pages given by I<page> to names of target
pages. It is no error if a I<page> is not mapped by the Dict.

I<page-dict> must be in the same format as I<page>. For the format of a
MoinMoin Dict please consult the MoinMoin sources :-( .

The idea of that option is that in the target Wiki you can maintain a list of
page name mappings for importing pages from another Wiki regularly.

If not given no mapping applies.

If this option is given but no I<page> is given the keys from this Dict are
used as I<page>.

This option is currently supported by source option B<--media-source> only.

=cut
    """
    generalGroup.add_option(default="",
                            *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<-v>

=item B<--verbose>

Operate verbose.

=cut
    """
    generalGroup.add_option(action="store_true",
                            *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=item B<-x> I<extension>

=item B<--extension>=I<extension>

Extension part for all files with page content. This is added to page names for
generation of a proper file name for source option B<-d/--directory> and to
saved files when B<-m/--merge> is B<save>.

Defaults to C<.moin>.

=cut
    """
    generalGroup.add_option(default=".moin",
                            *pod2OptionList(pod), **pod2OptionKeywords(pod))

    pod = """

=back

=head2 Arguments

=over 4

=cut
    """
    argumentGroup = OptionGroup(optionParser, pod2Head(pod),
                                pod2Description(pod))
    optionParser.add_option_group(argumentGroup)

    pod = """

=item I<target-url>

Gives the base URL of the target Wiki where pages should be put to.

=cut
    """
    argument1Group = OptionGroup(optionParser, *pod2Argument(pod))
    optionParser.add_option_group(argument1Group)

    pod = """

=item I<page>

Gives a page to put to the target Wiki. The page in the Wiki is named exactly
I<page> and the name must be valid UTF-8.

May be given any number of times.

If not given all possible pages in that source are considered. For
B<-s/--source> this is the whole Wiki. For B<-d/--directory> this is the whole
tree of files with the extension given by B<-x/--extension>. For
B<--media-source> this is not yet implemented.

=cut
    """
    argument2Group = OptionGroup(optionParser, *pod2Argument(pod))
    optionParser.add_option_group(argument2Group)

    pod = """

=back

=cut
    """
    ( options, args, ) = optionParser.parse_args()

    if len(args) < 1:
        optionParser.error("Target URL required")
    url = args.pop(0)

    if not (options.source_directory or options.source_url
            or options.media_url):
        optionParser.error("No source given")
    if options.media_url and not options.account:
        optionParser.error("Account in target Wiki must be given for MediaWiki source")
    if not options.merge_mode in MergeModes:
        optionParser.error("Unknown merge mode `%s'" % ( options.merge_mode, ))
    if options.merge_mode == 'save' and not options.save_directory:
        optionParser.error("Missing option -S/--save-directory for merge mode `%s'"
                           % ( options.merge_mode, ))
    if not options.auth_type in AuthTypes:
        optionParser.error("Unknown auth type `%s'" % ( options.auth_type, ))
    if not options.account:
        options.auth_type = AuthTypes[-1]

    return ( url, args, )

###############################################################################

def errorOut(lines):
    """
    Outputs messages as error.

    @param lines: Messages to be output as single lines.
    @type lines: ( str, ..., )

    @return: 0
    @rtype: int
    """
    scriptName = os.path.basename(sys.argv[0])
    for line in lines:
        print >>sys.stderr, ("%s: %s" % ( scriptName, line, ))
    return 0

###############################################################################

def verboseOut(lines):
    """
    Outputs messages as a verbose message.

    @param lines: Messages to be output as single lines.
    @type lines: ( str, ..., )

    @return: 0
    @rtype: int
    """
    if options.verbose:
        errorOut([ "## " + line
                   for line in lines ])
    return 0

###############################################################################

def errorExit(code, lines):
    """
    Exit program with an error message.

    @param code: Exit Code to use.
    @type code: int

    @param lines: Strings to output as error message.
    @type lines: ( str, ..., )

    @return: Does not return.
    """
    errorOut(lines)
    sys.exit(code)

###############################################################################
###############################################################################
# Functions to upload files

def putFiles(wiki, pages):
    """
    Put files to the target Wiki.

    @param wiki: The target Wiki.
    @type wiki: Wiki

    @param pages: A list of page names to put to the target Wiki in UTF-8
                  encoding. If empty the source directory is traversed.
    @type pages: [ str, ..., ]
    """
    if options.page_dict:
        # TODO
        errorExit(1, ( "Option -p/--page-dict not yet supported for file upload", ))
    if options.prepend or options.append:
        # TODO
        errorExit(1, ( "Options --prepend and --append not yet supported for file upload", ))

    if not pages:
        # Traverse the tree
        for ( path, dummy, files, ) in os.walk(options.source_directory):
            for fileName in files:
                if fileName.endswith(options.extension):
                    file = os.path.join(path, fileName)
                    pageName = file[len(os.path.join(options.source_directory,
                                                     "")):-len(options.extension)]
                    pages.append(pageName)

    for pageName in pages:
        fileName = os.path.join(options.source_directory,
                                pageName + options.extension)
        if not os.access(fileName, os.R_OK):
            errorExit(2, ( "Can't read file `%s'" % ( fileName, ), ))
        pageFile = open(fileName)
        pageData = pageFile.read()
        pageFile.close()

        verboseOut(( "Processing %r[%d] for page %r" %
                     ( fileName, len(pageData), pageName, ), ))
        wiki.putPage(pageName, pageData)

###############################################################################
###############################################################################
# Functions for merging

def data2File(data, directory=None, name=None):
    """
    Creates a file and fills it. All intervening directories are created if
    necessary. File is written in UTF-8. A trailing linefeed is added if none
    is present and data contains something. This prevents all kinds of trouble
    with tools which expect this trailing linefeed.

    @param data: Data to fill into the file. UTF-8 unless unicode.
    @type data: str | unicode

    @param directory: Directory where to put the file. If C{None} the working
                      directory is used if C{name} is given. If C{name} is not
                      given this is the base directory for creating a temporary
                      file. Defaults to C{None}.
    @type directory: str

    @param name: Name of the file. May contain a (relative) path. If C{None} a
                 temporary file is created. If this is a unicode string it is
                 translated to UTF-8.
    @type name: str | unicode

    @return: File name of the file created as UTF-8.
    @rtype: str
    """
    if not name:
        name = os.tempnam(directory)
    else:
        if isinstance(name, unicode):
            name = name.encode('utf-8')
        if not directory:
            directory = "."
        name = os.path.join(directory, name)

    path = os.path.dirname(name) or "."
    if not os.path.isdir(path):
        try:
            os.makedirs(path)
        except os.error, exception:
            errorExit(2, ( "Can not create directory %r" % ( path, ), ))

    if not isinstance(data, unicode):
        data = unicode(data, 'utf-8')
    if data and not data.endswith("\n"):
        data += "\n"
    file = codecs.open(name, 'w', 'utf-8')
    file.write(data)
    file.close()
    return name

###############################################################################

def mergePage(target, source, change, sourceCurrentName, targetAccessName, pageName, commonVersion, targetCurrentVersion, errorMail):
    """
    Merge a page according to option setting.

    @param target: The target Wiki.
    @type target: Wiki

    @param source: The source Wiki.
    @type source: Wiki

    @param change: Change in the source to execute in the target.
    @type change: ChangeEntry

    @param sourceCurrentName: Name of the page in the source now.
    @type sourceCurrentName: unicode

    @param targetAccessName: Name of the page by which it can be accessed in
                             the target now.
    @type targetAccessName: unicode

    @param pageName: Name of the overlapping page.
    @type pageName: unicode

    @param commonVersion: Last version common to both Wikis.
    @type commonVersion: int

    @param targetCurrentVersion: Most recent version of this page in the target
                                 Wiki.
    @type targetCurrentVersion: int

    @param errorMail: Mail containing error messages to send by mail.
    @type errorMail: ErrorMail
    """
    try:
        sourceData = source.getPage(sourceCurrentName, change.getVersion())
    except NoSuchPage:
        # Source page has been deleted in this version
        sourceData = u""
    if options.merge_mode == 'ignore':
        errorMail.addMergeError(pageName, "Ignoring changes",
                                sourceData.encode("utf-8"))
        errorOut(( "MERGE[%s]: Ignoring changes in page %r"
                   % ( options.merge_mode, pageName, ), ))
        return

    if commonVersion > 0:
        try:
            commonData = source.getPage(sourceCurrentName, commonVersion)
        except NoSuchPage:
            # Page was deleted in common version
            commonData = u""
    else:
        # Page has been created in both Wikis in parallel
        commonData = u""

    try:
        targetData = target.getPage(targetAccessName, targetCurrentVersion)
    except NoSuchPage:
        # Target page has been deleted
        targetData = u""

    # Deletion is handled as a normal merge
    mergeData = merge(sourceData, commonData, targetData, targetAccessName,
                      errorMail)
    if mergeData is not None:
        if mergeData:
            target.putPage(targetAccessName, mergeData,
                           comment=change.getComment(None))
        else:
            try:
                target.deletePage(targetAccessName, change.getComment(u""))
            except NotSupported:
                errorOut(( "Page deletion not supported: Skipping deletion of merged page %r V%d"
                           % ( targetAccessName, change.getVersion(), ), ))

###############################################################################

def updatePage(target, source, change, sourceCurrentName, targetCurrentName, targetAccessName, pageName2DeletionPending):
    """
    Update a page either by copying or deleting it in the target.

    @param target: The target Wiki.
    @type target: Wiki

    @param source: The source Wiki.
    @type source: Wiki

    @param change: Change in the source to execute in the target.
    @type change: ChangeEntry

    @param sourceCurrentName: Name of the page in the source now.
    @type sourceCurrentName: unicode

    @param targetCurrentName: Logical name of the page in the target now.
    @type targetCurrentName: unicode

    @param targetAccessName: Name of the page by which it can be accessed in
                             the target now.
    @type targetAccessName: unicode

    @param pageName2DeletionPending: See C{executeChange}.
    @type pageName2DeletionPending: { unicode: bool, ..., }
    """
    try:
        pageData = source.getPage(sourceCurrentName, change.getVersion())
    except NoSuchPage:
        # This version was a deletion
        pageName2DeletionPending[targetCurrentName] = True
    if pageName2DeletionPending[targetCurrentName]:
        # A deletion
        verboseOut(( "Deleting %r V%d"
                     % ( targetAccessName, change.getVersion(), ), ))
        try:
            target.deletePage(targetAccessName, change.getComment(u""))
            pageName2DeletionPending[targetCurrentName] = False
        except NotSupported:
            errorOut(( "Page deletion not supported: Skipping deletion of %r V%d"
                       % ( targetAccessName, change.getVersion(), ), ))
    else:
        # A normal update
        verboseOut(( "Updating %r[%d] V%d"
                     % ( targetAccessName, len(pageData),
                         change.getVersion(), ), ))
        target.putPage(targetAccessName, pageData,
                       comment=change.getComment(None))

###############################################################################

def renamePage(target, source, change, targetChanges, renamedFrom, pageName, sourceCurrentName):
    """
    Rename a page in the target.

    @param target: The target Wiki.
    @type target: Wiki

    @param source: The source Wiki.
    @type source: Wiki

    @param change: Change in the source to execute in the target.
    @type change: ChangeEntry

    @param targetChanges: All changes in the target Wiki.
    @type targetChanges: Changes

    @param renamedFrom: Name of the page in the target now which is to be
                        renamed.
    @type renamedFrom: unicode

    @param pageName: New name of the page to be renamed to.
    @type pageName: unicode

    @param sourceCurrentName: Name of the page in the source now.
    @type sourceCurrentName: unicode
    """
    verboseOut(( "Renaming page %r to %r V%d"
                 % ( renamedFrom, pageName, change.getVersion(), ), ))
    try:
        target.renamePage(renamedFrom, pageName, change.getComment(u""))
    except NotSupported:
        errorOut(( "Page rename not supported: Deleting %r and creating %r"
                   % ( renamedFrom, pageName, ), ))
        try:
            target.deletePage(renamedFrom, u"[Renamed to %s] %s"
                              % ( pageName, change.getComment(u"")))
        except NotSupported:
            errorOut(( "Page deletion not supported: Skipping deletion of original page %r"
                       % ( renamedFrom, ), ))
            if options.merge_mode == 'save':
                overlapFile = data2File(u"", options.save_directory,
                                        renamedFrom + options.extension)
                errorOut(( "RENAME[%s]: Created empty file %r"
                           % ( options.merge_mode, overlapFile, ), ))
            errorMail.addMergeError(renamedFrom,
                                    "Rename page: Rename and deletion not supported",
                                    u"")

        # Deletion of original page is cared for - now simulate a rename by
        # creating the target page with a comment
        pageData = (u"## page was renamed from %s\n%s"
                    % ( renamedFrom,
                        source.getPage(sourceCurrentName,
                                       change.getVersion() - 1), ))
        target.putPage(pageName, pageData,
                       comment=(u"[Renamed from %s] %s"
                                % ( renamedFrom, change.getComment(u""), )))
    if not options.dry_run:
        targetChanges.setAccessPageName(renamedFrom, pageName)

###############################################################################

# Test cases
# 
# +--------------------+--------------------+------------------------+---+
# |Source              |Target              |Result                  |Ok?|
# +------+------+------+------+------+------+--------+--------+------+---+
# |1     |2     |3     |1     |2     |3     |1       |2       |3     |   |
# +------+------+------+------+------+------+--------+--------+------+---+
# |R[A,B]|C[B,a]|      |C[A,b]|      |      |R[A,B]  |M[B,a,b]|      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |C[A,a]|R[A,B]|      |C[A,b]|      |      |M[A,a,b]|R[A,B]  |      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |C[A,a]|      |      |R[A,B]|C[B,b]|      |M[B,a,b]|        |      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |C[A,a]|      |      |C[A,b]|R[A,B]|      |M[B,a,b]|        |      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |C[A,a]|R[A,B]|      |C[A,b]|R[A,C]|      |M[C,a,b]|ERROR   |      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |R[A,B]|C[B,a]|      |C[A,b]|R[A,C]|      |ERROR   |M[C,a,b]|      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |C[A,a]|R[A,B]|      |R[A,C]|C[C,b]|      |M[C,a,b]|ERROR   |      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |R[A,B]|C[B,a]|      |R[A,C]|C[C,b]|      |ERROR   |M[C,a,b]|      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |R[A,B]|C[A,a]|      |      |      |      |R[A,B]  |C[A,a]  |      |+  |
# +------+------+------+------+------+------+--------+--------+------+---+
# |C[A,a]|R[A,B]|C[A,b]|      |      |      |C[A,a]  |R[A,B]  |C[A,b]|!  |
# +------+------+------+------+------+------+--------+--------+------+---+
# 
# R[A,B]
#   Rename from A to B
# 
# C[A,a]
#   Change a on page A
# 
# M[B,a,b]
#   Merge of a and b on page B

# TODO Changing a page, renaming it and then recreating the original page
#      raises an exception in the server.

def executeChange(target, source, targetChanges, sourceChanges, change, pageName2DeletionPending, errorMail):
    """
    Execute a single change on a page.

    @param target: The target Wiki.
    @type target: Wiki

    @param source: The source Wiki.
    @type source: Wiki

    @param targetChanges: All changes in the target Wiki.
    @type targetChanges: Changes

    @param sourceChanges: All changes in the source Wiki.
    @type sourceChanges: Changes

    @param change: Change in the source to execute in the target. Must be
                   contained in C{sourceChanges}.
    @type change: ChangeEntry

    @param pageName2DeletionPending: Maps target page names to deletion pending
                                     state. Maintained here completely.
    @type pageName2DeletionPending: { unicode: bool, ..., }

    @param errorMail: Mail containing error messages to send by mail.
    @type errorMail: ErrorMail
    """
    pageName = change.getPageName()

    # Determine names in source
    originalName = sourceChanges.getOriginalPageName(pageName)
    sourceCurrentName = sourceChanges.getCurrentPageName(pageName)

    # Determine names in target
    targetCurrentName = targetChanges.getCurrentPageName(originalName)
    assert originalName == targetChanges.getOriginalPageName(targetCurrentName)

    # Determine versions
    sourceOriginalVersion = sourceChanges.getOriginalVersion(sourceCurrentName)
    targetOriginalVersion = targetChanges.getOriginalVersion(targetCurrentName)
    assert (targetOriginalVersion is None
            or targetOriginalVersion == sourceOriginalVersion)

    renamedFrom = change.getRenamedFrom(source, sourceCurrentName, u"")

    pageName2DeletionPending[targetCurrentName] = False
    if renamedFrom:
        # Name changed
        if originalName != targetCurrentName:
            # Page was renamed in target as well - can not be resolved
            message = ("Page %r has been renamed to %r in source and to %r in target - can not be resolved"
                       % ( renamedFrom, pageName, targetCurrentName, ))
            errorOut(( message, ))
            errorMail.addMergeError(renamedFrom, message, u"")
        else:
            # Normal rename
            renamePage(target, source, change, targetChanges, renamedFrom,
                       pageName, sourceCurrentName)
    else:
        # Content changed
        if sourceOriginalVersion == 0:
            # Page has been created in source - target name is unchanged
            targetAccessName = targetCurrentName
        else:
            # Page may have been subject to renames
            targetAccessName = targetChanges.getAccessPageName(targetCurrentName)
        if targetOriginalVersion is None:
            # Did not change in target
            updatePage(target, source, change, sourceCurrentName,
                       targetCurrentName, targetAccessName,
                       pageName2DeletionPending)
        else:
            mergePage(target, source, change, sourceCurrentName,
                      targetAccessName, pageName, sourceOriginalVersion,
                      targetChanges.getLastChange(targetCurrentName).getVersion(),
                      errorMail)

    if (pageName2DeletionPending[targetCurrentName]
        and change is sourceChanges.getLastChange(sourceCurrentName)):
        # Last change was a deletion and it could not be executed
        if options.merge_mode == 'save':
            overlapFile = data2File(u"", options.save_directory,
                                    pageName + options.extension)
            errorOut(( "DELETE[%s]: Created empty file %r"
                       % ( options.merge_mode, overlapFile, ), ))
        errorMail.addMergeError(pageName,
                                "Deleted page: Deletion not supported", u"")

###############################################################################

def merge(sourceData, commonData, targetData, pageName, errorMail):
    """
    Merge a page according to option setting. If data is returned it should be
    put to the target Wiki to stay in sync with the error mail.

    @param sourceData: Current data from the source.
    @type sourceData: unicode

    @param commonData: Data from the common ancestor.
    @type commonData: unicode

    @param targetData: Current data from the target.
    @type targetData: unicode

    @param pageName: Current name of the overlapping page in the target.
    @type pageName: unicode

    @param errorMail: Mail containing error messages to send by mail.
    @type errorMail: ErrorMail

    @return: Data of the merged page or C{None} if no update is needed.
    @rtype: unicode | None
    """
    if sourceData == targetData:
        verboseOut(( "Changes in page %r are identical" % ( pageName, ), ))
        return None

    # Prepare files to merge
    commonFile = data2File(commonData)
    sourceFile = data2File(sourceData)
    targetFile = data2File(targetData)

    # Merge files
    verboseOut(( "Merging changes in page %r" % ( pageName, ), ))
    command = ("merge -p -q -L source -L common -L target %s %s %s"
               % ( sourceFile, commonFile, targetFile, ))
    pipe = os.popen(command)
    mergeData = pipe.read()
    result = pipe.close()
    if result is None:
        result = 0
    os.remove(commonFile)
    os.remove(sourceFile)
    os.remove(targetFile)
    if not os.WIFEXITED(result):
        errorExit(2, ( "`%s' did not exit normally" % ( command, ), ))
    result = os.WEXITSTATUS(result)
    if result > 1:
        errorExit(2, ( "`%s' went into trouble (%d)" % ( command, result, ), ))

    # Handle overlaps
    if result > 0:
        errorOut(( "MERGE[%s]: Overlapping change in page %r"
                   % ( options.merge_mode, pageName, ), ))
        if options.merge_mode == 'clean':
            errorMail.addMergeError(pageName,
                                    "Overlapping change: Not updated",
                                    mergeData)
            errorOut(( "MERGE[%s]: Not updating page"
                       % ( options.merge_mode, ), ))
            return None
        elif options.merge_mode == 'force':
            errorMail.addMergeError(pageName,
                                    "Overlapping change: Forcing update",
                                    mergeData)
            errorOut(( "MERGE[%s]: Forcing page update including overlaps"
                       % ( options.merge_mode, ), ))
        elif options.merge_mode == 'save':
            errorOut(( "MERGE[%s]: Saving page including overlaps to file"
                       % ( options.merge_mode, ), ))
            overlapFile = data2File(mergeData, options.save_directory,
                                    pageName + options.extension)
            errorMail.addMergeError(pageName,
                                    "Overlapping change: Saving overlaps",
                                    mergeData)
            errorOut(( "MERGE[%s]: Saved overlaps to file %r"
                       % ( options.merge_mode, overlapFile, ), ))
            return None

    # Return the merged result
    resultData = unicode(mergeData, 'utf-8')
    if resultData == targetData:
        verboseOut(( "Merge in page %r did not change anything"
                     % ( pageName, ), ))
        return None
    else:
        return resultData

###############################################################################
###############################################################################
# Functions to synchronize two MoinMoin Wikis

def syncWikis(target, source, pages, errorMail):
    """
    Put files from a source Wiki to a target Wiki.

    @param target: The target Wiki.
    @type target: Wiki

    @param source: The source Wiki.
    @type source: Wiki

    @param pages: A list of page names to synchronize in UTF-8 encoding. Empty
                  list for all pages.
    @type pages: [ str, ..., ]

    @param errorMail: Mail containing error messages to send by mail.
    @type errorMail: ErrorMail
    """
    if options.page_dict:
        # TODO
        errorExit(1, ( "Option -p/--page-dict not yet supported for two MoinMoin Wikis", ))
    if options.prepend or options.append:
        # TODO
        errorExit(1, ( "Options --prepend and --append not yet supported for two MoinMoin Wikis", ))

    pagesUnicode = [ unicode(page, 'utf-8')
                     for page in pages ]
    sourceChanges = Changes(source, pagesUnicode)
    targetChanges = Changes(target, pagesUnicode)
    try:
        sourceChanges.reduceToForked(targetChanges)
    except ValueError:
        errorExit(2, ( "Least recent change in source and target Wiki are not identical", ))
    if not sourceChanges.getLength():
        verboseOut(( "No changes in source Wiki", ))
        return

    # Compute various page lists
    # TODO Implement more informative output
    verboseOut(( "%d new changes in source Wiki on %d page(s)"
                 % ( sourceChanges.getLength(),
                     len(sourceChanges.getPageSet()), ), ))

    sourceChanges.evalRenames()
    targetChanges.evalRenames()

    # Iterate over all source changes
    pageName2DeletionPending = { }
    for change in sourceChanges.getChanges():
        executeChange(target, source, targetChanges, sourceChanges, change,
                      pageName2DeletionPending, errorMail)

###############################################################################
###############################################################################
# Functions to synchronize pages from a MediaWiki

def syncMedia(wiki, pages, errorMail):
    """
    Synchronize pages from a MediaWiki.

    @param wiki: The target Wiki.
    @type wiki: MoinWiki

    @param pages: A list of page names to put to the target Wiki in UTF-8
                  encoding.
    @type pages: [ str, ..., ]

    @param errorMail: Mail containing error messages to send by mail.
    @type errorMail: ErrorMail
    """
    pageDict = { }
    if options.page_dict:
        try:
            dictData = wiki.getPage(options.page_dict)
        except NoSuchPage:
            errorExit(2, ("Can not get page dict %r from target Wiki"
                          % ( options.page_dict, ), ))
        regex = re.compile(r'^\s(?P<source>.+?)::\s(?P<target>.*?)\s*$',
                           re.MULTILINE | re.UNICODE)
        for match in regex.finditer(dictData):
            # The match erroneously returns the leading blank - better do an
            # extra strip
            pageDict[match.group('source').strip()] = match.group('target').strip()
        if not pages:
            pages = pageDict.keys()
    if not pages:
        # TODO
        errorExit(1, ( "Sychronizing all pages from a MediaWiki not yet implemented", ))

    mediaWiki = MediaWiki(options.media_url)
    prepend = unicode(options.prepend, 'utf-8').replace(ur'\n', u"\n")
    append = unicode(options.append, 'utf-8').replace(ur'\n', u"\n")
    for pageName in pages:
        sourcePageName = pageName
        targetPageName = pageDict.get(pageName, pageName)
        try:
            content = mediaWiki.getPage(sourcePageName)
        except NoSuchPage:
            errorExit(2, ("No page %r in source Wiki" % ( sourcePageName, ), ))
        sourceData = (prepend.replace("@SOURCEPAGE@", sourcePageName) + content
                      + append.replace("@SOURCEPAGE@", sourcePageName))
        verboseOut(( "Processing %r[%d] for page %r"
                     % ( sourcePageName, len(sourceData), targetPageName, ), ))

        # Look for most recent version created by this author - this is the
        # common ancestor
        foundVersion = None
        pageExists = False
        while 1:
            verboseOut(( "Checking V%s for being common ancestor"
                         % ( foundVersion, ), ))
            try:
                targetInfo = wiki.getPageInfo(targetPageName, foundVersion)
            except NoSuchPage:
                foundVersion = None
                break
            pageExists = True
            foundVersion = targetInfo.getVersion()
            if targetInfo.getAuthor().encode('utf-8') == options.account:
                break
            foundVersion -= 1

        if foundVersion is None:
            if pageExists:
                errorExit(2, ( "Page %r exists in target Wiki but so far has not been merged by user %r"
                               % ( targetPageName, options.account, ), ))
            verboseOut(( "Target page %r does not exist - creating it"
                         % ( targetPageName, ), ))
            wiki.putPage(targetPageName, sourceData)
        else:
            verboseOut(( "Merging using common ancestor V%d"
                         % ( foundVersion, ), ))
            commonData = wiki.getPage(targetPageName, foundVersion)
            targetData = wiki.getPage(targetPageName)
            mergeData = merge(sourceData, commonData, targetData,
                              targetPageName, errorMail)
            if mergeData is not None:
                wiki.putPage(targetPageName, mergeData)

##############################################################################
##############################################################################
# Now work

if __name__ == '__main__':
    ( url, pages, ) = parseOptions()

    targetWiki = MoinWiki(url, options.auth_type, options.account,
                          options.password)
    errorMail = ErrorMail(options.mail_address)
    if options.source_url:
        syncWikis(targetWiki, MoinWiki(options.source_url, options.auth_type,
                                       options.account, options.password),
                  pages, errorMail)
    elif options.source_directory:
        options.source_directory = os.path.normpath(options.source_directory)
        putFiles(targetWiki, pages)
    elif options.media_url:
        syncMedia(targetWiki, pages, errorMail)
    else:
        errorExit(1, ( "Unknown source option used", ))
    errorMail.send()

"""

=head1 PREREQUISITES

Due to limitations in the standard XML-RPC calls some restrictions apply unless
the respective Wiki has the B<remoteMoin> XML-RPC plugins installed.

=over 4

=item Deletions in the source Wiki

Handled if the target Wiki has the plugins. Otherwise deletions are handled as
merge errors.

=item Transfer of comments

Handled only if both Wikis have the plugins. Otherwise all operations loose the
comments.

=item Renaming of pages

Handled only if both Wikis have the plugins. If source Wiki does not have the
plugins renames are not recognized and original pages still exist. If target
Wiki does not have the plugins the rename is replaced by a delete / creation
pair destroying the page history.

=item Using standalone server

For synching two MoinMoin Wikis using B<-s/--source> it is crucial that the
recent changes are retrieved by the same users (or at least by users with the
same rights to read pages in both Wikis). For the standalone server version
there is no simple way to authorize an XML-RPC call, however. If you want to
use I<http> authorization you need to apply this patch to F<request.py>:

  --- MoinMoin/request.py.orig	2006-06-21 11:27:47.000000000 +0200
  +++ MoinMoin/request.py	2006-10-01 13:38:01.000000000 +0200
  @@ -1646,6 +1646,18 @@

               ##self.debugEnvironment(sa.headers)

  +            # Create an environment for authorization checks -- StefanMerten
  +            self.env = { }
  +            authorization = sa.headers.getheader('authorization')
  +            if authorization:
  +                # Check for HTTP basic authorization
  +                ( auth_type, user_password, ) = authorization.split()
  +                from base64 import decodestring
  +                ( user, password, ) = decodestring(user_password).split(':', 1)
  +                # Simply believe it's true...
  +                self.env['AUTH_TYPE'] = auth_type
  +                self.env['REMOTE_USER'] = user
  +
               RequestBase.__init__(self, properties)

           except Exception, err:

=back

=head1 SEE ALSO

B<remoteMoin> contains a couple of XML-RPC plugins for MoinMoin allowing page
deletion over XML-RPC and other things. See

	http://www.merten-home.de/FreeSoftware/remoteMoin/

=head1 AUTHOR

Stefan Merten <smerten@oekonux.de>

=head1 LICENSE

This program is licensed under the terms of the GPL. See

	http://www.gnu.org/licenses/gpl.txt

=head1 AVAILABILTY

See

	http://www.merten-home.de/FreeSoftware/moinupdate/

=cut

"""

# TODO

"""
=head1 BUGS

Special changes like added attachments are not considered. This applies also to
the changes from C<PageComment2>.

Page reverts are not treated special.

It would be great if changes using B<-d/--directory> could merge. Then this
could be used to dump pages, modify/rename them in the filesystem and update
the original Wiki with the modified version.

A skip option is needed to skip a given number of changes. This is useful if a
previous update attempt failed for some reason and is repeated later.

=cut

"""