preparse 1.0.18__tar.gz → 1.1.0__tar.gz

{preparse-1.0.18 → preparse-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: preparse
-Version: 1.0.18
+Version: 1.1.0
 Summary: This project preparses args for further parsing later on.
 Author-email: Johannes <johannes.programming@gmail.com>
 License-Expression: MIT
@@ -14,6 +14,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
@@ -23,8 +24,7 @@ Requires-Dist: copyable<2,>=1.0
 Requires-Dist: datahold<4,>=3.0
 Requires-Dist: datarepr<2,>=1.1
 Requires-Dist: frozendict<3,>=2.4.7
-Requires-Dist: overloadable<2,>=1.1
-Requires-Dist: setdoc<2,>=1.2.10
+Requires-Dist: setdoc<2,>=1.2.20
 Requires-Dist: tofunc<2,>=1.0
 Dynamic: license-file
 

{preparse-1.0.18 → preparse-1.1.0}/docs/v1.0.rst

@@ -4,14 +4,6 @@ Overview
 The preparse project allows to preparse arguments before the main parsing.
 Its ability to deabbreviate options is especially useful for use with ``click``.
 
-Links
------
-
-- Download: https://pypi.org/project/preparse/#files
-- Index: https://pypi.org/project/preparse/
-- Source: https://github.com/johannes-programming/preparse/
-- Website: https://preparse.johannes-programming.online/
-
 Installation
 ------------
 
@@ -277,21 +269,29 @@ This class warns about unallowed arguments. This can only happen for long option
 The Tests
 ~~~~~~~~~
 
-``preparse.test() -> unittest.TextTestResult``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``preparse.tests.test() -> unittest.TextTestResult``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This project can be tested through its test function.
 
 .. code-block:: python
 
-    import preparse
-    preparse.test()
+    import preparse.tests
+    preparse.tests.test()
 
 License
 -------
 
 This project is licensed under the MIT License.
 
+Links
+-----
+
+- Download: https://pypi.org/project/preparse/#files
+- Index: https://pypi.org/project/preparse/
+- Source: https://github.com/johannes-programming/preparse/
+- Website: https://preparse.johannes-programming.online/
+
 Impressum
 ---------
 

preparse-1.1.0/docs/v1.1.rst

@@ -0,0 +1,312 @@
+Overview
+--------
+
+The preparse project allows to preparse arguments before the main parsing.
+Its ability to deabbreviate options is especially useful for use with ``click``.
+
+Installation
+------------
+
+To install preparse, you can use pip. Open your terminal and run:
+
+.. code-block:: shell
+
+    pip install preparse
+
+Typing
+------
+
+The typing conforms (not strictly) to ``mypy``.
+
+.. container:: versionadded
+
+    **Added in version 1.1.**
+
+Introduction
+------------
+
+The preparse project allows for preprocessing a list of arguments so that they can be parsed definitively in a later step. This way, the functionality of another parsing system can be modified. The project is especially adapted to work with the click project.
+
+The project preparse is strongly inspired by the getopt and getopt_long libraries within C.
+
+Here is the implementation of the ``expit`` project (Version 1.0.13) to illustrate how preparse can be used to modify click.
+
+.. code-block:: python
+
+    import math
+
+    import click
+    import preparse
+
+    __all__ = ["function", "main"]
+
+
+    def function(x: float) -> float:
+        "This function is the logistical sigmoid, i.e. the expit function."
+        try:
+            p = math.exp(-x)
+        except OverflowError:
+            p = float("+inf")
+        return 1 / (1 + p)
+
+
+    @preparse.PreParser().click()
+    @click.command(add_help_option=False)
+    @click.help_option("-h", "--help")
+    @click.version_option(None, "-V", "--version")
+    @click.argument("x", type=float)
+    def main(x: float) -> None:
+        "This command applies the expit function to x."
+        click.echo(function(x))
+
+Features
+--------
+
+The PreParser class
+~~~~~~~~~~~~~~~~~~~
+
+``class preparse.PreParser(*, allowslong: Any = True, allowsshort: Any = True, bundling: Any = Tuning.MAINTAIN, expandsabbr: Any = True, expectsabbr: Any = True, expectsposix: Any = False, optdict: Any = (), prog: Any = None, reconcilesorders: Any = True, special: Any = preparse.Tuning.MAINTAIN, warn: Callable = str)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This class is the centerpiece of the preparse. Its behaviour follows the principles of getopt from C.
+
+``allowslong: bool``
+""""""""""""""""""""
+
+This boolean property determines whether long options are allowed.
+
+``allowsshort: bool``
+"""""""""""""""""""""
+
+This boolean property determines whether short options are allowed.
+
+``bundling: preparse.Tuning``
+"""""""""""""""""""""""""""""
+
+This ``preparse.Tuning`` property determines the approach to bundling of short option.
+
+``click(cmd: Any = True, ctx: Any = True) -> preparse.Click``
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This method returns a decorator that infuses the current instance into ``parse_args``.
+
+``copy() -> Self``
+""""""""""""""""""
+
+This method returns a copy of the current instance.
+
+``expandsabbr: bool``
+"""""""""""""""""""""
+
+This boolean property determines whether recognized abbreviations of long options are to be expanded to their full length.
+
+``expectsabbr: bool``
+"""""""""""""""""""""
+
+This boolean property determines whether abbreviations of long options are expected.
+
+``expectsposix: bool``
+""""""""""""""""""""""
+
+This boolean property determines whether the order of arguments to conform to the POSIX standard, i.e. all arguments after the first positional argument also being positonal.
+
+``optdict: preparse.Optdict``
+"""""""""""""""""""""""""""""
+
+This property holds a dict-like object.
+Its keys are the options.
+Its values specify ``preparse.Nargs``.
+Options not found within the dictionary
+cause a ``preparse.PreparseInvalidOptionWarning``
+and are then assumed to have no arguments.
+
+``parse_args(args: Optional[Iterable] = None) -> list[str]``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This method is at the core of the class.
+It returns a preparsed list of arguments.
+If ``None`` is passed as args then ``sys.argv[1:]`` is used.
+If the method is applied repeatedly to a list there will be no changes after the first run.
+
+``prog: str``
+"""""""""""""
+
+This ``str`` property represents the name of the program.
+If the value passed to the property is ``None`` then ``str(sys.argv[0])`` is saved.
+
+``reconcilesorders: bool``
+""""""""""""""""""""""""""
+
+This boolean property determines whether compatibility with both orders,
+POSIX and the interleaving of options with positonal arguments, should be enforced.
+
+``reflectClickCommand(cmd: click.Command) -> None``
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This method alters the current instance to reflect a ``click.Command`` object.
+Concretely the optdict property is changed.
+
+``reflectClickContext(ctx: click.Context) -> None``
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This method alters the current instance to reflect a ``click.Context`` object.
+Concretely the prog property is changed.
+
+``special: preparse.Tuning``
+""""""""""""""""""""""""""""
+
+This ``preparse.Tuning`` property determines the approach to the special argument ``'--'``.
+
+``todict() -> dict``
+""""""""""""""""""""
+
+This method a dict representing the current instance.
+
+``warn: types.FunctionType``
+""""""""""""""""""""""""""""
+
+This property holds a function that is called whenever ``parse_args`` encounters a warning.
+The warning is given as the only positional arguments.
+No keyword arguments are given.
+Its return value is discarded.
+Therefore, ``str`` is used to discard the warnings.
+
+The Click class
+~~~~~~~~~~~~~~~
+
+``class preparse.Click(parser: preparse.PreParser, cmd: Any = True, ctx: Any = True)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This dataclass provides decorators for embedding a ``PreParser`` object.
+
+``__call__(target: Any) -> Any``
+""""""""""""""""""""""""""""""""
+
+This magic method implements ``self(target)``.
+It works as a decorator that embeds its parser into a given target from the library click.
+
+``cmd: Any``
+""""""""""""
+
+This property determines if the ``reflectClickCommand`` method of parser is to be called.
+
+``copy() -> Self``
+""""""""""""""""""
+
+``ctx: Any``
+""""""""""""
+
+This property determines if the ``reflectClickContext`` method of parser is to be called.
+
+``parser: preparse.PreParser``
+""""""""""""""""""""""""""""""
+
+This property holds the parser to be embedded.
+
+The Optdict class
+~~~~~~~~~~~~~~~~~
+
+``class preparse.Optdict``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This class is a subclass of ``datahold.HoldDict[str, preparse.Nargs]``
+with strings as keys and with ``preparse.Nargs`` as values.
+It is designed for ``preparse.PreParser.optdict``.
+
+The Enums
+~~~~~~~~~
+
+These classes are subclasses of ``enum.IntEnum``.
+Any value different from ``0`` (meaning no) and ``1`` (meaning yes) is interpreted as ``2`` (meaning intermediate).
+
+``class preparse.Tuning``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
++--------------+-------+-----------------------------------------------------------------------------+
+| Name         | Value | Explanation                                                                 |
++==============+=======+=============================================================================+
+| ``MINIMIZE`` | ``0`` | The PreParser minimizes the aspect in question.                             |
++--------------+-------+-----------------------------------------------------------------------------+
+| ``MAXIMIZE`` | ``1`` | The PreParser maximizes the aspect in question.                             |
++--------------+-------+-----------------------------------------------------------------------------+
+| ``MAINTAIN`` | ``2`` | The PreParser does not make any unforced changes to the aspect in question. |
++--------------+-------+-----------------------------------------------------------------------------+
+
+``class preparse.Nargs``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
++-------------------+-------+----------------------------------------------+
+| Name              | Value | Explanation                                  |
++===================+=======+==============================================+
+| NO_ARGUMENT       | ``0`` | The option does not take an argument.        |
++-------------------+-------+----------------------------------------------+
+| REQUIRED_ARGUMENT | ``1`` | The option requires an argument.             |
++-------------------+-------+----------------------------------------------+
+| OPTIONAL_ARGUMENT | ``2`` | The option may take an argument.             |
++-------------------+-------+----------------------------------------------+
+
+The Warnings
+~~~~~~~~~~~~
+
+These classes are subclasses of ``Warning`` that are specifically designed to communicate issues with parsing.
+
+``class preparse.PreparseWarning``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This abstract base class is the base for all other warning types.
+
+``class preparse.PreparseAmbiguousOptionWarning(prog: Any, option: Any, possibilities: Any)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This class warns about ambiguous options. This can only happen for long options.
+
+``class preparse.PreparseInvalidOptionWarning(prog: Any, option: Any, islong: Any)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This class warns about invalid options.
+
+``class preparse.PreparseRequiredArgumentWarning(prog: Any, option: Any, islong: Any)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This class warns about missing required arguments.
+
+``class preparse.PreparseUnallowedArgumentWarning(prog: Any, option: Any)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This class warns about unallowed arguments. This can only happen for long options.
+
+The Tests
+~~~~~~~~~
+
+``preparse.tests.test() -> unittest.TextTestResult``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This project can be tested through its test function.
+
+.. code-block:: python
+
+    import preparse.tests
+    preparse.tests.test()
+
+License
+-------
+
+This project is licensed under the MIT License.
+
+Links
+-----
+
+- Download: https://pypi.org/project/preparse/#files
+- Index: https://pypi.org/project/preparse/
+- Source: https://github.com/johannes-programming/preparse/
+- Website: https://preparse.johannes-programming.online/
+
+Impressum
+---------
+
+**Johannes Programming**
+
+- Name: Johannes
+- Email: johannes.programming@gmail.com
+- Homepage: https://www.johannes-programming.online/
+- Gravatar: https://www.johannes-programming.fyi/

{preparse-1.0.18 → preparse-1.1.0}/pyproject.toml

@@ -15,6 +15,7 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    "Typing :: Typed",
 ]
 dependencies = [
     "click>=8.2,<9",
@@ -23,8 +24,7 @@ dependencies = [
     "datahold>=3.0,<4",
     "datarepr>=1.1,<2",
     "frozendict>=2.4.7,<3",
-    "overloadable>=1.1,<2",
-    "setdoc>=1.2.10,<2",
+    "setdoc>=1.2.20,<2",
     "tofunc>=1.0,<2",
 ]
 description = "This project preparses args for further parsing later on."
@@ -36,10 +36,26 @@ license-files = [
 name = "preparse"
 readme = "README.rst"
 requires-python = ">=3.11"
-version = "1.0.18"
+version = "1.1.0"
 
 [project.urls]
 Download = "https://pypi.org/project/preparse/#files"
 Index = "https://pypi.org/project/preparse/"
 Source = "https://github.com/johannes-programming/preparse/"
 Website = "https://preparse.johannes-programming.online/"
+
+[tool.mypy]
+files = [
+    ".",
+]
+python_version = "3.11"
+strict = false
+
+[[tool.mypy.overrides]]
+module = [
+    "cmp3",
+    "cmp3.*",
+    "datahold",
+    "datahold.*",
+]
+ignore_missing_imports = true

{preparse-1.0.18 → preparse-1.1.0}/src/preparse/_items/Bundle.py

@@ -4,7 +4,6 @@ import setdoc
 
 from preparse._items.Item import Item
 from preparse._items.Option import Option
-from preparse._utils.dataprop import dataprop
 from preparse.core.enums import *
 
 __all__ = ["Bundle"]
@@ -12,23 +11,25 @@ __all__ = ["Bundle"]
 
 class Bundle(Option):
 
-    chars: str
-    joined: bool
-    nargs: Nargs
-    right: Optional[str]
-
-    __slots__ = ()
+    __slots__ = (
+        "_chars",
+        "_joined",
+        "_nargs",
+        "_right",
+    )
 
     @setdoc.basic
     def __init__(
         self: Self,
         *,
         chars: str,
+        nargs: Any,
         joined: bool = False,
         right: Optional[str] = None,
     ) -> None:
         self.chars = chars
         self.joined = joined
+        self.nargs = nargs
         self.right = right
 
     @classmethod
@@ -38,7 +39,7 @@ class Bundle(Option):
         ans = list()
         for x in chars:
             if x == "-":
-                ans[-1].chars += "-"
+                ans[-1] += "-"
             else:
                 ans.append(x)
         return ans
@@ -61,9 +62,13 @@ class Bundle(Option):
                 x = x[:-1]
         return ans
 
-    @dataprop
-    def chars(self: Self, x: Any) -> str:
-        return str(x)
+    @property
+    def chars(self: Self) -> str:
+        return self._chars
+
+    @chars.setter
+    def chars(self: Self, x: Any) -> None:
+        self._chars = str(x)
 
     def deparse(self: Self) -> list[str]:
         if self.right is None:
@@ -73,7 +78,16 @@ class Bundle(Option):
         else:
             return ["-" + self.chars, self.right]
 
-    def split(self: Self, *, allowslong: bool) -> list[Item]:
+    @classmethod
+    def getslotnames(cls: type[Self]) -> tuple[str, ...]:
+        return (
+            "_chars",
+            "_joined",
+            "_nargs",
+            "_right",
+        )
+
+    def split(self: Self, *, allowslong: bool) -> list[Self]:
         ans: list[Self]
         parts: list[str]
         x: str
@@ -83,7 +97,7 @@ class Bundle(Option):
             parts = self._split_shortonly(self.chars)
         ans = list()
         for x in parts:
-            ans.append(Bundle(chars=x))
+            ans.append(type(self)(chars=x, nargs=Nargs.NO_ARGUMENT))
         self.chars = ans[-1].chars
         ans[-1] = self
         return ans

{preparse-1.0.18 → preparse-1.1.0}/src/preparse/_items/Item.py

@@ -10,7 +10,11 @@ __all__ = ["Item"]
 
 
 class Item(Copyable):
-    __slots__ = ("_data",)
+    __slots__ = ()
+
+    @abc.abstractmethod
+    @setdoc.basic
+    def __init__(self: Self, *args: Any, **kwargs: Any) -> None: ...
 
     @setdoc.basic
     def copy(self: Self) -> Self:
@@ -19,18 +23,19 @@ class Item(Copyable):
     @abc.abstractmethod
     def deparse(self: Self) -> list[str]: ...
 
+    @classmethod
+    @abc.abstractmethod
+    def getslotnames(cls: type[Self]) -> tuple[str, ...]: ...
+
     @classmethod
     @abc.abstractmethod
     def sortkey(cls: type) -> int: ...
 
     def todict(self: Self) -> dict:
         "This method returns a dict representing the current instance."
-        ans: dict
-        try:
-            ans = self._data
-        except AttributeError:
-            self._data = dict()
-            ans = dict()
-        else:
-            ans = dict(ans)
+        ans: dict[str, Any]
+        x: str
+        ans = dict()
+        for x in self.getslotnames():
+            ans[x] = getattr(self, x)
         return ans

preparse-1.1.0/src/preparse/_items/Long.py

@@ -0,0 +1,75 @@
+import operator
+from typing import *
+
+import setdoc
+
+from preparse._items.Option import Option
+from preparse.core.enums import *
+
+__all__ = ["Long"]
+
+
+class Long(Option):
+
+    __slots__ = (
+        "_nargs",
+        "_joined",
+        "_right",
+        "_abbrlen",
+        "_fullkey",
+    )
+
+    @setdoc.basic
+    def __init__(
+        self: Self,
+        *,
+        fullkey: str,
+        abbrlen: Optional[int] = None,
+        joined: bool = False,
+        right: Optional[str] = None,
+    ) -> None:
+        self.fullkey = fullkey
+        self.abbrlen = abbrlen
+        self.joined = joined
+        self.right = right
+
+    @property
+    def abbr(self: Self) -> str:
+        return self.fullkey[: self.abbrlen]
+
+    @property
+    def abbrlen(self: Self) -> Optional[int]:
+        return self._abbrlen
+
+    @abbrlen.setter
+    def abbrlen(self: Self, x: Optional[SupportsIndex]) -> None:
+        if x is None:
+            self._abbrlen = None
+        else:
+            self._abbrlen = operator.index(x)
+
+    def deparse(self: Self) -> list[str]:
+        if self.right is None:
+            return [self.abbr]
+        elif self.joined:
+            return [self.abbr + "=" + self.right]
+        else:
+            return [self.abbr, self.right]
+
+    @property
+    def fullkey(self: Self) -> str:
+        return self._fullkey
+
+    @fullkey.setter
+    def fullkey(self: Self, x: Any) -> None:
+        self._fullkey = str(x)
+
+    @classmethod
+    def getslotnames(cls: type[Self]) -> tuple[str, ...]:
+        return (
+            "_nargs",
+            "_joined",
+            "_right",
+            "_abbrlen",
+            "_fullkey",
+        )

preparse-1.1.0/src/preparse/_items/Option.py

@@ -0,0 +1,50 @@
+import operator
+from typing import *
+
+from preparse._items.Item import Item
+from preparse.core.enums import *
+
+__all__ = ["Option"]
+
+
+class Option(Item):
+
+    __slots__ = ()
+
+    _joined: Any
+    _nargs: Any
+    _right: Any
+
+    def ishungry(self: Self) -> bool:
+        return (self.right is None) and (self.nargs == Nargs.REQUIRED_ARGUMENT)
+
+    @property
+    def joined(self: Self) -> bool:
+        return self._joined
+
+    @joined.setter
+    def joined(self: Self, x: SupportsIndex) -> None:
+        self._joined = bool(operator.index(x))
+
+    @property
+    def nargs(self: Self) -> Nargs:
+        return self._nargs
+
+    @nargs.setter
+    def nargs(self: Self, x: Any) -> None:
+        self._nargs = Nargs(x)
+
+    @property
+    def right(self: Self) -> Optional[str]:
+        return self._right
+
+    @right.setter
+    def right(self: Self, x: Any) -> None:
+        if x is None:
+            self._right = None
+        else:
+            self._right = str(x)
+
+    @classmethod
+    def sortkey(cls: type) -> int:
+        return 0