#Copyright ReportLab Europe Ltd. 2000-2004

#see license.txt for license details

#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/pdfbase/pdfdoc.py

__version__=''' $Id$ '''

__doc__="""

The module pdfdoc.py handles the 'outer structure' of PDF documents, ensuring that

all objects are properly cross-referenced and indexed to the nearest byte.  The

'inner structure' - the page descriptions - are presumed to be generated before

each page is saved.

pdfgen.py calls this and provides a 'canvas' object to handle page marking operators.

piddlePDF calls pdfgen and offers a high-level interface.

The classes within this generally mirror structures in the PDF file

and are not part of any public interface.  Instead, canvas and font

classes are made available elsewhere for users to manipulate.

"""

import string, types, binascii, codecs

from reportlab.pdfbase import pdfutils

from reportlab.pdfbase.pdfutils import LINEEND # this constant needed in both

from reportlab import rl_config

from reportlab.lib.utils import import_zlib, open_for_read, fp_str, _digester

from reportlab.pdfbase import pdfmetrics

try:

    from hashlib import md5

except ImportError:

    from md5 import md5

from sys import platform

try:

    from sys import version_info

except: # pre-2.0

    # may be inaccurate but will at least

    #work in anything which seeks to format

    # version_info into a string

    version_info = (1,5,2,'unknown',0)

if platform[:4] == 'java' and version_info[:2] == (2, 1):

    # workaround for list()-bug in Jython 2.1 (should be fixed in 2.2)

    def list(sequence):

        def f(x):

            return x

        return map(f, sequence)

def utf8str(x):

    if isinstance(x,unicode):

        return x.encode('utf8')

    else:

        return str(x)

class PDFError(Exception):

    pass

# set this flag to get more vertical whitespace (and larger files)

LongFormat = 1

##if LongFormat: (doesn't work)

##    pass

##else:

##    LINEEND = "\n" # no wasteful carriage returns!

# __InternalName__ is a special attribute that can only be set by the Document arbitrator

__InternalName__ = "__InternalName__"

# __RefOnly__ marks reference only elements that must be formatted on top level

__RefOnly__ = "__RefOnly__"

# __Comment__ provides a (one line) comment to inline with an object ref, if present

#   if it is more than one line then percentize it...

__Comment__ = "__Comment__"

# If DoComments is set then add helpful (space wasting) comment lines to PDF files

DoComments = 1

if not LongFormat:

    DoComments = 0

# name for standard font dictionary

BasicFonts = "BasicFonts"

# name for the pages object

Pages = "Pages"

### generic utilities

# for % substitutions

LINEENDDICT = {"LINEEND": LINEEND, "PERCENT": "%"}

PDF_VERSION_DEFAULT = (1, 3)

PDF_SUPPORT_VERSION = dict(     #map keyword to min version that supports it

    transparency = (1, 4),

    )

from types import InstanceType

def format(element, document, toplevel=0, InstanceType=InstanceType):

    """Indirection step for formatting.

       Ensures that document parameters alter behaviour

       of formatting for all elements.

    """

    if hasattr(element,'__PDFObject__'):

        if not toplevel and hasattr(element, __RefOnly__):

            # the object cannot be a component at non top level.

            # make a reference to it and return it's format

            return document.Reference(element).format(document)

        else:

            f = element.format(document)

            if not rl_config.invariant and DoComments and hasattr(element, __Comment__):

                f = "%s%s%s%s" % ("% ", element.__Comment__, LINEEND, f)

            return f

    elif type(element) in (float, int):

        #use a controlled number formatting routine

        #instead of str, so Jython/Python etc do not differ

        return fp_str(element)

    else:

        return str(element)

def xObjectName(externalname):

    return "FormXob.%s" % externalname

# backwards compatibility

formName = xObjectName

# no encryption

class NoEncryption:

    def encode(self, t):

        "encode a string, stream, text"

        return t

    def prepare(self, document):

        # get ready to do encryption

        pass

    def register(self, objnum, version):

        # enter a new direct object

        pass

    def info(self):

        # the representation of self in file if any (should be None or PDFDict)

        return None

class DummyDoc:

    "used to bypass encryption when required"

    __PDFObject__ = True

    encrypt = NoEncryption()

### the global document structure manager

