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

deepdoctection/utils/fs.py

@@ -32,7 +32,7 @@ from urllib.request import urlretrieve
 from .develop import deprecated
 from .logger import LoggingRecord, logger
 from .pdf_utils import get_pdf_file_reader, get_pdf_file_writer
-from .settings import CONFIGS, DATASET_DIR, MODEL_DIR, PATH
+from .settings import CACHE_DIR, CONFIGS, DATASET_DIR, MODEL_DIR, PATH
 from .tqdm import get_tqdm
 from .types import B64, B64Str, JsonDict, PathLikeOrStr, PixelValues
 from .utils import is_file_extension
@@ -48,6 +48,7 @@ __all__ = [
     "load_json",
     "sub_path",
     "get_package_path",
+    "get_cache_dir_path",
     "get_configs_dir_path",
     "get_weights_dir_path",
     "get_dataset_dir_path",
@@ -57,7 +58,19 @@ __all__ = [
 
 def sizeof_fmt(num: float, suffix: str = "B") -> str:
     """
-    Converting bytes number into human-readable
+    Converts a number of bytes into a human-readable string.
+
+    Example:
+        ```python
+        sizeof_fmt(1024)
+        ```
+
+    Args:
+        num: The number of bytes.
+        suffix: The suffix to use (default is `B`).
+
+    Returns:
+        A human-readable string representation of the byte size.
     """
     for unit in ["", "Ki", "Mi", "Gi", "Ti", "Pi", "Ei", "Zi"]:
         if abs(num) < 1024.0:
@@ -70,9 +83,18 @@ def sizeof_fmt(num: float, suffix: str = "B") -> str:
 # Licensed under the Apache License, Version 2.0 (the "License")
 def mkdir_p(dir_name: PathLikeOrStr) -> None:
     """
-    Like "mkdir -p", make a dir recursively, but do nothing if the dir exists
+    Creates a directory recursively, similar to `mkdir -p`. Does nothing if the directory already exists.
+
+    Example:
+        ```python
+        mkdir_p('/tmp/mydir')
+        ```
+
+    Args:
+        dir_name: The name of the directory to create.
 
-    :param dir_name: name of dir
+    Returns:
+        None
     """
     assert dir_name is not None
     if dir_name == "" or os.path.isdir(dir_name):
@@ -90,7 +112,21 @@ def download(
     url: str, directory: PathLikeOrStr, file_name: Optional[str] = None, expect_size: Optional[int] = None
 ) -> str:
     """
-    Download URL to a directory. Will figure out the filename automatically from URL, if not given.
+    Downloads a file from a URL to a directory. Determines the filename from the URL if not provided.
+
+    Example:
+        ```python
+        download('http://example.com/file.txt', '/tmp')
+        ```
+
+    Args:
+        url: The URL to download from.
+        directory: The directory to save the file in.
+        file_name: The name of the file (optional).
+        expect_size: The expected size of the file in bytes (optional).
+
+    Returns:
+        The path to the downloaded file.
     """
     mkdir_p(directory)
     if file_name is None:
@@ -150,12 +186,20 @@ def load_image_from_file(
     path: PathLikeOrStr, type_id: Literal["np", "b64"] = "np"
 ) -> Optional[Union[B64Str, PixelValues]]:
     """
-    Loads an image from path and passes back an encoded base64 string, a numpy array or None if file is not found
-    or a conversion error occurs.
+    Loads an image from a file and returns either a base64-encoded string, a numpy array, or `None` if the file is not
+    found or a conversion error occurs.
+
+    Example:
+        ```python
+        load_image_from_file('image.png', type_id='b64')
+        ```
 
-    :param path: A path to the image.
-    :param type_id:  "np" or "b64".
-    :return: image of desired representation
+    Args:
+        path: The path to the image.
+        type_id: The type of output, either `np` for numpy array or `b64` for base64 string.
+
+    Returns:
+        The image in the desired representation or `None`.
     """
     image: Optional[Union[str, PixelValues]] = None
     path = path.as_posix() if isinstance(path, Path) else path
@@ -177,12 +221,21 @@ def load_image_from_file(
 
 def load_bytes_from_pdf_file(path: PathLikeOrStr, page_number: int = 0) -> B64:
     """
-    Loads a pdf file with one single page and passes back a bytes' representation of this file. Can be converted into
-    a numpy or directly passed to the attr: image of Image.
+    Loads a PDF file with a single page and returns a bytes representation of this file. Can be converted into a numpy
+    array or passed directly to the `image` attribute of `Image`.
+
+    Example:
+        ```python
+        load_bytes_from_pdf_file('document.pdf', page_number=0)
+        ```
+
+    Args:
+        path: The path to a PDF file. If more pages are available, it will take the first page.
+        page_number: The page number to load. Raises `IndexError` if the document has fewer pages.
+
+    Returns:
+        A bytes representation of the file.
 
-    :param path: A path to a pdf file. If more pages are available, it will take the first page.
-    :param page_number: If a document has less than page_number it will raise an `IndexError`
-    :return: A bytes' representation of the file, width and height
     """
 
     assert is_file_extension(path, [".pdf"]), f"type not allowed: {path}"
@@ -197,7 +250,10 @@ def load_bytes_from_pdf_file(path: PathLikeOrStr, page_number: int = 0) -> B64:
 
 class LoadImageFunc(Protocol):
     """
-    Protocol for typing load_image_from_file
+    Protocol for typing `load_image_from_file`.
+
+    Info:
+        This protocol defines the call signature for image loading functions.
     """
 
     def __call__(self, path: PathLikeOrStr) -> Optional[PixelValues]:
@@ -208,10 +264,21 @@ def get_load_image_func(
     path: PathLikeOrStr,
 ) -> Union[LoadImageFunc, Callable[[PathLikeOrStr], B64]]:
     """
-    Return the loading function according to its file extension.
+    Returns the loading function according to the file extension.
+
+    Example:
+        ```python
+        get_load_image_func('image.png')
+        ```
+
+    Args:
+        path: The path to a file.
+
+    Returns:
+        The function that loads the file and converts it to the desired format.
 
-    :param path: Path to a file
-    :return: The function loading the file (and converting to its desired format)
+    Raises:
+        NotImplementedError: If the file extension is not supported.
     """
 
     assert is_file_extension(path, [".png", ".jpeg", ".jpg", ".pdf", ".tif"]), f"image type not allowed: " f"{path}"
@@ -227,12 +294,19 @@ def get_load_image_func(
 
 def maybe_path_or_pdf(path: PathLikeOrStr) -> int:
     """
-    Checks if the path points to a directory, a pdf document or a single image. Returns 1 if the path points to a
-    directory, 2 if the path points to a pdf doc and 3 if path points to either a PNG, JPG or JPEG or 0 if none of the
-    previous is true.
+    Checks if the path points to a directory, a PDF document, or a single image.
 
-    :param path: A path
-    :return: A value of 0,1,2,3
+    Example:
+        ```python
+        maybe_path_or_pdf('/path/to/file.pdf')
+        ```
+
+    Args:
+        path: The path to check.
+
+    Returns:
+        `1` if the path points to a directory, `2` if it points to a PDF document, `3` if it points to a PNG, JPG,
+            JPEG, or TIF image, or `0` otherwise.
     """
 
     if os.path.isdir(path):
@@ -247,10 +321,18 @@ def maybe_path_or_pdf(path: PathLikeOrStr) -> int:
 
 def load_json(path_ann: PathLikeOrStr) -> JsonDict:
     """
-    Loading json file
+    Loads a JSON file.
+
+    Example:
+        ```python
+        load_json('annotations.json')
+        ```
+
+    Args:
+        path_ann: The path to the JSON file.
 
-    :param path_ann: path
-    :return: dict
+    Returns:
+        The loaded JSON as a dictionary.
     """
     with open(path_ann, "r", encoding="utf-8") as file:
         json_dict = json.loads(file.read())
@@ -259,28 +341,50 @@ def load_json(path_ann: PathLikeOrStr) -> JsonDict:
 
 def get_package_path() -> Path:
     """
-    :return: full base path of this package
+    Returns the full base path of this package.
+
+    Returns:
+        The base path of the package.
     """
     return PATH
 
 
+def get_cache_dir_path() -> Path:
+    """
+    Returns the full base path to the cache directory.
+
+    Returns:
+        The base path to the cache directory.
+    """
+    return CACHE_DIR
+
+
 def get_weights_dir_path() -> Path:
     """
-    :return: full base path to the model dir
+    Returns the full base path to the model directory.
+
+    Returns:
+        The base path to the model directory.
     """
     return MODEL_DIR
 
 
 def get_configs_dir_path() -> Path:
     """
-    :return: full base path to the configs dir
+    Returns the full base path to the configs directory.
+
+    Returns:
+        The base path to the configs directory.
     """
     return CONFIGS
 
 
 def get_dataset_dir_path() -> Path:
     """
-    :return: full base path to the dataset dir
+    Returns the full base path to the dataset directory.
+
+    Returns:
+        The base path to the dataset directory.
     """
     return DATASET_DIR
 
@@ -289,13 +393,21 @@ def maybe_copy_config_to_cache(
     package_path: PathLikeOrStr, configs_dir_path: PathLikeOrStr, file_name: str, force_copy: bool = True
 ) -> str:
     """
-    Initial copying of various files
-    :param package_path: base path to directory of source file `file_name`
-    :param configs_dir_path: base path to target directory
-    :param file_name: file to copy
-    :param force_copy: If file is already in target directory, will re-copy the file
+    Copies a file from the source directory to the target directory.
+
+    Example:
+        ```python
+        maybe_copy_config_to_cache('/src', '/dst', 'config.yaml')
+        ```
 
-    :return: path to the copied file_name
+    Args:
+        package_path: The base path to the source directory of the file.
+        configs_dir_path: The base path to the target directory.
+        file_name: The name of the file to copy.
+        force_copy: If `True`, will re-copy the file even if it already exists in the target directory.
+
+    Returns:
+        The path to the copied file.
     """
 
     absolute_path_source = os.path.join(package_path, file_name)
@@ -309,14 +421,21 @@ def maybe_copy_config_to_cache(
 @deprecated("Use pathlib operations instead", "2022-06-08")
 def sub_path(anchor_dir: PathLikeOrStr, *paths: PathLikeOrStr) -> PathLikeOrStr:
     """
-    Generate a path from the anchor directory and various paths args.
+    Generates a path from the anchor directory and additional path arguments.
+
+    Example:
+        ```python
+        sub_path('/path/to', 'dir1', 'dir2')
+        ```
 
-        sub_path(/path/to,"dir1","dir2")
+    Args:
+        anchor_dir: The anchor directory.
+        *paths: Additional directories to add to the path.
 
-    will return `/path/to/dir1/dir2`
+    Returns:
+        The generated sub-path.
 
-    :param anchor_dir: anchor directory
-    :param paths: args of directories that should be added to path
-    :return: sub_path
+    Note:
+        Deprecated. Use pathlib operations instead.
     """
     return os.path.join(os.path.dirname(os.path.abspath(anchor_dir)), *paths)

deepdoctection/utils/identifier.py

@@ -16,7 +16,7 @@
 # limitations under the License.
 
 """
-Methods for generating and checking uuids
+Generating and checking uuids
 """
 import hashlib
 import uuid
@@ -28,14 +28,18 @@ __all__ = ["is_uuid_like", "get_uuid_from_str", "get_uuid"]
 
 def is_uuid_like(input_id: str) -> bool:
     """
-    Check, if input string has uuid3 string representation format.
+    Check if the input string has a UUID3 string representation format.
 
-    **Example:**
+    Example:
+        ```python
+        is_uuid_like("886313e1-3b8a-5372-9b90-0c9aee199e5d")
+        ```
 
-            "886313e1-3b8a-5372-9b90-0c9aee199e5d"
+    Args:
+        input_id: An input string.
 
-    :param input_id: An input string
-    :return: A boolean output
+    Returns:
+        A boolean output.
     """
     try:
         uuid.UUID(str(input_id))
@@ -46,20 +50,26 @@ def is_uuid_like(input_id: str) -> bool:
 
 def get_uuid_from_str(input_id: str) -> str:
     """
-    Returns an uuid3 string representation generated from an input string.
+    Return a UUID3 string representation generated from an input string.
 
-    :param input_id:
-    :return: uuid3 string representation
+    Args:
+        input_id: Input string.
+
+    Returns:
+        UUID3 string representation.
     """
     return str(uuid.uuid3(uuid.NAMESPACE_DNS, input_id))
 
 
 def get_uuid(*inputs: str) -> str:
     """
-    Set an uuid generated by the concatenation of string inputs.
+    Set a UUID generated by the concatenation of string inputs.
+
+    Args:
+        *inputs: String inputs.
 
-    :param inputs: string inputs
-    :return: uuid3 string representation
+    Returns:
+        UUID3 string representation.
     """
     str_input = "".join(inputs)
     return get_uuid_from_str(str_input)
@@ -67,11 +77,14 @@ def get_uuid(*inputs: str) -> str:
 
 def get_md5_hash(path: PathLikeOrStr, buffer_size: int = 65536) -> str:
     """
-    Calculate a md5 hash for a given file
+    Calculate an MD5 hash for a given file.
+
+    Args:
+        path: Path to a file.
+        buffer_size: Will calculate the hash in chunks.
 
-    :param path: path to a file
-    :param buffer_size: Will calculate the hash in chunks
-    :return: md5 string
+    Returns:
+        MD5 string.
     """
 
     hash_md5 = hashlib.md5()

deepdoctection/utils/logger.py

@@ -3,23 +3,23 @@
 
 # Copyright (c) Tensorpack Contributors
 # Licensed under the Apache License, Version 2.0 (the "License")
+
 """
 This file is modified from
-https://github.com/tensorpack/tensorpack/blob/master/tensorpack/utils/logger.py
+<https://github.com/tensorpack/tensorpack/blob/master/tensorpack/utils/logger.py>
 
 The logger module itself has the common logging functions of Python's
 `logging.Logger`.
 
-**Example:**
-
-    ..code-block::python
-
-        from deepdoctection.utils.logger import logger
+Example:
+    ```python
+    from deepdoctection.utils.logger import logger
 
-        logger.set_logger_dir("path/to/dir")
-        logger.info("Something has happened")
-        logger.warning("Attention!")
-        logger.error("Error happened!")
+    logger.set_logger_dir("path/to/dir")
+    logger.info("Something has happened")
+    logger.warning("Attention!")
+    logger.error("Error happened!")
+    ```
 
 Log levels can be set via the environment variable `LOG_LEVEL` (default: INFO).
 `STD_OUT_VERBOSE` will print a verbose message to the terminal (default: False).
@@ -49,7 +49,17 @@ ENV_VARS_TRUE: set[str] = {"1", "True", "TRUE", "true", "yes"}
 
 @dataclass
 class LoggingRecord:
-    """LoggingRecord to pass to the logger in order to distinguish from third party libraries."""
+    """
+    `LoggingRecord` to pass to the logger in order to distinguish from third party libraries.
+
+    Note:
+        `log_dict` will be added to the log record as a dict.
+
+    Args:
+        msg: The log message.
+        log_dict: Optional dictionary to add to the log record.
+
+    """
 
     msg: str
     log_dict: Optional[dict[Union[int, str], Any]] = field(default=None)
@@ -192,17 +202,16 @@ def set_logger_dir(dir_name: PathLikeOrStr, action: Optional[str] = None) -> Non
     """
     Set the directory for global logging.
 
-    :param dir_name: log directory
-    :param action: an action of ["k","d","q"] to be performed
-                   when the directory exists. Will ask user by default.
-
-                   "d": delete the directory. Note that the deletion may fail when
-                   the directory is used by tensorboard.
-                   "k": keep the directory. This is useful when you resume from a
-                   previous training and want the directory to look as if the
-                   training was not interrupted.
-                   Note that this option does not load old models or any other
-                   old states for you. It simply does nothing.
+    Args:
+        dir_name: Log directory.
+        action: An action of ["k", "d", "q"] to be performed when the directory exists. Will ask user by default.
+            "d": Delete the directory. Note that the deletion may fail when the directory is used by tensorboard.
+            "k": Keep the directory. This is useful when you resume from a previous training and want the directory to
+                 look as if the training was not interrupted.
+            Note that this option does not load old models or any other old states for you. It simply does nothing.
+
+    Raises:
+        OSError: If the directory exists and an invalid action is selected.
     """
     if isinstance(dir_name, Path):
         dir_name = dir_name.as_posix()
@@ -253,10 +262,11 @@ def set_logger_dir(dir_name: PathLikeOrStr, action: Optional[str] = None) -> Non
 def auto_set_dir(action: Optional[str] = None, name: Optional[str] = None) -> None:
     """
     Will set the log directory to './train_log/{script_name}:{name}'.
-    'script_name' is the name of the main python file currently running.
+    `script_name` is the name of the main python file currently running.
 
-    :param action: an action of ["k","d","q"] to be performed (see also func: set_logger_dir)
-    :param name: Optional suffix of file name.
+    Args:
+        action: An action of ["k", "d", "q"] to be performed (see also `set_logger_dir`).
+        name: Optional suffix of file name.
     """
 
     mod = sys.modules["__main__"]
@@ -269,8 +279,10 @@ def auto_set_dir(action: Optional[str] = None, name: Optional[str] = None) -> No
 
 def get_logger_dir() -> Optional[PathLikeOrStr]:
     """
-    The logger directory, or None if not set.
-    The directory is used for general logging, tensorboard events, checkpoints, etc.
+    The logger directory, or `None` if not set.
+
+    Returns:
+        The directory used for general logging, tensorboard events, checkpoints, etc.
     """
     return _LOG_DIR
 
@@ -278,11 +290,16 @@ def get_logger_dir() -> Optional[PathLikeOrStr]:
 @functools.lru_cache(maxsize=None)
 def log_once(message: str, function: str = "info") -> None:
     """
-    Log certain message only once. Call this function more than one times with
-    the same message will result in no-op.
+    Log certain message only once. Calling this function more than once with
+    the same message will result in no operation.
+
+    Example:
+        ```python
+        log_once("This will only be logged once", "info")
+        ```
 
-    :param message:  message to log
-    :param function: the name of the logger method. e.g. "info", "warn", "error".
-    :return:
+    Args:
+        message: Message to log.
+        function: The name of the logger method. For example, "info", "warn", "error".
     """
     getattr(logger, function)(message)