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

deepdoctection/train/hf_detr_train.py

@@ -16,8 +16,7 @@
 # limitations under the License.
 
 """
-Module for training Hugging Face Detr implementation. Note, that this scripts only trans Tabletransformer like Detr
-models that are a slightly different from the plain Detr model that are provided by the transformer library.
+Fine-tuning Hugging Face Detr implementation.
 """
 from __future__ import annotations
 
@@ -50,6 +49,7 @@ with try_import() as pt_import_guard:
 with try_import() as hf_import_guard:
     from transformers import (
         AutoFeatureExtractor,
+        DeformableDetrForObjectDetection,
         IntervalStrategy,
         PretrainedConfig,
         PreTrainedModel,
@@ -65,12 +65,11 @@ with try_import() as wb_import_guard:
 class DetrDerivedTrainer(Trainer):
     """
     Huggingface Trainer for training Transformer models with a custom evaluate method in order
-    to use dd Evaluator. Train setting is not defined in the trainer itself but in config setting as
-    defined in `TrainingArguments`. Please check the Transformer documentation
+    to use dd Evaluator.
 
-    <https://huggingface.co/docs/transformers/main_classes/trainer>
-
-    for custom training setting.
+    Train setting is not defined in the trainer itself but in config setting as defined in `TrainingArguments`.
+    Please check the Transformer documentation: https://huggingface.co/docs/transformers/main_classes/trainer for
+    custom training setting.
     """
 
     def __init__(
@@ -81,6 +80,16 @@ class DetrDerivedTrainer(Trainer):
         train_dataset: DatasetAdapter,
         eval_dataset: Optional[DatasetBase] = None,
     ):
+        """
+        Initializes `DetrDerivedTrainer`.
+
+        Args:
+            model: Model to be trained, either `PreTrainedModel` or `nn.Module`.
+            args: Training arguments.
+            data_collator: Data collator for Detr.
+            train_dataset: Training dataset.
+            eval_dataset: Optional evaluation dataset.
+        """
         self.evaluator: Optional[Evaluator] = None
         self.build_eval_kwargs: Optional[dict[str, Any]] = None
         super().__init__(model, args, data_collator, train_dataset, eval_dataset=eval_dataset)
@@ -94,14 +103,16 @@ class DetrDerivedTrainer(Trainer):
         **build_eval_kwargs: Union[str, int],
     ) -> None:
         """
-        Setup of evaluator before starting training. During training, predictors will be replaced by current
-        checkpoints.
-
-        :param dataset_val: dataset on which to run evaluation
-        :param pipeline_component: pipeline component to plug into the evaluator
-        :param metric: A metric class
-        :param run: WandB run
-        :param build_eval_kwargs:
+        Setup of evaluator before starting training.
+
+        During training, predictors will be replaced by current checkpoints.
+
+        Args:
+            dataset_val: Dataset on which to run evaluation.
+            pipeline_component: Pipeline component to plug into the evaluator.
+            metric: A metric class.
+            run: WandB run.
+            **build_eval_kwargs: Additional keyword arguments for evaluation.
         """
 
         self.evaluator = Evaluator(dataset_val, pipeline_component, metric, num_threads=1, run=run)