class PDFDocument:

    __PDFObject__ = True

    # set this to define filters

    defaultStreamFilters = None

    encrypt = NoEncryption() # default no encryption

    def __init__(self,

                 dummyoutline=0,

                 compression=rl_config.pageCompression,

                 invariant=rl_config.invariant,

                 filename=None,

                 pdfVersion=PDF_VERSION_DEFAULT,

                 ):

        # allow None value to be passed in to mean 'give system defaults'

        if invariant is None:

            self.invariant = rl_config.invariant

        else:

            self.invariant = invariant

        self.setCompression(compression)

        self._pdfVersion = pdfVersion

        # signature for creating PDF ID

        sig = self.signature = md5()

        sig.update("a reportlab document")

        if not self.invariant:

            cat = _getTimeStamp()

        else:

            cat = 946684800.0

        sig.update(repr(cat)) # initialize with timestamp digest

        # mapping of internal identifier ("Page001") to PDF objectnumber and generation number (34, 0)

        self.idToObjectNumberAndVersion = {}

        # mapping of internal identifier ("Page001") to PDF object (PDFPage instance)

        self.idToObject = {}

        # internal id to file location

        self.idToOffset = {}

        # number to id

        self.numberToId = {}

        cat = self.Catalog = self._catalog = PDFCatalog()

        pages = self.Pages = PDFPages()

        cat.Pages = pages

        if dummyoutline:

            outlines = PDFOutlines0()

        else:

            outlines = PDFOutlines()

        self.Outlines = self.outline = outlines

        cat.Outlines = outlines

        self.info = PDFInfo()

        self.info.invariant = self.invariant

        #self.Reference(self.Catalog)

        #self.Reference(self.Info)

        self.fontMapping = {}

        #make an empty font dictionary

        DD = PDFDictionary({})

        DD.__Comment__ = "The standard fonts dictionary"

        self.Reference(DD, BasicFonts)

        self.delayedFonts = []

    def setCompression(self, onoff):

        # XXX: maybe this should also set self.defaultStreamFilters?

        self.compression = onoff

    def ensureMinPdfVersion(self, *keys):

        "Ensure that the pdf version is greater than or equal to that specified by the keys"

        for k in keys:

            self._pdfVersion = max(self._pdfVersion, PDF_SUPPORT_VERSION[k])

    def updateSignature(self, thing):

        "add information to the signature"

        if self._ID: return # but not if its used already!

        self.signature.update(utf8str(thing))

    def ID(self):

        "A unique fingerprint for the file (unless in invariant mode)"

        if self._ID:

            return self._ID

        digest = self.signature.digest()

        doc = DummyDoc()

        ID = PDFString(digest,enc='raw')

        IDs = ID.format(doc)

        self._ID = "%s %% ReportLab generated PDF document -- digest (http://www.reportlab.com) %s [%s %s] %s" % (

                LINEEND, LINEEND, IDs, IDs, LINEEND)

        return self._ID

    def SaveToFile(self, filename, canvas):

        if hasattr(getattr(filename, "write",None),'__call__'):

            myfile = 0

            f = filename

            filename = utf8str(getattr(filename,'name',''))

        else :

            myfile = 1

            filename = utf8str(filename)

            f = open(filename, "wb")

        f.write(self.GetPDFData(canvas))

        if myfile:

            f.close()

            import os

            if os.name=='mac':

                from reportlab.lib.utils import markfilename

                markfilename(filename) # do platform specific file junk

        if getattr(canvas,'_verbosity',None): print 'saved', filename

    def GetPDFData(self, canvas):

        # realize delayed fonts

        for fnt in self.delayedFonts:

            fnt.addObjects(self)

        # add info stuff to signature

        self.info.invariant = self.invariant

        self.info.digest(self.signature)

        ### later: maybe add more info to sig?

        # prepare outline

        self.Reference(self.Catalog)

        self.Reference(self.info)

        outline = self.outline

        outline.prepare(self, canvas)

        return self.format()

    def inPage(self):

        """specify the current object as a page (enables reference binding and other page features)"""

        if self.inObject is not None:

            if self.inObject=="page": return

            raise ValueError, "can't go in page already in object %s" % self.inObject

        self.inObject = "page"

    def inForm(self):

        """specify that we are in a form xobject (disable page features, etc)"""

        # don't need this check anymore since going in a form pushes old context at canvas level.

        #if self.inObject not in ["form", None]:

        #    raise ValueError, "can't go in form already in object %s" % self.inObject

        self.inObject = "form"

        # don't need to do anything else, I think...

    def getInternalFontName(self, psfontname):

        fm = self.fontMapping

        if psfontname in fm:

            return fm[psfontname]

        else:

            try:

                # does pdfmetrics know about it? if so, add

                fontObj = pdfmetrics.getFont(psfontname)

                if fontObj._dynamicFont:

                    raise PDFError("getInternalFontName(%s) called for a dynamic font" % repr(psfontname))

                fontObj.addObjects(self)

                #self.addFont(fontObj)

                return fm[psfontname]

            except KeyError:

                raise PDFError("Font %s not known!" % repr(psfontname))

    def thisPageName(self):

        return "Page"+repr(self.pageCounter)

    def thisPageRef(self):

        return PDFObjectReference(self.thisPageName())

    def addPage(self, page):

        name = self.thisPageName()

        self.Reference(page, name)

        self.Pages.addPage(page)

        self.pageCounter += 1

        self.inObject = None

    def addForm(self, name, form):

        """add a Form XObject."""

        # XXX should check that name is a legal PDF name

        if self.inObject != "form":

            self.inForm()

        self.Reference(form, xObjectName(name))

        self.inObject = None

    def annotationName(self, externalname):

        return "Annot.%s"%externalname

    def addAnnotation(self, name, annotation):

        self.Reference(annotation, self.annotationName(name))

    def refAnnotation(self, name):

        internalname = self.annotationName(name)

        return PDFObjectReference(internalname)

    def addColor(self,cmyk):

        sname = cmyk.spotName

        name = PDFName(sname)[1:]

        if name not in self.idToObject:

            sep = PDFSeparationCMYKColor(cmyk).value()  #PDFArray([/Separation /name /DeviceCMYK tint_tf])

            self.Reference(sep,name)

        return name,sname

    def setTitle(self, title):

        "embeds in PDF file"

        if title is None:

            self.info.title = '(anonymous)'

        else:

            self.info.title = title

    def setAuthor(self, author):

        "embedded in PDF file"

        #allow resetting to clear it

        if author is None:

            self.info.author = '(anonymous)'

        else:

            self.info.author = author

    def setSubject(self, subject):

        "embeds in PDF file"

        #allow resetting to clear it

        if subject is None:

            self.info.subject = '(unspecified)'

        else:

            self.info.subject = subject

    def setCreator(self, creator):

        "embeds in PDF file"

        #allow resetting to clear it

        if creator is None:

            self.info.creator = '(unspecified)'

        else:

            self.info.creator = creator

    def setKeywords(self, keywords):

        "embeds a string containing keywords in PDF file"

        #allow resetting to clear it but ensure it's a string

        if keywords is None:

            self.info.keywords = ''

        else:

            self.info.keywords = keywords

    def setDateFormatter(self, dateFormatter):

        self.info._dateFormatter = dateFormatter

    def getAvailableFonts(self):

        fontnames = self.fontMapping.keys()

        # the standard 14 are also always available! (even if not initialized yet)

        import _fontdata

        for name in _fontdata.standardFonts:

            if name not in fontnames:

                fontnames.append(name)

        fontnames.sort()

        return fontnames

    def format(self):

        # register the Catalog/INfo and then format the objects one by one until exhausted

        # (possible infinite loop if there is a bug that continually makes new objects/refs...)

        # Prepare encryption

        self.encrypt.prepare(self)

        cat = self.Catalog

        info = self.info

        self.Reference(self.Catalog)

        self.Reference(self.info)

        # register the encryption dictionary if present

        encryptref = None

        encryptinfo = self.encrypt.info()

        if encryptinfo:

            encryptref = self.Reference(encryptinfo)

        # make std fonts (this could be made optional

        counter = 0 # start at first object (object 1 after preincrement)

        ids = [] # the collection of object ids in object number order

        numbertoid = self.numberToId

        idToNV = self.idToObjectNumberAndVersion

        idToOb = self.idToObject

        idToOf = self.idToOffset

        ### note that new entries may be "appended" DURING FORMATTING

        done = None

        File = PDFFile(self._pdfVersion) # output collector

        while done is None:

            counter += 1 # do next object...

            if counter in numbertoid:

                id = numbertoid[counter]

                #printidToOb

                obj = idToOb[id]

                IO = PDFIndirectObject(id, obj)

                # register object number and version

                #encrypt.register(id,

                IOf = IO.format(self)

                # add a comment to the PDF output

                if not rl_config.invariant and DoComments:

                    try:

                        classname = obj.__class__.__name__

                    except:

                        classname = repr(obj)

                    File.add("%% %s: class %s %s" % (repr(id), classname[:50], LINEEND))

                offset = File.add(IOf)

                idToOf[id] = offset

                ids.append(id)

            else:

                done = 1

        # sanity checks (must happen AFTER formatting)

        lno = len(numbertoid)

        if counter-1!=lno:

            raise ValueError, "counter %s doesn't match number to id dictionary %s" %(counter, lno)

        # now add the xref

        xref = PDFCrossReferenceTable()

        xref.addsection(0, ids)

        xreff = xref.format(self)

        xrefoffset = File.add(xreff)

        # now add the trailer

        trailer = PDFTrailer(

            startxref = xrefoffset,

            Size = lno+1,

            Root = self.Reference(cat),

            Info = self.Reference(info),

            Encrypt = encryptref,

            ID = self.ID(),

            )

        trailerf = trailer.format(self)

        File.add(trailerf)

        # return string format for pdf file

        return File.format(self)

    def hasForm(self, name):

        """test for existence of named form"""

        internalname = xObjectName(name)

        return internalname in self.idToObject

    def getFormBBox(self, name, boxType="MediaBox"):

        """get the declared bounding box of the form as a list.

        If you specify a different PDF box definition (e.g. the

        ArtBox) and it has one, that's what you'll get."""

        internalname = xObjectName(name)

        if internalname in self.idToObject:

            theform = self.idToObject[internalname]

            if hasattr(theform,'_extra_pageCatcher_info'):

                return theform._extra_pageCatcher_info[boxType]

            if isinstance(theform, PDFFormXObject):

                # internally defined form

                return theform.BBoxList()

            elif isinstance(theform, PDFStream):

                # externally defined form

                return list(theform.dictionary.dict[boxType].sequence)

            else:

                raise ValueError, "I don't understand the form instance %s" % repr(name)

    def getXObjectName(self, name):

        """Lets canvas find out what form is called internally.