Changeset 765

Timestamp:

12/12/06 13:32:13 (2 years ago)

Author:

mfenniak

Message:

Add pythondoc documentation.

Files:

• pypdf/trunk/pyPdf/pdf.py (modified) (15 diffs)

pypdf/trunk/pyPdf/pdf.py

@@ -48 +48 @@
-from sets import ImmutableSet
-
+##
+# This class supports writing PDF files out, given pages produced by another
+# class (typically {@link #PdfFileReader PdfFileReader}).
-class PdfFileWriter(object):
-    def __init__(self):
@@ -85 +88 @@
-        return self._objects[ido.idnum - 1]
-
+    ##
+    # Adds a page to this PDF file.  The page is usually acquired from a
+    # {@link #PdfFileReader PdfFileReader} instance.
+    # <p>
+    # Stability: Added in v1.0, will exist for all v1.x releases.
+    #
+    # @param page The page to add to the document.  This argument should be
+    #             an instance of {@link #PageObject PageObject}.
-    def addPage(self, page):
-        """
-        Adds a page to this PDF file.  A dictionary of /Type = /Page.
-        Currently usually aquired from PdfFileReader.getPage().
-
-        Stability: Added in v1.0, will exist for all v1.x releases.
-        """
-        assert page["/Type"] == "/Page"
-        page[NameObject("/Parent")] = self._pages
@@ -99 +104 @@
-        pages["/Count"] = NumberObject(pages["/Count"] + 1)
-
+    ##
+    # Writes the collection of pages added to this object out as a PDF file.
+    # <p>
+    # Stability: Added in v1.0, will exist for all v1.x releases.
+    # @param stream An object to write the file to.  The object must support
+    # the write method, and the tell method, similar to a file object.
-    def write(self, stream):
-        """
-        Writes this PDF file to an output stream.  Writes the file as a
-        PDF-1.3 format file.
-
-        Stability: Added in v1.0, will exist for all v1.x releases.
-        """
-
-        externalReferenceMap = {}
-        self.stack = []
@@ -196 +200 @@
-
-
+##
+# Initializes a PdfFileReader object.  This operation can take some time, as
+# the PDF stream's cross-reference tables are read into memory.
+# <p>
+# Stability: Added in v1.0, will exist for all v1.x releases.
+#
+# @param stream An object that supports the standard read and seek methods
+#               similar to a file object.
-class PdfFileReader(object):
-    def __init__(self, stream):
-        """
-        Initializes a PdfFileReader object.  This operation can take some time,
-        as the PDF file cross-reference tables are read.  "stream" parameter
-        must be a data stream, not a string or a path name.
-
-        Stability: Added in v1.0, will exist for all v1.x releases.
-        """
-        self.flattenedPages = None
-        self.resolvedObjects = {}
@@ -210 +215 @@
-        self.stream = stream
-
+    ##
+    # Retrieves the PDF file's document information dictionary, if it exists.
+    # Note that some PDF files use metadata streams instead of docinfo
+    # dictionaries, and these metadata streams will not be accessed by this
+    # function.
+    # <p>
+    # Stability: Added in v1.6, will exist for all future v1.x releases.
+    # @return Returns a {@link #DocumentInformation DocumentInformation}
+    #         instance, or None if none exists.
-    def getDocumentInfo(self):
-        """
-        Retrieves the PDF file's document information dictionary, if it
-        exists.  Returns a DocumentInformation instance, or None.
-        Note that some PDF files use metadata streams instead of docinfo
-        dictionaries, and these metadata streams will not be accessed by this
-        function.
-
-        Stability: Added in v1.6, will exist for all v1.x releases.
-        """
-        if not self.trailer.has_key("/Info"):
-            return None
@@ -227 +232 @@
-        return retval
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-    def getNumPages(self):
-        """
-        Returns the number of pages in this PDF file.
-
-        Stability: Added in v1.0, will exist for all v1.x releases.
-        """
-        if self.flattenedPages == None:
-            self._flatten()
-        return len(self.flattenedPages)
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-    def getPage(self, pageNumber):
-        """
-        Retrieves a page by number from this PDF file.  Returns a PageObject
-        instance.
-
-        Stability: Added in v1.0, will exist for all v1.x releases.
-        """
-        # ensure that we're not trying to access an encrypted PDF
-        assert not self.trailer.has_key("/Encrypt")
@@ -258 +268 @@
-        return self.flattenedPages[pageNumber]
-
+    ##
+    # Read-only property that emulates a list based upon the {@link
+    # #PdfFileReader.getNumPages getNumPages} and {@link #PdfFileReader.getPage
+    # getPage} functions.
+    # <p>
+    # Stability: Added in v1.7, and will exist for all future v1.x releases.
-    pages = property(lambda self: ConvertFunctionsToVirtualList(self.getNumPages, self.getPage),
-
-
+
-
-    def _flatten(self, pages = None, inherit = None):
@@ -513 +528 @@
-    del self[name]
-
-addRectangleAccessor(klass, propname, name, fallback, docs
-setattr(klass, propname,
+createRectangleAccessor(name, fallback
+return \
-        property(
-            lambda self: getRectangle(self, name, fallback),
-            lambda self, value: setRectangle(self, name, value),
-
-
+
-            )
-
-
+
+
+
+
+
-class PageObject(DictionaryObject):
-    def __init__(self, pdf):
@@ -528 +545 @@
-        self.pdf = pdf
-
+    ##
+    # Rotates a page clockwise by increments of 90 degrees.
+    # <p>
+    # Stability: Added in v1.1, will exist for all future v1.x releases.
+    # @param angle Angle to rotate the page.  Must be an increment of 90 deg.
-    def rotateClockwise(self, angle):
-        """
-        Rotates a page clockwise by increments of 90 degrees.
-
-        Stability: Added in v1.1, will exist for all v1.x releases thereafter.
-        """
-        assert angle % 90 == 0
-        self._rotate(angle)
-        return self
-
+    ##
+    # Rotates a page counter-clockwise by increments of 90 degrees.
+    # <p>
+    # Stability: Added in v1.1, will exist for all future v1.x releases.
+    # @param angle Angle to rotate the page.  Must be an increment of 90 deg.
-    def rotateCounterClockwise(self, angle):
-        """
-        Rotates a page counter-clockwise by increments of 90 degrees.  Note
-        that this is equivilant to calling rotateClockwise(-angle).
-
-        Stability: Added in v1.1, will exist for all v1.x releases thereafter.
-        """
-        assert angle % 90 == 0
-        self._rotate(-angle)
@@ -590 +606 @@
-    _pushPopGS = staticmethod(_pushPopGS)
-
+    ##
+    # Merges the content streams of two pages into one.  Resource references
+    # (i.e. fonts) are maintained from both pages.  The mediabox/cropbox/etc
+    # of this page are not altered.  The parameter page's content stream will
+    # be added to the end of this page's content stream, meaning that it will
+    # be drawn after, or "on top" of this page.
+    # <p>
+    # Stability: Added in v1.4, will exist for all future 1.x releases.
+    # @param page2 An instance of {@link #PageObject PageObject} to be merged
+    #              into this one.
-    def mergePage(self, page2):
-        """
-        Merges the content streams of two pages into one.  Resource
-        references (i.e. fonts) are maintained from both pages.  The
-        mediabox/cropbox/etc on "self" are not altered.
-
-        Stability: Added in v1.4, will exist for all v1.x releases thereafter.
-        """
-
-        # First we work on merging the resource dictionaries.  This allows us
@@ -634 +653 @@
-        self[NameObject('/Resources')] = newResources
-
+    ##
+    # Compresses the size of this page by joining all content streams and
+    # applying a FlateDecode filter.
+    # <p>
+    # Stability: Added in v1.6, will exist for all future v1.x releases.
+    # However, it is possible that this function will perform no action if
+    # content stream compression becomes "automatic" for some reason.
-    def compressContentStreams(self):
-        """
-        Join all content streams and apply a FlateDecode filter to decrease
-        the stream's size.
-
-        Stability: Added in v1.6, will exist for all v1.x releases thereafter.
-        However, if content stream compression is ever handled in a different
-        and/or more transparent way, this function may not do anything.
-        """
-        content = self["/Contents"].getObject()
-        if not isinstance(content, ContentStream):
@@ -648 +666 @@
-        self[NameObject("/Contents")] = content.flateEncode()
-
+    ##
+    # Locate all text drawing commands, in the order they are provided in the
+    # content stream, and extract the text.  This works well for some PDF
+    # files, but poorly for others, depending on the generator used.  This will
+    # be refined in the future.  Do not rely on the order of text coming out of
+    # this function, as it will change if this function is made more
+    # sophisticated.
+    # <p>
+    # Stability: Added in v1.7, will exist for all future v1.x releases.  May
+    # be overhauled to provide more ordered text in the future.
+    # @return a string object
-    def extractText(self):
-        """
-        Locate all text drawing commands, in the order they are provided in
-        the content stream, and extract the text.  This works well for some
-        PDF files, but poorly for others, depending on the generator used.
-        This will be refined in the future.  Do not rely on the order of text
-        coming out of this function, as it will change if this function is 
-        made more sophisticated.
-
-        Stability: Added in v1.7, will exist for all v1.x releases thereafter.
-        May be overhauled to provide more ordered text in the future.
-        """
-        text = ""
-        content = self["/Contents"].getObject()
@@ -681 +699 @@
-        return text
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
@@ -817 +839 @@
-
-
+##
+# A class representing the basic document metadata provided in a PDF File.
-class DocumentInformation(DictionaryObject):
-    def __init__(self):
-        DictionaryObject.__init__(self)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
@@ -869 +894 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+#
+#
+
+#
+#
+
+#
+#
+#
+#
+#
+
+#
+#
+
+#
+
+#
+#
+
+