str-to-obj 2023.11__py3-none-any.whl → 2025.2__py3-none-any.whl

str_to_obj/__init__.py

@@ -1,35 +1,67 @@
-# Copyright CNRS/Inria/UCA
-# Contributor(s): Eric Debreuve (since 2023)
-#
-# eric.debreuve@cnrs.fr
-#
-# This software is governed by the CeCILL  license under French law and
-# abiding by the rules of distribution of free software.  You can  use,
-# modify and/ or redistribute the software under the terms of the CeCILL
-# license as circulated by CEA, CNRS and INRIA at the following URL
-# "http://www.cecill.info".
-#
-# As a counterpart to the access to the source code and  rights to copy,
-# modify and redistribute granted by the license, users are provided only
-# with a limited warranty  and the software's author,  the holder of the
-# economic rights,  and the successive licensors  have only  limited
-# liability.
-#
-# In this respect, the user's attention is drawn to the risks associated
-# with loading,  using,  modifying and/or developing or reproducing the
-# software by the user in light of its specific status of free software,
-# that may mean  that it is complicated to manipulate,  and  that  also
-# therefore means  that it is reserved for developers  and  experienced
-# professionals having in-depth computer knowledge. Users are therefore
-# encouraged to load and test the software's suitability as regards their
-# requirements in conditions enabling the security of their systems and/or
-# data to be ensured and,  more generally, to use and operate it in the
-# same conditions as regards security.
-#
-# The fact that you are presently reading this means that you have had
-# knowledge of the CeCILL license and that you accept its terms.
+"""
+Copyright CNRS/Inria/UniCA
+Contributor(s): Eric Debreuve (eric.debreuve@cnrs.fr) since 2023
+SEE COPYRIGHT NOTICE BELOW
+"""
+
+try:
+    from beartype.claw import beartype_this_package  # noqa
+except ModuleNotFoundError:
+    pass
+else:
+    import site
+    from pathlib import Path as path_t
+    paths = site.getsitepackages() + [site.getusersitepackages()]
+    folder = path_t(__file__).parent
+    if folder not in paths:
+        beartype_this_package()
 
 from str_to_obj.main import ObjectFromStr
-from str_to_obj.task.casting import CastValue
-from str_to_obj.type.annotation import annotation_t
+from str_to_obj.runtime.value import INVALID_VALUE
 from str_to_obj.version import __version__
+
+"""
+COPYRIGHT NOTICE
+
+This software is governed by the CeCILL  license under French law and
+abiding by the rules of distribution of free software.  You can  use,
+modify and/ or redistribute the software under the terms of the CeCILL
+license as circulated by CEA, CNRS and INRIA at the following URL
+"http://www.cecill.info".
+
+As a counterpart to the access to the source code and  rights to copy,
+modify and redistribute granted by the license, users are provided only
+with a limited warranty  and the software's author,  the holder of the
+economic rights,  and the successive licensors  have only  limited
+liability.
+
+In this respect, the user's attention is drawn to the risks associated
+with loading,  using,  modifying and/or developing or reproducing the
+software by the user in light of its specific status of free software,
+that may mean  that it is complicated to manipulate,  and  that  also
+therefore means  that it is reserved for developers  and  experienced
+professionals having in-depth computer knowledge. Users are therefore
+encouraged to load and test the software's suitability as regards their
+requirements in conditions enabling the security of their systems and/or
+data to be ensured and,  more generally, to use and operate it in the
+same conditions as regards security.
+
+The fact that you are presently reading this means that you have had
+knowledge of the CeCILL license and that you accept its terms.
+
+SEE LICENCE NOTICE: file README-LICENCE-utf8.txt at project source root.
+
+This software is being developed by Eric Debreuve, a CNRS employee and
+member of team Morpheme.
+Team Morpheme is a joint team between Inria, CNRS, and UniCA.
+It is hosted by the Centre Inria d'Université Côte d'Azur, Laboratory
+I3S, and Laboratory iBV.
+
+CNRS: https://www.cnrs.fr/index.php/en
+Inria: https://www.inria.fr/en/
+UniCA: https://univ-cotedazur.eu/
+Centre Inria d'Université Côte d'Azur: https://www.inria.fr/en/centre/sophia/
+I3S: https://www.i3s.unice.fr/en/
+iBV: http://ibv.unice.fr/
+Team Morpheme: https://team.inria.fr/morpheme/
+"""

