veridret-plugins-core 1__tar.gz → 2__tar.gz

{veridret_plugins_core-1 → veridret_plugins_core-2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: veridret-plugins-core
-Version: 1
+Version: 2
 Import-Name: veridret_plugins.core
 Import-Namespace: veridret_plugins
-Summary: The *official* Python package of the *official* standard core VerIdRet plugins
+Summary: The *official* Python package of the core *official* standard VerIdRet plugins
 Project-URL: homepage, https://codeberg.org/jonathan-gruber-jg/veridret-plugins-core.git
 Project-URL: source, https://codeberg.org/jonathan-gruber-jg/veridret-plugins-core.git
 Author-email: Jonathan Gruber <jonathan.gruber.jg@gmail.com>
@@ -17,4 +17,4 @@ Description-Content-Type: text/markdown
 <!-- SPDX-License-Identifier: BSD-3-Clause -->
 
 `veridret-plugins-core` is the *official* Python package
-of the *official* standard core VerIdRet plugins.
+of the core *official* standard VerIdRet plugins.

{veridret_plugins_core-1 → veridret_plugins_core-2}/README.md

@@ -1,4 +1,4 @@
 <!-- SPDX-License-Identifier: BSD-3-Clause -->
 
 `veridret-plugins-core` is the *official* Python package
-of the *official* standard core VerIdRet plugins.
+of the core *official* standard VerIdRet plugins.

{veridret_plugins_core-1 → veridret_plugins_core-2}/pyproject.toml

@@ -13,7 +13,7 @@ dynamic = [
 ]
 description = """\
 The *official* Python package \
-of the *official* standard core VerIdRet plugins\
+of the core *official* standard VerIdRet plugins\
 """
 readme = 'README.md'
 license = 'BSD-3-Clause'
@@ -47,6 +47,10 @@ packages = [
 
 [tool.hatch.version]
 path = 'src/veridret_plugins/core/__init__.py'
+pattern = '''(?x)
+    ^\s*__version__\s*:\s*Final\s*\[\s*LiteralString\s*\]\s*=\s*
+    (?P<q>['"])(?P<version>.*?)(?P=q)
+'''
 
 [tool.pylint.main]
 disable = [

veridret_plugins_core-2/src/veridret_plugins/core/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+The *official* Python package
+of the core *official* standard VerIdRet plugins.
+"""
+
+from typing import Final, LiteralString
+
+__all__: Final[tuple[LiteralString, ...]] = (
+    '__version__',
+)
+
+__version__: Final[LiteralString] = '2'
+"""
+The version of the package.
+"""

{veridret_plugins_core-1 → veridret_plugins_core-2}/src/veridret_plugins/core/_plugin.py

@@ -4,17 +4,17 @@
 Plugin utilities.
 """
 
-from typing import Annotated, Any, ClassVar
+from typing import Annotated, Any, ClassVar, Final, LiteralString
 
 import pydantic
 
 import veridret.plugin
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'AnnotatedCall',
     'Call',
     'evaluate_call',
-]
+)
 
 class Call(pydantic.BaseModel):
     """

veridret_plugins_core-2/src/veridret_plugins/core/comparison/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+Utilities for comparing values.
+"""
+
+from typing import Final, LiteralString
+
+__all__: Final[tuple[LiteralString, ...]] = (
+)

{veridret_plugins_core-1/src/veridret_plugins/core/cmptools → veridret_plugins_core-2/src/veridret_plugins/core/comparison}/reverse.py

@@ -8,12 +8,12 @@ from collections.abc import Callable
 import dataclasses
 import operator
 import types
-from typing import Any, final, Never, override
+from typing import Any, Final, final, LiteralString, Never, override
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
     'Reverse',
-]
+)
 
 @final
 @dataclasses.dataclass(frozen=True)

{veridret_plugins_core-1/src/veridret_plugins/core/cmptools → veridret_plugins_core-2/src/veridret_plugins/core/comparison}/unordered.py

