fractal-task-tools 0.2.0__py3-none-any.whl

fractal_task_tools/_titles.py

@@ -0,0 +1,100 @@
+import logging
+from typing import Any
+
+
+_Schema = dict[str, Any]
+
+
+def _include_titles_for_properties(
+    properties: dict[str, dict],
+    verbose: bool = False,
+) -> dict[str, dict]:
+    """
+    Scan through properties of a JSON Schema, and set their title when it is
+    missing.
+
+    The title is set to `name.title()`, where `title` is a standard string
+    method - see https://docs.python.org/3/library/stdtypes.html#str.title.
+
+    Args:
+        properties: TBD
+    """
+    if verbose:
+        logging.info(
+            f"[_include_titles_for_properties] Original properties:\n"
+            f"{properties}"
+        )
+
+    new_properties = properties.copy()
+    for prop_name, prop in properties.items():
+        if "title" not in prop.keys():
+            new_prop = prop.copy()
+            new_prop["title"] = prop_name.title()
+            new_properties[prop_name] = new_prop
+    if verbose:
+        logging.info(
+            f"[_include_titles_for_properties] New properties:\n"
+            f"{new_properties}"
+        )
+    return new_properties
+
+
+def _include_titles(
+    schema: _Schema,
+    definitions_key: str,
+    verbose: bool = False,
+) -> _Schema:
+    """
+    Include property titles, when missing.
+
+    This handles both:
+
+    - first-level JSON Schema properties (corresponding to task
+        arguments);
+    - properties of JSON Schema definitions (corresponding to
+        task-argument attributes).
+
+    Args:
+        schema: TBD
+        definitions_key: Either `"definitions"` (for Pydantic V1) or
+            `"$defs"` (for Pydantic V2)
+        verbose:
+    """
+    new_schema = schema.copy()
+
+    if verbose:
+        logging.info("[_include_titles] START")
+        logging.info(f"[_include_titles] Input schema:\n{schema}")
+
+    # Update first-level properties (that is, task arguments)
+    new_properties = _include_titles_for_properties(
+        schema["properties"], verbose=verbose
+    )
+    new_schema["properties"] = new_properties
+
+    if verbose:
+        logging.info("[_include_titles] Titles for properties now included.")
+
+    # Update properties of definitions
+    if definitions_key in schema.keys():
+        new_definitions = schema[definitions_key].copy()
+        for def_name, def_schema in new_definitions.items():
+            if "properties" not in def_schema.keys():
+                if verbose:
+                    logging.info(
+                        f"Definition schema {def_name} has no 'properties' "
+                        "key. Skip."
+                    )
+            else:
+                new_properties = _include_titles_for_properties(
+                    def_schema["properties"], verbose=verbose
+                )
+                new_definitions[def_name]["properties"] = new_properties
+        new_schema[definitions_key] = new_definitions
+
+    if verbose:
+        logging.info(
+            "[_include_titles] Titles for definitions properties now included."
+        )
+        logging.info("[_include_titles] END")
+    return new_schema

fractal_task_tools/_union_types.py

@@ -0,0 +1,55 @@
+import types
+import typing
+
+from pydantic.fields import FieldInfo
+
+_UNION_TYPES = {typing.Union, types.UnionType}
+
+
+def is_union(_type) -> bool:
+    """
+    Determine whether `_type` is a union.
+
+    Based on
+    https://docs.python.org/3/library/typing.html#typing.Union
+    https://discuss.python.org/t/how-to-check-if-a-type-annotation-represents-an-union/77692/2.
+    """
+    result = typing.get_origin(_type) in _UNION_TYPES
+    alternative_result = (
+        type(_type) is typing._UnionGenericAlias
+        or type(_type) is types.UnionType
+    )
+    if result != alternative_result:
+        # This is a safety check, which is meant to be unreachable
+        raise ValueError(
+            f"Could not determine whether {_type} is a union. Please report "
+            "this at https://github.com/fractal-analytics-platform/"
+            "fractal-task-tools/issues."
+        )
+    return result
+
+
+def is_annotated_union(_type) -> bool:
+    """
+    Determine whether `_type` is `Annotated` and its wrapped type is a union.
+
+    See https://docs.python.org/3/library/typing.html#typing.Annotated
+    """
+    return typing.get_origin(_type) is typing.Annotated and is_union(
+        _type.__origin__
+    )
+
+
+def is_tagged(_type) -> bool:
+    """
+    Determine whether annotations make an `Annotated` type a tagged union.
+
+    Note that this function only gets called after `is_annotated_union(_type)`
+    returned `True`.
+
+    See https://docs.python.org/3/library/typing.html#typing.Annotated
+    """
+    return any(
+        isinstance(_item, FieldInfo) and _item.discriminator is not None
+        for _item in _type.__metadata__
+    )