str_to_obj/api/catalog.py

@@ -0,0 +1,58 @@
+"""
+Copyright CNRS/Inria/UniCA
+Contributor(s): Eric Debreuve (eric.debreuve@cnrs.fr) since 2023
+SEE COPYRIGHT NOTICE BELOW
+"""
+
+from str_to_obj.catalog.boolean import boolean_mode_e, boolean_t
+from str_to_obj.catalog.callable import callable_t
+from str_to_obj.catalog.choices import choices_t
+from str_to_obj.catalog.collection import collection_t
+from str_to_obj.catalog.number import number_t
+from str_to_obj.catalog.path import path_purpose_e, path_t, path_type_e
+
+"""
+COPYRIGHT NOTICE
+
+This software is governed by the CeCILL  license under French law and
+abiding by the rules of distribution of free software.  You can  use,
+modify and/ or redistribute the software under the terms of the CeCILL
+license as circulated by CEA, CNRS and INRIA at the following URL
+"http://www.cecill.info".
+
+As a counterpart to the access to the source code and  rights to copy,
+modify and redistribute granted by the license, users are provided only
+with a limited warranty  and the software's author,  the holder of the
+economic rights,  and the successive licensors  have only  limited
+liability.
+
+In this respect, the user's attention is drawn to the risks associated
+with loading,  using,  modifying and/or developing or reproducing the
+software by the user in light of its specific status of free software,
+that may mean  that it is complicated to manipulate,  and  that  also
+therefore means  that it is reserved for developers  and  experienced
+professionals having in-depth computer knowledge. Users are therefore
+encouraged to load and test the software's suitability as regards their
+requirements in conditions enabling the security of their systems and/or
+data to be ensured and,  more generally, to use and operate it in the
+same conditions as regards security.
+
+The fact that you are presently reading this means that you have had
+knowledge of the CeCILL license and that you accept its terms.
+
+SEE LICENCE NOTICE: file README-LICENCE-utf8.txt at project source root.
+
+This software is being developed by Eric Debreuve, a CNRS employee and
+member of team Morpheme.
+Team Morpheme is a joint team between Inria, CNRS, and UniCA.
+It is hosted by the Centre Inria d'Université Côte d'Azur, Laboratory
+I3S, and Laboratory iBV.
+
+CNRS: https://www.cnrs.fr/index.php/en
+Inria: https://www.inria.fr/en/
+UniCA: https://univ-cotedazur.eu/
+Centre Inria d'Université Côte d'Azur: https://www.inria.fr/en/centre/sophia/
+I3S: https://www.i3s.unice.fr/en/
+iBV: http://ibv.unice.fr/
+Team Morpheme: https://team.inria.fr/morpheme/
+"""

str_to_obj/api/type.py

@@ -0,0 +1,58 @@
+"""
+Copyright CNRS/Inria/UniCA
+Contributor(s): Eric Debreuve (eric.debreuve@cnrs.fr) since 2023
+SEE COPYRIGHT NOTICE BELOW
+"""
+
+from str_to_obj.runtime.type import ANY_TYPE
+from str_to_obj.task.casting import CastValue
+from str_to_obj.task.comparison import TypesAreCompatible
+from str_to_obj.type.annotation import annotation_t
+from str_to_obj.type.hint_tree import hint_t
+from str_to_obj.type.type import type_t
+
+"""
+COPYRIGHT NOTICE
+
+This software is governed by the CeCILL  license under French law and
+abiding by the rules of distribution of free software.  You can  use,
+modify and/ or redistribute the software under the terms of the CeCILL
+license as circulated by CEA, CNRS and INRIA at the following URL
+"http://www.cecill.info".
+
+As a counterpart to the access to the source code and  rights to copy,
+modify and redistribute granted by the license, users are provided only
+with a limited warranty  and the software's author,  the holder of the
+economic rights,  and the successive licensors  have only  limited
+liability.
+
+In this respect, the user's attention is drawn to the risks associated
+with loading,  using,  modifying and/or developing or reproducing the
+software by the user in light of its specific status of free software,
+that may mean  that it is complicated to manipulate,  and  that  also
+therefore means  that it is reserved for developers  and  experienced
+professionals having in-depth computer knowledge. Users are therefore
+encouraged to load and test the software's suitability as regards their
+requirements in conditions enabling the security of their systems and/or
+data to be ensured and,  more generally, to use and operate it in the
+same conditions as regards security.
+
+The fact that you are presently reading this means that you have had
+knowledge of the CeCILL license and that you accept its terms.
+
+SEE LICENCE NOTICE: file README-LICENCE-utf8.txt at project source root.
+
+This software is being developed by Eric Debreuve, a CNRS employee and
+member of team Morpheme.
+Team Morpheme is a joint team between Inria, CNRS, and UniCA.
+It is hosted by the Centre Inria d'Université Côte d'Azur, Laboratory
+I3S, and Laboratory iBV.
+
+CNRS: https://www.cnrs.fr/index.php/en
+Inria: https://www.inria.fr/en/
+UniCA: https://univ-cotedazur.eu/
+Centre Inria d'Université Côte d'Azur: https://www.inria.fr/en/centre/sophia/
+I3S: https://www.i3s.unice.fr/en/
+iBV: http://ibv.unice.fr/
+Team Morpheme: https://team.inria.fr/morpheme/
+"""

