docp 0.0.0.dev1__py3-none-any.whl → 0.2.0__py3-none-any.whl

docp/objects/_docbaseobject.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+:Purpose:   This module provides the generalised base functionality for
+            the document-type-specific base classes.
+
+:Platform:  Linux/Windows | Python 3.10+
+:Developer: J Berendt
+:Email:     development@s3dev.uk
+
+:Comments:  n/a
+
+"""
+
+
+class _DocBase:
+    """Private document base class.
+
+    .. attention::
+
+        This class is *not* designed to be interacted with directly, but
+        rather to be inherited by the document-type-specific document
+        objects.
+
+    """
+
+    def __init__(self):
+        """Base document object class initialiser."""
+        self._common = None     # Used by the header/footer scanner.
+        self._fname = None      # Filename (basename)
+        self._fpath = None      # Full file path
+        self._meta = None       # Metadata from the document parger
+        self._npages = 0        # Number of pages in the document
+        self._ntables = 0       # Number of tables extracted
+        self._parser = None     # Underlying document parser functionality
+
+    @property
+    def basename(self) -> str:
+        """Accessor for the file's basename."""
+        return self._fname
+
+    @property
+    def filepath(self) -> str:
+        """Accessor for the explicit path to this file."""
+        return self._fpath
+
+    @property
+    def metadata(self) -> dict | object:
+        """The meta data as extracted from the document."""
+        return self._meta
+
+    @property
+    def npages(self) -> int:
+        """The number of pages successfully extracted from the source."""
+        return self._npages
+
+    @property
+    def ntables(self) -> int:
+        """The number of tables successfully extracted from the source."""
+        return self._ntables
+
+    @property
+    def parser(self) -> object:
+        """Accessor to the underlying document parser's functionality."""
+        return self._parser

docp/objects/_pageobject.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+:Purpose:   This module provides the implementation for the
+            ``PageObject`` object.
+
+:Platform:  Linux/Windows | Python 3.10+
+:Developer: J Berendt
+:Email:     development@s3dev.uk
+
+:Comments:  n/a
+
+"""
+
+from __future__ import annotations
+
+
+class PageObject:
+    """This class provides the implementation for the ``PageObject``.
+
+    For each page in a document, an instance of this class is created,
+    populated and appended into the document's ``pages`` list attribute.
+
+    Args:
+        content (str, optional): Page content as a single string.
+            Defaults to ''.
+        pageno (int, optional): Page number. Defaults to 0.
+        parser (object, optional): The underlying document parser object.
+            Defaults to None.
+
+    """
+
+    __slots__ = ('_content', '_hastext', '_pageno', '_parser', '_tables')
+
+    def __init__(self, content: str='', pageno: int=0, parser: object=None):
+        """Page object class initialiser."""
+        self._content = content
+        self._pageno = pageno
+        self._parser = parser
+        self._hastext = bool(content)
+        self._tables = []
+
+    def __repr__(self) -> str:
+        """Formatted representation of this object."""
+        if self._pageno == 0:
+            return f'<Page: {self._pageno}; <index offset>>'
+        return f'<Page: {self._pageno}; Chars: {len(self._content)}>'
+
+    def __str__(self) -> str:
+        """Formatted string displayed when printing this object."""
+        c = self._content[:25].replace('\n', ' ') + ' ...' if self._content else ''
+        fmt = (f'Page no: {self._pageno}; '
+               f'Content: "{c}"; '
+               f'Chars: {len(self._content)}; '
+               f'nTables: {len(self._tables)}; '
+               f'Parser avail: {bool(self._parser)}')
+        return fmt
+
+    @property
+    def content(self) -> str:
+        """Accessor to the page's textual content."""
+        return self._content
+
+    @content.setter
+    def content(self, value: str) -> None:
+        """Setter for the ``content`` attribute.
+
+        If the ``value`` argument is populated, the content is set and
+        the ``hastext`` attribute is set to ``True``.
+
+        """
+        if value:
+            self._content = value
+            self._hastext = True
+
+    @property
+    def hastext(self) -> bool:
+        """Flag indicating if the ``content`` attribute is populated."""
+        return self._hastext
+
+    @property
+    def pageno(self) -> int:
+        """Accessor to the page number.
+
+        Note:
+            This is the page number with regard to the page's *sequence
+            in the overall document*. This is *not* guaranteed to be the
+            page's number per the document's page labeling scheme.
+
+        """
+        return self._pageno
+
+    @property
+    def parser(self) -> object:
+        """Accessor to the document parser's internal functionality.
+
+        Note:
+            The population of this property is determined by the
+            document-type-specific ``docp`` parser. If the underlying
+            parsing library has functionality worth preserving and making
+            available to the user, it is stored to this property.
+            Otherwise, this property will remain as ``None``.
+
+        """
+        return self._parser
+
+    @property
+    def tables(self) -> list:
+        """Accessor to the page's tables, if parsed."""
+        return self._tables
+
+    def show(self) -> pdfplumber.display.PageImage:  # pylint: disable=undefined-variable  # noqa
+        """Display the page as an image.
+
+        Additionally, the return value exposes access to the underlying
+        ``pdfplumber`` debugging visualisation methods such as:
+
+            - :func:`img.debug_tablefinder`
+            - :func:`img.draw_*`
+            - :func:`img.outline_chars`
+            - :func:`img.outline_words`
+            - :func:`img.reset`
+            - etc.
+
+
+        """
+        return self.parser.to_image()

