docxray 0.0.0a0__py3-none-any.whl

docxray/__init__.py

@@ -0,0 +1,6 @@
+from .api import Document
+
+__version__ = "0.0.0.alpha+build.1"
+
+
+__all__ = ["Document"]

docxray/api.py

@@ -0,0 +1,28 @@
+"""Main class for loading DOCX (Word documents)."""
+
+from .opc.constants import CONTENT_TYPE as CT
+from .oxml import TransitionalPartFactory
+from .oxml.trans.package import TransitionalPackage
+from .oxml.trans.proxy.document import Document as DocumentObject
+from .types import PkgFile
+
+
+def Document(docx: PkgFile) -> DocumentObject:
+    """Load Word document of an `.docx` format (OOXML) only for reading.
+
+    Args:
+        docx (PkgFile): String path or `Path` instance or byte stream.
+
+    Raises:
+        ValueError: If cannot get document part or parse file.
+
+    Returns:
+        DocumentObject: `Document` instance.
+    """
+    document_part = TransitionalPackage.open(
+        docx, TransitionalPartFactory
+    ).main_document_part
+    if document_part.content_type != CT.WML_DOCUMENT_MAIN:
+        tmpl = "file '%s' is not a Word file, content type is '%s'"
+        raise ValueError(tmpl % (docx, document_part.content_type))
+    return document_part.document

docxray/enum/lxml.py

@@ -0,0 +1,12 @@
+"""Enumrations for lxml (XML)."""
+
+from enum import IntEnum
+
+
+class POS(IntEnum):
+    """Describes the position of an element relative to its siblings."""
+
+    START = 0
+    MIDDLE = 1
+    END = 2
+    ONE_ITEM = 3

docxray/exceptions.py

@@ -0,0 +1,10 @@
+"""Module with exception used in `docxray`."""
+
+
+class DocxrayError(Exception):
+    """Generic error class."""
+
+
+class InvalidXmlError(DocxrayError):
+    """Raised when invalid XML is encountered, such as on attempt to access a missing
+    required child element."""

docxray/lxml.py

@@ -0,0 +1,70 @@
+"""Base module of an XML-element/functions in project"""
+
+from collections.abc import Iterator, Mapping
+from typing import Any, TypeVar
+
+from lxml import etree
+
+BASE_ELM_T = TypeVar("BASE_ELM_T", bound="BaseOxmlElement")
+
+
+class BaseOxmlElement(etree.ElementBase):
+    """Base XML-element for project (inherits from lxml `ElementBase`), provides type hints."""
+
+    def xpath(self, xpath: str, ns: dict[str, str] | None = None) -> Any:  # type: ignore[override]
+        return super().xpath(xpath, namespaces=ns)
+
+    def getparent(self, elm_hint: type[BASE_ELM_T]) -> BASE_ELM_T | None:  # type: ignore[override]
+        # Cache parent for styles
+        if not hasattr(self, "_parent"):
+            self._parent = super().getparent()
+        return self._parent  # type: ignore[return-value]
+
+    def iterfind(  # type: ignore[override]
+        self,
+        elm_qn: str,
+        elm_hint: type[BASE_ELM_T],
+        namespaces: Mapping[str, str] | None = None,
+    ) -> Iterator[BASE_ELM_T]:
+        return super().iterfind(elm_qn, namespaces)  # type: ignore[return-value]
+
+    def find(  # type: ignore[override]
+        self,
+        elm_qn: str,
+        elm_hint: type[BASE_ELM_T],
+        namespaces: Mapping[str, str] | None = None,
+    ) -> BASE_ELM_T | None:
+        return super().find(elm_qn, namespaces)  # type: ignore[return-value]
+
+    def findall(  # type: ignore[override]
+        self,
+        elm_qn: str,
+        elm_hint: type[BASE_ELM_T],
+        namespaces: Mapping[str, str] | None = None,
+    ) -> list[BASE_ELM_T]:
+        return super().findall(elm_qn, namespaces)  # type: ignore[return-value]
+
+    def __repr__(self) -> str:
+        """Repsentation of an xml-element for debug."""
+        return (
+            super().__repr__().replace("Element", self.__class__.__name__, 1)
+        )
+
+
+def elm_ns_cls_lookup(
+    fallback_cls: type[BaseOxmlElement] = BaseOxmlElement,
+) -> etree.ElementNamespaceClassLookup:
+    """Get lookup with fallback cls of an `BaseOxmlElement` or given param.
+
+    Args:
+        default_element_class (type[BaseOxmlElement], optional): Fallback cls. Defaults to BaseOxmlElement.
+
+    Returns:
+        etree.ElementNamespaceClassLookup: `ElementNamespaceClassLookup` instance.
+    """
+    lookup: etree.ElementNamespaceClassLookup = (
+        etree.ElementNamespaceClassLookup()
+    )
+    fallback = etree.ElementDefaultClassLookup(element=fallback_cls)
+    lookup.set_fallback(fallback)
+    return lookup

docxray/numeral/bcp47.py

@@ -0,0 +1,61 @@
+"""Module for getting BCP47 (Best Current Practice 47, RFC5646/4676) language tag
+in format like: `Cyrl` (Cyrillic-based chars), Latn (Latin-based chars), etc for locales like `en-US`.
+"""
+
+import csv
+from functools import lru_cache
+from pathlib import Path
+
+_DIR_ = Path(__file__).parent
+_DFLT_SCRIPT_PATH_ = _DIR_ / "iso639-default-script.tsv"
+_ICIDS_PATH_ = _DIR_ / "iso639-lcids.tsv"
+
+with open(_DFLT_SCRIPT_PATH_, "r", encoding="utf-8") as f:
+    reader = csv.DictReader(f, delimiter="\t")
+    _ISO639_DEFAULT_SCRIPT_ = {}
+    for row in reader:
+        _ISO639_DEFAULT_SCRIPT_[row["tag3"]] = row["script"]
+
+with open(_ICIDS_PATH_, "r", encoding="utf-8") as f:
+    reader = csv.DictReader(f, delimiter="\t")
+    _ISO639_ICIDS_ = {}
+    for row in reader:
+        _ISO639_ICIDS_[(row["tag1"], row["region"])] = (
+            row["tag3"],
+            row["script"],
+        )
+
+
+@lru_cache
+def script(locale: str) -> str:
+    """Get language tag for `locale`.
+
+    Examples:
+        For `en-US` it will return `Latn`.
+
+    Args:
+        locale (str): Locale with dash-format `en-US` or single lang tag `ru`.
+
+    Raises:
+        ValueError: Wrong locale format OR script not found.
+
+    Returns:
+        str: Language tag like `Latn`.
+    """
+    locale_split = locale.split("-")
+    if len(locale_split) == 2:
+        key = tuple(locale_split)
+    elif len(locale_split) == 1:
+        key = locale_split[0], ""
+    else:
+        raise ValueError(f"Wrong locale `{locale}`")
+    inf = _ISO639_ICIDS_.get(key)  # type: ignore[arg-type]
+    if inf is None:
+        raise ValueError(f"No such script for locale `{locale}`")
+    tag3, script = inf
+    if script:
+        return script
+    script = _ISO639_DEFAULT_SCRIPT_.get(tag3)
+    if script is None:
+        raise ValueError(f"No such script for locale `{locale}`")
+    return script