numdaplot 0.1.0__py3-none-any.whl

numdaplot/rules/is_present.py

@@ -0,0 +1,25 @@
+"""
+Rule keeping the values that are not missing.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.rules.rule import Rule
+
+
+@dataclass(frozen=True)
+class IsPresent(Rule):
+	"""
+	Keep the values that are not missing. It is the opposite of ``IsMissing``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> temperatures = ndp.Array.from_list([12.5, None, 18.0])
+	>>> temperatures.select(ndp.IsPresent())
+	Array([12.5, 18. ], dtype=FLOAT64)
+	"""

numdaplot/rules/less.py

@@ -0,0 +1,39 @@
+"""
+Rule keeping the values strictly less than a reference value.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.rules.rule_values import OrderedValue
+from numdaplot.rules.value_rule import ValueRule
+
+
+@dataclass(frozen=True)
+class Less(ValueRule[OrderedValue]):
+	"""
+	Keep the values strictly less than a reference value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The reference value, an ``OrderedValue`` such as ``10``, ``"M"`` or ``date(2026, 1, 31)``, which is not
+		kept itself.
+
+	Raises
+	------
+	InvalidTypeError
+		When ``value`` is not a single value, such as an Array or a list.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([80, 100, 120])
+	>>> prices.select(ndp.Less(100))
+	Array([80], dtype=INT64)
+	"""
+
+	value: OrderedValue

numdaplot/rules/less_or_equal.py

@@ -0,0 +1,38 @@
+"""
+Rule keeping the values less than or equal to a reference value.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.rules.rule_values import OrderedValue
+from numdaplot.rules.value_rule import ValueRule
+
+
+@dataclass(frozen=True)
+class LessOrEqual(ValueRule[OrderedValue]):
+	"""
+	Keep the values less than or equal to a reference value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The reference value, an ``OrderedValue`` such as ``10``, ``"M"`` or ``date(2026, 1, 31)``, which is kept itself.
+
+	Raises
+	------
+	InvalidTypeError
+		When ``value`` is not a single value, such as an Array or a list.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([80, 100, 120])
+	>>> prices.select(ndp.LessOrEqual(100))
+	Array([ 80, 100], dtype=INT64)
+	"""
+
+	value: OrderedValue

numdaplot/rules/not_equal.py

@@ -0,0 +1,45 @@
+"""
+Rule keeping the values different from a reference value.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+from numdaplot.rules.rule_values import ScalarValue
+from numdaplot.rules.value_rule import ValueRule
+
+
+@dataclass(frozen=True)
+class NotEqual(ValueRule[ScalarValue]):
+	"""
+	Keep the values different from a reference value.
+
+	Missing values are not kept: use ``IsMissing`` to test them.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The reference value, a ``ScalarValue`` such as ``"Paris"``, ``10`` or ``True``.
+
+	Raises
+	------
+	RefusedOperationError
+		When ``value`` is None: ``IsPresent`` tests the missing values.
+	InvalidTypeError
+		When ``value`` is not a single value, such as an Array or a list.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> countries = ndp.Array.from_list(["FR", "DE", "FR"])
+	>>> countries.select(ndp.NotEqual("FR"))
+	Array(['DE'], dtype=TEXT)
+	"""
+
+	MISSING_VALUE_RULE: ClassVar[str | None] = "IsPresent"
+
+	value: ScalarValue

numdaplot/rules/rule.py

