numdaplot 0.1.0__py3-none-any.whl

numdaplot/errors/invalid_type_error.py

@@ -0,0 +1,79 @@
+"""
+Error raised when a setting or an argument receives a value of the wrong type.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+TYPE_MESSAGE = "{target_name} expects {expected}, got {given!r}."
+CLASS_GIVEN_MESSAGE = "ndp.{class_name} is a class, use ndp.{class_name}() instead."
+
+
+class InvalidTypeError(NumdaplotError):
+	"""
+	Raised when a setting or an argument receives a value of the wrong type, such as a number for ``Region`` rows.
+
+	A class given in place of an object, such as ``ndp.Sum`` in place of ``ndp.Sum()``, gets a message naming the
+	parentheses.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	target_name
+		What received the value, such as ``"Region rows"``.
+	expected
+		What it accepts, such as ``"an Index, a Range or None"``.
+	given
+		The rejected value.
+
+	Attributes
+	----------
+	target_name
+		What received the value.
+	expected
+		What it accepts.
+	given
+		The rejected value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Region(rows=0)
+	... except ndp.InvalidTypeError as error:
+	... 	print(error)
+	Region rows expects an Index, a Range or None, got 0.
+	>>> try:
+	... 	ndp.Array.from_list([1, 2]).compute(ndp.Sum)
+	... except ndp.InvalidTypeError as error:
+	... 	print(error)
+	ndp.Sum is a class, use ndp.Sum() instead.
+	"""
+
+	def __init__(self, target_name: str, expected: str, given: object) -> None:
+		"""
+		Build the error message from what received the value, what it accepts and the rejected value.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		target_name
+			What received the value.
+		expected
+			What it accepts.
+		given
+			The rejected value.
+		"""
+		if isinstance(given, type):
+			message = CLASS_GIVEN_MESSAGE.format(class_name=given.__name__)
+		else:
+			message = TYPE_MESSAGE.format(target_name=target_name, expected=expected, given=given)
+
+		super().__init__(message)
+
+		self.target_name = target_name
+		self.expected = expected
+		self.given = given

numdaplot/errors/irregular_list_error.py

@@ -0,0 +1,36 @@
+"""
+Error raised when nested lists do not form a regular block.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+IRREGULAR_LIST_MESSAGE = "Expected nested lists of equal lengths."
+
+
+class IrregularListError(NumdaplotError):
+	"""
+	Raised when nested lists do not form a regular block of rows and columns.
+
+	The lists at one level have different lengths, or mix lists and single values.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Array.from_list([[1, 2], [3]])
+	... except ndp.IrregularListError as error:
+	... 	print(error)
+	Expected nested lists of equal lengths.
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Build the error message.
+
+		.. versionadded:: 0.1.0
+		"""
+		super().__init__(IRREGULAR_LIST_MESSAGE)

numdaplot/errors/join_relation_error.py