docp/objects/_slideobject.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+:Purpose:   This module provides the implementation for the
+            ``SlideObject`` object.
+
+:Platform:  Linux/Windows | Python 3.10+
+:Developer: J Berendt
+:Email:     development@s3dev.uk
+
+:Comments:  n/a
+
+"""
+
+
+class SlideObject:
+    r"""This class provides the implementation for the ``SlideObject``.
+
+    For each slide in a document (e.g. PowerPoint), an instance of this
+    class is created, populated and appended into the PPTX document's
+    ``slides`` list attribute.
+
+    Args:
+        pageno (int, optional): Page number. Defaults to 0.
+        parser (object, optional): The underlying document parser object.
+            Defaults to None.
+
+    .. tip::
+        To display the textual contents of a slide, simply call the
+        following, where 42 is the slide to be displayed::
+
+            >>> print(*pptx.doc.slides[42].texts, sep='\n\n')
+
+    """
+
+    __slots__ = ('_imgs', '_tables', '_texts', '_pageno', '_parser')
+
+    def __init__(self, pageno: int=0, parser: object=None):
+        """Slide object class initialiser."""
+        self._imgs = []
+        self._tables = []
+        self._texts = []
+        self._pageno = pageno
+        self._parser = parser
+
+    def __repr__(self) -> str:
+        """Formatted representation of this object."""
+        return f'<Slide: {self._pageno}>'
+
+    def __str__(self) -> str:
+        """Formatted representation of this object, when printed."""
+        if self._pageno == 0:
+            return f'<Slide: {self._pageno}; <index offset>>'
+        return (f'<Slide: {self._pageno}; '
+                f'Text blocks: {len(self._texts)}; '
+                f'Tables: {len(self._tables)}; '
+                f'Images: {len(self._imgs)}; '
+                f'Parser: {bool(self._parser)}>')
+
+    @property
+    def content(self) -> str:
+        """Accessor to the textual content of a slide.
+
+        Returns:
+            str: A concatenated string for all text objects found on the
+            slide; each object separated by a double-newline.
+
+        """
+        return '\n\n'.join(i.content for i in self._texts)
+
+    @property
+    def images(self) -> list:
+        """Accessor to a slide's image objects."""
+        return self._imgs
+
+    @property
+    def pageno(self) -> int:
+        """Accessor to the page number.
+
+        Note:
+            This is the page number with regard to the page's *sequence
+            in the overall document*. This is *not* guaranteed to be the
+            page's number per the document's page labeling scheme.
+
+        """
+        return self._pageno
+
+    @property
+    def parser(self) -> object:
+        """Accessor to the document parser's internal functionality.
+
+        Note:
+            The population of this property is determined by the
+            document-type-specific ``docp`` parser. If the underlying
+            parsing library has functionality worth preserving and making
+            available to the user, it is stored to this property.
+            Otherwise, this property will remain as ``None``.
+
+        """
+        return self._parser
+
+    @property
+    def tables(self) -> list:
+        """Accessor to a slide's table objects."""
+        return self._tables
+
+    @property
+    def texts(self) -> list:
+        """Accessor to a slide's text objects."""
+        return self._texts

