approval-utilities 14.4.0__tar.gz → 14.6.0__tar.gz

{approval_utilities-14.4.0/approval_utilities.egg-info → approval_utilities-14.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: approval_utilities
-Version: 14.4.0
+Version: 14.6.0
 Summary: Utilities for your production code that work well with approvaltests
 Home-page: https://github.com/approvals/ApprovalTests.Python
 Author: ApprovalTests Contributors

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/README.md

@@ -37,6 +37,7 @@ For more information see: [www.approvaltests.com](http://approvaltests.com/).
 [![Build Status](https://github.com/approvals/ApprovalTests.Python/workflows/Test/badge.svg?branch=master)](https://github.com/approvals/ApprovalTests.Python/actions)
 [![Build Status](https://github.com/approvals/ApprovalTests.Python/workflows/on-push-do-doco/badge.svg)](https://github.com/approvals/ApprovalTests.Python/actions?query=workflow%3Aon-push-do-doco)
 [![Build Status](https://github.com/approvals/ApprovalTests.Python/workflows/Upload%20Python%20Package/badge.svg)](https://github.com/approvals/ApprovalTests.Python/actions?query=workflow%3A%22Upload+Python+Package%22)
+[![Discord](https://img.shields.io/discord/1349240939406819409?logo=discord)](https://discord.gg/XDrgy6x6Se)
 
 ## What can I use ApprovalTests for?
 
@@ -84,7 +85,7 @@ golden master.
 from approvaltests.approvals import verify
 
 
-def test_simple():
+def test_simple() -> None:
     result = "Hello ApprovalTests"
     verify(result)
 ```
@@ -111,7 +112,7 @@ from approvaltests.approvals import verify
 
 
 class GettingStartedTest(unittest.TestCase):
-    def test_simple(self):
+    def test_simple(self) -> None:
         verify("Hello ApprovalTests")
 
 
@@ -170,7 +171,7 @@ class TestSelectReporterFromClass(unittest.TestCase):
     def test_simple(self):
         verify("Hello", options=Options().with_reporter(report_with_beyond_compare()))
 ```
-<sup><a href='/tests/samples/test_getting_started.py#L25-L31' title='Snippet source file'>snippet source</a> | <a href='#snippet-select_reporter_from_class' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/tests/samples/test_getting_started.py#L28-L34' title='Snippet source file'>snippet source</a> | <a href='#snippet-select_reporter_from_class' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 You can also use the `GenericDiffReporterFactory` to find and select the first diff utility that exists on our system.
@@ -181,6 +182,7 @@ An advantage of this method is you can modify the reporters.json file directly t
 <a id='snippet-select_reporter_from_factory'></a>
 ```py
 class TestSelectReporter(unittest.TestCase):
+    @override
     def setUp(self):
         self.factory = GenericDiffReporterFactory()
 
@@ -189,7 +191,7 @@ class TestSelectReporter(unittest.TestCase):
             "Hello", options=Options().with_reporter(self.factory.get("BeyondCompare"))
         )
 ```
-<sup><a href='/tests/samples/test_getting_started.py#L11-L22' title='Snippet source file'>snippet source</a> | <a href='#snippet-select_reporter_from_factory' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/tests/samples/test_getting_started.py#L13-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-select_reporter_from_factory' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Or you can build your own GenericDiffReporter on the fly
@@ -206,7 +208,7 @@ class GettingStartedTest(unittest.TestCase):
             ),
         )
 ```
-<sup><a href='/tests/samples/test_getting_started.py#L34-L45' title='Snippet source file'>snippet source</a> | <a href='#snippet-custom_generic_diff_reporter' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/tests/samples/test_getting_started.py#L37-L48' title='Snippet source file'>snippet source</a> | <a href='#snippet-custom_generic_diff_reporter' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 As long as `C:/my/favorite/diff/utility.exe` can be invoked from the command line using the format `utility.exe file1 file2`
@@ -314,7 +316,7 @@ The best way to contribute is to [join our weekly mob/ensemble](./docs/Contribut
 Pull requests are welcomed, particularly those accompanied by automated tests.
 
 To run the self-tests:
-`./run_tests.sh`
+`./build_and_test.sh`
 
 This will run the self-tests on several python versions. We support python 3.8 and above.
 

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/approvaltests/core/executable_command.py

@@ -1,4 +1,4 @@
-from abc import abstractmethod, ABC
+from abc import ABC, abstractmethod
 
 
 class CommandGetter(ABC):

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/approvaltests/core/verifiable.py

@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
 
 from approval_utilities.approvaltests.core.verify_parameters import VerifyParameters
+from approvaltests.core.options import Options
 
 
 class Verifiable(ABC):

approval_utilities-14.6.0/approval_utilities/approvaltests/core/verify_parameters.py

@@ -0,0 +1,9 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from approvaltests.core.options import Options
+
+
+class VerifyParameters:
+    def __init__(self, options: "Options"):
+        self.options = options

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/list_utils.py

@@ -1,7 +1,7 @@
-from typing import Callable, List, Optional
+from typing import Any, Callable, List, Optional
 
 
-def format_list(alist: List[str], formatter: Optional[Callable], header: str) -> str:
+def format_list(alist: List[Any], formatter: Optional[Callable], header: str) -> str:
     if formatter is None:
         formatter = FormatLineItem().print_item
     text = (header + "\n\n") if header else ""
@@ -14,7 +14,7 @@ class FormatLineItem(object):
     def __init__(self) -> None:
         self.index = 0
 
-    def print_item(self, item: str) -> str:
+    def print_item(self, item: Any) -> str:
         text = str(self.index) + ") " + str(item)
         self.index += 1
         return text

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/clipboard_utilities.py

@@ -1,4 +1,4 @@
-def copy_to_clipboard(text):
+def copy_to_clipboard(text: str) -> None:
     """
     This acts as a wrapper to defer the importing of pyperclip util actual usage
     """

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/deprecated.py

@@ -1,10 +1,10 @@
-import warnings
 import functools
+import warnings
 from typing import Callable
 
 
 def deprecated(reason: str) -> Callable:
-    def decorator(func):
+    def decorator(func: Callable) -> Callable:
         """This is a decorator which can be used to mark functions
         as deprecated. It will result in a warning being emitted
         when the function is used."""

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/exceptions/exception_collector.py

@@ -1,4 +1,4 @@
-from typing import Callable, Sequence, Any
+from typing import Any, Callable, List, Sequence
 
 from approval_utilities.utilities.exceptions.multiple_exceptions import (
     MultipleExceptions,
@@ -6,16 +6,16 @@ from approval_utilities.utilities.exceptions.multiple_exceptions import (
 
 
 class ExceptionCollector:
-    def __init__(self):
-        self._exceptions = []
+    def __init__(self) -> None:
+        self._exceptions: List[Exception] = []
 
-    def gather(self, code_to_execute: Callable):
+    def gather(self, code_to_execute: Callable[[], Any]) -> None:
         try:
             code_to_execute()
         except Exception as exception:
             self._exceptions.append(exception)
 
-    def release(self):
+    def release(self) -> None:
         if len(self._exceptions) == 0:
             return
         if len(self._exceptions) == 1:

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/exceptions/exception_utils.py

@@ -1,2 +1,2 @@
-def to_string(exception: Exception) -> str:
+def to_string(exception: BaseException) -> str:
     return f"{type(exception).__name__}: {str(exception)}"

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/logger/logging_instance.py

@@ -1,12 +1,12 @@
 import datetime
 import inspect
 import traceback
-from typing import Callable, Any, Iterable, ContextManager
-
+from types import TracebackType
+from typing import Any, Callable, ContextManager, Iterable, Optional, Type, Union
 
 from approval_utilities.utilities.exceptions.exception_utils import to_string
-from approval_utilities.utilities.string_wrapper import StringWrapper
 from approval_utilities.utilities.stack_frame_utilities import get_class_name_for_frame
+from approval_utilities.utilities.string_wrapper import StringWrapper
 
 
 class Toggles:
@@ -19,21 +19,21 @@ class Toggles:
         self.events = show
 
 
-def _is_iterable(arg):
+def _is_iterable(arg: Any) -> bool:
     return isinstance(arg, Iterable) and not isinstance(arg, str)
 
 
-def print_type(value):
+def print_type(value: Any) -> str:
     return f"<{type(value).__name__}>"
 
 
 class LoggingInstance:
-    def __init__(self):
+    def __init__(self) -> None:
         self.log_stack_traces = True
         self.toggles = Toggles(True)
-        self.previous_timestamp = None
-        self.logger = lambda t: print(t, end="")
-        self.tabbing = 0
+        self.previous_timestamp: Optional[datetime.datetime] = None
+        self.logger: Callable[[str], None] = lambda t: print(t, end="")
+        self.tabbing: int = 0
         self.counter = 0
         self.log_with_timestamps = True
         self.timer: Callable[[], datetime.datetime] = datetime.datetime.now
@@ -45,53 +45,71 @@ class LoggingInstance:
         self.log_stack_traces = False
         return buffer
 
-    def indent(self) -> ContextManager:
+    def indent(self) -> ContextManager[None]:
         class Indent:
-            def __init__(self, log):
+            def __init__(self, log: "LoggingInstance") -> None:
                 self.log = log
 
-            def __enter__(self):
+            def __enter__(self) -> None:
                 self.log.tabbing += 1
 
-            def __exit__(self, exc_type, exc_val, exc_tb):
+            def __exit__(
+                self,
+                exc_type: Optional[Type[BaseException]],
+                exc_val: Optional[BaseException],
+                exc_tb: Optional[TracebackType],
+            ) -> None:
                 self.log.tabbing -= 1
 
         return Indent(self)
 
     def use_markers(
-        self, parameter_text: [str, Callable[[], str]] = None, additional_stack: int = 0
-    ) -> ContextManager:
+        self,
+        parameter_text: Optional[Union[str, Callable[[], str]]] = None,
+        additional_stack: int = 0,
+    ) -> ContextManager[None]:
         class Nothing:
-            def __enter__(self):
+            def __enter__(self) -> None:
                 pass
 
-            def __exit__(self, exc_type, exc_val, exc_tb):
+            def __exit__(
+                self,
+                exc_type: Optional[type],
+                exc_val: Optional[BaseException],
+                exc_tb: Optional[TracebackType],
+            ) -> None:
                 pass
 
         if not self.toggles.markers:
             return Nothing()
 
         class Markers:
-            def __init__(self, log, method_name, filename, parameter_text):
+            def __init__(
+                self, log: "LoggingInstance", method_name: str, filename: str
+            ) -> None:
                 self.log = log
                 self.method_name = method_name
                 self.filename = filename
-                self.parameter_text = parameter_text
 
-            def __enter__(self):
+            def __enter__(self) -> None:
                 expected = f"-> in: {self.method_name}({self.get_parameters(False)}) in {self.filename}"
                 self.log.log_line(expected)
                 self.log.tabbing = self.log.tabbing + 1
 
-            def __exit__(self, exc_type, exc_val, exc_tb):
+            def __exit__(
+                self,
+                exc_type: Optional[type],
+                exc_val: Optional[BaseException],
+                exc_tb: Optional[TracebackType],
+            ) -> None:
                 self.log.tabbing = self.log.tabbing - 1
                 expected = f"<- out: {self.method_name}({self.get_parameters(True)})"
                 self.log.log_line(expected)
 
-            def get_parameters(self, is_exit: bool):
-                if isinstance(self.parameter_text, Callable):
+            def get_parameters(self, is_exit: bool) -> str:
+                if callable(parameter_text):
                     return parameter_text()
-                elif self.parameter_text is None or is_exit:
+                elif parameter_text is None or is_exit:
                     return ""
                 else:
                     return str(parameter_text)
@@ -101,9 +119,9 @@ class LoggingInstance:
         method_name = stack.function
 
         filename = get_class_name_for_frame(stack)
-        return Markers(self, method_name, filename, parameter_text)
+        return Markers(self, method_name, filename)
 
-    def log_line(self, text: str, use_timestamps=True) -> None:
+    def log_line(self, text: str, use_timestamps: bool = True) -> None:
         if self.counter != 0:
             self.logger("\n")
             self.counter = 0
@@ -152,7 +170,7 @@ class LoggingInstance:
         if not self.toggles.variables:
             return
 
-        def to_type(value: Any, spacing=" ") -> str:
+        def to_type(value: Any, spacing: str = " ") -> str:
             return f"{spacing}{print_type(value)}" if show_types else ""
 
         if _is_iterable(value):
@@ -176,12 +194,16 @@ class LoggingInstance:
             return
         self.log_line(f"Sql: {query_text}")
 
-    def message(self, message):
+    def message(self, message: str) -> None:
         if not self.toggles.messages:
             return
         self.log_line(f"message: {message}")
 
-    def warning(self, text: str = "", exception: BaseException = None) -> None:
+    def warning(
+        self,
+        text: Union[str, BaseException] = "",
+        exception: Optional[BaseException] = None,
+    ) -> None:
         if isinstance(text, Exception):
             temp = ""
             if exception:
@@ -206,23 +228,23 @@ class LoggingInstance:
             self.log_line(stack_trace, use_timestamps=False)
         self.log_line(warning_stars, use_timestamps=False)
 
-    def show_queries(self, show):
+    def show_queries(self, show: bool) -> None:
         self.toggles.queries = show
 
     def show_all(self, show: bool) -> None:
         self.toggles = Toggles(show)
 
-    def show_messages(self, show):
+    def show_messages(self, show: bool) -> None:
         self.toggles.messages = show
 
-    def show_variables(self, show):
+    def show_variables(self, show: bool) -> None:
         self.toggles.variables = show
 
-    def show_hour_glass(self, show):
+    def show_hour_glass(self, show: bool) -> None:
         self.toggles.hour_glass = show
 
-    def show_markers(self, show):
+    def show_markers(self, show: bool) -> None:
         self.toggles.markers = show
 
-    def show_events(self, show):
+    def show_events(self, show: bool) -> None:
         self.toggles.events = show

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/logger/simple_logger.py

@@ -1,20 +1,20 @@
 import threading
-from typing import Iterator, Any, Callable
+from typing import Any, Callable, ContextManager, Iterator, Optional, Union
 
 from approval_utilities.utilities.logger.logging_instance import LoggingInstance
 from approval_utilities.utilities.string_wrapper import StringWrapper
-from approval_utilities.utilities.wrapper import SingleWrapper, ThreadedWrapper
+from approval_utilities.utilities.wrapper import SingleWrapper, ThreadedWrapper, Wrapper
 
 
 class SimpleLogger:
-    _wrapper = SingleWrapper(LoggingInstance())
+    _wrapper: Wrapper[LoggingInstance] = SingleWrapper(LoggingInstance())
 
     @staticmethod
     def register_logger(log_method: Callable[[str], None]) -> None:
         SimpleLogger._wrapper.get().logger = log_method
 
     @staticmethod
-    def log_to_string(log_separate_threads=True) -> StringWrapper:
+    def log_to_string(log_separate_threads: bool = True) -> StringWrapper:
         with threading.Lock():
             if log_separate_threads and not isinstance(
                 SimpleLogger._wrapper, ThreadedWrapper
@@ -23,7 +23,9 @@ class SimpleLogger:
         return SimpleLogger._wrapper.get().log_to_string()
 
     @staticmethod
-    def use_markers(parameter_text: [str, Callable[[], str]] = None) -> Iterator[None]:
+    def use_markers(
+        parameter_text: Optional[Union[str, Callable[[], str]]] = None,
+    ) -> ContextManager[None]:
         return SimpleLogger._wrapper.get().use_markers(
             parameter_text, additional_stack=1
         )
@@ -53,33 +55,35 @@ class SimpleLogger:
         SimpleLogger._wrapper.get().message(message)
 
     @staticmethod
-    def warning(text: str = "", exception: BaseException = None) -> None:
+    def warning(
+        text: Union[str, BaseException] = "", exception: Optional[BaseException] = None
+    ) -> None:
         SimpleLogger._wrapper.get().warning(text, exception)
 
     @staticmethod
-    def show_queries(show: bool):
+    def show_queries(show: bool) -> None:
         SimpleLogger._wrapper.get().show_queries(show)
 
     @staticmethod
-    def show_all(show: bool):
+    def show_all(show: bool) -> None:
         SimpleLogger._wrapper.get().show_all(show)
 
     @staticmethod
-    def show_messages(show: bool):
+    def show_messages(show: bool) -> None:
         SimpleLogger._wrapper.get().show_messages(show)
 
     @staticmethod
-    def show_variables(show: bool):
+    def show_variables(show: bool) -> None:
         SimpleLogger._wrapper.get().show_variables(show)
 
     @staticmethod
-    def show_hour_glass(show: bool):
+    def show_hour_glass(show: bool) -> None:
         SimpleLogger._wrapper.get().show_hour_glass(show)
 
     @staticmethod
-    def show_markers(show: bool):
+    def show_markers(show: bool) -> None:
         SimpleLogger._wrapper.get().show_markers(show)
 
     @staticmethod
-    def show_events(show: bool):
+    def show_events(show: bool) -> None:
         SimpleLogger._wrapper.get().show_events(show)

approval_utilities-14.6.0/approval_utilities/utilities/map_reduce.py

@@ -0,0 +1,17 @@
+import itertools
+from typing import Any, Callable, Dict, Generator, Sequence
+
+
+def first(sequence: Sequence[Any], predicate: Callable[[Any], bool]) -> Any:
+    matching = filter(predicate, sequence)
+    return next(matching, None)
+
+
+def product_dict(**kwargs: Sequence[Any]) -> Generator[Dict[str, Any], None, None]:
+    """
+    Similar to `itertools.product`, but the resulting combinations retain the names.
+    """
+    keys = kwargs.keys()
+    vals = kwargs.values()
+    for instance in itertools.product(*vals):
+        yield dict(zip(keys, instance))

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/markdown_table.py

@@ -1,13 +1,19 @@
-from typing import Any, Callable, Iterable
+from typing import TYPE_CHECKING, Any, Callable, Iterable
+
+from typing_extensions import override
 
 from approval_utilities.approvaltests.core.verifiable import Verifiable
 from approval_utilities.approvaltests.core.verify_parameters import VerifyParameters
 
+if TYPE_CHECKING:
+    from approvaltests.core.options import Options
+
 
 class MarkdownTable(Verifiable):
-    def __init__(self):
-        self.markdown = ""
+    def __init__(self) -> None:
+        self.markdown: str = ""
 
+    @override
     def get_verify_parameters(self, options: "Options") -> VerifyParameters:
         return VerifyParameters(options.for_file.with_extension(".md"))
 
@@ -23,6 +29,7 @@ class MarkdownTable(Verifiable):
         self.markdown += MarkdownTable.print_row(*column_names)
         return self
 
+    @override
     def __str__(self) -> str:
         return self.markdown
 

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/multiline_string_utils.py

@@ -1,9 +1,10 @@
 import textwrap
+from typing import Optional
 
 from approval_utilities.utilities.logger.simple_logger import SimpleLogger
 
 
-def remove_indentation_from(text: str) -> str:
+def remove_indentation_from(text: Optional[str]) -> str:
     SimpleLogger.variable("text", text)
     if not text:
         return ""

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/persistence/loader.py

@@ -1,5 +1,5 @@
 from abc import abstractmethod
-from typing import TypeVar, Generic
+from typing import Generic, TypeVar
 
 T = TypeVar("T")
 

{approval_utilities-14.4.0 → approval_utilities-14.6.0}/approval_utilities/utilities/persistence/saver.py

@@ -1,5 +1,5 @@
 from abc import abstractmethod
-from typing import TypeVar, Generic
+from typing import Generic, TypeVar
 
 T = TypeVar("T")
 

approval_utilities-14.6.0/approval_utilities/utilities/string_wrapper.py

@@ -0,0 +1,17 @@
+from typing_extensions import override
+
+
+class StringWrapper:
+    def __init__(self) -> None:
+        self.string = ""
+
+    def append(self, text: str) -> None:
+        self.string += text
+
+    @override
+    def __str__(self) -> str:
+        return self.string
+
+    @override
+    def __repr__(self) -> str:
+        return self.string

approval_utilities-14.6.0/approval_utilities/utilities/time_utilities.py

@@ -0,0 +1,28 @@
+import os
+from types import TracebackType
+from typing import Optional, Type
+
+from typing_extensions import ContextManager
+
+
+def use_utc_timezone() -> ContextManager[None]:
+    class TimeZoneSwap:
+        def __init__(self) -> None:
+            self.timezone: Optional[str] = ""
+
+        def __enter__(self) -> None:
+            self.timezone = os.environ.get("TZ")
+            os.environ["TZ"] = "UTC"
+
+        def __exit__(
+            self,
+            exc_type: Optional[Type[BaseException]],
+            exc_val: Optional[BaseException],
+            exc_tb: Optional[TracebackType],
+        ) -> bool:
+            if self.timezone is None:
+                os.environ.pop("TZ")
+            else:
+                os.environ["TZ"] = self.timezone
+
+    return TimeZoneSwap()

approval_utilities-14.6.0/approval_utilities/utilities/wrapper.py

@@ -0,0 +1,34 @@
+import threading
+from abc import ABC, abstractmethod
+from typing import Callable, Generic, TypeVar, cast
+
+from typing_extensions import override
+
+_T = TypeVar("_T")
+
+
+class Wrapper(ABC, Generic[_T]):
+    @abstractmethod
+    def get(self) -> _T:
+        pass
+
+
+class SingleWrapper(Wrapper[_T]):
+    def __init__(self, instance: _T):
+        self.instance = instance
+
+    @override
+    def get(self) -> _T:
+        return self.instance
+
+
+class ThreadedWrapper(Wrapper[_T]):
+    def __init__(self, generator: Callable[[], _T]):
+        self.generator = generator
+        self.local = threading.local()
+
+    @override
+    def get(self) -> _T:
+        if not hasattr(self.local, "value"):
+            self.local.value = self.generator()
+        return cast(_T, self.local.value)