@@ -0,0 +1,183 @@
+"""
+Error raised when a key appears several times where a join expects it once.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+from numdaplot.errors.repeated_key import RepeatedKey
+
+JOIN_RELATION_MESSAGE = (
+	"Expected each key of {table_name} to appear once for {relation_name}, but {key_names} {key_values} appears "
+	"{count} times."
+)
+VALUE_SEPARATOR = ", "
+COMBINATION_FORMAT = "({joined_values})"
+SINGLE_KEY_COUNT = 1
+
+
+class JoinRelationError(NumdaplotError):
+	"""
+	Raised when a key appears several times in a Table of a join whose ``Relation`` expects it once.
+
+	For example, ``Relation.ONE_TO_MANY`` expects each key once in the left Table, the one joined.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	relation_name
+		The relation checked, such as ``"Relation.ONE_TO_MANY"``.
+	table_name
+		The Table holding the repeated key: ``"the left Table"`` or ``"the right Table"``.
+	repeated_key
+		The first repeated key, its values and its number of rows.
+
+	Attributes
+	----------
+	relation_name
+		The relation checked.
+	table_name
+		The Table holding the repeated key.
+	repeated_key
+		The first repeated key, its values and its number of rows.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> accidents = ndp.Table.from_arrays({"Num_Acc": ndp.Array.from_list([101, 101])})
+	>>> users = ndp.Table.from_arrays({"Num_Acc": ndp.Array.from_list([101])})
+	>>> try:
+	... 	accidents.join(ndp.Join(other=users, keys=["Num_Acc"], relation=ndp.Relation.ONE_TO_MANY))
+	... except ndp.JoinRelationError as error:
+	... 	print(error)
+	Expected each key of the left Table to appear once for Relation.ONE_TO_MANY, but 'Num_Acc' 101 appears 2 times.
+	"""
+
+	def __init__(self, relation_name: str, table_name: str, repeated_key: RepeatedKey) -> None:
+		"""
+		Build the error message from the relation, the Table and the repeated key.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		relation_name
+			The relation checked.
+		table_name
+			The Table holding the repeated key.
+		repeated_key
+			The first repeated key, its values and its number of rows.
+		"""
+		key_names = format_key_names(repeated_key.key_names)
+		key_values = format_key_values(repeated_key.key_values)
+		message = JOIN_RELATION_MESSAGE.format(
+			table_name=table_name,
+			relation_name=relation_name,
+			key_names=key_names,
+			key_values=key_values,
+			count=repeated_key.count,
+		)
+		super().__init__(message)
+
+		self.relation_name = relation_name
+		self.table_name = table_name
+		self.repeated_key = repeated_key
+
+
+def format_key_names(key_names: list[str]) -> str:
+	"""
+	Return the names of the key columns as written in the message: one name, or the combination of several.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	key_names
+		The names of the key columns.
+
+	Returns
+	-------
+	str
+		``'Num_Acc'`` for one key, ``('Num_Acc', 'id_vehicule')`` for several.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.join_relation_error import format_key_names
+	>>> format_key_names(["Num_Acc"]), format_key_names(["Num_Acc", "id_vehicule"])
+	("'Num_Acc'", "('Num_Acc', 'id_vehicule')")
+	"""
+	quoted_names = [repr(key_name) for key_name in key_names]
+	names_text = format_combination(quoted_names)
+
+	return names_text
+
+
+def format_key_values(key_values: list[Any]) -> str:
+	"""
+	Return the values of a key as written in the message, texts in quotes.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	key_values
+		The value of each key column.
+
+	Returns
+	-------
+	str
+		``202500000001`` for one key, ``(202500000001, 'A01')`` for several.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.join_relation_error import format_key_values
+	>>> format_key_values([202500000001, "A01"])
+	"(202500000001, 'A01')"
+	"""
+	value_texts = list[str]()
+
+	for key_value in key_values:
+		value_text = str(key_value)
+		if isinstance(key_value, str):
+			value_text = repr(key_value)
+
+		value_texts.append(value_text)
+
+	values_text = format_combination(value_texts)
+
+	return values_text
+
+
+def format_combination(texts: list[str]) -> str:
+	"""
+	Return a single text as it is, or several texts between parentheses.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	texts
+		The text of each key column.
+
+	Returns
+	-------
+	str
+		The single text, or the texts separated by commas between parentheses.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.join_relation_error import format_combination
+	>>> format_combination(["101"]), format_combination(["101", "'A01'"])
+	('101', "(101, 'A01')")
+	"""
+	text_count = len(texts)
+	if text_count == SINGLE_KEY_COUNT:
+		return texts[0]
+
+	joined_values = VALUE_SEPARATOR.join(texts)
+	combination = COMBINATION_FORMAT.format(joined_values=joined_values)
+
+	return combination

numdaplot/errors/missing_dependency_error.py

@@ -0,0 +1,58 @@
+"""
+Error raised when a file format needs an optional package that is not installed.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+MISSING_DEPENDENCY_MESSAGE = (
+	"This file format needs the {package_name} package, install it with: pip install numdaplot[{extra_name}]"
+)
+
+
+class MissingDependencyError(NumdaplotError):
+	"""
+	Raised when reading or writing Excel or Parquet files without the matching optional package.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	package_name
+		Name of the missing package, such as ``openpyxl``.
+	extra_name
+		Name of the numdaplot extra that installs it, such as ``excel``.
+
+	Attributes
+	----------
+	package_name
+		Name of the missing package, such as ``openpyxl``.
+	extra_name
+		Name of the numdaplot extra that installs it, such as ``excel``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> print(ndp.MissingDependencyError("openpyxl", "excel"))
+	This file format needs the openpyxl package, install it with: pip install numdaplot[excel]
+	"""
+
+	def __init__(self, package_name: str, extra_name: str) -> None:
+		"""
+		Build the error message from the package name and the extra name.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		package_name
+			Name of the missing package, such as ``openpyxl``.
+		extra_name
+			Name of the numdaplot extra that installs it, such as ``excel``.
+		"""
+		message = MISSING_DEPENDENCY_MESSAGE.format(package_name=package_name, extra_name=extra_name)
+		super().__init__(message)
+
+		self.package_name = package_name
+		self.extra_name = extra_name