@@ -7,12 +7,12 @@ upon an object.
 """
 
 import dataclasses
-from typing import Any, final, Never, override
+from typing import Any, Final, final, LiteralString, Never, override
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
     'Unordered',
-]
+)
 
 @final
 @dataclasses.dataclass(frozen=True)

veridret_plugins_core-2/src/veridret_plugins/core/function/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+Utilities for manipulating functions.
+
+The functions with which :mod:`veridret_plugins.core` is concerned
+are chiefly unary functions,
+i.e.,
+those matching ``Callable[[T], U]`` for some ``T`` and ``U``;
+multiparameter functions are substituted for by equivalent curried functions.
+"""
+
+from typing import Final, LiteralString
+
+__all__: Final[tuple[LiteralString, ...]] = (
+)

veridret_plugins_core-1/src/veridret_plugins/core/functools/call.py → veridret_plugins_core-2/src/veridret_plugins/core/function/apply.py

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 """
-The function call operator.
+The function application operator.
 
 The operator is in fact the identity function over the functions;
 letting ``op`` denote the operator,
@@ -9,35 +9,35 @@ we have ``op f x = (op f) x = f x``.
 """
 
 from collections.abc import Callable
-from typing import Any, Protocol
+from typing import Any, Final, LiteralString, Protocol
 
-__all__ = [
-    'Call',
+__all__: Final[tuple[LiteralString, ...]] = (
+    'Apply',
     'call',
-]
+)
 
-class Call(Protocol):
+class Apply(Protocol):
     """
-    A protocol for the function call operator.
+    A protocol for the function application operator.
     """
 
     def __call__[F: Callable[[Any], Any]](self, obj: F, /) -> F:
         ...
 
-def _identity[F: Callable[[Any], Any]](func: F, /) -> F:
+def _apply[F: Callable[[Any], Any]](func: F, /) -> F:
     return func
 
-def call(args: dict[str, object]) -> Call:
+def call(args: dict[str, object]) -> Apply:
     """
     Call the plugin.
 
     :param args:
         A dictionary of the plugin's arguments;
         unused.
-    :return: The function call operator.
+    :return: The function application operator.
     """
 
     # Unused.
     del args
 
-    return _identity
+    return _apply

veridret_plugins_core-2/src/veridret_plugins/core/function/apply_right.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+The reverse or rightist function application operator.
+
+The operator is in fact the normal function application operator
+with the first two parameters switched;
+letting ``op`` denote the operator,
+we have ``op x f = f x``.
+Since,
+in an expression like ``operator a b``,
+the normal function application operator calls
+the *left* operand ``a`` upon the right operand ``b``
+while the reverse function application operator calls
+the *right* operand ``b`` upon the left operand ``a``,
+we refer to the latter operator as also
+the *right*\\ ist function application operator.
+"""
+
+from collections.abc import Callable
+from typing import Final, LiteralString, Protocol
+
+__all__: Final[tuple[LiteralString, ...]] = (
+    'ApplyRight',
+    'ApplyRightOne',
+    'call',
+)
+
+class ApplyRightOne[T](Protocol):
+    """
+    A protocol for the reverse function application operator
+    with the first parameter bound to an object of type ``T``.
+    """
+
+    def __call__[U](self, func: Callable[[T], U], /) -> U:
+        ...
+
+class ApplyRight(Protocol):
+    """
+    A protocol for the reverse function application operator.
+    """
+
+    def __call__[T](self, obj: T, /) -> ApplyRightOne[T]:
+        ...
+
+def _apply_right[T](obj: T, /) -> ApplyRightOne[T]:
+    def apply_right_one[U](func: Callable[[T], U], /) -> U:
+        return func(obj)
+
+    return apply_right_one
+
+def call(args: dict[str, object]) -> ApplyRight:
+    """
+    Call the plugin.
+
+    :param args:
+        A dictionary of the plugin's arguments;
+        unused.
+    :return: The reverse function application operator.
+    """
+
+    # Unused.
+    del args
+
+    return _apply_right

{veridret_plugins_core-1/src/veridret_plugins/core/functools → veridret_plugins_core-2/src/veridret_plugins/core/function}/compose_left.py

@@ -14,18 +14,18 @@ we call the operator the *left*\\ ist function composition operator.
 """
 
 from collections.abc import Callable
-from typing import Protocol
+from typing import Final, LiteralString, Protocol
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
     'ComposeLeft',
     'ComposeLeftOne',
-]
+)
 
 class ComposeLeftOne[T, U](Protocol):
     """
     A protocol for the leftist function composition operator
-    with the first argument bound to a function of type ``T -> U``.
+    with the first parameter bound to a function of type ``T -> U``.
     """
 
     def __call__[V](self, func: Callable[[U], V], /) -> Callable[[T], V]:

