aspose-pdf-foss-for-python 0.1.0__py3-none-any.whl

aspose_pdf/__init__.py

@@ -0,0 +1,367 @@
+"""Production-facing public API for the ``aspose_pdf`` package."""
+
+from ._version import __version__
+from .annotations import (
+    Annotation,
+    AnnotationCollection,
+    AnnotationFlags,
+    AnnotationType,
+    CircleAnnotation,
+    FileAttachmentAnnotation,
+    FreeTextAnnotation,
+    HighlightAnnotation,
+    InkAnnotation,
+    LineAnnotation,
+    LinkAnnotation,
+    MarkupAnnotation,
+    PolygonAnnotation,
+    PolyLineAnnotation,
+    PopupAnnotation,
+    RedactAnnotation,
+    SquareAnnotation,
+    SquigglyAnnotation,
+    StampAnnotation,
+    StrikeOutAnnotation,
+    TextAnnotation,
+    UnderlineAnnotation,
+    quad_from_rect,
+)
+from .attachments import AF_RELATIONSHIPS, FileSpecification
+from .auto_links import AutoLinkResult
+from .block_extraction import ExtractedBlock
+from .color import Color
+from .destinations import NamedDestinationCollection
+from .document import Document
+from .document_fonts import DocumentFont
+from .exceptions import (
+    FontEmbeddingException,
+    PdfResourceLimitException,
+    UnsupportedFeatureException,
+)
+from .facades import (
+    PdfAnnotationEditor,
+    PdfBookmarkEditor,
+    PdfConverter,
+    PdfExtractor,
+    PdfFileEditor,
+    PdfFileInfo,
+    PdfFileSecurity,
+    PdfFileStamp,
+    PdfPageEditor,
+    PdfXmpMetadata,
+)
+from .font_registry import FontDescriptor
+from .font_repository import (
+    FileFontSource,
+    FolderFontSource,
+    FontRepository,
+    FontSource,
+    MemoryFontSource,
+    SystemFontSource,
+)
+from .font_substitution import FontSubstitutionOptions
+from .forms import (
+    Field,
+    FieldType,
+    FieldWidget,
+    Form,
+    FormType,
+    FormValidationIssue,
+    UnsignedContent,
+    UnsignedContentAbsorber,
+)
+from .image_resolution import ImageResolutionIssue
+from .interactive import (
+    Action,
+    Destination,
+    FitBDestination,
+    FitBHDestination,
+    FitBVDestination,
+    FitDestination,
+    FitHDestination,
+    FitRDestination,
+    FitVDestination,
+    GoToAction,
+    GoToRAction,
+    JavaScriptAction,
+    LaunchAction,
+    NamedAction,
+    ResetFormAction,
+    SubmitFormAction,
+    URIAction,
+    XYZDestination,
+)
+from .link_extraction import ExtractedLink
+from .link_validation import LinkValidationIssue
+from .lists import ListItem, TextList
+from .load_limits import PdfLoadLimits
+from .lowcode import (
+    ByteArrayDataSource,
+    DataSource,
+    FileDataSource,
+    FormFiller,
+    FormFillerOptions,
+    MergeOptions,
+    Merger,
+    OperationResult,
+    OptimizeOptions,
+    Optimizer,
+    PdfPlugin,
+    Plugin,
+    PluginOptions,
+    ResultContainer,
+    SplitOptions,
+    Splitter,
+    StreamDataSource,
+    TextExtractor,
+    TextExtractorOptions,
+)
+from .optimization import OptimizationOptions
+from .outlines import OutlineCollection, OutlineItem
+from .page_labels import NumberingStyle, PageLabel, PageLabelCollection
+from .page_ranges import parse_page_range
+from .page_size import PageSize
+from .pages import Page, PageCollection
+from .paths import GraphicsPath
+from .pdfa import PdfAValidateOptions, PdfAValidationResult, PdfAValidator
+from .pdfua import PdfUaValidateOptions, PdfUaValidationResult, PdfUaValidator
+from .pdfx import (
+    PdfXStandard,
+    PdfXValidateOptions,
+    PdfXValidationResult,
+    PdfXValidator,
+)
+from .permissions import Permissions
+from .recipients import Recipient
+from .sanitization import SanitizationReport
+from .signature import PdfSignature
+from .signature_appearance import SignatureAppearance
+from .stamps import (
+    HorizontalAlignment,
+    ImageStamp,
+    PageNumberStamp,
+    PageStamp,
+    Stamp,
+    TextStamp,
+    VerticalAlignment,
+)
+from .table_extraction import ExtractedTable
+from .tables import Cell, Row, Table
+from .tagged import StructureElement, TaggedContent
+from .text import TextHighlightResult, TextMarkupResult, TextWord
+from .text_block import Paragraph, TextBlock
+from .text_comparison import PageTextComparison
+from .text_layout import TextLayoutOptions
+from .validation import (
+    CertificationLevel,
+    RevocationStatus,
+    TrustStatus,
+    ValidationMethod,
+    ValidationMode,
+    ValidationOptions,
+    ValidationResult,
+    ValidationStatus,
+)
+from .viewer_preferences import (
+    DuplexMode,
+    PageBoundary,
+    PageLayout,
+    PageMode,
+    PrintScaling,
+    ReadingDirection,
+    ViewerPreferences,
+)
+from .visual_comparison import PageVisualComparison
+from .visualization import RasterizedPage
+from .xmp import (
+    NamespaceProvider,
+    XmpArray,
+    XmpField,
+    XmpPacket,
+    XmpProperty,
+    XmpStruct,
+)
+from .xmp import (
+    parse as parse_xmp,
+)
+from .xmp import (
+    serialize as serialize_xmp,
+)
+
+__all__ = [
+    "AF_RELATIONSHIPS",
+    "Action",
+    "Annotation",
+    "AnnotationCollection",
+    "AnnotationFlags",
+    "AnnotationType",
+    "AutoLinkResult",
+    "ByteArrayDataSource",
+    "Cell",
+    "CertificationLevel",
+    "CircleAnnotation",
+    "Color",
+    "DataSource",
+    "Destination",
+    "Document",
+    "DocumentFont",
+    "DuplexMode",
+    "ExtractedBlock",
+    "ExtractedLink",
+    "ExtractedTable",
+    "Field",
+    "FieldType",
+    "FieldWidget",
+    "FileAttachmentAnnotation",
+    "FileDataSource",
+    "FileFontSource",
+    "FileSpecification",
+    "FitBDestination",
+    "FitBHDestination",
+    "FitBVDestination",
+    "FitDestination",
+    "FitHDestination",
+    "FitRDestination",
+    "FitVDestination",
+    "FolderFontSource",
+    "FontDescriptor",
+    "FontEmbeddingException",
+    "FontRepository",
+    "FontSource",
+    "FontSubstitutionOptions",
+    "Form",
+    "FormFiller",
+    "FormFillerOptions",
+    "FormType",
+    "FormValidationIssue",
+    "FreeTextAnnotation",
+    "GoToAction",
+    "GoToRAction",
+    "GraphicsPath",
+    "HighlightAnnotation",
+    "HorizontalAlignment",
+    "ImageResolutionIssue",
+    "ImageStamp",
+    "InkAnnotation",
+    "JavaScriptAction",
+    "LaunchAction",
+    "LineAnnotation",
+    "LinkAnnotation",
+    "LinkValidationIssue",
+    "ListItem",
+    "MarkupAnnotation",
+    "MemoryFontSource",
+    "MergeOptions",
+    "Merger",
+    "NamedAction",
+    "NamedDestinationCollection",
+    "NamespaceProvider",
+    "NumberingStyle",
+    "OperationResult",
+    "OptimizationOptions",
+    "OptimizeOptions",
+    "Optimizer",
+    "OutlineCollection",
+    "OutlineItem",
+    "Page",
+    "PageBoundary",
+    "PageCollection",
+    "PageLabel",
+    "PageLabelCollection",
+    "PageLayout",
+    "PageMode",
+    "PageNumberStamp",
+    "PageSize",
+    "PageStamp",
+    "PageTextComparison",
+    "PageVisualComparison",
+    "Paragraph",
+    "PdfAValidateOptions",
+    "PdfAValidationResult",
+    "PdfAValidator",
+    "PdfAnnotationEditor",
+    "PdfBookmarkEditor",
+    "PdfConverter",
+    "PdfExtractor",
+    "PdfFileEditor",
+    "PdfFileInfo",
+    "PdfFileSecurity",
+    "PdfFileStamp",
+    "PdfLoadLimits",
+    "PdfPageEditor",
+    "PdfPlugin",
+    "PdfResourceLimitException",
+    "PdfSignature",
+    "PdfUaValidateOptions",
+    "PdfUaValidationResult",
+    "PdfUaValidator",
+    "PdfXStandard",
+    "PdfXValidateOptions",
+    "PdfXValidationResult",
+    "PdfXValidator",
+    "PdfXmpMetadata",
+    "Permissions",
+    "Plugin",
+    "PluginOptions",
+    "PolyLineAnnotation",
+    "PolygonAnnotation",
+    "PopupAnnotation",
+    "PrintScaling",
+    "RasterizedPage",
+    "ReadingDirection",
+    "Recipient",
+    "RedactAnnotation",
+    "ResetFormAction",
+    "ResultContainer",
+    "RevocationStatus",
+    "Row",
+    "SanitizationReport",
+    "SignatureAppearance",
+    "SplitOptions",
+    "Splitter",
+    "SquareAnnotation",
+    "SquigglyAnnotation",
+    "Stamp",
+    "StampAnnotation",
+    "StreamDataSource",
+    "StrikeOutAnnotation",
+    "StructureElement",
+    "SubmitFormAction",
+    "SystemFontSource",
+    "Table",
+    "TaggedContent",
+    "TextAnnotation",
+    "TextBlock",
+    "TextExtractor",
+    "TextExtractorOptions",
+    "TextHighlightResult",
+    "TextLayoutOptions",
+    "TextList",
+    "TextMarkupResult",
+    "TextStamp",
+    "TextWord",
+    "TrustStatus",
+    "URIAction",
+    "UnderlineAnnotation",
+    "UnsignedContent",
+    "UnsignedContentAbsorber",
+    "UnsupportedFeatureException",
+    "ValidationMethod",
+    "ValidationMode",
+    "ValidationOptions",
+    "ValidationResult",
+    "ValidationStatus",
+    "VerticalAlignment",
+    "ViewerPreferences",
+    "XYZDestination",
+    "XmpArray",
+    "XmpField",
+    "XmpPacket",
+    "XmpProperty",
+    "XmpStruct",
+    "__version__",
+    "parse_page_range",
+    "parse_xmp",
+    "quad_from_rect",
+    "serialize_xmp",
+]

