interim commit

Author: dusktreader

.github/workflows/main.yml

@@ -27,6 +27,15 @@ jobs:
       run: make qa
 
     - name: Upload coverage reports to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v5
+      if: ${{ !cancelled() }}
+      files: ./.coverage.xml
       env:
         CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+    - name: Upload test results to Codecov
+      if: ${{ !cancelled() }}
+      uses: codecov/test-results-action@v1
+      files: ./.junit.xml
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -1,4 +1,4 @@
-coverage.json
+.junit.xml
 
 # Byte-compiled / optimized / DLL files
 __pycache__/
@@ -15,7 +15,6 @@ param_dict.json
 *java*
 application.sh
 lgcy*
-*demo*
 ~*
 # Distribution / packaging
 .Python

.readthedocs.yml

@@ -40,7 +40,9 @@ clean:
 	@rm -rf .mypy_cache
 	@rm -rf .pytest_cache
 	@rm -rf .ruff_cache
-	#
+	@rm .coverage*
+	@rm .junit.xml
+
 # Recipe stolen from: https://gist.github.com/prwhite/8168133?permalink_comment_id=4160123#gistcomment-4160123
 .PHONY: help
 help:  ## Show help message

Makefile

@@ -50,8 +50,10 @@ minversion = "7.4.0"
 addopts = [
     "--cov=src/buzz",
     "--cov-report=term-missing",
-    "--cov-report=json",
     "--cov-fail-under=90",
+    "--cov-report=xml:.coverage.xml",
+    "--junitxml=.junit.xml",
+    "--override-ini=junit_family=legacy",
 ]
 
 [tool.ruff]

pyproject.toml

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any
+from typing_extensions import override
+
+from buzz import enforce_defined
+
+
+def simple_enforce_defined():
+    """
+    This function demonstrates the simplest use of the enforce_defined
+    function. This function can be used any time a a value needs to be checked
+    to ensure it is defined. This function is best used in an assignment
+    expression so that static type checkers won't complain if you attempt to
+    access an attribute of a value that may not be undefined.
+    """
+    val: str | None = "test-value"
+    val = enforce_defined(val)
+    # I can safely access the `upper()` method of `val` now."
+    # There are also no type errors because `val` is now guaranteed to be a string.
+    val.upper()
+
+    enforce_defined(None)
+
+
+def complex_enforce_defined():
+    """
+    This function demonstrates a more complex usage of the enforce_defined
+    function. It shows the ability to supply a custom message, raise specific
+    exception types, and pass args and kwargs to the raised exception.
+    """
+    class DemoException(Exception):
+        def __init__(self, message: str, demo_arg: Any, demo_kwarg: Any | None = None):
+            super().__init__(message)
+            self.demo_arg: Any = demo_arg
+            self.demo_kwarg: Any = demo_kwarg
+
+        @override
+        def __str__(self):
+            return f"{super().__str__()} (with demo_arg={self.demo_arg} and demo_kwarg={self.demo_kwarg})"
+
+    def get_val(defined: bool = True) -> str | None:
+        if defined:
+            return "test-value"
+        else:
+            return None
+
+    val = enforce_defined(get_val(defined=True), "This condition should pass")
+    val.upper()
+    val = enforce_defined(
+        get_val(defined=False),
+        f'Value is not defined!!!',
+        raise_exc_class=DemoException,
+        raise_args=["jawa"],
+        raise_kwargs=dict(demo_kwarg="ewok"),
+    )
+    val.upper()

src/demo/__init__.py