fractal_task_tools/task_models.py

@@ -0,0 +1,168 @@
+from typing import Any
+from typing import Literal
+from typing import Optional
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+
+class _BaseTask(BaseModel):
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    name: str
+    executable: str
+    meta: Optional[dict[str, Any]] = None
+    input_types: Optional[dict[str, bool]] = None
+    output_types: Optional[dict[str, bool]] = None
+    category: Optional[str] = None
+    modality: Optional[str] = None
+    tags: list[str] = Field(default_factory=list)
+    docs_info: Optional[str] = None
+    type: str
+
+    @property
+    def executable_non_parallel(self) -> str:
+        raise NotImplementedError()
+
+    @property
+    def meta_non_parallel(self) -> Optional[dict[str, Any]]:
+        raise NotImplementedError()
+
+    @property
+    def executable_parallel(self) -> str:
+        raise NotImplementedError()
+
+    @property
+    def meta_parallel(self) -> Optional[dict[str, Any]]:
+        raise NotImplementedError()
+
+
+class CompoundTask(_BaseTask):
+    """
+    A `CompoundTask` object must include both `executable_init` and
+    `executable` attributes, and it may include the `meta_init` and `meta`
+    attributes.
+    """
+
+    executable_init: str
+    meta_init: Optional[dict[str, Any]] = None
+    type: Literal["compound"] = "compound"
+
+    @property
+    def executable_non_parallel(self) -> str:
+        return self.executable_init
+
+    @property
+    def meta_non_parallel(self) -> Optional[dict[str, Any]]:
+        return self.meta_init
+
+    @property
+    def executable_parallel(self) -> str:
+        return self.executable
+
+    @property
+    def meta_parallel(self) -> Optional[dict[str, Any]]:
+        return self.meta
+
+
+class ConverterCompoundTask(_BaseTask):
+    """
+    A `ConverterCompoundTask` task is the same as a `CompoundTask`, but it
+    is executed differently in the Fractal backend.
+    """
+
+    executable_init: str
+    meta_init: Optional[dict[str, Any]] = None
+    type: Literal["converter_compound"] = "converter_compound"
+
+    @property
+    def executable_non_parallel(self) -> str:
+        return self.executable_init
+
+    @property
+    def meta_non_parallel(self) -> Optional[dict[str, Any]]:
+        return self.meta_init
+
+    @property
+    def executable_parallel(self) -> str:
+        return self.executable
+
+    @property
+    def meta_parallel(self) -> Optional[dict[str, Any]]:
+        return self.meta
+
+
+class NonParallelTask(_BaseTask):
+    """
+    A `NonParallelTask` object must include the `executable` attribute, and it
+    may include the `meta` attribute.
+    """
+
+    type: Literal["non_parallel"] = "non_parallel"
+
+    @property
+    def executable_non_parallel(self) -> str:
+        return self.executable
+
+    @property
+    def meta_non_parallel(self) -> Optional[dict[str, Any]]:
+        return self.meta
+
+    @property
+    def executable_parallel(self) -> None:
+        return None
+
+    @property
+    def meta_parallel(self) -> None:
+        return None
+
+
+class ConverterNonParallelTask(_BaseTask):
+    """
+    A `ConverterNonParallelTask` task is the same as a `NonParallelTask`, but
+    it is executed differently in the Fractal backend.
+    """
+
+    type: Literal["converter_non_parallel"] = "converter_non_parallel"
+
+    @property
+    def executable_non_parallel(self) -> str:
+        return self.executable
+
+    @property
+    def meta_non_parallel(self) -> Optional[dict[str, Any]]:
+        return self.meta
+
+    @property
+    def executable_parallel(self) -> None:
+        return None
+
+    @property
+    def meta_parallel(self) -> None:
+        return None
+
+
+class ParallelTask(_BaseTask):
+    """
+    A `ParallelTask` object must include the `executable` attribute, and it may
+    include the `meta` attribute.
+    """
+
+    type: Literal["parallel"] = "parallel"
+
+    @property
+    def executable_non_parallel(self) -> None:
+        return None
+
+    @property
+    def meta_non_parallel(self) -> None:
+        return None
+
+    @property
+    def executable_parallel(self) -> str:
+        return self.executable
+
+    @property
+    def meta_parallel(self) -> Optional[dict[str, Any]]:
+        return self.meta

