deepdoctection 0.42.1__py3-none-any.whl → 0.43__py3-none-any.whl

deepdoctection/utils/metacfg.py

@@ -16,7 +16,8 @@
 # limitations under the License.
 
 """
-Class AttrDict for maintaining configs and some functions for generating and saving AttrDict instances to .yaml files
+Class `AttrDict` for maintaining configs and some functions for generating and saving `AttrDict` instances to
+`.yaml` files
 """
 from __future__ import annotations
 
@@ -32,7 +33,12 @@ from .types import PathLikeOrStr
 # Licensed under the Apache License, Version 2.0 (the "License")
 class AttrDict:
     """
-    Class for storing key,values as instance with attributes and values.
+    Class `AttrDict` for maintaining configs and some functions for generating and saving `AttrDict` instances to
+    `.yaml` files.
+
+    Info:
+        This module provides a class for storing key-value pairs as attributes and functions for serializing and
+        deserializing configurations.
     """
 
     _freezed = False
@@ -41,7 +47,17 @@ class AttrDict:
 
     def __getattr__(self, name: str) -> Any:
         """
-        __getattr__
+        Returns the attribute value for `name`. If the attribute does not exist and the instance is not frozen, a new
+        `AttrDict` is created and assigned.
+
+        Args:
+            name: The name of the attribute.
+
+        Returns:
+            The value of the attribute.
+
+        Raises:
+            AttributeError: If the instance is frozen or the attribute name starts with `_`.
         """
         if self._freezed:
             raise AttributeError(name)
@@ -54,29 +70,47 @@ class AttrDict:
 
     def __setattr__(self, name: str, value: Any) -> None:
         """
-        __setattr__
+        Sets the attribute `name` to `value`.
+
+        Args:
+            name: The name of the attribute.
+            value: The value to set.
+
+        Raises:
+            AttributeError: If the instance is frozen and `name` is not `_freezed`.
         """
-        if self._freezed and name not in self.__dict__:
+        if self._freezed and name != "_freezed":
             raise AttributeError(f"Config was freezed! Unknown config: {name}")
         super().__setattr__(name, value)
 
     def __str__(self) -> str:
         """
-        __str__
+        Returns a pretty-printed string representation of the configuration.
+
+        Returns:
+            A string representation of the configuration.
         """
         return pprint.pformat(self.to_dict(), width=100, compact=True)
 
     __repr__ = __str__
 
     def to_dict(self) -> dict[str, Any]:
-        """Convert to a nested dict."""
+        """
+        Convert to a nested dict.
+
+        Returns:
+            A dictionary representation of the configuration.
+        """
         return {
             k: v.to_dict() if isinstance(v, AttrDict) else v for k, v in self.__dict__.items() if not k.startswith("_")
         }
 
     def from_dict(self, d: dict[str, Any]) -> None:  # pylint: disable=C0103
         """
-        Generate an instance from a dict
+        Generate an instance from a dict.
+
+        Args:
+            d: The dictionary to load values from.
         """
         if isinstance(d, dict):
             self.freeze(False)
@@ -90,6 +124,9 @@ class AttrDict:
     def update_args(self, args: list[str]) -> None:
         """
         Update from command line args.
+
+        Args:
+            args: A list of command line arguments in the form `key1.key2=val`.
         """
         for cfg in args:
             keys, v = cfg.split("=", maxsplit=1)  # pylint: disable=C0103
@@ -110,8 +147,11 @@ class AttrDict:
         """
         Overwrite the current config with values from another config.
 
-        :param other_config: The other AttrDict instance to copy values from.
-        :raises AttributeError: If a key from other_config is not an attribute of self.
+        Args:
+            other_config: The other `AttrDict` instance to copy values from.
+
+        Raises:
+            AttributeError: If the config is frozen.
         """
         if self._freezed:
             raise AttributeError("Config was freezed! Cannot overwrite config.")
@@ -119,7 +159,10 @@ class AttrDict:
 
     def freeze(self, freezed: bool = True) -> None:
         """
-        :param freezed: freeze the instance, so that no attributes can be added or changed
+        Freeze or unfreeze the instance, so that no attributes can be added or changed.
+
+        Args:
+            freezed: Whether to freeze the instance.
         """
         self._freezed = freezed
         for v in self.__dict__.values():  # pylint: disable=C0103