str_to_obj/catalog/boolean.py

@@ -0,0 +1,99 @@
+"""
+Copyright CNRS/Inria/UniCA
+Contributor(s): Eric Debreuve (eric.debreuve@cnrs.fr) since 2023
+SEE COPYRIGHT NOTICE BELOW
+"""
+
+import dataclasses as d
+import typing as h
+from enum import Enum as enum_t
+
+from logger_36.content import MessageWithActualExpected
+from str_to_obj.type.annotation import annotation_t
+from str_to_obj.type.hint import annotated_hint_t
+
+
+class boolean_mode_e(enum_t):
+    # True value must be listed first.
+    true_false = ("True", "False")
+    yes_no = ("Yes", "No")
+    on_off = ("On", "Off")
+
+
+_BOOLEAN_MODES = tuple(boolean_mode_e.__members__.keys())
+
+
+@d.dataclass(slots=True, repr=False, eq=False)
+class boolean_t(annotation_t):
+
+    ACCEPTED_TYPES: h.ClassVar[tuple[type, ...]] = (bool,)
+
+    mode: boolean_mode_e = boolean_mode_e.true_false
+
+    @classmethod
+    def NewAnnotatedType(
+        cls, /, *, mode: boolean_mode_e | str | None = None
+    ) -> annotated_hint_t:
+        """"""
+        if mode is None:
+            mode = boolean_mode_e.true_false
+        elif isinstance(mode, str):
+            if mode in _BOOLEAN_MODES:
+                mode = boolean_mode_e[mode].value
+            else:
+                raise ValueError(
+                    MessageWithActualExpected(
+                        "Invalid boolean mode",
+                        actual=mode,
+                        expected=" or ".join(_BOOLEAN_MODES),
+                    )
+                )
+
+        return h.Annotated[bool, cls(mode=mode)]
+
+
+"""
+COPYRIGHT NOTICE
+
+This software is governed by the CeCILL  license under French law and
+abiding by the rules of distribution of free software.  You can  use,
+modify and/ or redistribute the software under the terms of the CeCILL
+license as circulated by CEA, CNRS and INRIA at the following URL
+"http://www.cecill.info".
+
+As a counterpart to the access to the source code and  rights to copy,
+modify and redistribute granted by the license, users are provided only
+with a limited warranty  and the software's author,  the holder of the
+economic rights,  and the successive licensors  have only  limited
+liability.
+
+In this respect, the user's attention is drawn to the risks associated
+with loading,  using,  modifying and/or developing or reproducing the
+software by the user in light of its specific status of free software,
+that may mean  that it is complicated to manipulate,  and  that  also
+therefore means  that it is reserved for developers  and  experienced
+professionals having in-depth computer knowledge. Users are therefore
+encouraged to load and test the software's suitability as regards their
+requirements in conditions enabling the security of their systems and/or
+data to be ensured and,  more generally, to use and operate it in the
+same conditions as regards security.
+
+The fact that you are presently reading this means that you have had
+knowledge of the CeCILL license and that you accept its terms.
+
+SEE LICENCE NOTICE: file README-LICENCE-utf8.txt at project source root.
+
+This software is being developed by Eric Debreuve, a CNRS employee and
+member of team Morpheme.
+Team Morpheme is a joint team between Inria, CNRS, and UniCA.
+It is hosted by the Centre Inria d'Université Côte d'Azur, Laboratory
+I3S, and Laboratory iBV.
+
+CNRS: https://www.cnrs.fr/index.php/en
+Inria: https://www.inria.fr/en/
+UniCA: https://univ-cotedazur.eu/
+Centre Inria d'Université Côte d'Azur: https://www.inria.fr/en/centre/sophia/
+I3S: https://www.i3s.unice.fr/en/
+iBV: http://ibv.unice.fr/
+Team Morpheme: https://team.inria.fr/morpheme/
+"""