numdaplot/errors/missing_type_error.py

@@ -0,0 +1,36 @@
+"""
+Error raised when the type of an Array cannot be guessed.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+MISSING_TYPE_MESSAGE = "Cannot guess the type of an Array without any present value, give dtype."
+
+
+class MissingTypeError(NumdaplotError):
+	"""
+	Raised when the type of a new Array cannot be guessed.
+
+	The Array is created without any present value and without ``dtype``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Array.from_list([])
+	... except ndp.MissingTypeError as error:
+	... 	print(error)
+	Cannot guess the type of an Array without any present value, give dtype.
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Build the error message.
+
+		.. versionadded:: 0.1.0
+		"""
+		super().__init__(MISSING_TYPE_MESSAGE)

numdaplot/errors/missing_value_error.py

@@ -0,0 +1,62 @@
+"""
+Error raised when a chart cannot draw a missing value.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+MISSING_VALUE_MESSAGE = "{chart_name} cannot draw a missing value, found one in {column_name!r}."
+
+
+class MissingValueError(NumdaplotError):
+	"""
+	Raised when a column drawn by a chart that needs every value, such as a ``PieChart``, has a missing value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart_name
+		Name of the chart class, such as ``PieChart``.
+	column_name
+		The column holding the missing value.
+
+	Attributes
+	----------
+	chart_name
+		Name of the chart class, such as ``PieChart``.
+	column_name
+		The column holding the missing value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> sales = ndp.Array.from_list([120.0, None])
+	>>> shares = ndp.Table.from_arrays({"city": cities, "sales": sales})
+	>>> chart = ndp.PieChart(labels="city", values="sales")
+	>>> try:
+	... 	ndp.Plot.pie(shares, chart)
+	... except ndp.MissingValueError as error:
+	... 	print(error)
+	PieChart cannot draw a missing value, found one in 'sales'.
+	"""
+
+	def __init__(self, chart_name: str, column_name: str) -> None:
+		"""
+		Build the error message from the chart and the column.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		chart_name
+			Name of the chart class, such as ``PieChart``.
+		column_name
+			The column holding the missing value.
+		"""
+		message = MISSING_VALUE_MESSAGE.format(chart_name=chart_name, column_name=column_name)
+		super().__init__(message)
+		self.chart_name = chart_name
+		self.column_name = column_name

numdaplot/errors/not_single_value_error.py

