joythief 0.1.0__tar.gz

joythief-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2025-present, Jonathan Sharpe
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+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.

joythief-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.3
+Name: joythief
+Version: 0.1.0
+Summary: Comparison is the thief of joy
+License: ISC
+Author: Jonathan Sharpe
+Author-email: mail@jonrshar.pe
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Description-Content-Type: text/markdown
+
+# JoyThief
+
+Comparison is the thief of joy.
+
+## Usage
+
+JoyThief provides a collection of matchers which can be used for testing.
+
+```python
+from joythief.numbers import NaN
+
+
+def test_my_func_with_no_arguments_returns_nan():
+    assert my_func() == NaN()
+```
+

joythief-0.1.0/README.md

@@ -0,0 +1,15 @@
+# JoyThief
+
+Comparison is the thief of joy.
+
+## Usage
+
+JoyThief provides a collection of matchers which can be used for testing.
+
+```python
+from joythief.numbers import NaN
+
+
+def test_my_func_with_no_arguments_returns_nan():
+    assert my_func() == NaN()
+```

joythief-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "joythief"
+# Version is set on publication
+version = "0.1.0"
+description = "Comparison is the thief of joy"
+authors = [
+    {name = "Jonathan Sharpe", email = "mail@jonrshar.pe"}
+]
+license = "ISC"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.coverage.run]
+omit = ["tests/**"]
+
+[tool.coverage.report]
+exclude_also = ["if tp\\.TYPE_CHECKING:"]
+
+[tool.isort]
+profile = "black"
+
+[tool.mypy]
+strict = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disable_error_code = [
+    "no-untyped-def"
+]
+
+[tool.poetry]
+packages = [{include = "joythief", from = "src"}]
+
+[tool.poetry.group.deployment]
+optional = true
+
+[tool.poetry.group.deployment.dependencies]
+twine = "^6.1.0"
+
+[tool.poetry.group.dev.dependencies]
+black = "^25.1.0"
+coverage = "^7.9.2"
+isort = "^6.0.1"
+mypy = "^1.16.1"
+pytest = "^8.4.1"
+tox = "^4.27.0"
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+myst-parser = {version = "^4.0.1", markers = "python_version>='3.11'"}
+sphinx = {version = "^8.2.3", markers = "python_version>='3.11'"}
+furo = {version = "^2024.8.6", markers = "python_version>='3.11'"}
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+envlist = py3{9,10,11,12,13}
+isolated_build = True
+
+[testenv]
+deps = pytest >=8.4.1, <9
+commands = pytest
+"""

joythief-0.1.0/src/joythief/core.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import typing as tp
+from abc import ABC, abstractmethod
+
+if tp.TYPE_CHECKING:
+    from typing_extensions import TypeAlias
+
+T = tp.TypeVar("T")
+
+
+class Matcher(tp.Generic[T], ABC):
+    """Defines the core requirements for any matcher.
+
+    - Must be comparable for equality with anything.
+    - Must have a sensible representation.
+
+    """
+
+    @abstractmethod
+    def __eq__(self, other: tp.Any) -> bool: ...
+
+    @abstractmethod
+    def __repr__(self) -> str: ...
+
+
+MaybeMatcher: TypeAlias = tp.Union[T, Matcher[T]]
+"""Either ``T`` or a matcher of ``T``."""

joythief-0.1.0/src/joythief/numbers.py

@@ -0,0 +1,35 @@
+"""Matchers for `numeric types`_ (e.g. :py:class:`float`).
+
+.. _numeric types: https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex
+
+"""
+
+import math
+import typing as tp
+from numbers import Real
+
+from joythief.core import Matcher
+
+
+class NaN(Matcher[Real]):
+    """Matches any :py:class:`float` instance representing NaN.
+
+    `IEEE 754`_ NaN (*"not a number"*) instances are, by definition, not
+    equal to each other. This matcher compares equal to e.g.
+    :py:data:`math.nan` or :code:`float("nan")` using
+    :py:func:`math.isnan`.
+
+    Originally formulated for `this answer`_.
+
+    .. _IEEE 754: https://en.wikipedia.org/wiki/IEEE_754
+    .. _this answer: https://stackoverflow.com/a/79699116/3001761
+
+    """
+
+    def __eq__(self, other: tp.Any) -> bool:
+        if not isinstance(other, Real):
+            return NotImplemented
+        return math.isnan(other)
+
+    def __repr__(self) -> str:
+        return "nan"

joythief-0.1.0/src/joythief/objects.py

@@ -0,0 +1,45 @@
+"""Matchers for general object types."""
+
+import typing as tp
+
+from joythief.core import Matcher
+
+T = tp.TypeVar("T")
+
+Type = tp.Union[type[T], tuple[type[T], ...]]
+
+
+class InstanceOf(Matcher[T]):
+    """Matches any instance of the specified type(s).
+
+    This matcher compares the received value using
+    :py:func:`isinstance`, so accepts either a single type or a tuple
+    of types. With :code:`nullable` set to :py:const:`True`, the
+    received value can also be :py:const:`None`.
+
+    Originally formulated for `this answer`_.
+
+    .. _this answer: https://stackoverflow.com/a/64973325/3001761
+
+    """
+
+    _nullable: bool
+    _type: Type[T]
+
+    def __init__(self, type_: Type[T], *, nullable: bool = False):
+        self._nullable = nullable
+        self._type = type_
+
+    def __eq__(self, other: tp.Any) -> bool:
+        type_: tuple[type[tp.Any], ...] = (
+            self._type if isinstance(self._type, tuple) else (self._type,)
+        )
+        if self._nullable:
+            type_ = type_ + (type(None),)
+        return isinstance(other, type_)
+
+    def __repr__(self) -> str:
+        return (
+            f"InstanceOf({self._type!r}"
+            f"{', nullable=True' if self._nullable else ''})"
+        )

joythief-0.1.0/src/joythief/strings.py

@@ -0,0 +1,142 @@
+"""Matchers for the `text sequence type`_ (:py:class:`str`).
+
+.. _text sequence type: https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str
+"""
+
+import json
+import re
+import typing as tp
+from collections.abc import Mapping, Sequence
+from urllib.parse import parse_qs, urlparse
+
+from joythief.core import Matcher, MaybeMatcher
+from joythief.objects import InstanceOf
+
+
+class JsonString(Matcher[str]):
+    """Matches any :py:class:`str` instance representing JSON.
+
+    :param expected: What the result of parsing the JSON should be.
+      If omitted, any valid JSON string is matched.
+
+    """
+
+    __ANYTHING = object()
+
+    _expected: tp.Any
+
+    def __init__(self, expected: tp.Any = __ANYTHING):
+        self._expected = InstanceOf(object) if expected == self.__ANYTHING else expected
+
+    def __eq__(self, other: tp.Any) -> bool:
+        if not isinstance(other, str):
+            return NotImplemented
+        try:
+            return tp.cast(bool, json.loads(other) == self._expected)
+        except json.decoder.JSONDecodeError:
+            return False
+
+    def __repr__(self) -> str:
+        return f"JsonString({self._expected!r})"
+
+
+class StringMatching(Matcher[str]):
+    """Matches any :py:class:`str` instance matching a regular expression.
+
+    :param pattern: Regex pattern to match, as a string or compiled pattern.
+
+    :param flags: Any `flags`_ to compile a :py:class:`str` pattern with
+
+    :raises ValueError: if flags are provided with a pre-compiled pattern.
+
+    .. _flags: https://docs.python.org/3/library/re.html#flags
+
+    """
+
+    _pattern: re.Pattern[str]
+
+    @tp.overload
+    def __init__(self, pattern: re.Pattern[str]): ...
+
+    @tp.overload
+    def __init__(self, pattern: str, *, flags: int = 0): ...
+
+    def __init__(
+        self,
+        pattern: tp.Union[str, re.Pattern[str]],
+        *,
+        flags: int = 0,
+    ):
+        self._pattern = re.compile(pattern, flags=flags)
+
+    def __eq__(self, other: tp.Any) -> bool:
+        if not isinstance(other, str):
+            return NotImplemented
+        return self._pattern.match(other) is not None
+
+    def __repr__(self) -> str:
+        return f"StringMatching({self._pattern!r})"
+
+
+class UrlString(Matcher[str]):
+    """Matches any :py:class:`str` instance representing a URL.
+
+    The string is parsed with :py:func:`~urllib.parse.urlparse` and
+    compared attribute-by-attribute.
+    Any attributes not provided are ignored.
+
+    :param scheme: the scheme (e.g. ``"https"``)
+    :param hostname: the hostname (e.g. ``"example.com"``)
+    :param path: the path (e.g. ``"/some/path"``)
+    :param query: the result of parsing the query string with
+      :py:func:`~urllib.parse.parse_qs`
+
+    :raises TypeError: if no arguments are provided.
+
+    """
+
+    _hostname: tp.Optional[MaybeMatcher[str]]
+    _path: tp.Optional[MaybeMatcher[str]]
+    _query: tp.Optional[Mapping[str, Sequence[str]]]
+    _scheme: tp.Optional[MaybeMatcher[str]]
+
+    def __init__(
+        self,
+        *,
+        scheme: tp.Optional[MaybeMatcher[str]] = None,
+        hostname: tp.Optional[MaybeMatcher[str]] = None,
+        path: tp.Optional[MaybeMatcher[str]] = None,
+        query: tp.Optional[Mapping[str, Sequence[str]]] = None,
+    ):
+        self._hostname = hostname
+        self._path = path
+        self._query = query
+        self._scheme = scheme
+        if all(
+            getattr(self, attr) is None
+            for attr in ["_hostname", "_path", "_query", "_scheme"]
+        ):
+            raise TypeError("A UrlString with no arguments matches any string")
+
+    def __eq__(self, other: tp.Any) -> bool:
+        if not isinstance(other, str):
+            return NotImplemented
+        parsed = urlparse(other)
+        for attribute in ["hostname", "path", "scheme"]:
+            if (expected := getattr(self, f"_{attribute}")) is not None and getattr(
+                parsed, attribute
+            ) != expected:
+                return False
+        if (expected := self._query) is not None and parse_qs(
+            parsed.query, keep_blank_values=True
+        ) != expected:
+            return False
+        return True
+
+    def __repr__(self) -> str:
+        parameters = [
+            f"{name}={value!r}"
+            for name in ["scheme", "hostname", "path", "query"]
+            if (value := getattr(self, f"_{name}")) is not None
+        ]
+        return f"UrlString({', '.join(parameters)})"