mares 2026.3.2__py3-none-any.whl

mares/__init__.py

@@ -0,0 +1,9 @@
+"""
+mares: mark's result class for safe value retrieval
+  with all my heart, 2023-2026, mark joshwel <mark@joshwel.co>
+  SPDX-License-Identifier: Unlicense OR 0BSD
+"""
+
+from .mares import Result, __VERSION__
+
+__all__ = ["Result", "__VERSION__"]

mares/mares.py

@@ -0,0 +1,343 @@
+"""
+mares: mark's result class for safe value retrieval
+  with all my heart, 2023-2026, mark joshwel <mark@joshwel.co>
+  SPDX-License-Identifier: Unlicense OR 0BSD
+"""
+
+from dataclasses import dataclass
+from functools import wraps
+from pathlib import Path
+from sys import argv, stderr, stdin, stdout
+from typing import Callable, Generic, NoReturn, ParamSpec, TypeVar, cast
+
+__VERSION__ = "2026.2.3"
+
+
+T = TypeVar("T")
+P = ParamSpec("P")
+R = TypeVar("R")
+U = TypeVar("U")
+
+
+@dataclass(frozen=True, slots=True)
+class Result(Generic[T]):
+    """
+    `dataclasses.dataclass` representing a result for safe value retrieval
+
+    attributes:
+        `value: T`
+            value to return or fallback value if erroneous
+        `error: BaseException | None = None`
+            exception if any
+
+    methods:
+        `def __bool__(self) -> bool: ...`
+            method for boolean comparison for exception safety
+        `def get(self) -> T: ...`
+            method that raises or returns an error if the Result is erroneous
+        `def map(self, func: Callable[[T], U]) -> Result[U]: ...`
+            method that maps the value when not erroneous
+        `def bind(self, func: Callable[[T], Result[U]]) -> Result[U]: ...`
+            method that binds to another Result-returning function
+        `def cry(self, string: bool = False) -> str: ...`
+            method that returns the result value or raises an error
+
+    usage:
+        ```python
+        # do something
+        def wrapped_read(path: str) -> Result[str]:
+            try:
+                with open(path, encoding="utf-8") as file:
+                    contents = file.read()
+            except Exception as exc:
+                # must pass a default value
+                return Result[str]("", error=exc)
+            else:
+                return Result[str](contents)
+
+        # call function and handle result
+        # and check if the result is erroneous
+        result = wrapped_read("some_file.txt")
+
+        if not result:
+            # .cry() raises the exception
+            # (or returns it as a string error message using string=True)
+            print(f"error: {result.cry()}")
+            exit()
+        else:
+            # .get() raises exception or returns value,
+            # but since we checked for errors this is safe
+            print(result.get())
+
+        # railway-oriented example
+        def parse_int(text: str) -> Result[int]:
+            try:
+                return Result[int](int(text.strip()))
+            except ValueError as exc:
+                return Result[int](0, error=exc)
+
+        chained = (
+            wrapped_read("some_file.txt")
+            .bind(parse_int)
+            .map(lambda value: value * 2)
+        )
+
+        if not chained:
+            print(f"error: {chained.cry()}")
+        else:
+            print(chained.get())
+        ```
+    """
+
+    value: T
+    error: BaseException | None = None
+
+    def __bool__(self) -> bool:
+        """
+        method for boolean comparison for easier exception handling
+
+        returns: `bool`
+            that returns True if `self.error` is not None
+        """
+        return self.error is None
+
+    def cry(self, string: bool = False) -> str:  # noqa: FBT001, FBT002
+        """
+        method that raises or returns an error if the Result is erroneous
+
+        arguments:
+            `string: bool = False`
+                if `self.error` is an Exception, returns it as a string
+                error message
+
+        returns: `str`
+            returns `self.error` as a string if `string` is True,
+            or returns an empty string if `self.error` is None
+        """
+
+        if isinstance(self.error, BaseException):
+            if string:
+                message = f"{self.error}"
+                name = self.error.__class__.__name__
+                return f"{message} ({name})" if (message != "") else name
+
+            raise self.error
+
+        return ""
+
+    def get(self) -> T:
+        """
+        method that returns the result value or raises an error
+
+        returns: `T`
+            returns `self.value` if `self.error` is None
+
+        raises: `BaseException`
+            if `self.error` is not None
+        """
+        if self.error is not None:
+            raise self.error
+        return self.value
+
+    def map(self, func: Callable[[T], U]) -> "Result[U]":
+        """
+        method that maps the value when not erroneous
+
+        arguments:
+            `func: Callable[[T], U]`
+                function to transform the value
+
+        returns: `Result[U]`
+            returns a new Result with the transformed value, or the same error
+        """
+        if self.error is not None:
+            return Result(cast(U, self.value), error=self.error)
+        return Result(func(self.value))
+
+    def bind(self, func: Callable[[T], "Result[U]"]) -> "Result[U]":
+        """
+        method that binds to another Result-returning function
+
+        arguments:
+            `func: Callable[[T], Result[U]]`
+                function to transform the value into a Result
+
+        returns: `Result[U]`
+            returns the bound Result, or the same error
+        """
+        if self.error is not None:
+            return Result(cast(U, self.value), error=self.error)
+        return func(self.value)
+
+    @staticmethod
+    def wrap(default: R) -> Callable[[Callable[P, R]], Callable[P, "Result[R]"]]:
+        """decorator that wraps a non-Result-returning function to return a Result"""
+
+        def result_decorator(func: Callable[P, R]) -> Callable[P, Result[R]]:
+            @wraps(func)
+            def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[R]:
+                try:
+                    return Result(func(*args, **kwargs))
+                except Exception as exc:
+                    return Result(default, error=exc)
+
+            return wrapper
+
+        return result_decorator
+
+
+def _result_snippet() -> str:
+    lines = Path(__file__).read_text(encoding="utf-8").splitlines()
+    snippet_lines = lines[15:186]
+    return "\n".join(snippet_lines)
+
+
+def _add_imports(lines: list[str]) -> list[str]:
+    required = [
+        "from dataclasses import dataclass",
+        "from functools import wraps",
+        "from typing import Callable, Generic, ParamSpec, TypeVar, cast",
+    ]
+    missing = [line for line in required if line not in lines]
+    if not missing:
+        return lines
+    insert_at = 0
+    if lines and lines[0].startswith("#!"):
+        insert_at = 1
+    while insert_at < len(lines) and lines[insert_at].startswith(
+        "from __future__ import"
+    ):
+        insert_at += 1
+    updated = lines[:insert_at] + missing + [""] + lines[insert_at:]
+    return updated
+
+
+def _replace_marker(text: str, snippet: str) -> str:
+    lines: list[str] = text.splitlines()
+    marker_index = next(
+        (
+            current_index
+            for current_index, line in enumerate(lines)
+            if line == "# mares"
+        ),
+        None,
+    )
+
+    if marker_index is None:
+        _die("mares: error: could not find a '# mares' marker to replace code with")
+
+    lines[marker_index : marker_index + 1] = snippet.splitlines()
+
+    output = "\n".join(lines)
+    if text.endswith("\n"):
+        output += "\n"
+    return output
+
+
+CLI_HELP = """mares: cli insertion tool for mark's result class for safe value retrieval
+
+usage:
+    mares insert [<path>] [--dont-import] [--read-from-stdin] [--write-to-stdout]
+    mares insert --read-from-stdin <path> [--dont-import]
+    mares insert --write-to-stdout [--dont-import]
+    mares --help
+    mares --version
+
+note: replaces a line exactly matching "# mares"
+note: --write-to-stdout with no path prints the Result code block
+"""
+
+
+def _print_help() -> None:
+    _ = stdout.write(CLI_HELP)
+
+
+def _die(message: str | None = None) -> NoReturn:
+    if message:
+        print(message, file=stderr)
+    raise SystemExit(1)
+
+
+def cli() -> None:
+    args: list[str] = argv[1:]
+    if not args:
+        print("mares: error: missing command\n", file=stderr)
+        _print_help()
+        _die()
+
+    if "--version" in args or "-V" in args:
+        _ = stdout.write(f"{__VERSION__}\n")
+        return
+
+    if args[0] in {"--help", "-h"}:
+        _print_help()
+        return
+
+    command = args[0]
+    if command != "insert":
+        _die(f"mares: error: unknown command {command}")
+
+    if "--help" in args[1:] or "-h" in args[1:]:
+        _print_help()
+        return
+
+    flags: set[str] = set()
+    positionals: list[str] = []
+    for item in args[1:]:
+        if item in {"--dont-import", "--read-from-stdin", "--write-to-stdout"}:
+            flags.add(item)
+        elif item.startswith("--"):
+            _die(f"mares: error: unknown option {item}")
+        else:
+            positionals.append(item)
+
+    if len(positionals) > 1:
+        _die("mares: error: too many arguments")
+
+    path: Path | None = Path(positionals[0]) if positionals else None
+    read_from_stdin: bool = "--read-from-stdin" in flags
+    write_to_stdout: bool = "--write-to-stdout" in flags
+    dont_import: bool = "--dont-import" in flags
+
+    if path is None and not read_from_stdin and not write_to_stdout:
+        _die("mares: error: missing path to insert into")
+
+    snippet: str = _result_snippet()
+    if path is None and write_to_stdout and not read_from_stdin:
+        snippet_lines = snippet.splitlines()
+        if not dont_import:
+            snippet_lines = _add_imports(snippet_lines)
+        output_text = "\n".join(snippet_lines)
+        if snippet.endswith("\n"):
+            output_text += "\n"
+        _ = stdout.write(output_text)
+        return
+
+    if read_from_stdin:
+        original: str = stdin.read()
+    else:
+        if path is None:
+            _die("mares: error: missing path to insert into")
+        original = path.read_text(encoding="utf-8")
+
+    replaced: str = _replace_marker(original, snippet)
+    lines: list[str] = replaced.splitlines()
+
+    if not dont_import:
+        lines = _add_imports(lines)
+
+    output: str = "\n".join(lines)
+    if replaced.endswith("\n"):
+        output += "\n"
+
+    if write_to_stdout:
+        _ = stdout.write(output)
+        return
+
+    if path is None:
+        _die("mares: error: missing path to write output to")
+    _ = path.write_text(output, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    cli()

mares-2026.3.2.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: mares
+Version: 2026.3.2
+Summary: mark's result class for safe value retrieval
+Author: Mark Joshwel
+Author-email: Mark Joshwel <mark@joshwel.co>
+License-Expression: Unlicense OR 0BSD
+License-File: LICENCING
+License-File: LICENSE-0BSD
+License-File: UNLICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# mares
+
+**ma**rk's **res**ult class for safe data retrieval
+
+or, as i learnt from opus 4.5, a railway-oriented two-track result pattern for 
+explicit success/failure handling
+
+- [the class](#the-class)
+- [an example](#an-example)
+
+## the class
+
+```python
+@dataclass(frozen=True, slots=True)
+class Result(Generic[T]):
+    """
+    `dataclasses.dataclass` representing a result for safe value retrieval
+
+    attributes:
+        `value: T`
+            value to return or fallback value if erroneous
+        `error: BaseException | None = None`
+            exception if any
+
+    methods:
+        `def __bool__(self) -> bool: ...`
+            method for boolean comparison for exception safety
+        `def get(self) -> T: ...`
+            method that raises or returns an error if the Result is erroneous
+        `def map(self, func: Callable[[T], U]) -> Result[U]: ...`
+            method that maps the value when not erroneous
+        `def bind(self, func: Callable[[T], Result[U]]) -> Result[U]: ...`
+            method that binds to another Result-returning function
+        `def cry(self, string: bool = False) -> str: ...`
+            method that returns the result value or raises an error
+    """
+
+    value: T
+    error: BaseException | None = None
+
+    def __bool__(self) -> bool:
+        """
+        method for boolean comparison for easier exception handling
+
+        returns: `bool`
+            that returns True if `self.error` is not None
+        """
+        return self.error is None
+
+    def cry(self, string: bool = False) -> str:  # noqa: FBT001, FBT002
+        """
+        method that raises or returns an error if the Result is erroneous
+
+        arguments:
+            `string: bool = False`
+                if `self.error` is an Exception, returns it as a string
+                error message
+
+        returns: `str`
+            returns `self.error` as a string if `string` is True,
+            or returns an empty string if `self.error` is None
+        """
+
+        if isinstance(self.error, BaseException):
+            if string:
+                message = f"{self.error}"
+                name = self.error.__class__.__name__
+                return f"{message} ({name})" if (message != "") else name
+
+            raise self.error
+
+        return ""
+
+    def get(self) -> T:
+        """
+        method that returns the result value or raises an error
+
+        returns: `T`
+            returns `self.value` if `self.error` is None
+
+        raises: `BaseException`
+            if `self.error` is not None
+        """
+        if self.error is not None:
+            raise self.error
+        return self.value
+
+    def map(self, func: Callable[[T], U]) -> "Result[U]":
+        """
+        method that maps the value when not erroneous
+
+        arguments:
+            `func: Callable[[T], U]`
+                function to transform the value
+
+        returns: `Result[U]`
+            returns a new Result with the transformed value, or the same error
+        """
+        if self.error is not None:
+            return Result(cast(U, self.value), error=self.error)
+        return Result(func(self.value))
+
+    def bind(self, func: Callable[[T], "Result[U]"]) -> "Result[U]":
+        """
+        method that binds to another Result-returning function
+
+        arguments:
+            `func: Callable[[T], Result[U]]`
+                function to transform the value into a Result
+
+        returns: `Result[U]`
+            returns the bound Result, or the same error
+        """
+        if self.error is not None:
+            return Result(cast(U, self.value), error=self.error)
+        return func(self.value)
+
+    @staticmethod
+    def wrap(default: R) -> Callable[[Callable[P, R]], Callable[P, "Result[R]"]]:
+        """decorator that wraps a non-Result-returning function to return a Result"""
+
+        def result_decorator(func: Callable[P, R]) -> Callable[P, Result[R]]:
+            @wraps(func)
+            def wrapper(*args: P.args, **kwargs: P.kwargs) -> Result[R]:
+                try:
+                    return Result(func(*args, **kwargs))
+                except Exception as exc:
+                    return Result(default, error=exc)
+
+            return wrapper
+
+        return result_decorator
+```
+
+## an example
+
+```python
+def fetch_json(url: str) -> Result[dict[str, Any]]:
+    try:
+        with urllib.request.urlopen(url, timeout=10) as response:
+            data = response.read().decode("utf-8")
+        return Result(json.loads(data))
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        return Result({}, error=exc)
+
+def require_field(data: dict[str, Any], field: str) -> Result[dict[str, Any]]:
+    if field not in data:
+        return Result({}, error=KeyError(f"Missing field: {field}"))
+    return Result(data)
+
+return (
+    fetch_json(f"https://jsonplaceholder.typicode.com/users/{randint(1, 10)}")
+    .bind(lambda payload: require_field(payload, "name"))
+    .map(lambda payload: str(payload["name"]))
+)
+```
+
+**bonus!** this is available as a library, and as a quick insertion tool.
+
+```
+pip install mares
+
+uv install mares
+
+uvx mares inject path/to/file.py
+```

mares-2026.3.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+mares/__init__.py,sha256=8Ec-AjFjo6w0QelCeHzmZyRcqzFatKJ9A4TSuNNVV-g,254
+mares/mares.py,sha256=5jMxkn9M-AFtULdncVng4n15f5AH8jKr4s_73t074m0,10299
+mares/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mares-2026.3.2.dist-info/licenses/LICENCING,sha256=cvXCbqLSG6gBjkXvVDGU2GpT-1ZJLp5lrRoCNaaAm1E,1072
+mares-2026.3.2.dist-info/licenses/LICENSE-0BSD,sha256=rKJ-BtUtVzvJJxPGJ1b6WkMxa7GrxuOFo87DIk_IgMk,677
+mares-2026.3.2.dist-info/licenses/UNLICENSE,sha256=8Bl77UGlO95Tuu1FjTzqAPr-UU_A11XBQdPct1-E3qE,1236
+mares-2026.3.2.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+mares-2026.3.2.dist-info/entry_points.txt,sha256=0OM-oTIuJ2o1oBTqJskJye_O2gTanxJb3_x-1zA9F8s,43
+mares-2026.3.2.dist-info/METADATA,sha256=9QXfa1kNlmVZBBOqs5r3cycFKRNPfER8iet6yfm7wvE,6231
+mares-2026.3.2.dist-info/RECORD,,

mares-2026.3.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any

mares-2026.3.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mares = mares.mares:cli
+

mares-2026.3.2.dist-info/licenses/LICENCING

@@ -0,0 +1,25 @@
+This software is unencumbered and free-as-in-freedom.
+
+This project is dual-licensed under The Unlicense or the BSD Zero Clause
+License. (SPDX: `Unlicense OR 0BSD`)
+
+The spirit and intent of the project is to treat the work as public domain via
+The Unlicense, but providing the BSD Zero Clause License where public domain
+dedication is not possible due to policies bound to a contributor or their
+employer. However, this is not a legal condition.
+
+Either way, you are free to use the software as you wish, without any
+restrictions or obligations, subject only to the warranty disclaimers in the
+licence texts.
+
+> Does dual licencing not invalidate the ethos behind The Unlicense?
+
+Well yeah, but like, even if ten percent of code is 0BSD-licenced, the rest
+is still unlicenced. And that's... good enough, and better than the
+alternative of a fully 0BSD-licenced project. _Everyone should be able to
+contribute._
+
+---
+
+See the [CONTRIBUTING](./CONTRIBUTING), [UNLICENSE](./UNLICENSE), and
+[LICENSE-0BSD](./LICENSE-0BSD) files for more information.

mares-2026.3.2.dist-info/licenses/LICENSE-0BSD

@@ -0,0 +1,12 @@
+Copyright (C) 2025 by Mark Joshwel <mark@joshwel.co>
+
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

mares-2026.3.2.dist-info/licenses/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org/>