fractal_task_tools/task_wrapper.py

@@ -0,0 +1,71 @@
+"""
+Standard input/output interface for tasks.
+"""
+import json
+import logging
+from argparse import ArgumentParser
+from json import JSONEncoder
+from pathlib import Path
+from typing import Optional
+
+
+class TaskParameterEncoder(JSONEncoder):
+    """
+    Custom JSONEncoder that transforms Path objects to strings.
+
+    Ref https://docs.python.org/3/library/json.html
+    """
+
+    def default(self, obj):
+        if isinstance(obj, Path):
+            return obj.as_posix()
+        return super().default(obj)
+
+
+def run_fractal_task(
+    *,
+    task_function: callable,
+    logger_name: Optional[str] = None,
+):
+    """
+    Implement standard task interface and call task_function.
+
+    Args:
+        task_function: the callable function that runs the task.
+        logger_name: TBD
+    """
+
+    # Parse `-j` and `--metadata-out` arguments
+    parser = ArgumentParser()
+    parser.add_argument(
+        "--args-json", help="Read parameters from json file", required=True
+    )
+    parser.add_argument(
+        "--out-json",
+        help="Output file to redirect serialised returned data",
+        required=True,
+    )
+    parsed_args = parser.parse_args()
+
+    # Set logger
+    logger = logging.getLogger(logger_name)
+
+    # Preliminary check
+    if Path(parsed_args.out_json).exists():
+        logger.error(
+            f"Output file {parsed_args.out_json} already exists. Terminating"
+        )
+        exit(1)
+
+    # Read parameters dictionary
+    with open(parsed_args.args_json, "r") as f:
+        pars = json.load(f)
+
+    # Run task
+    logger.info(f"START {task_function.__name__} task")
+    metadata_update = task_function(**pars)
+    logger.info(f"END {task_function.__name__} task")
+
+    # Write output metadata to file, with custom JSON encoder
+    with open(parsed_args.out_json, "w") as fout:
+        json.dump(metadata_update, fout, cls=TaskParameterEncoder, indent=2)