@@ -0,0 +1,53 @@
+"""
+Error raised when a single value is asked from an Array holding another number of values.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+NOT_SINGLE_VALUE_MESSAGE = "Expected exactly one value, got {value_count}."
+
+
+class NotSingleValueError(NumdaplotError):
+	"""
+	Raised when ``to_value`` is called on an Array that does not hold exactly one value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value_count
+		Number of values held by the Array.
+
+	Attributes
+	----------
+	value_count
+		Number of values held by the Array.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> array = ndp.Array.from_list([1, 2])
+	>>> try:
+	... 	array.to_value()
+	... except ndp.NotSingleValueError as error:
+	... 	print(error)
+	Expected exactly one value, got 2.
+	"""
+
+	def __init__(self, value_count: int) -> None:
+		"""
+		Build the error message from the value count.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		value_count
+			Number of values held by the Array.
+		"""
+		message = NOT_SINGLE_VALUE_MESSAGE.format(value_count=value_count)
+		super().__init__(message)
+
+		self.value_count = value_count

numdaplot/errors/numdaplot_error.py

@@ -0,0 +1,25 @@
+"""
+Base class of every numdaplot error.
+
+.. versionadded:: 0.1.0
+"""
+
+
+class NumdaplotError(Exception):
+	"""
+	Base class of every error raised by numdaplot.
+
+	Catch it to handle any numdaplot error at once, or catch a precise subclass
+	to handle only one case.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Quantile(1.5)
+	... except ndp.NumdaplotError as error:
+	... 	print(error)
+	Expected a fraction between 0 and 1, got 1.5.
+	"""

numdaplot/errors/numdaplot_warning.py

@@ -0,0 +1,34 @@
+"""
+Base class of every numdaplot warning.
+
+.. versionadded:: 0.1.0
+"""
+
+
+class NumdaplotWarning(UserWarning):
+	"""
+	Base class of every warning emitted by numdaplot.
+
+	Filter it with the standard ``warnings`` module to silence, or turn into errors, every numdaplot warning at once
+	and only them. Filter a precise subclass to handle only one case.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import warnings
+	>>> distances = ndp.Array.from_list([0.0, 3.0])
+	>>> hours = ndp.Array.from_list([0.0, 2.0])
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	speeds = distances / hours
+	>>> isinstance(caught_warnings[0].message, ndp.NumdaplotWarning)
+	True
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	warnings.simplefilter("ignore", ndp.NumdaplotWarning)
+	... 	speeds = distances / hours
+	>>> caught_warnings
+	[]
+	"""

numdaplot/errors/occupied_cell_error.py

@@ -0,0 +1,63 @@
+"""
+Error raised when a Plot is placed on a cell of a Figure that already holds one.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+OCCUPIED_CELL_MESSAGE = "Cell ({row}, {column}) already holds a Plot."
+
+
+class OccupiedCellError(NumdaplotError):
+	"""
+	Raised when a Plot is placed on a cell of a ``Figure`` already covered by another Plot, even partly.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	row
+		The row of the first occupied cell, from 0.
+	column
+		The column of the first occupied cell, from 0.
+
+	Attributes
+	----------
+	row
+		The row of the first occupied cell, from 0.
+	column
+		The column of the first occupied cell, from 0.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0])
+	>>> plot = ndp.Plot.line(prices)
+	>>> figure = ndp.Figure(ndp.Layout(rows=1, columns=2))
+	>>> first_cell = ndp.Cell(row=0, column=0)
+	>>> figure = figure.place(plot, first_cell)
+	>>> try:
+	... 	figure.place(plot, first_cell)
+	... except ndp.OccupiedCellError as error:
+	... 	print(error)
+	Cell (0, 0) already holds a Plot.
+	"""
+
+	def __init__(self, row: int, column: int) -> None:
+		"""
+		Build the error message from the occupied cell.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		row
+			The row of the first occupied cell, from 0.
+		column
+			The column of the first occupied cell, from 0.
+		"""
+		message = OCCUPIED_CELL_MESSAGE.format(row=row, column=column)
+		super().__init__(message)
+		self.row = row
+		self.column = column

numdaplot/errors/out_of_domain_error.py

@@ -0,0 +1,70 @@
+"""
+Error raised when a math function is applied to a value it is not defined for.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+OUT_OF_DOMAIN_MESSAGE = "{function_name} is not defined for {value}."
+BETWEEN_INTEGERS_MESSAGE = (
+	"{function_name} is not defined for {value} between integers. Convert the values to FLOAT64 first."
+)
+
+
+class OutOfDomainError(NumdaplotError):
+	"""
+	Raised when a math function or an operator receives a value it is not defined for.
+
+	For example, the square root of a negative number, the logarithm of 0, or an integer divided by 0 with ``//``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	function_name
+		Name of the math function.
+	value
+		The first value outside the domain of the function.
+	between_integers
+		True when decimals would accept the value, False by default.
+
+	Attributes
+	----------
+	function_name
+		Name of the math function.
+	value
+		The first value outside the domain of the function.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> array = ndp.Array.from_list([4, -9])
+	>>> try:
+	... 	array.apply(ndp.SquareRoot())
+	... except ndp.OutOfDomainError as error:
+	... 	print(error)
+	SquareRoot is not defined for -9.
+	"""
+
+	def __init__(self, function_name: str, value: float, between_integers: bool = False) -> None:
+		"""
+		Build the error message from the function name and the value.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		function_name
+			Name of the math function.
+		value
+			The first value outside the domain of the function.
+		between_integers
+			True when decimals would accept the value, False by default.
+		"""
+		message_format = BETWEEN_INTEGERS_MESSAGE if between_integers else OUT_OF_DOMAIN_MESSAGE
+		message = message_format.format(function_name=function_name, value=value)
+		super().__init__(message)
+
+		self.function_name = function_name
+		self.value = value