Source code for ppb_vector

import typing
from import Mapping, Sequence
from dataclasses import dataclass
from math import atan2, copysign, cos, degrees, hypot, isclose, radians, sin, sqrt

__all__ = ('Vector',)

#: ppb_vector's current version.
#: It follows the semantic versioning convention.
__version__ = "1.0"

# Anything convertable to a Vector, including lists, tuples, and dicts
VectorLike = typing.Union[
    'Vector',  # Or subclasses, unconnected to the Vector typevar above
    typing.Tuple[typing.SupportsFloat, typing.SupportsFloat],
    typing.Sequence[typing.SupportsFloat],  # TODO: Length 2
    typing.Mapping[str, typing.SupportsFloat],  # TODO: Length 2, keys 'x', 'y'

@dataclass(eq=False, frozen=True, init=False, repr=False)
class Vector:
    """The immutable, 2D vector class of the PursuedPyBear project.

    :py:class:`Vector` is an immutable 2D Vector, which can be instantiated as

    >>> from ppb_vector import Vector
    >>> Vector(3, 4)
    Vector(3.0, 4.0)

    :py:class:`Vector` implements many convenience features, as well as
    useful mathematical operations for 2D geometry and linear algebra.

    :py:class:`Vector` acts as an iterable and a sequence, allowing usage like
    converting, indexing, and unpacking:

    >>> v = Vector(-3, -5)
    >>> list(v)
    [-3.0, -5.0]
    >>> tuple(v)
    (-3.0, -5.0)

    >>> v[0]

    >>> x, y = Vector(1, 2)
    >>> x

    >>> print( *Vector(1, 2) )
    1.0 2.0

    It also acts mostly like a mapping, when it does not conflict with being a
    sequence. In particular, the coordinates may be accessed by subscripting:

    >>> v["y"]
    >>> v["x"]
    x: float
    y: float

    # Tell CPython that this isn't an extendable dict
    __slots__ = ('x', 'y', '__weakref__')

    def __new__(cls, x: typing.SupportsFloat, y: typing.SupportsFloat): pass

    def __new__(cls, other: VectorLike): pass

    def __new__(cls, *args, **kwargs):
        Make a vector from coordinates, or convert a vector-like.

        A vector-like can be:

        - a length-2 :py:class:`Sequence <>`, whose
          contents are interpreted as the ``x`` and ``y`` coordinates like ``(4, 2)``

        - a length-2 :py:class:`Mapping <>`, whose keys
          are ``x`` and ``y`` like ``{'x': 4, 'y': 2}``

        - any instance of :py:class:`Vector` or any subclass.
        if args and kwargs:
            raise TypeError("Got a mix of positional and keyword arguments")

        if not args and not kwargs or len(args) > 2:
            raise TypeError("Expected 1 vector-like or 2 float-like arguments, "
                            f"got {len(args) + len(kwargs)}")

        if kwargs and frozenset(kwargs) != {'x', 'y'}:
            raise TypeError(f"Expected keyword arguments x and y, got: {kwargs.keys().join(', ')}")

        if kwargs:
            x, y = kwargs['x'], kwargs['y']
        elif len(args) == 1:
            value = args[0]
            if isinstance(value, cls):
                # Short circuit if already a valid instance
                return value

            x, y = Vector._unpack(value)
        elif len(args) == 2:
            x, y = args

        self = super().__new__(cls)

            # The @dataclass decorator made the class frozen, so we need to
            #  bypass the class' default assignment function :
            object.__setattr__(self, 'x', float(x))
        except ValueError:
            raise TypeError(f"{type(x).__name__} object not convertable to float")

            object.__setattr__(self, 'y', float(y))
        except ValueError:
            raise TypeError(f"{type(y).__name__} object not convertable to float")

        return self

    def __reduce__(self):
        return Vector, (self.x, self.y)

    def update(self,
               x: typing.Optional[typing.SupportsFloat] = None,
               y: typing.Optional[typing.SupportsFloat] = None):
        """Return a new :py:class:`Vector` replacing specified fields with new values."""
        if x is None and y is None:
            return self

        return Vector(self.x if x is None else x,
                      self.y if y is None else y)

    def _unpack(value: VectorLike) -> typing.Tuple[float, float]:
        if isinstance(value, Vector):
            return value.x, value.y
        elif isinstance(value, Sequence) and len(value) == 2:
            return float(value[0]), float(value[1])
        elif isinstance(value, Mapping) and 'x' in value and 'y' in value and len(value) == 2:
            return float(value['x']), float(value['y'])
            raise ValueError(f"Cannot use {value} as a vector-like")

    def __bool__(self) -> bool:
        """Check whether the vector is non-zero.

        >>> assert Vector(1, 1)
        >>> assert not Vector(0, 0)
        return self != (0, 0)

    def length(self) -> float:
        """Compute the length of a vector.

        >>> Vector(45, 60).length
        # Surprisingly, caching this value provides no descernable performance
        # benefit, according to microbenchmarks.
        return hypot(self.x, self.y)

    def asdict(self) -> typing.Mapping[str, float]:
        """Convert a vector to a vector-like dictionary.

        >>> v = Vector(42, 69)
        >>> v.asdict()
        {'x': 42.0, 'y': 69.0}

        The conversion can be reversed by constructing:

        >>> assert v == Vector(v.asdict())
        return {'x': self.x, 'y': self.y}

    def __len__(self) -> int:
        return 2

    def __add__(self, other: VectorLike) -> 'Vector':
        """Add two vectors.

        :param other: A :py:class:`Vector` or a vector-like.
          For a description of vector-likes, see :py:func:`__new__`.

        >>> Vector(1, 0) + (0, 1)
        Vector(1.0, 1.0)
        >>> (0, 1) + Vector(1, 0)
        Vector(1.0, 1.0)
            other_x, other_y = Vector._unpack(other)
        except ValueError:
            return NotImplemented

        return Vector(self.x + other_x, self.y + other_y)

    def __radd__(self, other: VectorLike) -> 'Vector':
        return self + other

    def __sub__(self, other: VectorLike) -> 'Vector':
        """Subtract one vector from another.

        :param other: A :py:class:`Vector` or a vector-like.
          For a description of vector-likes, see :py:func:`__new__`.

        >>> Vector(3, 3) - (1, 1)
        Vector(2.0, 2.0)
            other_x, other_y = Vector._unpack(other)
        except ValueError:
            return NotImplemented

        return Vector(self.x - other_x, self.y - other_y)

    def dot(self, other: VectorLike) -> float:
        """Compute the dot product of two vectors.

        :param other: A :py:class:`Vector` or a vector-like.
          For a description of vector-likes, see :py:func:`__new__`.

        >>> Vector(1, 1).dot((-1, -1))

        This can also be expressed with :py:meth:`* <__mul__>`:

        >>> assert Vector(1, 2).dot([2, 1]) == Vector(1, 2) * [2, 1]
        other_x, other_y = Vector._unpack(other)
        return self.x * other_x + self.y * other_y

    def scale_by(self, scalar: typing.SupportsFloat) -> 'Vector':
        """Compute a vector-scalar multiplication.

        >>> Vector(1, 2).scale_by(3)
        Vector(3.0, 6.0)

        Can also be expressed with :py:meth:`* <__mul__>`:

        >>> assert Vector(1, 2).scale_by(3) == 3 * Vector(1, 2)
        scalar = float(scalar)
        return Vector(scalar * self.x, scalar * self.y)

    def __mul__(self, other: VectorLike) -> float: pass

    def __mul__(self, other: typing.SupportsFloat) -> 'Vector': pass

    def __mul__(self, other):
        """Perform a dot product or a scalar product, based on the parameter type.

        :param other: If ``other`` is a scalar (an instance of
          :py:class:`typing.SupportsFloat`), return
          :py:meth:`self.scale_by(other) <scale_by>`.

           >>> v = Vector(1, 1)
           >>> 3 * v
           Vector(3.0, 3.0)

           >>> assert 3 * v == v * 3 == v.scale_by(3)

          A :py:class:`Vector` can also be divided by a scalar,
            using the :py:meth:`/ <__truediv__>` operator:

           >>> assert 3 * v / 3 == v

        :param other: If ``other`` is a vector-like, return
          :py:meth:` <dot>`.

          >>> v * (-1, -1)

          >>> assert v * (-1, -1) == (-1, -1) * v ==, -1))

          Vector-likes are defined in :py:meth:`convert`.
        if isinstance(other, (float, int)):
            return self.scale_by(other)

        except (TypeError, ValueError):
            return NotImplemented

    def __rmul__(self, other: VectorLike) -> float: pass

    def __rmul__(self, other: typing.SupportsFloat) -> 'Vector': pass

    def __rmul__(self, other):
        return self.__mul__(other)

    def __truediv__(self, other: typing.SupportsFloat) -> 'Vector':
        """Perform a division between a vector and a scalar.

        >>> Vector(3, 3) / 3
        Vector(1.0, 1.0)
        other = float(other)
        return Vector(self.x / other, self.y / other)

    def __getitem__(self, item: typing.Union[str, int]) -> float:
        if hasattr(item, '__index__'):
            item = item.__index__()  # type: ignore
        if isinstance(item, str):
            if item == 'x':
                return self.x
            elif item == 'y':
                return self.y
                raise KeyError
        elif isinstance(item, int):
            if item == 0:
                return self.x
            elif item == 1:
                return self.y
                raise IndexError
            raise TypeError

    def __repr__(self) -> str:
        return f"Vector({self.x}, {self.y})"

    def __eq__(self, other: typing.Any) -> bool:
        """Test wheter two vectors are equal.

        :param other: A :py:class:`Vector` or a vector-like.
          For a description of vector-likes, see :py:func:`__new__`.

        >>> Vector(1, 0) == (0, 1)
            other_x, other_y = Vector._unpack(other)
        except (TypeError, ValueError):
            return NotImplemented
            return self.x == other_x and self.y == other_y

    def __iter__(self) -> typing.Iterator[float]:
        yield self.x
        yield self.y

    def __neg__(self) -> 'Vector':
        """Negate a vector.

        Negating a :py:class:`Vector` produces one with identical length and opposite
        direction. It is equivalent to multiplying it by -1.

        >>> -Vector(1, 1)
        Vector(-1.0, -1.0)
        return self.scale_by(-1)

    def angle(self, other: VectorLike) -> float:
        """Compute the angle between two vectors.

        :param other: A :py:class:`Vector` or a vector-like.
          For a description of vector-likes, see :py:func:`__new__`.

        >>> Vector(1, 0).angle( (0, 1) )

        As with :py:meth:`rotate`, angles are expressed in degrees, signed, and
        refer to a direct coordinate system (i.e. positive rotations are

        :py:meth:`angle` is guaranteed to produce an angle between -180° and 180°.
        other_x, other_y = Vector._unpack(other)

        rv = degrees(atan2(other_x, -other_y) - atan2(self.x, -self.y))
        # This normalizes the value to (-180, +180], which is the opposite of
        # what Python usually does but is normal for angles
        if rv <= -180:
            rv += 360
        elif rv > 180:
            rv -= 360

        return rv

    def isclose(self, other: VectorLike, *,
                abs_tol: typing.SupportsFloat = 1e-09, rel_tol: typing.SupportsFloat = 1e-09,
                rel_to: typing.Sequence[VectorLike] = ()) -> bool:
        """Perform an approximate comparison of two vectors.

        :param other: A :py:class:`Vector` or a vector-like.
          For a description of vector-likes, see :py:func:`__new__`.

        >>> assert Vector(1, 0).isclose((1, 1e-10))

        :py:meth:`isclose` takes optional, keyword arguments, akin to those of

        :param abs_tol: the absolute tolerance is the minimum magnitude (of the
            difference vector) under which two inputs are considered close,
            without consideration for (the magnitude of) the input values.

        :param rel_tol: the relative tolerance: if the length of the difference
            vector is less than ``rel_tol * input.length`` for any ``input``, the
            two vectors are considered close.

        :param rel_to: an iterable of additional vector-likes which are
            considered to be inputs, for the purpose of the relative tolerance.
        abs_tol, rel_tol = float(abs_tol), float(rel_tol)
        if abs_tol < 0 or rel_tol < 0:
            raise ValueError("Vector.isclose takes non-negative tolerances")

        other = Vector(other)

        rel_length = max(
            *map(lambda v: Vector(v).length, rel_to),

        diff = (self - other).length
        return (diff <= rel_tol * rel_length or diff <= float(abs_tol))

    def _trig(angle: typing.SupportsFloat) -> typing.Tuple[float, float]:
        r = radians(angle)
        r_cos, r_sin = cos(r), sin(r)

        if abs(r_cos) > abs(r_sin):
            # From the equation sin(r)² + cos(r)² = 1, we get
            #  sin(r) = ±√(1 - cos(r)²), so we can fix r_sin to that value
            #  preserving its original sign.
            # This way, r_sin² + r_cos² is closer to 1, meaning that the length
            #  of rotated vectors is better preserved
            r_sin = copysign(sqrt(1 - r_cos * r_cos), r_sin)
            # Same for r_cos
            r_cos = copysign(sqrt(1 - r_sin * r_sin), r_cos)

        return r_cos, r_sin

    def rotate(self, angle: typing.SupportsFloat) -> 'Vector':
        """Rotate a vector.

        Rotate a vector in relation to the origin and return a new :py:class:`Vector`.

        >>> Vector(1, 0).rotate(90)
        Vector(0.0, 1.0)

        Positive rotation is counter/anti-clockwise.
        r_cos, r_sin = Vector._trig(angle)

        x = self.x * r_cos - self.y * r_sin
        y = self.x * r_sin + self.y * r_cos
        return Vector(x, y)

    def normalize(self) -> 'Vector':
        """Return a vector with the same direction and unit length.

        >>> Vector(3, 4).normalize()
        Vector(0.6, 0.8)

        Note that :py:meth:`normalize()` is equivalent to :py:meth:`scale(1) <scale>`:

        >>> assert Vector(7, 24).normalize() == Vector(7, 24).scale_to(1)
        return self.scale(1)

    def truncate(self, max_length: typing.SupportsFloat) -> 'Vector':
        """Scale a given :py:class:`Vector` down to a given length, if it is larger.

        >>> Vector(7, 24).truncate(3)
        Vector(0.84, 2.88)

        It produces a vector with the same direction, but possibly a different

        Note that :py:meth:`vector.scale(max_length) <scale>` is equivalent to
        :py:meth:`vector.truncate(max_length) <truncate>` when
        :py:meth:`max_length ≨ vector.length <length>`.

        >>> Vector(3, 4).scale(4)
        Vector(2.4, 3.2)
        >>> Vector(3, 4).truncate(4)
        Vector(2.4, 3.2)

        >>> Vector(3, 4).scale(6)
        Vector(3.6, 4.8)
        >>> Vector(3, 4).truncate(6)
        Vector(3.0, 4.0)

        Note: :py:meth:`x.truncate(max_length) <truncate>` may sometimes be
        slightly-larger than ``max_length``, due to floating-point rounding
        max_length = float(max_length)
        if self.length <= max_length:
            return self

        return self.scale_to(max_length)

    def scale_to(self, length: typing.SupportsFloat) -> 'Vector':
        """Scale a given :py:class:`Vector` to a certain length.

        >>> Vector(7, 24).scale_to(2)
        Vector(0.56, 1.92)
        length = float(length)
        if length < 0:
            raise ValueError("Vector.scale_to takes non-negative lengths.")

        if length == 0:
            return Vector(0, 0)

        return (length * self) / self.length

    scale = scale_to

    def reflect(self, surface_normal: VectorLike) -> 'Vector':
        """Reflect a vector against a surface.

        :param other: A :py:class:`Vector` or a vector-like.
          For a description of vector-likes, see :py:func:`__new__`.

        Compute the reflection of a :py:class:`Vector` on a surface going
        through the origin, described by its normal vector.

        >>> Vector(5, 3).reflect( (-1, 0) )
        Vector(-5.0, 3.0)

        >>> Vector(5, 3).reflect( Vector(-1, -2).normalize() )
        Vector(0.5999999999999996, -5.800000000000001)
        surface_normal = Vector(surface_normal)
        if not isclose(surface_normal.length, 1):
            raise ValueError("Reflection requires a normalized vector.")

        return self - (2 * (self * surface_normal) * surface_normal)