{veridret_plugins_core-1/src/veridret_plugins/core/functools → veridret_plugins_core-2/src/veridret_plugins/core/function}/compose_right.py

@@ -14,18 +14,18 @@ we call the operator the *right*\\ ist function composition operator.
 """
 
 from collections.abc import Callable
-from typing import Protocol
+from typing import Final, LiteralString, Protocol
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
     'ComposeRight',
     'ComposeRightOne',
-]
+)
 
 class ComposeRightOne[T, U](Protocol):
     """
     A protocol for the rightist function composition operator
-    with the first argument bound to a function of type ``T -> U``.
+    with the first parameter bound to a function of type ``T -> U``.
     """
 
     def __call__[V](self, func: Callable[[V], T], /) -> Callable[[V], U]:

veridret_plugins_core-1/src/veridret_plugins/core/call.py → veridret_plugins_core-2/src/veridret_plugins/core/function/evaluate_application.py

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 """
-Evaluate a call expression.
+Evaluate a function application expression.
 
 In particular,
 the plugin evaluates ``id a[1] a[2] ... a[n]``,
@@ -11,15 +11,15 @@ and each operand ``a[i]`` is the result of a plugin call.
 
 from collections.abc import Callable
 import functools
-from typing import Any, cast, overload
+from typing import Any, cast, Final, LiteralString, overload
 
 import pydantic
 
 from veridret_plugins.core import _plugin
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
-]
+)
 
 class _Args(pydantic.BaseModel):
     operands: tuple[_plugin.AnnotatedCall, ...] = pydantic.Field(
@@ -45,14 +45,17 @@ def call(args: dict[str, object]) -> Any:
     Call the plugin.
 
     :param args: A dictionary of the plugin's arguments.
-    :return: The result of the call expression specified by ``args``.
+    :return:
+        The value
+        of the function application expression specified by ``args``.
     :raise Exception:
         If ``args`` is invalid,
         evaluating any of the plugin calls
-        that evaluate to the operands of the call expression
+        that evaluate to the operands
+        of the function application expression
         fails,
         or any of the individual calls
-        made in evaluating the whole call expression
+        made in evaluating the whole function application expression
         fails.
     """
 

{veridret_plugins_core-1/src/veridret_plugins/core/functools → veridret_plugins_core-2/src/veridret_plugins/core/function}/identity.py

@@ -4,12 +4,12 @@
 The identity function.
 """
 
-from typing import Protocol
+from typing import Final, LiteralString, Protocol
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
     'Identity',
-]
+)
 
 class Identity(Protocol):
     """

{veridret_plugins_core-1/src/veridret_plugins/core/itertools → veridret_plugins_core-2/src/veridret_plugins/core/iterable}/__init__.py

@@ -4,5 +4,7 @@
 Utilities for manipulating iterators and other iterables.
 """
 
-__all__: list[str] = [
-]
+from typing import Final, LiteralString
+
+__all__: Final[tuple[LiteralString, ...]] = (
+)

veridret_plugins_core-1/src/veridret_plugins/core/iterator.py → veridret_plugins_core-2/src/veridret_plugins/core/iterable/construct.py

@@ -8,18 +8,24 @@ the plugin constructs an iterator
 over the sequence ``(a[0], a[1], ..., a[n])``,
 where each ``a[i]`` is the result of a plugin call
 and is computed only once the iterator is made to yield it.
+As a result,
+if computing an ``a[i]``,
+i.e.,
+evaluating the corresponding plugin call,
+fails,
+then attempting to yield ``a[i]`` raises an exception.
 """
 
 from collections.abc import Iterator
-from typing import Any
+from typing import Any, Final, LiteralString
 
 import pydantic
 
 from veridret_plugins.core import _plugin
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
-]
+)
 
 class _Args(pydantic.BaseModel):
     operands: tuple[_plugin.AnnotatedCall, ...] = pydantic.Field(
@@ -34,15 +40,7 @@ def call(args: dict[str, object]) -> Iterator[Any]:
 
     :param args: A dictionary of the plugin's arguments.
     :return: An iterator of the sequence specified by ``args``.
-    :raise Exception:
-        If ``args`` is invalid.
-
-    Since the plugin calls that evaluate to the items yielded by the iterator
-    are each only evaluated once the iterator is made to yield them,
-    if evaluating any of those plugin calls fails,
-    then attempting to yield the item
-    to which the plugin call would have evaluated
-    raises an exception.
+    :raise Exception: If ``args`` is invalid.
     """
 
     validated_args = _Args.model_validate(args, strict=True, by_name=False)