str_to_obj/catalog/callable.py

@@ -0,0 +1,99 @@
+"""
+Copyright CNRS/Inria/UniCA
+Contributor(s): Eric Debreuve (eric.debreuve@cnrs.fr) since 2023
+SEE COPYRIGHT NOTICE BELOW
+"""
+
+import dataclasses as d
+import typing as h
+
+from str_to_obj.catalog.choices import choices_t
+from str_to_obj.type.annotation import annotation_t
+from str_to_obj.type.hint import annotated_hint_t
+
+
+@d.dataclass(slots=True, repr=False, eq=False)
+class callable_t(annotation_t):
+    ACCEPTED_TYPES: h.ClassVar[tuple[type, ...]] = (str,)
+
+    DUMMY_ENTRY: h.ClassVar[str] = "Dummy entry"
+    SEPARATOR: h.ClassVar[str] = ":"
+
+    kind: h.Literal["class", "function"]
+    choices: choices_t | None = None
+    allow_external: bool = False
+
+    @classmethod
+    def NewAnnotatedType(
+        cls,
+        /,
+        *,
+        kind: h.Literal["class", "function"] = "function",
+        catalog: h.Sequence[str] | bool | None = None,
+        allow_external: bool = False,
+    ) -> annotated_hint_t:
+        """"""
+        if catalog is None:
+            annotation = cls(kind=kind, allow_external=allow_external)
+        elif isinstance(catalog, bool):
+            if catalog:
+                annotation = cls(
+                    kind=kind,
+                    choices=choices_t((cls.DUMMY_ENTRY,)),
+                    allow_external=allow_external,
+                )
+            else:
+                annotation = cls(kind=kind, allow_external=allow_external)
+        else:
+            annotation = cls(
+                kind=kind, choices=choices_t(catalog), allow_external=allow_external
+            )
+
+        return h.Annotated[str, annotation]
+
+
+"""
+COPYRIGHT NOTICE
+
+This software is governed by the CeCILL  license under French law and
+abiding by the rules of distribution of free software.  You can  use,
+modify and/ or redistribute the software under the terms of the CeCILL
+license as circulated by CEA, CNRS and INRIA at the following URL
+"http://www.cecill.info".
+
+As a counterpart to the access to the source code and  rights to copy,
+modify and redistribute granted by the license, users are provided only
+with a limited warranty  and the software's author,  the holder of the
+economic rights,  and the successive licensors  have only  limited
+liability.
+
+In this respect, the user's attention is drawn to the risks associated
+with loading,  using,  modifying and/or developing or reproducing the
+software by the user in light of its specific status of free software,
+that may mean  that it is complicated to manipulate,  and  that  also
+therefore means  that it is reserved for developers  and  experienced
+professionals having in-depth computer knowledge. Users are therefore
+encouraged to load and test the software's suitability as regards their
+requirements in conditions enabling the security of their systems and/or
+data to be ensured and,  more generally, to use and operate it in the
+same conditions as regards security.
+
+The fact that you are presently reading this means that you have had
+knowledge of the CeCILL license and that you accept its terms.
+
+SEE LICENCE NOTICE: file README-LICENCE-utf8.txt at project source root.
+
+This software is being developed by Eric Debreuve, a CNRS employee and
+member of team Morpheme.
+Team Morpheme is a joint team between Inria, CNRS, and UniCA.
+It is hosted by the Centre Inria d'Université Côte d'Azur, Laboratory
+I3S, and Laboratory iBV.
+
+CNRS: https://www.cnrs.fr/index.php/en
+Inria: https://www.inria.fr/en/
+UniCA: https://univ-cotedazur.eu/
+Centre Inria d'Université Côte d'Azur: https://www.inria.fr/en/centre/sophia/
+I3S: https://www.i3s.unice.fr/en/
+iBV: http://ibv.unice.fr/
+Team Morpheme: https://team.inria.fr/morpheme/
+"""