@@ -152,29 +163,32 @@ def train_hf_detr(
 ) -> None:
     """
     Train Tabletransformer from scratch or fine-tune using an adaptation of the transformer trainer.
+
     Allowing experiments by using different config settings.
 
-    :param path_config_json: path to a Tabletransformer config file
-    :param dataset_train: dataset to use for training
-    :param path_weights: path to a checkpoint, if you want to resume training or fine-tune. Will train from scratch if
-                         an empty string is passed
-    :param path_feature_extractor_config_json: path to a feature extractor config file. In many situations you can use
-                                               the standard config file:
-
-                                                   ModelCatalog.
-                                                   get_full_path_preprocessor_configs
-                                                   ("microsoft/table-transformer-detection/pytorch_model.bin")
-
-    :param config_overwrite: Pass a list of arguments if some configs from the .json file are supposed to be replaced.
-                             Use the list convention, e.g. ['per_device_train_batch_size=4']
-    :param log_dir: Will default to 'train_log/detr'
-    :param build_train_config: dataflow build setting. Again, use list convention setting, e.g. ['max_datapoints=1000']
-    :param dataset_val: the dataset to use for validation
-    :param build_val_config: same as `build_train_config` but for dataflow validation
-    :param metric_name: A metric name to choose for validation. Will use the default setting. If you want a custom
-                        metric setting, pass a metric explicitly.
-    :param metric: A metric to choose for validation
-    :param pipeline_component_name: A pipeline component name to use for validation
+    Args:
+        path_config_json: Path to a Tabletransformer config file.
+        dataset_train: Dataset to use for training.
+        path_weights: Path to a checkpoint, if you want to resume training or fine-tune. Will train from scratch if an
+                      empty string is passed.
+        path_feature_extractor_config_json: Path to a feature extractor config file. In many situations you can use the
+                                            standard config file:
+            Example:
+                ```python
+                ModelCatalog.get_full_path_preprocessor_configs
+                ("microsoft/table-transformer-detection/pytorch_model.bin")
+                ```
+
+        config_overwrite: Pass a list of arguments if some configs from the .json file are supposed to be replaced.
+                          Use the list convention, e.g. `['per_device_train_batch_size=4']`.
+        log_dir: Will default to `train_log/detr`.
+        build_train_config: Dataflow build setting. Again, use list convention setting, e.g. `['max_datapoints=1000']`.
+        dataset_val: The dataset to use for validation.
+        build_val_config: Same as `build_train_config` but for dataflow validation.
+        metric_name: A metric name to choose for validation. Will use the default setting.
+                     If you want a custom metric setting, pass a metric explicitly.
+        metric: A metric to choose for validation.
+        pipeline_component_name: A pipeline component name to use for validation.
     """
 
     build_train_dict: dict[str, str] = {}