{veridret_plugins_core-1/src/veridret_plugins/core/itertools → veridret_plugins_core-2/src/veridret_plugins/core/iterable}/filter.py

@@ -9,12 +9,12 @@ including the special case where ``p`` is ``None``.
 """
 
 from collections.abc import Callable, Iterable, Iterator
-from typing import Protocol
+from typing import Final, LiteralString, Protocol
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
     'Filter',
-]
+)
 
 class Filter(Protocol):
     """

{veridret_plugins_core-1/src/veridret_plugins/core/itertools → veridret_plugins_core-2/src/veridret_plugins/core/iterable}/fold_left.py

@@ -1,7 +1,8 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 """
-The left-associative variant of the ``fold`` higher-order over the iterables.
+The left-associative variant of the ``fold`` higher-order function
+over the iterables.
 
 Letting ``fold_left`` denote the function,
 ``fold_left f z it`` is equivalent to the Python
@@ -10,17 +11,17 @@ Letting ``fold_left`` denote the function,
 
 from collections.abc import Callable, Iterable
 import functools
-from typing import Protocol
+from typing import Final, LiteralString, Protocol
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
     'FoldLeft',
-]
+)
 
 class FoldLeft(Protocol):
     """
-    A protocol for the left-associative variant of the ``fold`` higher-order
-    over the iterables.
+    A protocol for the left-associative variant
+    of the ``fold`` higher-order function over the iterables.
     """
 
     def __call__[T, U](
@@ -31,12 +32,12 @@ class FoldLeft(Protocol):
 def _fold_left[T, U](
     func: Callable[[T], Callable[[U], T]], /,
 ) -> Callable[[T], Callable[[Iterable[U]], T]]:
-    def uncurried_func(x: T, y: U) -> T:
+    def uncurried_func(x: T, y: U, /) -> T:
         return func(x)(y)
 
-    def fold_left_one(seed: T, /) -> Callable[[Iterable[U]], T]:
+    def fold_left_one(init: T, /) -> Callable[[Iterable[U]], T]:
         def fold_left_two(iterable: Iterable[U], /) -> T:
-            return functools.reduce(uncurried_func, iterable, initial=seed)
+            return functools.reduce(uncurried_func, iterable, initial=init)
 
         return fold_left_two
 
@@ -50,7 +51,7 @@ def call(args: dict[str, object]) -> FoldLeft:
         A dictionary of the plugin's arguments;
         unused.
     :return:
-        The left-associative variant of the ``fold`` higher-order
+        The left-associative variant of the ``fold`` higher-order function
         over the iterables.
     """
 

{veridret_plugins_core-1/src/veridret_plugins/core/itertools → veridret_plugins_core-2/src/veridret_plugins/core/iterable}/map.py

@@ -8,12 +8,12 @@ Letting ``map_`` denote the function,
 """
 
 from collections.abc import Callable, Iterable, Iterator
-from typing import Protocol
+from typing import Final, LiteralString, Protocol
 
-__all__ = [
+__all__: Final[tuple[LiteralString, ...]] = (
     'call',
     'Map',
-]
+)
 
 class Map(Protocol):
     """