@@ -136,9 +179,13 @@ class AttrDict:
 
 def set_config_by_yaml(path_yaml: PathLikeOrStr) -> AttrDict:
     """
-    Use to initialize the config class for tensorpack faster rcnn
+    Initialize the config class from a YAML file.
+
+    Args:
+        path_yaml: The path to the YAML file.
 
-    :param path_yaml: The path to the file
+    Returns:
+        An `AttrDict` instance initialized from the YAML file.
     """
     config = AttrDict()
     _C = config  # pylint: disable=C0103
@@ -153,9 +200,17 @@ def set_config_by_yaml(path_yaml: PathLikeOrStr) -> AttrDict:
 
 def save_config_to_yaml(config: AttrDict, path_yaml: PathLikeOrStr) -> None:
     """
-    :param config: The configuration instance as an AttrDict
-    :param path_yaml: Save the config class for tensorpack faster rcnn
-    :return: yaml_path: The path to save the file to
+    Save the configuration instance as a YAML file.
+
+    Example:
+        ```python
+        save_config_to_yaml(config, "config.yaml")
+        ```
+
+    Args:
+        config: The configuration instance as an `AttrDict`.
+        path_yaml: The path to save the YAML file to.
+
     """
 
     with open(path_yaml, "w") as file:  # pylint: disable=W1514
@@ -164,12 +219,19 @@ def save_config_to_yaml(config: AttrDict, path_yaml: PathLikeOrStr) -> None:
 
 def config_to_cli_str(config: AttrDict, *exclude: str) -> str:
     """
-    Transform an AttrDict to a string that can be passed to a cli. Add optionally keys of the config that should not be
-    added to the string.
+    Transform an `AttrDict` to a string that can be passed to a CLI. Optionally exclude keys from the string.
+
+    Example:
+        ```python
+        config_to_cli_str(config, "key1", "key2")
+        ```
+
+    Args:
+        config: An `AttrDict`.
+        *exclude: Keys of the `AttrDict` to exclude.
 
-    :param config: An `AttrDict`
-    :param exclude: keys of the AttrDict
-    :return: A string that can be passed to a cli
+    Returns:
+        A string that can be passed to a CLI.
     """
 
     config_dict = config.to_dict()

deepdoctection/utils/pdf_utils.py

@@ -16,8 +16,9 @@
 # limitations under the License.
 
 """
-Module with pdf processing tools
+Pdf processing tools
 """
+
 import os
 import platform
 import subprocess