@@ -275,11 +289,29 @@ def train_hf_detr(
     config.use_timm_backbone = True
 
     if path_weights != "":
-        model = TableTransformerForObjectDetection.from_pretrained(
-            pretrained_model_name_or_path=path_weights, config=config, ignore_mismatched_sizes=True
-        )
+        if "TableTransformerForObjectDetection" in config.architectures:
+            model = TableTransformerForObjectDetection.from_pretrained(
+                pretrained_model_name_or_path=path_weights, config=config, ignore_mismatched_sizes=True
+            )
+        elif "DeformableDetrForObjectDetection" in config.architectures:
+            return DeformableDetrForObjectDetection.from_pretrained(
+                pretrained_model_name_or_path=os.fspath(path_weights), config=config
+            )
+        else:
+            raise ValueError(
+                f"Model architecture {config.architectures} not eligible. Please use either "
+                "TableTransformerForObjectDetection or DeformableDetrForObjectDetection."
+            )
     else:
-        model = TableTransformerForObjectDetection(config)
+        if "TableTransformerForObjectDetection" in config.architectures:
+            model = TableTransformerForObjectDetection(config)
+        elif "DeformableDetrForObjectDetection" in config.architectures:
+            model = DeformableDetrForObjectDetection(config)
+        else:
+            raise ValueError(
+                f"Model architecture {config.architectures} not eligible. Please use either "
+                "TableTransformerForObjectDetection or DeformableDetrForObjectDetection."
+            )
 
     feature_extractor = AutoFeatureExtractor.from_pretrained(
         pretrained_model_name_or_path=path_feature_extractor_config_json

deepdoctection/train/hf_layoutlm_train.py

@@ -16,7 +16,10 @@
 # limitations under the License.
 
 """
-Module for training Huggingface implementation of LayoutLm
+Fine-tuning Huggingface implementation of LayoutLm.
+
+This module provides functions and classes for fine-tuning LayoutLM models for sequence or token classification using
+the Huggingface Trainer and custom evaluation. It supports LayoutLM, LayoutLMv2, LayoutLMv3, and LayoutXLM models.
 """
 from __future__ import annotations
 
@@ -85,11 +88,14 @@ with try_import() as wb_import_guard:
 
 def get_model_architectures_and_configs(model_type: str, dataset_type: DatasetType) -> tuple[Any, Any, Any]:
     """
-    Get the model architecture, model wrapper and config class for a given model type and dataset type.
+    Gets the model architecture, model wrapper, and config class for a given `model_type` and `dataset_type`.
+
+    Args:
+        model_type: The model type.
+        dataset_type: The dataset type.
 
-    :param model_type: The model type
-    :param dataset_type: The dataset type
-    :return: Tuple of model architecture, model wrapper and config class
+    Returns:
+        Tuple of model architecture, model wrapper, and config class.
     """
     return {
         ("layoutlm", DatasetType.SEQUENCE_CLASSIFICATION): (
@@ -141,19 +147,28 @@ def get_model_architectures_and_configs(model_type: str, dataset_type: DatasetTy
 
 
 def maybe_remove_bounding_box_features(model_type: str) -> bool:
-    """Listing of models that do not need bounding box features."""
+    """
+    Lists models that do not need bounding box features.
+
+    Args:
+        model_type: The model type.
+
+    Returns:
+        Whether the model does not need bounding box features.
+    """
     return {"xlm-roberta": True}.get(model_type, False)
 
 
 class LayoutLMTrainer(Trainer):
     """
-    Huggingface Trainer for training Transformer models with a custom evaluate method in order
-    to use dd Evaluator. Train setting is not defined in the trainer itself but in config setting as
-    defined in `TrainingArguments`. Please check the Transformer documentation
+    Huggingface Trainer for training Transformer models with a custom evaluate method to use the Deepdoctection
+    Evaluator.
 
-    <https://huggingface.co/docs/transformers/main_classes/trainer>
+    Train settings are not defined in the trainer itself but in the config setting as defined in `TrainingArguments`.
+    Please check the Transformer documentation for custom training settings.
 
-    for custom training setting.
+    Info:
+        https://huggingface.co/docs/transformers/main_classes/trainer
     """
 
     def __init__(
@@ -164,6 +179,16 @@ class LayoutLMTrainer(Trainer):
         train_dataset: DatasetAdapter,
         eval_dataset: Optional[DatasetBase] = None,
     ):
+        """
+        Initializes the `LayoutLMTrainer`.
+
+        Args:
+            model: The model to train.
+            args: Training arguments.
+            data_collator: Data collator for batching.
+            train_dataset: Training dataset.
+            eval_dataset: Optional evaluation dataset.
+        """
         self.evaluator: Optional[Evaluator] = None
         self.build_eval_kwargs: Optional[dict[str, Any]] = None
         super().__init__(model, args, data_collator, train_dataset, eval_dataset=eval_dataset)
@@ -177,14 +202,15 @@ class LayoutLMTrainer(Trainer):
         **build_eval_kwargs: Union[str, int],
     ) -> None:
         """
-        Setup of evaluator before starting training. During training, predictors will be replaced by current
+        Sets up the evaluator before starting training. During training, predictors will be replaced by current
         checkpoints.
 
-        :param dataset_val: dataset on which to run evaluation
-        :param pipeline_component: pipeline component to plug into the evaluator
-        :param metric: A metric class
-        :param run: WandB run
-        :param build_eval_kwargs:
+        Args:
+            dataset_val: Dataset on which to run evaluation.
+            pipeline_component: Pipeline component to plug into the evaluator.
+            metric: A metric class.
+            run: WandB run.
+            **build_eval_kwargs: Additional keyword arguments for evaluation.
         """
 
         self.evaluator = Evaluator(dataset_val, pipeline_component, metric, num_threads=1, run=run)
@@ -201,6 +227,14 @@ class LayoutLMTrainer(Trainer):
     ) -> dict[str, float]:
         """
         Overwritten method from `Trainer`. Arguments will not be used.
+
+        Args:
+            eval_dataset: Not used.
+            ignore_keys: Not used.
+            metric_key_prefix: Not used.
+
+        Returns:
+            Evaluation scores as a dictionary.
         """
         if self.evaluator is None:
             raise ValueError("Evaluator not set up. Please use `setup_evaluator` before running evaluation")
@@ -266,28 +300,32 @@ def train_hf_layoutlm(
     LayoutXLM. Training similar but different models like LILT <https://arxiv.org/abs/2202.13669> can be done by
     changing a few lines of code regarding the selection of the tokenizer.
 
-    The theoretical foundation can be taken from
-
-    <https://arxiv.org/abs/1912.13318>
+    Info:
+        The theoretical foundation can be taken from <https://arxiv.org/abs/1912.13318>.
 
-    This is not the pre-training script.
+        This is not the pre-training script.
 
     In order to remain within the framework of this library, the base and uncased LayoutLM model must be downloaded
     from the HF-hub in a first step for fine-tuning.  Models are available for this, which are registered in the
     ModelCatalog. It is possible to choose one of the following options:
 
-        "microsoft/layoutlm-base-uncased/pytorch_model.bin"
-        "microsoft/layoutlmv2-base-uncased/pytorch_model.bin"
-        "microsoft/layoutxlm-base/pytorch_model.bin"
-        "microsoft/layoutlmv3-base/pytorch_model.bin"
 
-     and
+        `microsoft/layoutlm-base-uncased/pytorch_model.bin`
+        `microsoft/layoutlmv2-base-uncased/pytorch_model.bin`
+        `microsoft/layoutxlm-base/pytorch_model.bin`
+        `microsoft/layoutlmv3-base/pytorch_model.bin`
+        `microsoft/layoutlm-large-uncased/pytorch_model.bin`
+        `SCUT-DLVCLab/lilt-roberta-en-base/pytorch_model.bin`
 
-         "microsoft/layoutlm-large-uncased/pytorch_model.bin"
 
-    (You can also choose the large versions of LayoutLMv2 and LayoutXLM but you need to organize the download yourself.)
+    Note:
+        You can also choose the large versions of LayoutLMv2 and LayoutXLM but you need to organize the download
+        yourself.
 
+    Example:
+        ```python
         ModelDownloadManager.maybe_download_weights_and_configs("microsoft/layoutlm-base-uncased/pytorch_model.bin")
+        ```
 
     The corresponding cased models are currently not available, but this is only to keep the model selection small.
 
@@ -296,30 +334,31 @@ def train_hf_layoutlm(
     How does the model selection work?
 
     The base model is selected by the transferred config file and the weights. Depending on the dataset type
-    ("SEQUENCE_CLASSIFICATION" or "TOKEN_CLASSIFICATION"), the complete model is then put together by placing a suitable
-    top layer on the base model.
+    `("SEQUENCE_CLASSIFICATION" or "TOKEN_CLASSIFICATION")`, the complete model is then put together by placing a
+    suitable top layer on the base model.
 
-    :param path_config_json: Absolute path to HF config file, e.g.
-                             ModelCatalog.get_full_path_configs("microsoft/layoutlm-base-uncased/pytorch_model.bin")
-    :param dataset_train: Dataset to use for training. Only datasets of type "SEQUENCE_CLASSIFICATION" or
+    Args:
+        path_config_json: Absolute path to HF config file, e.g.
+                             `ModelCatalog.get_full_path_configs("microsoft/layoutlm-base-uncased/pytorch_model.bin")`
+        dataset_train: Dataset to use for training. Only datasets of type "SEQUENCE_CLASSIFICATION" or
                           "TOKEN_CLASSIFICATION" are supported.
-    :param path_weights: path to a checkpoint for further fine-tuning
-    :param config_overwrite: Pass a list of arguments if some configs from `TrainingArguments` should be replaced. Check
-                             https://huggingface.co/docs/transformers/main_classes/trainer#transformers.TrainingArguments
+        path_weights: path to a checkpoint for further fine-tuning
+        config_overwrite: Pass a list of arguments if some configs from `TrainingArguments` should be replaced. Check
+                             <https://huggingface.co/docs/transformers/main_classes/trainer#transformers.TrainingArguments>
                              for the full training default setting.
-    :param log_dir: Path to log dir. Will default to `train_log/layoutlm`
-    :param build_train_config: dataflow build setting. Again, use list convention setting, e.g. ['max_datapoints=1000']
-    :param dataset_val: Dataset to use for validation. Dataset type must be the same as type of `dataset_train`
-    :param build_val_config: same as `build_train_config` but for validation
-    :param metric: A metric to choose for validation.
-    :param pipeline_component_name: A pipeline component name to use for validation (e.g. LMSequenceClassifierService or
+        log_dir: Path to log dir. Will default to `train_log/layoutlm`
+        build_train_config: dataflow build setting. Again, use list convention setting, e.g. `['max_datapoints=1000']`
+        dataset_val: Dataset to use for validation. Dataset type must be the same as type of `dataset_train`
+        build_val_config: same as `build_train_config` but for validation
+        metric: A metric to choose for validation.
+        pipeline_component_name: A pipeline component name to use for validation (e.g. `LMSequenceClassifierService` or
                                     LMTokenClassifierService.
-    :param use_xlm_tokenizer: This is only necessary if you pass weights of layoutxlm. The config cannot distinguish
-                              between Layoutlmv2 and Layoutxlm, so you need to pass this info explicitly.
-    :param use_token_tag: Will only be used for dataset_type="token_classification". If use_token_tag=True, will use
+        use_xlm_tokenizer: This is only necessary if you pass weights of LayoutXLM. The config cannot distinguish
+                              between Layoutlmv2 and LayoutXLM, so you need to pass this info explicitly.
+        use_token_tag: Will only be used for `dataset_type="token_classification"`. If `use_token_tag=True`, will use
                           labels from sub category `WordType.token_tag` (with `B,I,O` suffix), otherwise
                           `WordType.token_class`.
-    :param segment_positions: Using bounding boxes of segment instead of words improves model accuracy significantly.
+        segment_positions: Using bounding boxes of segment instead of words improves model accuracy significantly.
                               Choose a single or a sequence of layout segments to use their bounding boxes. Note, that
                               the layout segments need to have a child-relationship with words. If a word does not
                               appear as child, it will use the word bounding box.

deepdoctection/train/tp_frcnn_train.py

@@ -16,7 +16,7 @@
 # limitations under the License.
 
 """
-Module for training Tensorpack `GeneralizedRCNN`
+Training Tensorpack's `GeneralizedRCNN`
 """
 
 import os
@@ -75,6 +75,9 @@ __all__ = ["train_faster_rcnn"]
 class LoadAugmentAddAnchors:
     """
     A helper class for default mapping `load_augment_add_anchors`.
+
+    Args:
+        config: An `AttrDict` configuration for TP FRCNN.
     """
 
     def __init__(self, config: AttrDict) -> None:
@@ -89,9 +92,15 @@ def load_augment_add_anchors(dp: JsonDict, config: AttrDict) -> Optional[JsonDic
     Transforming an image before entering the graph. This function bundles all the necessary steps to feed
     the network for training.
 
-    :param dp: A dict with 'file_name', 'gt_boxes', 'gt_labels' and optional 'image'
-    :param config: An `AttrDict` with a TP frcnn config
-    :return: An dict with all necessary keys for feeding the graph
+    Args:
+        dp: A dict with `file_name`, `gt_boxes`, `gt_labels` and optional `image`.
+        config: An `AttrDict` with a TP frcnn config.
+
+    Returns:
+        A dict with all necessary keys for feeding the graph.
+
+    Note:
+        If `image` is not in `dp`, it will be loaded from `file_name`.
     """
     cfg = config
     if "image" not in dp:
@@ -124,14 +133,20 @@ def get_train_dataflow(
     dataset: DatasetBase, config: AttrDict, use_multi_proc_for_train: bool, **build_train_kwargs: str
 ) -> DataFlow:
     """
-    Return a dataflow for training TP Frcnn. The returned dataflow depends on the dataset and the configuration of
+    Return a dataflow for training TP FRCNN. The returned dataflow depends on the dataset and the configuration of
     the model, as the augmentation is part of the data preparation.
 
-    :param dataset: A dataset for object detection
-    :param config: An `AttrDict` with a TP Frcnn config
-    :param use_multi_proc_for_train: If set to `True` will use multi processes for augmenting
-    :param build_train_kwargs: build configuration of the dataflow.
-    :return: A dataflow
+    Args:
+        dataset: A dataset for object detection.
+        config: An `AttrDict` with a TP FRCNN config.
+        use_multi_proc_for_train: If set to `True` will use multi processes for augmenting.
+        build_train_kwargs: Build configuration of the dataflow.
+
+    Returns:
+        A dataflow.
+
+    Note:
+        If `use_multi_proc_for_train` is `True`, multi-processing will be used for augmentation.
     """
 
     set_mp_spawn()
@@ -202,23 +217,35 @@ def train_faster_rcnn(
     Train Faster-RCNN from Scratch or fine-tune a model using Tensorpack's training API. Observe the training with
     Tensorpack callbacks and evaluate the training progress with a validation data set after certain training intervals.
 
-    Tensorpack provides a training API under TF1. Training runs under a TF2 installation if TF2 behavior is deactivated.
-
-    :param path_config_yaml: path to TP config file. Check the
-                             [deepdoctection.extern.tp.tpfrcnn.config.config][] for various settings.
-    :param dataset_train: the dataset to use for training.
-    :param path_weights: path to a checkpoint, if you want to continue training or fine-tune. Will train from scratch if
-                         nothing is passed.
-    :param config_overwrite: Pass a list of arguments if some configs from the .yaml file should be replaced. Use the
-                             list convention, e.g. ['TRAIN.STEPS_PER_EPOCH=500', 'OUTPUT.RESULT_SCORE_THRESH=0.4']
-    :param log_dir: Path to log dir. Will default to TRAIN.LOG_DIR
-    :param build_train_config: dataflow build setting. Again, use list convention setting, e.g. ['max_datapoints=1000']
-    :param dataset_val: the dataset to use for validation.
-    :param build_val_config: same as 'build_train_config' but for validation
-    :param metric_name: A metric name to choose for validation. Will use the default setting. If you want a custom
-                        metric setting pass a metric explicitly.
-    :param metric: A metric to choose for validation.
-    :param pipeline_component_name: A pipeline component to use for validation.
+    Info:
+        Tensorpack provides a training API under TF1. Training runs under a TF2 installation if TF2 behavior is
+        deactivated.
+
+    Args:
+        path_config_yaml: Path to TP config file. Check the `deepdoctection.extern.tp.tpfrcnn.config.config` for various
+                          settings.
+        dataset_train: The dataset to use for training.
+        path_weights: Path to a checkpoint, if you want to continue training or fine-tune. Will train from scratch if
+                      nothing is passed.
+        config_overwrite: Pass a list of arguments if some configs from the .yaml file should be replaced. Use the list
+                          convention, e.g. `[`TRAIN.STEPS_PER_EPOCH=500`, `OUTPUT.RESULT_SCORE_THRESH=0.4`]`.
+        log_dir: Path to log dir. Will default to `TRAIN.LOG_DIR`.
+        build_train_config: Dataflow build setting. Use list convention setting, e.g. `[`max_datapoints=1000`]`.
+        dataset_val: The dataset to use for validation.
+        build_val_config: Same as `build_train_config` but for validation.
+        metric_name: A metric name to choose for validation. Will use the default setting. If you want a custom metric
+                     setting pass a metric explicitly.
+        metric: A metric to choose for validation.
+        pipeline_component_name: A pipeline component to use for validation.
+
+    Example:
+        ```python
+        train_faster_rcnn(
+            path_config_yaml="config.yaml",
+            dataset_train=my_train_dataset,
+            path_weights="weights.ckpt"
+        )
+        ```
     """
 
     assert disable_tfv2()  # TP works only in Graph mode
@@ -241,9 +268,10 @@ def train_faster_rcnn(
     config_overwrite.append(log_dir)
 
     config = set_config_by_yaml(path_config_yaml)
-
+    config.freeze(False)
     if config_overwrite:
         config.update_args(config_overwrite)
+    config.freeze(True)
 
     categories = dataset_train.dataflow.categories.get_categories(filtered=True)
     model_frcnn_config(config, categories, False)

deepdoctection/utils/concurrency.py

@@ -16,7 +16,7 @@
 # limitations under the License.
 
 """
-Some utility functions for multi threading purposes
+Functions for multi/threading purposes
 """
 
 import multiprocessing as mp
@@ -35,12 +35,17 @@ from .types import QueueType
 # taken from https://github.com/tensorpack/dataflow/blob/master/dataflow/utils/concurrency.py
 class StoppableThread(threading.Thread):
     """
-    A thread that has a 'stop' event.
+    A thread that has a `stop` event.
+
+    This class extends `threading.Thread` and provides a mechanism to stop the thread gracefully.
     """
 
     def __init__(self, evt: Optional[threading.Event] = None) -> None:
         """
-        :param evt: if None, will create one.
+        Initializes a `StoppableThread`.
+
+        Args:
+            evt: An optional `threading.Event`. If `None`, a new event will be created.
         """
         super().__init__()
         if evt is None:
@@ -48,17 +53,30 @@ class StoppableThread(threading.Thread):
         self._stop_evt = evt
 
     def stop(self) -> None:
-        """Stop the thread"""
+        """
+        Stop the thread.
+
+        Sets the internal stop event, signaling the thread to stop.
+        """
         self._stop_evt.set()
 
     def stopped(self) -> bool:
         """
-        :param bool: whether the thread is stopped or not
+        Check whether the thread is stopped.
+
+        Returns:
+            Whether the thread is stopped or not.
         """
         return self._stop_evt.is_set()
 
     def queue_put_stoppable(self, q: QueueType, obj: Any) -> None:
-        """Put obj to queue, but will give up when the thread is stopped"""
+        """
+        Put `obj` to queue `q`, but will give up when the thread is stopped.
+
+        Args:
+            q: The queue to put the object into.
+            obj: The object to put into the queue.
+        """
         while not self.stopped():
             try:
                 q.put(obj, timeout=5)
@@ -67,7 +85,15 @@ class StoppableThread(threading.Thread):
                 pass
 
     def queue_get_stoppable(self, q: QueueType) -> Any:
-        """Take obj from queue, but will give up when the thread is stopped"""
+        """
+        Take an object from queue `q`, but will give up when the thread is stopped.
+
+        Args:
+            q: The queue to get the object from.
+
+        Returns:
+            The object taken from the queue.
+        """
         while not self.stopped():
             try:
                 return q.get(timeout=5)
@@ -77,9 +103,14 @@ class StoppableThread(threading.Thread):
 
 @contextmanager
 def mask_sigint() -> Generator[Any, None, None]:
-    """[Any,None,None
-    :return: If called in main thread, returns a context where ``SIGINT`` is ignored, and yield True.
-             Otherwise, yield False.
+    """
+    Context manager to mask `SIGINT`.
+
+    If called in the main thread, returns a context where `SIGINT` is ignored, and yields `True`. Otherwise, yields
+    `False`.
+
+    Yields:
+        `True` if called in the main thread, otherwise `False`.
     """
     if threading.current_thread() == threading.main_thread():
         sigint_handler = signal.signal(signal.SIGINT, signal.SIG_IGN)
@@ -91,9 +122,15 @@ def mask_sigint() -> Generator[Any, None, None]:
 
 def enable_death_signal(_warn: bool = True) -> None:
     """
-    Set the "death signal" of the current process, so that
-    the current process will be cleaned with guarantee
-    in case the parent dies accidentally.
+    Set the "death signal" of the current process.
+
+    Ensures that the current process will be cleaned up if the parent process dies accidentally.
+
+    Args:
+        _warn: If `True`, logs a warning if `prctl` is not available.
+
+    Note:
+        Only works on Linux systems. Requires the `python-prctl` package.
     """
     if platform.system() != "Linux":
         return
@@ -118,11 +155,17 @@ def enable_death_signal(_warn: bool = True) -> None:
 @no_type_check
 def start_proc_mask_signal(proc):
     """
-    Start process(es) with SIGINT ignored.
+    Start process(es) with `SIGINT` ignored.
+
+    The signal mask is only applied when called from the main thread.
 
-    :param proc: (mp.Process or list)
+    Note:
+        Starting a process with the 'fork' method is efficient but not safe and may cause deadlock or crash.
+        Use 'forkserver' or 'spawn' method instead if you run into such issues.
+        See <https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods> on how to set them.
 
-    The signal mask is only applied when called from main thread.
+    Args:
+        proc: A `mp.Process` or a list of `mp.Process` instances.
     """
     if not isinstance(proc, list):
         proc = [proc]