veridret_plugins_core-2/src/veridret_plugins/core/iterable/reduce_left.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""
+The left-associative variant of the ``fold`` higher-order function,
+with no initial value,
+over the iterables.
+
+The function raises a :exc:`ValueError` if the iterable is empty.
+
+The "reduce" in the function's name is,
+on the one hand,
+meant to distinguish it from a "normal" fold,
+i.e.,
+one with an initial value;
+this scheme is taken from the Rust programming language,
+whose functions over iterators for a fold with and without an initial value
+are respectively named ``fold`` and ``reduce``.
+On the other hand,
+given that the fold has no initial value,
+its final result is ultimately based only
+upon the combining operation and the element sequence of the iterable
+and is of the same type as the elements of the iterable,
+so we can regard the fold as *reducing* that element sequence
+to a single value of the same type as the members of the sequence;
+meanwhile,
+the result of a "normal" fold,
+i.e.,
+one *with* an initial value,
+is generally based also upon that initial value
+and is not necessarily of the same type as the iterable's elements.
+"""
+
+from collections.abc import Callable, Iterable
+import functools
+from typing import Final, LiteralString, Protocol
+
+__all__: Final[tuple[LiteralString, ...]] = (
+    'call',
+    'ReduceLeft',
+)
+
+class ReduceLeft(Protocol):
+    """
+    A protocol for the left-associative variant
+    of the ``fold`` higher-order function,
+    with no initial value,
+    over the iterables.
+    """
+
+    def __call__[T](
+        self, func: Callable[[T], Callable[[T], T]], /,
+    ) -> Callable[[Iterable[T]], T]:
+        ...
+
+def _reduce_left[T](
+    func: Callable[[T], Callable[[T], T]], /,
+) -> Callable[[Iterable[T]], T]:
+    def uncurried_func(x: T, y: T, /) -> T:
+        return func(x)(y)
+
+    def reduce_left_one(iterable: Iterable[T], /) -> T:
+        it = iter(iterable)
+
+        try:
+            init = next(it)
+        except StopIteration as e:
+            raise ValueError('reduce_left of empty iterable') from e
+
+        return functools.reduce(uncurried_func, it, initial=init)
+
+    return reduce_left_one
+
+def call(args: dict[str, object]) -> ReduceLeft:
+    """
+    Call the plugin.
+
+    :param args:
+        A dictionary of the plugin's arguments;
+        unused.
+    :return:
+        The left-associative variant of the ``fold`` higher-order function,
+        with no initial value,
+        over the iterables.
+    """
+
+    # Unused
+    del args
+
+    return _reduce_left

veridret_plugins_core-1/src/veridret_plugins/core/__init__.py

@@ -1,11 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-
-"""
-The *official* Python package
-of the *official* standard core VerIdRet plugins.
-"""
-
-__all__: list[str] = [
-]
-
-__version__ = '1'

veridret_plugins_core-1/src/veridret_plugins/core/cmptools/__init__.py

@@ -1,8 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-
-"""
-Utilities for comparing values.
-"""
-
-__all__: list[str] = [
-]

veridret_plugins_core-1/src/veridret_plugins/core/functools/__init__.py

@@ -1,8 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-
-"""
-Utilities for manipulating functions.
-"""
-
-__all__: list[str] = [
-]

veridret_plugins_core-1/src/veridret_plugins/core/functools/call_right.py

@@ -1,65 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-
-"""
-The reverse or rightist function call operator.
-
-The operator is in fact the normal function call operator
-with the first two arguments switched;
-letting ``op`` denote the operator,
-we have ``op x f = f x``.
-Since,
-in an expression like ``operator a b``,
-the normal function call operator calls
-the *left* operand ``a`` upon the right operand ``b``
-while the reverse function call operator calls
-the *right* operand ``b`` upon the left operand ``a``,
-we refer to the latter operator as also
-the *right*\\ ist function call operator.
-"""
-
-from collections.abc import Callable
-from typing import Protocol
-
-__all__ = [
-    'call',
-    'CallRight',
-    'CallRightOne'
-]
-
-class CallRightOne[T](Protocol):
-    """
-    A protocol for the reverse function call operator
-    with the first argument bound to an object of type ``T``.
-    """
-
-    def __call__[U](self, func: Callable[[T], U], /) -> U:
-        ...
-
-class CallRight(Protocol):
-    """
-    A protocol for the reverse function call operator.
-    """
-
-    def __call__[T](self, obj: T, /) -> CallRightOne[T]:
-        ...
-
-def _call_right[T](obj: T, /) -> CallRightOne[T]:
-    def call_right_one[U](func: Callable[[T], U], /) -> U:
-        return func(obj)
-
-    return call_right_one
-
-def call(args: dict[str, object]) -> CallRight:
-    """
-    Call the plugin.
-
-    :param args:
-        A dictionary of the plugin's arguments;
-        unused.
-    :return: A curried reverse unary-function-call operator.
-    """
-
-    # Unused.
-    del args
-
-    return _call_right