numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/table_refusals.py

@@ -0,0 +1,295 @@
+"""
+Python operations refused by a Table, each pointing to the numdaplot way of doing it.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Iterator
+from typing import NoReturn
+
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+from numdaplot.tables.table_data import TableData
+
+COMPARISON_OPERATION = "Comparing a Table with {symbol}"
+EQUALITY_ALTERNATIVE = "is_equal with ndp.Equality"
+ORDER_ALTERNATIVE = "filter with a rule such as ndp.Greater"
+BRACKETS_OPERATION = "Brackets on a Table"
+BRACKETS_ALTERNATIVE = "column, take or filter"
+ITERATION_OPERATION = "Iterating over a Table with for"
+ITERATION_ALTERNATIVE = "for value in table.column(name).to_list()"
+MEMBERSHIP_OPERATION = "Testing membership in a Table with in"
+MEMBERSHIP_ALTERNATIVE = "filter with ndp.Equal or ndp.IsIn, or column_names"
+LENGTH_OPERATION = "len of a Table"
+LENGTH_ALTERNATIVE = "the row_count attribute"
+TRUTH_OPERATION = "Testing a Table as a boolean"
+TRUTH_ALTERNATIVE = "the row_count attribute, or is_equal"
+EQUAL_SYMBOL = "=="
+NOT_EQUAL_SYMBOL = "!="
+LESS_SYMBOL = "<"
+LESS_OR_EQUAL_SYMBOL = "<="
+GREATER_SYMBOL = ">"
+GREATER_OR_EQUAL_SYMBOL = ">="
+
+
+class TableRefusals(TableData):
+	"""
+	Python operations refused by a Table, each raising ``RefusedOperationError`` with the numdaplot way of doing it.
+
+	``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``, brackets, ``for``, ``in``, ``len`` and ``bool`` are refused.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	def __eq__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``table == other``; use ``is_equal``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		refuse_table_comparison(EQUAL_SYMBOL, EQUALITY_ALTERNATIVE)
+
+	def __ne__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``table != other``; use ``is_equal``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		refuse_table_comparison(NOT_EQUAL_SYMBOL, EQUALITY_ALTERNATIVE)
+
+	def __lt__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``table < other``; use ``filter``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])})
+		>>> try:
+		... 	table < 2
+		... except ndp.RefusedOperationError as error:
+		... 	print(error)
+		Comparing a Table with < is not available, use filter with a rule such as ndp.Greater instead.
+		"""
+		refuse_table_comparison(LESS_SYMBOL, ORDER_ALTERNATIVE)
+
+	def __le__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``table <= other``; use ``filter``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		refuse_table_comparison(LESS_OR_EQUAL_SYMBOL, ORDER_ALTERNATIVE)
+
+	def __gt__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``table > other``; use ``filter``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		refuse_table_comparison(GREATER_SYMBOL, ORDER_ALTERNATIVE)
+
+	def __ge__(self, other: object) -> NoReturn:
+		"""
+		Refuse ``table >= other``; use ``filter``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		other
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		refuse_table_comparison(GREATER_OR_EQUAL_SYMBOL, ORDER_ALTERNATIVE)
+
+	def __getitem__(self, key: object) -> NoReturn:
+		"""
+		Refuse ``table[...]``; use ``column``, ``take`` or ``filter``.
+
+		.. 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 ``table[...] = value``; use ``add_column``, which returns a new Table.
+
+		.. 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 row in table``; iterate over the values of a column instead.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> table = ndp.Table.from_arrays({"city": ndp.Array.from_list(["Paris", "Lyon"])})
+		>>> for city in table.column("city").to_list():
+		... 	print(city)
+		Paris
+		Lyon
+		"""
+		raise RefusedOperationError(ITERATION_OPERATION, ITERATION_ALTERNATIVE)
+
+	def __contains__(self, value: object) -> NoReturn:
+		"""
+		Refuse ``value in table``; use ``filter`` with ``ndp.Equal`` or ``ndp.IsIn``, or ``column_names``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		value
+			Any value.
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(MEMBERSHIP_OPERATION, MEMBERSHIP_ALTERNATIVE)
+
+	def __len__(self) -> NoReturn:
+		"""
+		Refuse ``len(table)``; read the ``row_count`` attribute instead.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(LENGTH_OPERATION, LENGTH_ALTERNATIVE)
+
+	def __bool__(self) -> NoReturn:
+		"""
+		Refuse ``if table:`` and ``bool(table)``, whose meaning would be unclear.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			Always.
+		"""
+		raise RefusedOperationError(TRUTH_OPERATION, TRUTH_ALTERNATIVE)
+
+
+def refuse_table_comparison(symbol: str, alternative: str) -> NoReturn:
+	"""
+	Raise the error refusing a comparison operator on a Table.
+
+	.. 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.tables.table_refusals import refuse_table_comparison
+	>>> try:
+	... 	refuse_table_comparison("==", "is_equal")
+	... except ndp.RefusedOperationError as error:
+	... 	print(error)
+	Comparing a Table with == is not available, use is_equal instead.
+	"""
+	operation = COMPARISON_OPERATION.format(symbol=symbol)
+	raise RefusedOperationError(operation, alternative)