str_to_obj/catalog/choices.py

@@ -0,0 +1,101 @@
+"""
+Copyright CNRS/Inria/UniCA
+Contributor(s): Eric Debreuve (eric.debreuve@cnrs.fr) since 2023
+SEE COPYRIGHT NOTICE BELOW
+"""
+
+import dataclasses as d
+import typing as h
+
+from str_to_obj.type.annotation import annotation_t
+from str_to_obj.type.hint import annotated_hint_t
+
+
+@d.dataclass(slots=True, repr=False, eq=False)
+class choices_t(annotation_t):
+    ACCEPTED_TYPES: h.ClassVar[tuple[type, ...]] = (h.Any,)
+
+    options: h.Sequence[h.Any]
+
+    @classmethod
+    def NewAnnotatedType(cls, options: h.Sequence, /) -> annotated_hint_t:
+        """
+        Note: options hint cannot be h.Sequence | h.Literal since h.Literal cannot be
+        used alone, although a value of type h.Literal[...] can be passed as options.
+        """
+        if h.get_origin(options) is h.Literal:
+            options = h.get_args(options)
+        else:
+            options = tuple(options)
+
+        stripes = tuple(set(type(_elm) for _elm in options))
+        if stripes.__len__() > 1:
+            stripe = h.Union[stripes]
+        else:
+            stripe = stripes[0]
+
+        return h.Annotated[stripe, cls(options=options)]
+
+    def ValueIssues(self, value: str | h.Any, /) -> list[str]:
+        """"""
+        issues = annotation_t.ValueIssues(self, value)
+        if issues.__len__() > 0:
+            return issues
+
+        if (self.options.__len__() == 0) or (value in self.options):
+            # Options can be empty for a controlling parameter whose controlled section
+            # has not been specified. In a GUI context, such controlled section should
+            # have been populated programmatically.
+            return []
+
+        options = map(lambda _elm: f'"{_elm}"', self.options)
+        options = " or ".join(options)
+
+        return [f"Invalid choice: Actual={value}; Expected={options}."]
+
+
+"""
+COPYRIGHT NOTICE
+
+This software is governed by the CeCILL  license under French law and
+abiding by the rules of distribution of free software.  You can  use,
+modify and/ or redistribute the software under the terms of the CeCILL
+license as circulated by CEA, CNRS and INRIA at the following URL
+"http://www.cecill.info".
+
+As a counterpart to the access to the source code and  rights to copy,
+modify and redistribute granted by the license, users are provided only
+with a limited warranty  and the software's author,  the holder of the
+economic rights,  and the successive licensors  have only  limited
+liability.
+
+In this respect, the user's attention is drawn to the risks associated
+with loading,  using,  modifying and/or developing or reproducing the
+software by the user in light of its specific status of free software,
+that may mean  that it is complicated to manipulate,  and  that  also
+therefore means  that it is reserved for developers  and  experienced
+professionals having in-depth computer knowledge. Users are therefore
+encouraged to load and test the software's suitability as regards their
+requirements in conditions enabling the security of their systems and/or
+data to be ensured and,  more generally, to use and operate it in the
+same conditions as regards security.
+
+The fact that you are presently reading this means that you have had
+knowledge of the CeCILL license and that you accept its terms.
+
+SEE LICENCE NOTICE: file README-LICENCE-utf8.txt at project source root.
+
+This software is being developed by Eric Debreuve, a CNRS employee and
+member of team Morpheme.
+Team Morpheme is a joint team between Inria, CNRS, and UniCA.
+It is hosted by the Centre Inria d'Université Côte d'Azur, Laboratory
+I3S, and Laboratory iBV.
+
+CNRS: https://www.cnrs.fr/index.php/en
+Inria: https://www.inria.fr/en/
+UniCA: https://univ-cotedazur.eu/
+Centre Inria d'Université Côte d'Azur: https://www.inria.fr/en/centre/sophia/
+I3S: https://www.i3s.unice.fr/en/
+iBV: http://ibv.unice.fr/
+Team Morpheme: https://team.inria.fr/morpheme/
+"""