docp/objects/_textobject.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+:Purpose:   This module provides the implementation for the
+            ``TextObject`` object.
+
+:Platform:  Linux/Windows | Python 3.10+
+:Developer: J Berendt
+:Email:     development@s3dev.uk
+
+:Comments:  n/a
+
+"""
+
+
+class TextObject:
+    """This class provides the implementation for the ``TextObject``.
+
+    For each page (or slide) in a document, an instance of this class is
+    created, populated and appended into the page's ``texts`` list
+    attribute.
+
+    Args:
+        content (str): Page content as a single string.
+
+    Note:
+        No string cleaning is performed by this class. The string
+        contained in the :attr:`contents` attribute is stored exactly as
+        extracted from the page or slide's text object.
+
+    """
+
+    __slots__ = ('_content', '_hastext')
+
+    def __init__(self, content: str):
+        """Text object class initialiser."""
+        self._content = content
+        self._hastext = bool(content)
+
+    def __str__(self) -> str:
+        """When printing this object, display the text contents."""
+        return self._content
+
+    @property
+    def content(self) -> str:
+        """Accessor to the textual content."""
+        return self._content
+
+    @content.setter
+    def content(self, value: str) -> None:
+        """Setter for the ``content`` attribute.
+
+        If the ``value`` argument is populated, the content is set and
+        the ``hastext`` attribute is set to ``True``.
+
+        """
+        if value:
+            self._content = value
+            self._hastext = True
+
+    @property
+    def hastext(self) -> bool:
+        """Flag indicating if the ``content`` attribute is populated."""
+        return self._hastext

docp/objects/pdfobject.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+:Purpose:   This module provides the 'PDF Document' object structure into
+            which PDF documents are parsed into for transport and onward
+            use.
+
+:Platform:  Linux/Windows | Python 3.10+
+:Developer: J Berendt
+:Email:     development@s3dev.uk
+
+:Comments:  n/a
+
+"""
+
+try:
+    from .objects._docbaseobject import _DocBase
+    from .objects._pageobject import PageObject
+except ImportError:
+    from objects._docbaseobject import _DocBase
+    from objects._pageobject import PageObject
+
+
+class DocPDF(_DocBase):
+    """Container class for storing data parsed from a PDF file."""
+
+    def __init__(self):
+        """PDF document object class initialiser."""
+        super().__init__()
+        self._tags = False
+        # List of PageObjects, offset by 1 to align the index with page numbers.
+        self._pages = [PageObject(pageno=0)]
+
+    @property
+    def pages(self) -> list[PageObject]:
+        """A list of containing an object for each page in the document.
+
+        .. tip::
+
+            The page number index aligns to the page number in the PDF
+            file.
+
+            For example, to access the ``PageObject`` for page 42, use::
+
+                pages[42]
+
+       """
+        return self._pages
+
+    @property
+    def parsed_using_tags(self) -> bool:
+        """Flag indicating if the document was parsed using tags.
+
+        PDF documents can be created with 'marked content' tags. When
+        a PDF document is parsed using tags, as this flag indicates, the
+        parser respects columns and other page formatting schemes. If a
+        multi-column page is parsed without tags, the parser reads
+        straight across the line, thus corrupting the text.
+
+        """
+        return self._tags

docp/objects/pptxobject.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+:Purpose:   This module provides the 'PPTX Document' object structure
+            into which MS PowerPoint documents are parsed into for
+            transport and onward use.
+
+:Platform:  Linux/Windows | Python 3.10+
+:Developer: J Berendt
+:Email:     development@s3dev.uk
+
+:Comments:  n/a
+
+"""
+
+try:
+    from .objects._docbaseobject import _DocBase
+    from .objects._slideobject import SlideObject
+except ImportError:
+    from objects._docbaseobject import _DocBase
+    from objects._slideobject import SlideObject
+
+
+class DocPPTX(_DocBase):
+    """Container class for storing data parsed from a PPTX file."""
+
+    def __init__(self):
+        """PPTX document object class initialiser."""
+        super().__init__()
+        self._slides = [SlideObject(pageno=0)]
+
+    @property
+    def slides(self) -> list[SlideObject]:
+        """A list of containing an object for each slide in the document.
+
+        .. tip::
+
+            The slide number index aligns to the slide number in the
+            PPTX file.
+
+            For example, to access the ``SlideObject`` for side 42, use::
+
+                slides[42]
+
+       """
+        return self._slides