numdaplot/tables/table_selection.py

@@ -0,0 +1,163 @@
+"""
+Selection of the rows and columns of a Table, by conditions and by position, and check of its values.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Self
+
+from numdaplot.positions.region import Region
+from numdaplot.rules.rule import Rule
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.filtering.checked_frame import check_frame
+from numdaplot.tables.filtering.filter import Filter
+from numdaplot.tables.filtering.row_mask import build_filter_mask
+from numdaplot.tables.frames.region_positions import take_region
+from numdaplot.tables.table_data import TableData
+
+
+class TableSelection(TableData):
+	"""
+	Selection of rows with ``filter``, of a region with ``take``, and check of every value with ``check``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def check(self, rule: Rule) -> Self:
+		"""
+		Return which values satisfy a rule, in every column.
+
+		To check some columns only, choose them first with ``choose_columns``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		rule
+			A ``Rule``, such as ``ndp.Greater(10)`` or ``ndp.IsIn(["Paris"])``: see ``Rule`` for every rule.
+			A missing value only satisfies ``IsMissing``.
+
+		Returns
+		-------
+		Self
+			A new Table with the same columns and rows, holding True where the value satisfies the rule.
+			Every column is of type ``BOOL``.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		IncompatibleTypesError
+			When the rule does not apply to the type of one of the columns.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([120.0, None, 150.0])
+		>>> stocks = ndp.Array.from_list([3.0, 5.0, None])
+		>>> table = ndp.Table.from_arrays({"price": prices, "stock": stocks})
+		>>> table.check(ndp.IsMissing())
+		   price  stock
+		    BOOL   BOOL
+		0  False  False
+		1   True  False
+		2  False   True
+		"""
+		checked_frame = check_frame(self._frame, rule)
+		checked_table = self._wrap(checked_frame)
+
+		return checked_table
+
+	@checked_arguments
+	def filter(self, row_filter: Filter) -> Self:
+		"""
+		Return the rows satisfying a filter.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		row_filter
+			The conditions and how they combine. A missing value only satisfies ``IsMissing``.
+
+		Returns
+		-------
+		Self
+			A new Table with the kept rows, in their order, numbered from 0.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		ColumnNotFoundError
+			When a condition names a column the Table does not have.
+		IncompatibleTypesError
+			When a rule does not apply to the type of one of its columns.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Pau"])
+		>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+		>>> table = ndp.Table.from_arrays({"city": cities, "price": prices})
+		>>> expensive = ndp.Condition(rule=ndp.Greater(100), columns=["price"])
+		>>> table.filter(ndp.Filter(conditions=[expensive]))
+		    city   price
+		    TEXT FLOAT64
+		0  Paris   120.0
+		1    Pau   150.0
+		"""
+		mask = build_filter_mask(self._frame, row_filter)
+		kept_frame = self._frame[mask]
+		numbered_frame = kept_frame.reset_index(drop=True)
+		filtered_table = self._wrap(numbered_frame)
+
+		return filtered_table
+
+	@checked_arguments
+	def take(self, region: Region) -> Self:
+		"""
+		Return the rows and the columns of a region.
+
+		A row chosen with ``Index`` gives a Table of one row. Use ``to_value`` to read a single value.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		region
+			The rows and the columns, every one of a dimension when omitted. Columns are positions or names;
+			negative positions count from the end.
+
+		Returns
+		-------
+		Self
+			A new Table, rows numbered from 0, columns in the order of the region.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		InvalidPositionError
+			When a position is not a whole number inside its dimension.
+		ColumnNotFoundError
+			When a column name matches no column.
+		DuplicateColumnError
+			When a column name appears twice in the region.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+		>>> table = ndp.Table.from_arrays({"price": prices})
+		>>> table.take(ndp.Region(rows=ndp.Range(start=1, stop=2), columns=["price"]))
+		    price
+		  FLOAT64
+		0    80.0
+		1   150.0
+		"""
+		region_frame = take_region(self._frame, region)
+		region_table = self._wrap(region_frame)
+
+		return region_table