aspose_pdf/_compat_surface.py

@@ -0,0 +1,142 @@
+"""Explicit rejection of compatibility names that have no implementation.
+
+The package ships option, enumeration, and value objects for the parts of the
+Aspose.PDF API this project does not implement (HTML/SVG/CGM/OFD/CDR import,
+LaTeX authoring, PPTX export, printing). They exist so that porting code keeps
+importing, not so that it silently produces nothing: every real operation routes
+its format/option arguments through the helpers below and raises
+:class:`~aspose_pdf.exceptions.UnsupportedFeatureException` instead.
+
+Surfaces are matched by class name rather than by import so that this module
+stays free of package-level import cycles and keeps working for the thin
+subclasses in :mod:`aspose_pdf.svg` and friends.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+from aspose_pdf.exceptions import UnsupportedFeatureException
+
+__all__ = [
+    "describe",
+    "reject_load_options",
+    "reject_operation",
+    "require_pdf_save_format",
+]
+
+_DOC_POINTER = (
+    "See 'Known Unsupported Compatibility Surfaces' in supported-features.md."
+)
+
+# Class name -> feature the class stands for.
+_UNSUPPORTED_TYPES: dict[str, str] = {
+    "CdrLoadOptions": "CorelDRAW (CDR) import",
+    "CgmLoadOptions": "CGM import",
+    "HtmlLoadOptions": "HTML import",
+    "LatexFragment": "LaTeX authoring",
+    "OfdLoadOptions": "OFD import",
+    "PrinterSettings": "printing",
+    "SvgLoadOptions": "SVG import",
+}
+
+# (enum class name, member name) -> feature the member stands for.
+_UNSUPPORTED_MEMBERS: dict[tuple[str, str], str] = {
+    ("SaveFormat", "PPTX"): "PPTX export",
+}
+
+# (enum class name, member name) pairs that mean "plain PDF".
+_PDF_MEMBERS: frozenset[tuple[str, str]] = frozenset(
+    {("DocFormat", "PDF"), ("SaveFormat", "PDF")}
+)
+
+
+def _is_package_class(cls: type) -> bool:
+    module = getattr(cls, "__module__", "")
+    return module == "aspose_pdf" or module.startswith("aspose_pdf.")
+
+
+def _member_key(value: Any) -> tuple[str, str] | None:
+    name = getattr(value, "name", None)
+    if not isinstance(name, str):
+        return None
+    cls = type(value)
+    if not _is_package_class(cls):
+        return None
+    return (cls.__name__, name)
+
+
+def describe(value: Any) -> str | None:
+    """Return the unimplemented feature *value* stands for, else ``None``."""
+    if value is None:
+        return None
+
+    key = _member_key(value)
+    if key is not None and key in _UNSUPPORTED_MEMBERS:
+        return _UNSUPPORTED_MEMBERS[key]
+
+    for cls in type(value).__mro__:
+        if not _is_package_class(cls):
+            continue
+        feature = _UNSUPPORTED_TYPES.get(cls.__name__)
+        if feature is not None:
+            return feature
+    return None
+
+
+def _fail(feature: str, subject: str) -> NoReturn:
+    raise UnsupportedFeatureException(
+        f"{feature} is not implemented; {subject} is an API-compatibility "
+        f"placeholder. {_DOC_POINTER}"
+    )
+
+
+def reject_operation(value: Any, subject: str) -> NoReturn:
+    """Reject an operation on a placeholder object.
+
+    A placeholder may be *constructed* -- that is what keeps ported code
+    importing and running as far as the first real use. Asking one to do work
+    is the real use, and doing nothing quietly would leave the caller to find
+    out from a blank page.
+    """
+    feature = describe(value) or "this surface"
+    _fail(feature, subject)
+
+
+def reject_load_options(value: Any) -> NoReturn:
+    """Reject a non-``None`` load-options argument.
+
+    No load options are implemented: importing a non-PDF format is out of
+    scope, and PDF loading is configured through ``password`` and ``limits``.
+    """
+    feature = describe(value)
+    if feature is not None:
+        _fail(feature, f"`{type(value).__name__}`")
+    raise TypeError(
+        "load options are not supported; loading accepts PDF data only, "
+        "configured through the password and limits keywords. "
+        f"{_DOC_POINTER}"
+    )
+
+
+def require_pdf_save_format(value: Any) -> None:
+    """Accept ``None`` or a PDF save format; reject every other export."""
+    if value is None:
+        return
+
+    key = _member_key(value)
+    if key is not None:
+        if key in _PDF_MEMBERS:
+            return
+        feature = _UNSUPPORTED_MEMBERS.get(key)
+        if feature is not None:
+            _fail(feature, f"`{key[0]}.{key[1]}`")
+
+    feature = describe(value)
+    if feature is not None:
+        _fail(feature, f"`{type(value).__name__}`")
+
+    raise TypeError(
+        "save_format must be SaveFormat.PDF, DocFormat.PDF, or None; "
+        f"saving writes PDF only. {_DOC_POINTER}"
+    )

aspose_pdf/_export_files.py

@@ -0,0 +1,108 @@
+"""The files an HTML, Markdown or SVG export writes, and the options that shape them.
+
+An export can be several files -- a document per page, the images it links to
+-- so everything is produced in memory first, the targets are checked against
+``overwrite`` all together, and only then is anything written, each file
+atomically (:func:`~aspose_pdf.engine.file_output.write_file_atomically`). A
+refused save writes nothing; a failed one leaves every file it had not reached
+as it was, and every file it had reached complete.
+"""
+
+from __future__ import annotations
+
+import os
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+from aspose_pdf.engine.file_output import write_file_atomically
+from aspose_pdf.exceptions import PdfValidationException, UnsupportedFeatureException
+
+
+def directory_beside(target: Path, directory: str | os.PathLike[str]) -> Path:
+    """*directory*, a relative one taken from the folder *target* is written to."""
+    path = Path(directory)
+    return path if path.is_absolute() else target.parent / path
+
+
+def relative_url(path: Path, base: Path) -> str:
+    """The URL of *path* as a document in folder *base* refers to it."""
+    try:
+        relative = os.path.relpath(path, base)
+    except ValueError:  # another drive (Windows): no relative path exists
+        return path.resolve().as_uri()
+    return urllib.parse.quote(Path(relative).as_posix())
+
+
+class ExportImages:
+    """Figures written as PNG files in *directory*, each distinct image once.
+
+    Called with a figure's PNG bytes, it names the file the image goes to and
+    returns the URL the document at *base* refers to it by.
+    """
+
+    def __init__(self, directory: Path, stem: str, base: Path) -> None:
+        self.directory = directory
+        self.stem = stem
+        self.base = base
+        self.files: dict[bytes, Path] = {}
+
+    def __call__(self, png: bytes) -> str:
+        path = self.files.get(png)
+        if path is None:
+            path = self.directory / f"{self.stem}-image-{len(self.files) + 1}.png"
+            self.files[png] = path
+        return relative_url(path, self.base)
+
+    def outputs(self) -> list[tuple[Path, bytes]]:
+        return [(path, png) for png, path in self.files.items()]
+
+
+def check_targets(paths: list[Path], overwrite: bool) -> None:
+    """Refuse the whole export when one of its files exists and may not be replaced."""
+    if overwrite:
+        return
+    for path in paths:
+        if path.exists():
+            raise FileExistsError(f"File already exists: {path}")
+
+
+def write_files(files: list[tuple[Path, bytes]], overwrite: bool) -> None:
+    """Write every file of an export, after checking all of them."""
+    check_targets([path for path, _ in files], overwrite)
+    for path, data in files:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        write_file_atomically(path, data)
+
+
+def html_arguments(options: Any) -> dict[str, Any]:
+    """``Document.save_as_html`` keywords for an ``HtmlSaveOptions``."""
+    for name in ("xps_intermediate_file", "aps_intermediate_file"):
+        if getattr(options, name, None) is not None:
+            raise UnsupportedFeatureException(
+                f"HtmlSaveOptions.{name} names an intermediate file this export "
+                "does not produce: it converts the page structure directly"
+            )
+    gap = getattr(options, "max_distance_between_text_lines", None)
+    return {
+        "split_into_pages": bool(getattr(options, "split_into_pages", False)),
+        "resources_directory": getattr(options, "resources_directory", None),
+        "clip_to_page": bool(getattr(options, "use_area_clipping", True)),
+        "paragraph_gap": None if gap is None else float(gap),
+    }
+
+
+def markdown_arguments(options: Any) -> dict[str, Any]:
+    """``Document.save_as_markdown`` keywords for a ``MarkdownSaveOptions``."""
+    image_directory = getattr(options, "image_directory", None)
+    resources_name = getattr(options, "resources_directory_name", None)
+    if image_directory is not None and resources_name is not None:
+        raise PdfValidationException(
+            "MarkdownSaveOptions: set image_directory or resources_directory_name, "
+            "not both -- they name the same folder"
+        )
+    return {
+        "embed_images": bool(getattr(options, "extract_images", True)),
+        "image_directory": image_directory if image_directory is not None else resources_name,
+        "markdown_format": getattr(options, "markdown_format", "GFM"),
+    }