numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/array_reflected_arithmetic.py

@@ -0,0 +1,334 @@
+"""
+Arithmetic operators of an Array, with a single value on the left.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+import numpy
+
+from numdaplot.arrays.array_arithmetic import (
+	ADDITION_SYMBOL,
+	DIVISION_SYMBOL,
+	FLOOR_DIVISION_SYMBOL,
+	MULTIPLICATION_SYMBOL,
+	POWER_SYMBOL,
+	REMAINDER_SYMBOL,
+	SUBTRACTION_SYMBOL,
+)
+from numdaplot.arrays.array_data import ArrayData
+from numdaplot.rules.rule_values import ScalarValue
+from numdaplot.settings.argument_types import checked_arguments
+
+
+class ArrayReflectedArithmetic(ArrayData):
+	"""
+	Arithmetic operators of an Array with a single value on the left, such as ``100 - array``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def __radd__(self, other: ScalarValue) -> Self:
+		"""
+		Return the sum of a single value and each value, written ``value + array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``ScalarValue``, such as ``10`` or ``2.5``, on the left of the operator.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+		TimeOverflowError
+			When a date or a datetime leaves 1677 to 2262, a duration exceeds about 292 years, or a time of day moves
+			past midnight.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> 5 + prices
+		Array([15, 25], dtype=INT64)
+		"""
+		combined_array = self._combine_reflected(other, numpy.add, ADDITION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __rsub__(self, other: ScalarValue) -> Self:
+		"""
+		Return the difference of a single value and each value, written ``value - array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``ScalarValue``, such as ``10`` or ``2.5``, on the left of the operator.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+		TimeOverflowError
+			When a date or a datetime leaves 1677 to 2262, a duration exceeds about 292 years, or a time of day moves
+			past midnight.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> 100 - prices
+		Array([90, 80], dtype=INT64)
+		"""
+		combined_array = self._combine_reflected(other, numpy.subtract, SUBTRACTION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __rmul__(self, other: ScalarValue) -> Self:
+		"""
+		Return the product of a single value and each value, written ``value * array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``ScalarValue``, such as ``10`` or ``2.5``, on the left of the operator.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+		TimeOverflowError
+			When a date or a datetime leaves 1677 to 2262, or a duration exceeds about 292 years.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> 2 * prices
+		Array([20, 40], dtype=INT64)
+		"""
+		combined_array = self._combine_reflected(other, numpy.multiply, MULTIPLICATION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __rtruediv__(self, other: ScalarValue) -> Self:
+		"""
+		Return the quotient of a single value and each value, written ``value / array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``ScalarValue``, such as ``10`` or ``2.5``, on the left of the operator.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> 100 / prices
+		Array([10.,  5.], dtype=FLOAT64)
+		"""
+		combined_array = self._combine_reflected(other, numpy.true_divide, DIVISION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __rfloordiv__(self, other: ScalarValue) -> Self:
+		"""
+		Return the whole quotient of a single value and each value, written ``value // array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``ScalarValue``, such as ``10`` or ``2.5``, on the left of the operator.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		OutOfDomainError
+			When integers are divided by 0: convert them to ``FLOAT64`` first.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> 100 // prices
+		Array([10,  5], dtype=INT64)
+		"""
+		combined_array = self._combine_reflected(other, numpy.floor_divide, FLOOR_DIVISION_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __rmod__(self, other: ScalarValue) -> Self:
+		"""
+		Return the remainder of a single value and each value, written ``value % array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``ScalarValue``, such as ``10`` or ``2.5``, on the left of the operator.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		OutOfDomainError
+			When integers are divided by 0: convert them to ``FLOAT64`` first.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> 25 % prices
+		Array([5, 5], dtype=INT64)
+		"""
+		combined_array = self._combine_reflected(other, numpy.remainder, REMAINDER_SYMBOL)
+
+		return combined_array
+
+	@checked_arguments
+	def __rpow__(self, other: ScalarValue) -> Self:
+		"""
+		Return the power of a single value and each value, written ``value ** array``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			A ``ScalarValue``, such as ``10`` or ``2.5``, on the left of the operator.
+
+		Returns
+		-------
+		Self
+			A new Array.
+
+		Warns
+		-----
+		CalculationWarning
+			When values of decimals become NaN or an infinite value.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the operation does not apply to the types, such as a number and a text.
+		OutOfDomainError
+			When integers are raised to a negative power: convert them to ``FLOAT64`` first.
+		IntegerOverflowError
+			When a result does not fit its integer type, which refuses to wrap around to a wrong number.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([10, 20])
+		>>> 2 ** prices
+		Array([   1024, 1048576], dtype=INT64)
+		"""
+		combined_array = self._combine_reflected(other, numpy.power, POWER_SYMBOL)
+
+		return combined_array

numdaplot/arrays/array_refusals.py

@@ -0,0 +1,339 @@
+"""
+Python operations refused by an Array, each pointing to the numdaplot way of doing it.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Iterator
+from typing import NoReturn
+
+from numdaplot.arrays.array_data import ArrayData
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.rules.greater import Greater
+from numdaplot.rules.greater_or_equal import GreaterOrEqual
+from numdaplot.rules.less import Less
+from numdaplot.rules.less_or_equal import LessOrEqual
+
+COMPARISON_OPERATION = "Comparing an Array with {symbol}"
+EQUALITY_ALTERNATIVE = "is_equal with ndp.Equality, or check with ndp.Equal for each value"
+ORDER_ALTERNATIVE = "select or check with a rule such as ndp.{rule_name}"
+BRACKETS_OPERATION = "Brackets on an Array"
+BRACKETS_ALTERNATIVE = "take, replace, select or check"
+ITERATION_OPERATION = "Iterating over an Array with for"
+ITERATION_ALTERNATIVE = "for value in array.to_list()"
+MEMBERSHIP_OPERATION = "Testing membership in an Array with in"
+MEMBERSHIP_ALTERNATIVE = "check with ndp.Equal or ndp.IsIn"
+LENGTH_OPERATION = "len of an Array"
+LENGTH_ALTERNATIVE = "the shape attribute"
+TRUTH_OPERATION = "Testing an Array as a boolean"
+TRUTH_ALTERNATIVE = "compute with ndp.Count, or is_equal"
+MATRIX_PRODUCT_OPERATION = "The matrix product @ of an Array"
+MATRIX_PRODUCT_ALTERNATIVE = "to_numpy and numpy"
+EQUAL_SYMBOL = "=="
+NOT_EQUAL_SYMBOL = "!="
+LESS_SYMBOL = "<"
+LESS_OR_EQUAL_SYMBOL = "<="
+GREATER_SYMBOL = ">"
+GREATER_OR_EQUAL_SYMBOL = ">="
+
+
+class ArrayRefusals(ArrayData):
+	"""
+	Python operations refused by an Array, each raising ``RefusedOperationError`` with the numdaplot way of doing it.
+
+	``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``, brackets, ``for``, ``in``, ``len``, ``bool`` and ``@`` are refused.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	def __eq__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``array == other``; use ``is_equal`` or ``check(ndp.Equal(...))``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		refuse_comparison(EQUAL_SYMBOL, EQUALITY_ALTERNATIVE)
+
+	def __ne__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``array != other``; use ``is_equal`` or ``check(ndp.NotEqual(...))``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		refuse_comparison(NOT_EQUAL_SYMBOL, EQUALITY_ALTERNATIVE)
+
+	def __lt__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``array < other``; use ``select`` or ``check`` with ``ndp.Less``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> try:
+		... 	ndp.Array.from_list([1, 2]) < 2
+		... except ndp.RefusedOperationError as error:
+		... 	print(error)
+		Comparing an Array with < is not available, use select or check with a rule such as ndp.Less instead.
+		"""
+		alternative = ORDER_ALTERNATIVE.format(rule_name=Less.__name__)
+		refuse_comparison(LESS_SYMBOL, alternative)
+
+	def __le__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``array <= other``; use ``select`` or ``check`` with ``ndp.LessOrEqual``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		alternative = ORDER_ALTERNATIVE.format(rule_name=LessOrEqual.__name__)
+		refuse_comparison(LESS_OR_EQUAL_SYMBOL, alternative)
+
+	def __gt__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``array > other``; use ``select`` or ``check`` with ``ndp.Greater``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		alternative = ORDER_ALTERNATIVE.format(rule_name=Greater.__name__)
+		refuse_comparison(GREATER_SYMBOL, alternative)
+
+	def __ge__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``array >= other``; use ``select`` or ``check`` with ``ndp.GreaterOrEqual``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		alternative = ORDER_ALTERNATIVE.format(rule_name=GreaterOrEqual.__name__)
+		refuse_comparison(GREATER_OR_EQUAL_SYMBOL, alternative)
+
+	def __getitem__(self, key: object) -> NoReturn:
+		"""
+		Refuse ``array[...]``; use ``take``, ``select`` or ``check``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		key
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(BRACKETS_OPERATION, BRACKETS_ALTERNATIVE)
+
+	def __setitem__(self, key: object, value: object) -> NoReturn:
+		"""
+		Refuse ``array[...] = value``; use ``replace``, which returns a new Array.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		key
+			Any value.
+		value
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(BRACKETS_OPERATION, BRACKETS_ALTERNATIVE)
+
+	def __iter__(self) -> Iterator[object]:
+		"""
+		Refuse ``for value in array``; iterate over ``array.to_list()`` instead.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> for price in ndp.Array.from_list([10, 20]).to_list():
+		... 	print(price)
+		10
+		20
+		"""
+		raise RefusedOperationError(ITERATION_OPERATION, ITERATION_ALTERNATIVE)
+
+	def __contains__(self, value: object) -> NoReturn:
+		"""
+		Refuse ``value in array``; use ``check`` with ``ndp.Equal`` or ``ndp.IsIn``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		value
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(MEMBERSHIP_OPERATION, MEMBERSHIP_ALTERNATIVE)
+
+	def __len__(self) -> NoReturn:
+		"""
+		Refuse ``len(array)``; read the ``shape`` attribute instead.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(LENGTH_OPERATION, LENGTH_ALTERNATIVE)
+
+	def __bool__(self) -> NoReturn:
+		"""
+		Refuse ``if array:`` and ``bool(array)``, whose meaning would be unclear.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(TRUTH_OPERATION, TRUTH_ALTERNATIVE)
+
+	def __matmul__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``array @ other``; numdaplot has no linear algebra.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(MATRIX_PRODUCT_OPERATION, MATRIX_PRODUCT_ALTERNATIVE)
+
+	def __rmatmul__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``other @ array``; numdaplot has no linear algebra.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(MATRIX_PRODUCT_OPERATION, MATRIX_PRODUCT_ALTERNATIVE)
+
+
+def refuse_comparison(symbol: str, alternative: str) -> NoReturn:
+	"""
+	Raise the error refusing a comparison operator.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	symbol
+		The comparison operator, such as ``"<"``.
+	alternative
+		What to use instead.
+
+	Raises
+	------
+	RefusedOperationError
+		Always.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.array_refusals import refuse_comparison
+	>>> try:
+	... 	refuse_comparison("<", "select")
+	... except ndp.RefusedOperationError as error:
+	... 	print(error)
+	Comparing an Array with < is not available, use select instead.
+	"""
+	operation = COMPARISON_OPERATION.format(symbol=symbol)
+	raise RefusedOperationError(operation, alternative)