@@ -57,17 +58,20 @@ __all__ = [
 
 def decrypt_pdf_document(path: PathLikeOrStr) -> bool:
     """
-    Decrypting a pdf. As copying a pdf document removes the password that protects pdf, this method
-    generates a copy and decrypts the copy using qpdf. The result is saved as the original
-    document.
+    Decrypt a PDF file.
+
+    As copying a PDF document removes the password that protects the PDF, this method generates a copy and decrypts the
+    copy using `qpdf`. The result is saved as the original document.
 
-    qpdf: <http://qpdf.sourceforge.net/>
+    Note:
+        This decryption does not work if the PDF has a readable protection, in which case no solution is provided.
+        `qpdf`: <http://qpdf.sourceforge.net/>
 
-    Note, that this is decryption does not work, if the pdf has a readable protection, in which case we do not
-    provide any solution.
+    Args:
+        path: A path to the PDF file.
 
-    :param path: A path to the pdf file
-    :return: True if document has been successfully decrypted
+    Returns:
+        True if the document has been successfully decrypted.
     """
     if qpdf_available():
         path_base, file_name = os.path.split(path)
@@ -88,12 +92,20 @@ def decrypt_pdf_document(path: PathLikeOrStr) -> bool:
 
 def decrypt_pdf_document_from_bytes(input_bytes: bytes) -> bytes:
     """
-    Decrypting a pdf given as bytes. Under the hood, it saves the bytes to a temporary file and then calls
+    Decrypt a PDF given as bytes.
+
+    Under the hood, it saves the bytes to a temporary file and then calls `decrypt_pdf_document`.
+
+    Note:
+        `qpdf`: <http://qpdf.sourceforge.net/>
+
+    Args:
+        input_bytes: A bytes object representing the PDF file.
+
+    Returns:
+        The decrypted bytes object.
 
-    qpdf: <http://qpdf.sourceforge.net/>
 
-    :param input_bytes: A bytes object representing the pdf file
-    :return: The decrypted bytes object
     """
     with save_tmp_file(input_bytes, "pdf_") as (_, input_file_name):
         is_decrypted = decrypt_pdf_document(input_file_name)
@@ -107,11 +119,16 @@ def decrypt_pdf_document_from_bytes(input_bytes: bytes) -> bytes:
 
 def get_pdf_file_reader(path_or_bytes: Union[PathLikeOrStr, bytes]) -> PdfReader:
     """
-    Creates a file reader object from a pdf document. Will try to decrypt the document if it is
-    encrypted. (See `decrypt_pdf_document` to understand what is meant with "decrypt").
+    Create a file reader object from a PDF document.
+
+    Will try to decrypt the document if it is encrypted. (See `decrypt_pdf_document` to understand what is meant with
+    "decrypt").
 
-    :param path_or_bytes: A path to a pdf document
-    :return: A file reader object from which you can iterate through the document.
+    Args:
+        path_or_bytes: A path to a PDF document or bytes.
+
+    Returns:
+        A file reader object from which you can iterate through the document.
     """
 
     if isinstance(path_or_bytes, bytes):
@@ -153,39 +170,47 @@ def get_pdf_file_reader(path_or_bytes: Union[PathLikeOrStr, bytes]) -> PdfReader
 
 def get_pdf_file_writer() -> PdfWriter:
     """
-    `PdfWriter` instance
+    `PdfWriter` instance.
+
+    Returns:
+        A new `PdfWriter` instance.
     """
     return PdfWriter()
 
 
 class PDFStreamer:
     """
-    A class for streaming pdf documents as bytes objects. Build as a generator, it is possible to load the document
-    iteratively into memory. Uses py2pdf FileReader and FileWriter.
-
-    **Example:**
-
-             # Building a Dataflow with a PDFStreamer
-             df = dataflow.DataFromIterable(PDFStreamer(path=path))
-             df.reset_state()
-
-             for page in df:
-                ... # do whatever you like
-
-             # Something else you can do:
-            streamer = PDFStreamer(path=path)
-            pages = len(streamer)  # get the number of pages
-            random_int = random.sample(range(0, pages), 2) # select some pages
-            for ran in random_int:
-                pdf_bytes = streamer[ran]   # get the page bytes directly
-
-            streamer.close() # Do not forget to close the streamer, otherwise the file will never be closed and might
-                             # cause memory leaks if you open many files.
+    A class for streaming PDF documents as bytes objects.
+
+    Built as a generator, it is possible to load the document iteratively into memory. Uses `pypdf` `PdfReader` and
+    `PdfWriter`.
+
+    Example:
+        ```python
+        df = dataflow.DataFromIterable(PDFStreamer(path=path))
+        df.reset_state()
+        for page in df:
+            ...
+        streamer = PDFStreamer(path=path)
+        pages = len(streamer)
+        random_int = random.sample(range(0, pages), 2)
+        for ran in random_int:
+            pdf_bytes = streamer[ran]
+        streamer.close()
+        ```
+
+    Note:
+        Do not forget to close the streamer, otherwise the file will never be closed and might cause memory leaks if
+        you open many files.
     """
 
     def __init__(self, path_or_bytes: Union[PathLikeOrStr, bytes]) -> None:
         """
-        :param path_or_bytes: to a pdf.
+        Args:
+            path_or_bytes: Path to a PDF.
+
+        Returns:
+            None.
         """
         self.file_reader = get_pdf_file_reader(path_or_bytes)
         self.file_writer = PdfWriter()
@@ -256,10 +281,15 @@ def _input_to_cli_str(
 
 class PopplerError(RuntimeError):
     """
-    Poppler Error
+    Poppler Error.
     """
 
     def __init__(self, status: int, message: str) -> None:
+        """
+        Args:
+            status: Error status code.
+            message: Error message.
+        """
         super().__init__()
         self.status = status
         self.message = message
@@ -283,13 +313,20 @@ def pdf_to_np_array_poppler(
     pdf_bytes: bytes, size: Optional[tuple[int, int]] = None, dpi: Optional[int] = None
 ) -> PixelValues:
     """
-    Convert a single pdf page from its byte representation to a numpy array. This function will save the pdf as to a tmp
-    file and then call poppler via `pdftoppm` resp. `pdftocairo` if the former is not available.
+    Convert a single PDF page from its byte representation to a numpy array using Poppler.
+
+    This function will save the PDF as a temporary file and then call Poppler via `pdftoppm` or `pdftocairo`.
 
-    :param pdf_bytes: Bytes representing the PDF file
-    :param size: Size of the resulting image(s), uses (width, height) standard
-    :param dpi:  Image quality in DPI/dots-per-inch (default 200)
-    :return: numpy array
+    Raises:
+        ValueError: If neither `dpi` nor `size` is provided.
+
+    Args:
+        pdf_bytes: Bytes representing the PDF file.
+        size: Size of the resulting image(s), as (width, height).
+        dpi: Image quality in DPI/dots-per-inch.
+
+    Returns:
+        `np.array`.
     """
     if dpi is None and size is None:
         raise ValueError("Either dpi or size must be provided.")
@@ -302,11 +339,17 @@ def pdf_to_np_array_poppler(
 
 def pdf_to_np_array_pdfmium(pdf_bytes: bytes, dpi: Optional[int] = None) -> PixelValues:
     """
-    Convert a single pdf page from its byte representation to a numpy array using pdfium.
+    Convert a single PDF page from its byte representation to a numpy array using pdfium.
+
+    Args:
+        pdf_bytes: Bytes representing the PDF file.
+        dpi: Image quality in DPI/dots-per-inch.
 
-    :param pdf_bytes: Bytes representing the PDF file
-    :param dpi:  Image quality in DPI/dots-per-inch (default 200)
-    :return: numpy array
+    Returns:
+        `np.array`.
+
+    Raises:
+        ValueError: If `dpi` is not provided.
     """
     if dpi is None:
         raise ValueError("dpi must be provided.")
@@ -316,13 +359,21 @@ def pdf_to_np_array_pdfmium(pdf_bytes: bytes, dpi: Optional[int] = None) -> Pixe
 
 def pdf_to_np_array(pdf_bytes: bytes, size: Optional[tuple[int, int]] = None, dpi: Optional[int] = None) -> PixelValues:
     """
-    Convert a single pdf page from its byte representation to a numpy array. This function will either use Poppler or
-    pdfium to render the pdf.
+    Convert a single PDF page from its byte representation to a `np.array`.
+
+    This function will either use Poppler or pdfium to render the PDF.
+
+    Args:
+        pdf_bytes: Bytes representing the PDF file.
+        size: Size of the resulting image(s), as (width, height).
+        dpi: Image quality in DPI/dots-per-inch.
 
-    :param pdf_bytes: Bytes representing the PDF file
-    :param size: Size of the resulting image(s), uses (width, height) standard
-    :param dpi:  Image quality in DPI/dots-per-inch (default 200)
-    :return: numpy array
+    Returns:
+        `np.array`.
+
+    Note:
+        If `USE_DD_PDFIUM` is set, `pdf_to_np_array_pdfmium` does not support the `size` parameter and will use
+        `dpi` instead.
     """
     if os.environ.get("USE_DD_PDFIUM", "False") in ENV_VARS_TRUE:
         if size is not None:
@@ -339,12 +390,18 @@ def split_pdf(
     pdf_path: PathLikeOrStr, output_dir: PathLikeOrStr, file_type: Literal["image", "pdf"], dpi: int = 200
 ) -> None:
     """
-    Split a pdf into single pages. The pages are saved as single pdf/png files in a subfolder of the output directory.
+    Split a PDF into single pages.
+
+    The pages are saved as single PDF or PNG files in a subfolder of the output directory.
+
+    Args:
+        pdf_path: Path to the PDF file.
+        output_dir: Path to the output directory.
+        file_type: Type of the output file. Either "image" or "pdf".
+        dpi: Image quality in DPI/dots-per-inch.
 
-    :param pdf_path: Path to the pdf file
-    :param output_dir: Path to the output directory
-    :param file_type: Type of the output file. Either "image" or "pdf"
-    :param dpi: Image quality in DPI/dots-per-inch (default
+    Returns:
+        None.
     """
     pdf_path = Path(pdf_path)
     filename = pdf_path.stem

deepdoctection/utils/settings.py

@@ -79,6 +79,7 @@ class SummaryType(ObjectTypes):
     """Summary type member"""
 
     SUMMARY = "summary"
+    DOCUMENT_SUMMARY = "document_summary"
 
 
 @object_types_registry.register("DocumentType")
@@ -329,12 +330,18 @@ _TOKEN_AND_TAG_TO_TOKEN_CLASS_WITH_TAG = {
 
 def token_class_tag_to_token_class_with_tag(token: ObjectTypes, tag: ObjectTypes) -> ObjectTypes:
     """
-    Mapping TokenClassWithTag enum member from token class and tag, e.g. `TokenClasses.header` and `BioTag.inside`
-    maps to TokenClassWithTag.i_header.
+    Maps a `TokenClassWithTag` enum member from a token class and tag, e.g. `TokenClasses.header` and `BioTag.inside`
+    maps to `TokenClassWithTag.i_header`.
 
-    :param token: TokenClasses member
-    :param tag: BioTag member
-    :return: TokenClassWithTag member
+    Args:
+        token: TokenClasses member.
+        tag: BioTag member.
+
+    Returns:
+        TokenClassWithTag member.
+
+    Raises:
+        TypeError: If token is not of type TokenClasses or tag is not of type BioTag.
     """
     if isinstance(token, TokenClasses) and isinstance(tag, BioTag):
         return _TOKEN_AND_TAG_TO_TOKEN_CLASS_WITH_TAG[(token, tag)]
@@ -349,8 +356,11 @@ def token_class_with_tag_to_token_class_and_tag(
     """
     This is the reverse mapping from TokenClassWithTag members to TokenClasses and BioTag
 
-    :param token_class_with_tag: TokenClassWithTag member
-    :return: Tuple of TokenClasses member and BioTag member
+    Args:
+        token_class_with_tag: `TokenClassWithTag` member
+
+    Returns:
+        Tuple of `TokenClasses` member and `BioTag` member
     """
     return {val: key for key, val in _TOKEN_AND_TAG_TO_TOKEN_CLASS_WITH_TAG.items()}.get(token_class_with_tag)
 
@@ -405,10 +415,13 @@ def update_black_list(item: str) -> None:
 
 
 def get_type(obj_type: Union[str, ObjectTypes]) -> ObjectTypes:
-    """Get an object type property from a given string. Does nothing if an ObjectType is passed
+    """
+    Get an object type property from a given string. Does nothing if an `ObjectType` is passed
 
-    :param obj_type: String or ObjectTypes
-    :return: ObjectType
+    Args:
+        obj_type: String or ObjectTypes
+    Returns:
+        `ObjectType`
     """
     if isinstance(obj_type, ObjectTypes):
         return obj_type
@@ -435,6 +448,7 @@ if os.environ.get("DEEPDOCTECTION_CACHE"):
 else:
     dd_cache_home = Path(os.getenv("XDG_CACHE_HOME", Path.home() / ".cache")) / "deepdoctection"
 
+CACHE_DIR = dd_cache_home
 MODEL_DIR = dd_cache_home / "weights"
 
 # configs cache directory

deepdoctection/utils/tqdm.py

@@ -32,8 +32,10 @@ def get_tqdm_default_kwargs(
     **kwargs: Optional[Union[str, int, float]]
 ) -> Dict[str, Union[str, float, bool, int, None]]:
     """
-    Return default arguments to be used with tqdm.
-    :param kwargs: extra arguments to be used.
+    Return default arguments to be used with `tqdm`.
+
+    Args:
+        kwargs: extra arguments to be used.
     """
 
     return {
@@ -49,10 +51,13 @@ def get_tqdm_default_kwargs(
 
 def get_tqdm(total: Optional[Union[int, float]] = None, **kwargs: Union[str, int, float]) -> TqdmType:
     """
-    Get tqdm progress bar with some default options to have consistent style.
+    Get `tqdm` progress bar with some default options to have consistent style.
+
+    Args:
+        total:  The number of expected iterations.
 
-    :param total:  The number of expected iterations.
-    :return: A tqdm instance
+    Returns:
+        A `tqdm` instance
     """
 
     default_tqdm_setting = get_tqdm_default_kwargs(total=total)