fractal_task_tools-0.2.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: fractal-task-tools
+Version: 0.2.0
+Summary: Shared tools for Fractal tasks
+Author-email: Tommaso Comparin <tommaso.comparin@exact-lab.it>
+License: BSD-3-Clause
+Project-URL: homepage, https://github.com/fractal-analytics-platform/fractal-task-tools
+Project-URL: repository, https://github.com/fractal-analytics-platform/fractal-task-tools
+Project-URL: changelog, https://github.com/fractal-analytics-platform/fractal-task-tools/blob/main/CHANGELOG.md
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<=2.13.0,>=2.0.0
+Requires-Dist: docstring-parser<=0.16,>=0.15
+Requires-Dist: packaging
+Provides-Extra: dev
+Requires-Dist: bumpver==2024.1130; extra == "dev"
+Requires-Dist: devtools==0.12.2; extra == "dev"
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == "dev"
+Requires-Dist: coverage<7.7.0,>=7.6.0; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: requests<2.33.0,>2.32.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs==1.6.1; extra == "docs"
+Requires-Dist: mkdocstrings[python]==0.30.0; extra == "docs"
+Requires-Dist: mkdocs-material==9.6.15; extra == "docs"
+Requires-Dist: mkdocs-gen-files==0.5.0; extra == "docs"
+Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "docs"
+Requires-Dist: mkdocs-section-index==0.3.10; extra == "docs"
+Requires-Dist: mkdocs-include-markdown-plugin==7.1.8; extra == "docs"
+Dynamic: license-file
+
+# Fractal task tools
+
+[![PyPI version](https://img.shields.io/pypi/v/fractal-task-tools?color=gree)](https://pypi.org/project/fractal-task-tools/)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![CI Status](https://github.com/fractal-analytics-platform/fractal-task-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/fractal-analytics-platform/fractal-task-tools/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/fractal-analytics-platform/fractal-task-tools/python-coverage-comment-action-data/badge.svg)](https://htmlpreview.github.io/?https://github.com/fractal-analytics-platform/fractal-task-tools/blob/python-coverage-comment-action-data/htmlcov/index.html)
+
+Fractal-task-tools provides some basic tools for building tasks for the [Fractal](https://fractal-analytics-platform.github.io/) framework.
+
+![Fractal_overview_small](https://github.com/user-attachments/assets/666c8797-2594-4b8e-b1d2-b43fca66d1df)
+
+[Fractal](https://fractal-analytics-platform.github.io/) is a framework developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html) to process bioimaging data at scale in the OME-Zarr format and prepare the images for interactive visualization.
+
+
+# Get started
+```console
+$ python -m venv venv
+
+$ source venv/bin/activate
+
+$ python -m pip install -e .
+[...]
+Successfully installed annotated-types-0.7.0 docstring-parser-0.15 fractal-task-tools-0.0.1 pydantic-2.8.2 pydantic-core-2.20.1 typing-extensions-4.12.2
+
+$ fractal-manifest create --help
+usage: fractal-manifest create [-h] --package PACKAGE [--task-list-path TASK_LIST_PATH]
+
+Create new manifest file
+
+options:
+  -h, --help            show this help message and exit
+  --package PACKAGE     Example: 'fractal_tasks_core'
+  --task-list-path TASK_LIST_PATH
+                        Dot-separated path to the `task_list.py` module, relative to the package root (default value:
+                        'dev.task_list').
+
+```
+
+# Development
+
+```console
+$ python -m venv venv
+
+$ source venv/bin/activate
+
+$ python -m pip install -e .[dev]
+[...]
+Successfully installed asttokens-2.4.1 bumpver-2024.1130 click-8.1.8 colorama-0.4.6 coverage-7.6.12 devtools-0.12.2 exceptiongroup-1.2.2 executing-2.2.0 fractal-task-tools-0.0.1 iniconfig-2.0.0 lexid-2021.1006 packaging-24.2 pluggy-1.5.0 pygments-2.19.1 pytest-8.3.5 six-1.17.0 toml-0.10.2 tomli-2.2.1
+
+$ pre-commit install
+pre-commit installed at .git/hooks/pre-commit
+```
+
+## How to make a release
+From the development environment:
+```
+bumpver update --patch --dry
+```
+
+
+## Contributors and license
+
+Fractal was conceived in the Liberali Lab at the Friedrich Miescher Institute for Biomedical Research and in the Pelkmans Lab at the University of Zurich by [@jluethi](https://github.com/jluethi) and [@gusqgm](https://github.com/gusqgm). The Fractal project is now developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html) at the University of Zurich and the project lead is with [@jluethi](https://github.com/jluethi). The core development is done under contract by [eXact lab S.r.l.](https://www.exact-lab.it).
+
+Unless otherwise specified, Fractal components are released under the BSD 3-Clause License, and copyright is with the BioVisionCenter at the University of Zurich.

fractal_task_tools-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+fractal_task_tools/__init__.py,sha256=AwEt_j9THts4zcoSWRDJs6u1ZOkQO_ghLtEOccPI4UE,79
+fractal_task_tools/_args_schemas.py,sha256=OGSFM6AZDFVXSzWJrZo1tQFvI6uHkmMYq6X-9GwQRiU,9102
+fractal_task_tools/_cli.py,sha256=FdFkWj92wCQDaFm4b44yxsD1SbBH1qARbiH7DgiXpgM,2459
+fractal_task_tools/_cli_tools.py,sha256=6G7zXvL6o5t7n4HvVAqP6an0o7qx5fEau5KjtoDXFuc,2622
+fractal_task_tools/_create_manifest.py,sha256=NQAAqTLGgDECQEh4g8E5DzEBkVk_ywCOnWqNC640EVY,5431
+fractal_task_tools/_deepdiff.py,sha256=Or9wO0E9Icb_ki_DTjIdgJKd4JpSJrk8UL3DqqUf-5g,2241
+fractal_task_tools/_descriptions.py,sha256=qYwmpN11UYUmW-PH85ZrHJ3gB6bVjJZ52V9I9Rad3-w,7975
+fractal_task_tools/_package_name_tools.py,sha256=9CyzFwOw4akvQc5GViBm4g-vU8pCc0ULh9hs3b_7VCY,823
+fractal_task_tools/_pydantic_generatejsonschema.py,sha256=qZuID7YUXOdAcL8OqsWjNFNumOIAgdJillc1lA2cHIY,3136
+fractal_task_tools/_signature_constraints.py,sha256=69qs0yeckZAr37wo75qU_E0g-wPiMp_Ho3FFt6xgwjU,4566
+fractal_task_tools/_task_arguments.py,sha256=gw9xN3E50pyyvyIqkWfd-WE5D6CRIRIk618Nw96WmDg,2753
+fractal_task_tools/_task_docs.py,sha256=aEXozSKf3a7weOwJMHyTVJTvHlCKgDr1qoU-AAO3bZI,3401
+fractal_task_tools/_titles.py,sha256=GLWn-06fgQD6qzOM75H59EV0MMCXc8jVpHqGanYzNbw,3000
+fractal_task_tools/_union_types.py,sha256=Dz7CiLY6sJM631bJJva0k-OBtA-jdjKO1lENnRL2TrI,1639
+fractal_task_tools/task_models.py,sha256=4qBDUAoqIgdfAV-7CKkVO5--Y_2Y6CflNVMIiwJxn9g,4177
+fractal_task_tools/task_wrapper.py,sha256=dhphKgxDm4EUxZnsrAy20hJPD6bGdqx7tNg9N_QzlCo,1878
+fractal_task_tools-0.2.0.dist-info/licenses/LICENSE,sha256=1SGAsQ3Jm_nIU7c2TgtTZe_IOKjm9BDsrcf2r98xrdk,1584
+fractal_task_tools-0.2.0.dist-info/METADATA,sha256=6gxxqP68TK0RnhKP03Q5Le7iR7ojiQ7JYaYPnUMNrT8,4793
+fractal_task_tools-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fractal_task_tools-0.2.0.dist-info/entry_points.txt,sha256=zE4qv7QhuiqN6DaPkmJV18X1xyYoUi0HIJ-uAg2M6TU,66
+fractal_task_tools-0.2.0.dist-info/top_level.txt,sha256=2VBpiMDIBMJGOEPiHHX3njYEZGLhr4L0nu8vfkcNVzw,19
+fractal_task_tools-0.2.0.dist-info/RECORD,,

fractal_task_tools-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fractal_task_tools-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fractal-manifest = fractal_task_tools._cli:main

fractal_task_tools-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright 2024 (C) Friedrich Miescher Institute for Biomedical Research and University of Zurich
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

fractal_task_tools-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fractal_task_tools