@@ -0,0 +1,110 @@
+"""
+This example set demonstrates the use of the handle_errors context manager.
+The handle_errors context manager effectively wraps a block of code with
+a try-except without having to explicitly declare them. Additionally, it wraps
+all caught exceptions from the block in custom error messages
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from buzz import handle_errors, DoExceptParams
+
+
+def simple_handle_errors():
+    """
+    This function demonstrates the simplest use of the handle_errors ctx_mgr.
+    Note how the nested exception type is ValueError. The error produced by
+    the handle_errors context manager should be of type HandleError. The
+    resulting exception message will include the message supplied to the
+    handle_error context manager as well as the message of the nested exception
+    """
+    with handle_errors("something went wrong (simple example)"):
+        print("here we are fine")
+        raise ValueError("here we die")
+    print("we should not get here")  # pyright: ignore[reportUnreachable]
+
+
+def absorbing_handle_errors():
+    """
+    This function demonstrates a more complex usage of the handle_errors
+    context manager where exceptions are absorbed. The following features
+    are demonstrated:
+
+    * Handling a specific exception type with `exception_class`
+    * Absorbing exceptions by setting `raise_exc_class` to `None`
+    * Branching with `do_except`, `do_else`, and `do_finally`
+    """
+    def _handler_function(dep: DoExceptParams):
+        """
+        This function is a helper function for handling an exception from
+        the handle_errors ctx_mgr.
+        """
+        print(f"do_except() was called!")
+        print(f"Handling exception: {dep.err}")
+        print(f"Final Message: {dep.final_message}")
+
+    with handle_errors(
+        f"something went wrong (complex example)",
+        raise_exc_class=None,
+        do_except=_handler_function,
+        do_else=lambda: print('do_else() was called!'),
+        do_finally=lambda: print('do_finally() was called!'),
+    ):
+        print("here we are fine")
+        raise ValueError("here we die")
+        print("we should not get here")  # pyright: ignore[reportUnreachable]
+
+
+def multiple_handle_errors():
+    """
+    This function demonstrates handling more than one exception type with the
+    handle_errors context manager. The following features are demonstrated:
+
+    * Handling multiple exception types
+
+    Note that the final `TypeError` is _not_ handled!
+    """
+    def _handler_function(dep: DoExceptParams):
+        """
+        This function is a helper function for handling an exception from
+        the handle_errors context manager.
+        """
+        print(f"Handling exception type {dep.err.__class__}: {dep.final_message}")
+
+    for exception_class in (ValueError, RuntimeError, AttributeError, TypeError):
+        with handle_errors(
+            f"something went wrong (multiple example)",
+            handle_exc_class=(ValueError, RuntimeError, AttributeError),
+            do_except=_handler_function,
+            raise_exc_class=None,
+        ):
+            print("here we are fine")
+            raise exception_class("here we die")
+            print("we should not get here")  # pyright: ignore[reportUnreachable]
+
+
+def specific_handle_errors():
+    """
+    This function demonstrates how handle_errors can be used to raise a specific
+    exception type that wraps the error message of the handled exception. The
+    following features are demonstrated:
+
+    * Raising a specific exception instance using the `raise_exc_class` parameter
+    * Passing along ``raise_args` and `raise_kwargs` when raising the exception
+    """
+    class DerivedError(Exception):
+
+        def __init__(self, message: str, init_arg: Any, init_kwarg: Any | None = None):
+            super().__init__(message)
+            print(f"Derived Error initialized with: {init_arg=}, {init_kwarg=}")
+
+    with handle_errors(
+        f"something went wrong (specific example)",
+        raise_exc_class=DerivedError,
+        raise_args=["init arg"],
+        raise_kwargs=dict(init_kwarg="init kwarg"),
+    ):
+        print("here we are fine")
+        raise ValueError("here we die")
+        print("we should not get here")  # pyright: ignore[reportUnreachable]

src/demo/enforce_defined.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import io
+import inspect
+import sys
+import textwrap
+from typing import Any
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from rich import box
+from rich.text import Text
+
+import snick
+from rich.console import Console, Group, RenderableType
+from rich.panel import Panel
+from rich.prompt import Confirm
+from rich.markdown import Markdown
+from rich.rule import Rule
+
+
+@dataclass
+class Decomposed:
+    name: str
+    docstring: str
+    source: str
+
+
+@dataclass
+class Captured:
+    error: Exception | None = None
+    output: str | None = None
+
+BlankLine = Rule(characters=" ")
+
+def decompose(func: Callable[..., Any]) -> Decomposed:
+    """
+    This is really hacky.
+
+    Maybe improve this sometime.
+    """
+    name = func.__name__
+
+    if func.__doc__ is None:
+        raise RuntimeError("Can't demo a function with no docstring!")
+    docstring = textwrap.dedent(func.__doc__).strip()
+
+    source_lines = inspect.getsourcelines(func)[0]
+    first_quotes = False
+    code_start_index = 0
+    for i, line in enumerate(source_lines):
+        if line.strip() == '"""':
+            if not first_quotes:
+                first_quotes = True
+            else:
+                code_start_index = i
+                break
+    if code_start_index == 0:
+        raise RuntimeError("Failed to strip function declaration and docstring!")
+    source = textwrap.dedent("".join(source_lines[code_start_index+1:]))
+
+    return Decomposed(name=name, docstring=docstring, source=source)
+
+
+def capture(demo: Callable[..., None]) -> Captured:
+    cap = Captured()
+
+    string_buffer = io.StringIO()
+    original_stdout = sys.stdout
+    sys.stdout = string_buffer
+
+    try:
+        demo()
+    except Exception as exc:
+        cap.error = exc
+    finally:
+        sys.stdout = original_stdout
+
+    dump = string_buffer.getvalue()
+    if dump:
+        cap.output = dump
+
+    return cap
+
+
+def run_demo(demo: Callable[..., None], console: Console) -> bool:
+    console.clear()
+
+    decomposed = decompose(demo)
+    cap: Captured = capture(demo)
+
+    parts: list[RenderableType] = [
+        Markdown(decomposed.docstring),
+        BlankLine,
+        BlankLine,
+        Panel(
+            Markdown(
+                "\n".join([
+                    "```python",
+                    decomposed.source,
+                    "```",
+                ])
+            ),
+            title=f"Here is the source code for [green]{decomposed.name}()[/green]",
+            title_align="left",
+            padding=1,
+            expand=False,
+            box=box.SIMPLE,
+        ),
+    ]
+
+    if cap.output:
+        parts.extend([
+            BlankLine,
+            BlankLine,
+            Panel(
+                Markdown(
+                    snick.conjoin(
+                        "```text",
+                        cap.output,
+                        "```"
+                    ),
+                ),
+                title=f"Here is the output captured from [green]{decomposed.name}()[/green]",
+                title_align="left",
+                padding=1,
+                expand=False,
+                box=box.SIMPLE,
+            ),
+        ])
+
+    if cap.error:
+        parts.extend([
+            BlankLine,
+            BlankLine,
+            Panel(
+                f"[red]{cap.error.__class__.__name__}[/red]: [yellow]{str(cap.error)}[/yellow]",
+                title=f"Here is the uncaught exception from [green]{decomposed.name}()[/green]",
+                title_align="left",
+                padding=1,
+                expand=False,
+                box=box.SIMPLE,
+            )
+        ])
+
+    console.print(
+        Panel(
+            Group(*parts),
+            padding=1,
+            title=f"[yellow]{decomposed.name}() demo[/yellow]",
+            title_align="left",
+            subtitle="[blue]https://github.com/dusktreader/py-buzz[/blue]",
+            subtitle_align="left",
+        ),
+    )
+    console.print(BlankLine)
+    console.print(BlankLine)
+    further: bool = Confirm.ask("Would you like to continue?", default=True)
+    return further