@@ -0,0 +1,62 @@
+"""
+Base class of every rule.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+
+CONSTRUCTOR_OPERATION = "Creating a Rule with ndp.Rule()"
+CONSTRUCTOR_ALTERNATIVE = "a rule such as ndp.Greater"
+
+
+class Rule:
+	"""
+	Base class of every rule, a test applied to each value of an Array or of Table columns.
+
+	A rule is immutable and checks its settings when it is created.
+
+	Only its subclasses are created: calling ``ndp.Rule()`` raises ``RefusedOperationError``.
+
+	Every rule, passed to ``Array.select``, ``Array.check``, ``Table.check`` and ``Condition``:
+
+	|Rule|What it keeps|Example|
+	|---|---|---|
+	|``Equal``|The values equal to a reference value|``ndp.Equal("Paris")``|
+	|``NotEqual``|The values different from a reference value|``ndp.NotEqual("Paris")``|
+	|``Greater``|The values strictly greater than a reference value|``ndp.Greater(10)``|
+	|``GreaterOrEqual``|The values greater than or equal to a reference value|``ndp.GreaterOrEqual(10)``|
+	|``Less``|The values strictly less than a reference value|``ndp.Less(10)``|
+	|``LessOrEqual``|The values less than or equal to a reference value|``ndp.LessOrEqual(10)``|
+	|``Between``|The values inside an interval|``ndp.Between(10, 20)``|
+	|``IsIn``|The values that belong to a list of accepted values|``ndp.IsIn(["Paris", "Lyon"])``|
+	|``Contains``|The texts that contain a given text|``ndp.Contains("Pa")``|
+	|``IsMissing``|The missing values|``ndp.IsMissing()``|
+	|``IsPresent``|The values that are not missing|``ndp.IsPresent()``|
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([80, 120])
+	>>> for rule in [ndp.Greater(100), ndp.Less(100)]:
+	... 	print(prices.select(rule))
+	Array([120], dtype=INT64)
+	Array([80], dtype=INT64)
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Refuse the creation of the base class itself, and let a subclass be created.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			When the created object is a Rule and not one of its subclasses.
+		"""
+		created_class = type(self)
+		if created_class is Rule:
+			raise RefusedOperationError(CONSTRUCTOR_OPERATION, CONSTRUCTOR_ALTERNATIVE)

numdaplot/rules/rule_values.py

@@ -0,0 +1,44 @@
+"""
+Kinds of values that a rule compares against.
+
+.. versionadded:: 0.1.0
+"""
+
+from datetime import date, datetime, time, timedelta
+
+type ScalarValue = bool | int | float | str | date | datetime | timedelta | time
+"""
+A single value: a boolean, a number, a text, a date, a datetime, a duration or a time of day.
+
+It is a name used by the documentation and the annotations, not an object to create: pass the value itself,
+such as ``True``, ``10``, ``2.5``, ``"Paris"``, ``date(2026, 1, 31)``, ``datetime(2026, 1, 31, 14, 30)`` or
+``timedelta(days=1)`` or ``time(15, 35)``.
+
+.. versionadded:: 0.1.0
+
+Examples
+--------
+>>> import numdaplot as ndp
+>>> countries = ndp.Array.from_list(["FR", "DE", "FR"])
+>>> countries.check(ndp.Equal("FR"))
+Array([ True, False,  True], dtype=BOOL)
+"""
+
+type OrderedValue = int | float | str | date | datetime | timedelta | time
+"""
+A single value that can be ordered: a number, a text in alphabetical order, a date, a datetime, a duration or a
+time of day.
+
+It is a name used by the documentation and the annotations, not an object to create: pass the value itself,
+such as ``10``, ``2.5``, ``"Paris"``, ``date(2026, 1, 31)``, ``datetime(2026, 1, 31, 14, 30)`` or
+``timedelta(days=1)`` or ``time(15, 35)``.
+
+.. versionadded:: 0.1.0
+
+Examples
+--------
+>>> import numdaplot as ndp
+>>> prices = ndp.Array.from_list([80, 120])
+>>> prices.select(ndp.Greater(100))
+Array([120], dtype=INT64)
+"""

numdaplot/rules/value_rule.py

@@ -0,0 +1,110 @@
+"""
+Base class of the rules that compare each value to a single reference value.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from typing import ClassVar, cast
+
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.rules.rule import Rule
+from numdaplot.settings.field_types import require_field_types
+
+MISSING_VALUE_OPERATION = "{rule_name}(None)"
+
+
+@dataclass(frozen=True)
+class ValueRule[ReferenceValue](Rule):
+	"""
+	Base class of the rules that compare each value to a single reference value.
+
+	Two rules are equal only when they have the same class and the same reference value,
+	so ``Greater(1)`` and ``Less(1)`` are different.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The reference value each tested value is compared to.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	RefusedOperationError
+		When ``value`` is None for a rule with a rule of its own for missing values, such as ``Equal(None)``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> limit = ndp.Greater(100)
+	>>> limit.value
+	100
+	>>> ndp.Array.from_list([80, 120]).select(limit)
+	Array([120], dtype=INT64)
+	"""
+
+	# The rule testing missing values in place of this rule given None, such as IsMissing for Equal.
+	MISSING_VALUE_RULE: ClassVar[str | None] = None
+
+	value: ReferenceValue
+
+	def __post_init__(self) -> None:
+		"""
+		Check the reference value.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		RefusedOperationError
+			When ``value`` is None for a rule with a rule of its own for missing values, such as ``Equal(None)``.
+		"""
+		rule_class = type(self)
+		value = cast(object, self.value)
+		refuse_missing_value(rule_class.__name__, self.MISSING_VALUE_RULE, value)
+		require_field_types(self)
+
+
+def refuse_missing_value(rule_name: str, missing_value_rule: str | None, value: object) -> None:
+	"""
+	Refuse None as the reference value of a rule that has a rule of its own for missing values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	rule_name
+		The name of the rule, such as ``"Equal"``.
+	missing_value_rule
+		The rule testing missing values in its place, such as ``"IsMissing"``, or None when there is none.
+	value
+		The reference value.
+
+	Raises
+	------
+	RefusedOperationError
+		When the value is None and the rule has a rule of its own for missing values.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.rules.value_rule import refuse_missing_value
+	>>> try:
+	... 	refuse_missing_value("Equal", "IsMissing", None)
+	... except ndp.RefusedOperationError as error:
+	... 	print(error)
+	Equal(None) is not available, use IsMissing instead.
+	"""
+	if value is not None:
+		return
+
+	if missing_value_rule is None:
+		return
+
+	operation = MISSING_VALUE_OPERATION.format(rule_name=rule_name)
+	raise RefusedOperationError(operation, missing_value_rule)

numdaplot/settings/__init__.py

@@ -0,0 +1,5 @@
+"""
+Checks of the settings and of the arguments against their annotations.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/settings/argument_types.py

@@ -0,0 +1,327 @@
+"""
+Check of the arguments of the public methods and functions against their annotations.
+
+.. versionadded:: 0.1.0
+"""
+
+# typing.Self is a special form the type checker only knows inside annotations.
+# pyright: reportUnknownMemberType=false
+
+import functools
+import inspect
+import typing
+from collections.abc import Callable
+from typing import cast
+
+from numdaplot.errors.invalid_type_error import InvalidTypeError
+from numdaplot.settings.field_types import (
+	AcceptedKinds,
+	accepts_value,
+	describe_kinds,
+	find_rejected_value,
+	read_accepted_kinds,
+	read_annotations,
+)
+
+INSTANCE_PARAMETER = "self"
+CLASS_PARAMETER = "cls"
+CONSTRUCTOR_NAME = "__init__"
+TARGET_FORMAT = "{callable_name} {parameter_name}"
+METHOD_NAME_FORMAT = "{owner_name}.{method_name}"
+OPERATOR_NAME_FORMAT = "{owner_name} {symbol}"
+OPERATOR_SYMBOLS = {
+	"__add__": "+",
+	"__radd__": "+",
+	"__sub__": "-",
+	"__rsub__": "-",
+	"__mul__": "*",
+	"__rmul__": "*",
+	"__truediv__": "/",
+	"__rtruediv__": "/",
+	"__floordiv__": "//",
+	"__rfloordiv__": "//",
+	"__mod__": "%",
+	"__rmod__": "%",
+	"__pow__": "**",
+	"__rpow__": "**",
+	"__and__": "&",
+	"__rand__": "&",
+	"__or__": "|",
+	"__ror__": "|",
+}
+
+
+def checked_arguments[**Parameters, Result](function: Callable[Parameters, Result]) -> Callable[Parameters, Result]:
+	"""
+	Make a method or a function check its arguments against its annotations at each call.
+
+	The annotations are read once, at the first call. An argument left to its default is not checked.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	function
+		The method or the function.
+
+	Returns
+	-------
+	Callable
+		The same function, with the same signature, refusing an argument of the wrong type.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Array.from_list([1, 2]).sort(5)
+	... except ndp.InvalidTypeError as error:
+	... 	print(error)
+	Array.sort sorting expects an ArraySorting or None, got 5.
+	"""
+	parameter_names = tuple(inspect.signature(function).parameters)
+
+	@functools.wraps(function)
+	def call_after_check(*args: Parameters.args, **kwargs: Parameters.kwargs) -> Result:
+		"""
+		Check the given arguments, then call the function.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		args
+			The positional arguments.
+		kwargs
+			The named arguments.
+
+		Returns
+		-------
+		Result
+			What the function returns.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		"""
+		owner = find_owner(parameter_names, args)
+		argument_kinds = find_argument_kinds(function, owner)
+		named_arguments = zip(parameter_names, args, strict=False)
+
+		for parameter_name, value in named_arguments:
+			require_argument_type(function, owner, argument_kinds.get(parameter_name), (parameter_name, value))
+
+		for parameter_name, value in kwargs.items():
+			require_argument_type(function, owner, argument_kinds.get(parameter_name), (parameter_name, value))
+
+		return function(*args, **kwargs)
+
+	return call_after_check
+
+
+def find_owner(parameter_names: tuple[str, ...], args: tuple[object, ...]) -> type | None:
+	"""
+	Return the class a method is called on, or None for a function.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	parameter_names
+		The names of the parameters of the method or the function.
+	args
+		The positional arguments of the call.
+
+	Returns
+	-------
+	type or None
+		The class of ``self``, the ``cls`` itself, or None.
+
+	Examples
+	--------
+	>>> from numdaplot.settings.argument_types import find_owner
+	>>> find_owner(("self", "other"), (1, 2))
+	<class 'int'>
+	>>> find_owner(("data",), (1,)) is None
+	True
+	"""
+	if not parameter_names:
+		return None
+
+	first_name = parameter_names[0]
+	if first_name == INSTANCE_PARAMETER:
+		return type(args[0])
+
+	if first_name == CLASS_PARAMETER:
+		return cast(type, args[0])
+
+	return None
+
+
+@functools.cache
+def find_argument_kinds(function: Callable[..., object], owner: type | None) -> dict[str, AcceptedKinds]:
+	"""
+	Return what each parameter of a method or a function accepts, read once for each class.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	function
+		The method or the function.
+	owner
+		The class it is called on, which ``Self`` names in its annotations, or None for a function.
+
+	Returns
+	-------
+	dict[str, AcceptedKinds]
+		What each annotated parameter accepts.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.settings.argument_types import find_argument_kinds
+	>>> find_argument_kinds(ndp.Plot.missing_map, None)["table"].names
+	('Table',)
+	"""
+	annotations = read_annotations(function)
+	annotations.pop("return", None)
+	argument_kinds = dict[str, AcceptedKinds]()
+
+	for parameter_name, annotation in annotations.items():
+		owned_annotation = replace_self(annotation, owner)
+		argument_kinds[parameter_name] = read_accepted_kinds(owned_annotation)
+
+	return argument_kinds
+
+
+def replace_self(annotation: object, owner: type | None) -> object:
+	"""
+	Return an annotation with ``Self`` replaced by the class a method is called on.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	annotation
+		The annotation.
+	owner
+		The class, or None for a function.
+
+	Returns
+	-------
+	object
+		The annotation naming the class.
+
+	Examples
+	--------
+	>>> from typing import Self
+	>>> from numdaplot.settings.argument_types import replace_self
+	>>> replace_self(Self | None, int) == int | None
+	True
+	"""
+	if annotation is typing.Self:
+		return owner
+
+	members = typing.get_args(annotation)
+	has_self = typing.Self in members
+	if not has_self:
+		return annotation
+
+	owned_members = tuple(owner if member is typing.Self else member for member in members)
+	owned_union = cast(object, typing.Union[owned_members])  # noqa: UP007
+
+	return owned_union
+
+
+def require_argument_type(
+	function: Callable[..., object],
+	owner: type | None,
+	kinds: AcceptedKinds | None,
+	argument: tuple[str, object],
+) -> None:
+	"""
+	Check one argument of a call.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	function
+		The method or the function called.
+	owner
+		The class it is called on, or None.
+	kinds
+		What the parameter accepts, or None when it has no annotation, such as ``self``.
+	argument
+		The name of the parameter and the given value.
+
+	Raises
+	------
+	InvalidTypeError
+		When the value is not of an accepted kind.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.settings.argument_types import require_argument_type
+	>>> from numdaplot.settings.field_types import read_accepted_kinds
+	>>> try:
+	... 	require_argument_type(ndp.Plot.line, ndp.Plot, read_accepted_kinds(str), ("chart", 5))
+	... except ndp.InvalidTypeError as error:
+	... 	print(error)
+	Plot.line chart expects a str, got 5.
+	"""
+	if kinds is None:
+		return
+
+	parameter_name, value = argument
+	is_accepted = accepts_value(kinds, value)
+	if is_accepted:
+		return
+
+	callable_name = name_callable(function, owner)
+	target_name = TARGET_FORMAT.format(callable_name=callable_name, parameter_name=parameter_name)
+	expected = describe_kinds(kinds, value)
+	rejected_value = find_rejected_value(kinds, value)
+	raise InvalidTypeError(target_name, expected, rejected_value)
+
+
+def name_callable(function: Callable[..., object], owner: type | None) -> str:
+	"""
+	Return the name of a method or a function, as the user writes it.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	function
+		The method or the function.
+	owner
+		The class it is called on, or None.
+
+	Returns
+	-------
+	str
+		``Plot.line``, ``Table.filter``, ``Array +``, or ``Figure`` for a constructor.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.settings.argument_types import name_callable
+	>>> name_callable(ndp.Array.__add__, ndp.Array)
+	'Array +'
+	"""
+	function_name = function.__name__
+	if owner is None:
+		return function_name
+
+	owner_name = owner.__name__
+	if function_name == CONSTRUCTOR_NAME:
+		return owner_name
+
+	symbol = OPERATOR_SYMBOLS.get(function_name)
+	if symbol is not None:
+		return OPERATOR_NAME_FORMAT.format(owner_name=owner_name, symbol=symbol)
+
+	return METHOD_NAME_FORMAT.format(owner_name=owner_name, method_name=function_name)