numdaplot 0.1.0__py3-none-any.whl

numdaplot/errors/duplicate_column_error.py

@@ -0,0 +1,82 @@
+r"""
+Error raised when a column name appears more than once.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+DUPLICATE_COLUMN_MESSAGE = "The column name {column_name!r} appears more than once."
+DUPLICATE_CLEANED_MESSAGE = (
+	"The column names {first_name!r} and {second_name!r} both become {column_name!r} once cleaned. "
+	"Use ColumnNames.KEPT to keep them as written."
+)
+
+
+class DuplicateColumnError(NumdaplotError):
+	r"""
+	Raised when a column name appears twice.
+
+	For example in a file header, in a list of columns, when renaming or adding a column, or when two names of a file
+	become the same once their spaces and line breaks are removed.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column_name
+		The repeated name.
+	original_names
+		The two names, as written in the file, that both become ``column_name`` once cleaned. When omitted, the
+		name itself appears twice.
+
+	Attributes
+	----------
+	column_name
+		The repeated name.
+	original_names
+		The two names as written before cleaning, ``None`` when the name itself appears twice.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.ColumnChoice(columns=["price", "price"])
+	... except ndp.DuplicateColumnError as error:
+	... 	print(error)
+	The column name 'price' appears more than once.
+	>>> path = Path(tempfile.mkdtemp()) / "sales.csv"
+	>>> _ = path.write_text("id,id \n1,2\n")
+	>>> try:
+	... 	ndp.Table.from_csv(path)
+	... except ndp.DuplicateColumnError as error:
+	... 	print(error)
+	The column names 'id' and 'id ' both become 'id' once cleaned. Use ColumnNames.KEPT to keep them as written.
+	"""
+
+	def __init__(self, column_name: str, original_names: list[str] | None = None) -> None:
+		"""
+		Build the error message from the column name, and from the names before cleaning when they are given.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_name
+			The repeated name.
+		original_names
+			The two names before cleaning. When omitted, the name itself appears twice.
+		"""
+		message = DUPLICATE_COLUMN_MESSAGE.format(column_name=column_name)
+		if original_names is not None:
+			first_name, second_name = original_names
+			message = DUPLICATE_CLEANED_MESSAGE.format(
+				first_name=first_name, second_name=second_name, column_name=column_name
+			)
+
+		super().__init__(message)
+
+		self.column_name = column_name
+		self.original_names = original_names

numdaplot/errors/duplicate_label_error.py

@@ -0,0 +1,55 @@
+"""
+Error raised when a chart labels two values with the same text.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+DUPLICATE_LABEL_MESSAGE = "The label {label!r} appears more than once."
+
+
+class DuplicateLabelError(NumdaplotError):
+	"""
+	Raised when two slices of a ``PieChart`` have the same label, which could not tell them apart.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	label
+		The repeated label.
+
+	Attributes
+	----------
+	label
+		The repeated label.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Paris"])
+	>>> sales = ndp.Array.from_list([120.0, 80.0])
+	>>> shares = ndp.Table.from_arrays({"city": cities, "sales": sales})
+	>>> chart = ndp.PieChart(labels="city", values="sales")
+	>>> try:
+	... 	ndp.Plot.pie(shares, chart)
+	... except ndp.DuplicateLabelError as error:
+	... 	print(error)
+	The label 'Paris' appears more than once.
+	"""
+
+	def __init__(self, label: str) -> None:
+		"""
+		Build the error message from the label.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		label
+			The repeated label.
+		"""
+		message = DUPLICATE_LABEL_MESSAGE.format(label=label)
+		super().__init__(message)
+		self.label = label

numdaplot/errors/duplicate_statistic_error.py

@@ -0,0 +1,55 @@
+"""
+Error raised when a statistic appears twice in a list of statistics.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+DUPLICATE_STATISTIC_MESSAGE = "The statistic {statistic!r} appears more than once."
+
+
+class DuplicateStatisticError(NumdaplotError):
+	"""
+	Raised when the same statistic appears twice in the functions of a ``Description``, which would give two equal rows.
+
+	Two statistics are the same when they have the same class and the same settings, so ``Quantile(0.25)`` and
+	``Quantile(0.75)`` are different.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	statistic
+		The statistic given twice.
+
+	Attributes
+	----------
+	statistic
+		The statistic given twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Description(functions=[ndp.Sum(), ndp.Sum()])
+	... except ndp.DuplicateStatisticError as error:
+	... 	print(error)
+	The statistic Sum() appears more than once.
+	"""
+
+	def __init__(self, statistic: object) -> None:
+		"""
+		Build the error message from the statistic given twice.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		statistic
+			The statistic given twice.
+		"""
+		message = DUPLICATE_STATISTIC_MESSAGE.format(statistic=statistic)
+		super().__init__(message)
+
+		self.statistic = statistic

numdaplot/errors/duplicate_value_error.py

@@ -0,0 +1,54 @@
+"""
+Error raised when a value is given twice where each value must be unique.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+DUPLICATE_VALUE_MESSAGE = "The value {value!r} appears more than once."
+
+
+class DuplicateValueError(NumdaplotError):
+	"""
+	Raised when a value is given twice where each value must be unique.
+
+	For example, the same old value in two ``ValueChange`` of a ``ValueMapping``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The repeated value.
+
+	Attributes
+	----------
+	value
+		The repeated value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.ValueMapping(changes=[ndp.ValueChange(2, "Femme"), ndp.ValueChange(2, "F")])
+	... except ndp.DuplicateValueError as error:
+	... 	print(error)
+	The value 2 appears more than once.
+	"""
+
+	def __init__(self, value: object) -> None:
+		"""
+		Build the error message from the repeated value.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		value
+			The repeated value.
+		"""
+		message = DUPLICATE_VALUE_MESSAGE.format(value=value)
+		super().__init__(message)
+
+		self.value = value

numdaplot/errors/empty_array_error.py

@@ -0,0 +1,55 @@
+"""
+Error raised when a statistic needs at least one present value and gets none.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+EMPTY_ARRAY_MESSAGE = "Cannot compute {statistic_name} without any present value."
+
+
+class EmptyArrayError(NumdaplotError):
+	"""
+	Raised when a statistic that needs at least one value gets none.
+
+	``Mean`` or ``Max`` cannot be computed on values that are all missing, or on no value at all.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	statistic_name
+		Name of the statistic.
+
+	Attributes
+	----------
+	statistic_name
+		Name of the statistic.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> array = ndp.Array.from_list([None, None], dtype=ndp.Type.FLOAT64)
+	>>> try:
+	... 	array.compute(ndp.Mean())
+	... except ndp.EmptyArrayError as error:
+	... 	print(error)
+	Cannot compute Mean without any present value.
+	"""
+
+	def __init__(self, statistic_name: str) -> None:
+		"""
+		Build the error message from the statistic name.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		statistic_name
+			Name of the statistic.
+		"""
+		message = EMPTY_ARRAY_MESSAGE.format(statistic_name=statistic_name)
+		super().__init__(message)
+
+		self.statistic_name = statistic_name

numdaplot/errors/empty_list_error.py

@@ -0,0 +1,52 @@
+"""
+Error raised when a setting receives an empty list.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+EMPTY_LIST_MESSAGE = "Expected at least one {item_name}, got an empty list."
+
+
+class EmptyListError(NumdaplotError):
+	"""
+	Raised when a setting needs at least one element, such as the conditions of a ``Filter``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	item_name
+		What the list holds, such as ``condition``.
+
+	Attributes
+	----------
+	item_name
+		What the list holds, such as ``condition``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Filter(conditions=[])
+	... except ndp.EmptyListError as error:
+	... 	print(error)
+	Expected at least one condition, got an empty list.
+	"""
+
+	def __init__(self, item_name: str) -> None:
+		"""
+		Build the error message from the item name.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		item_name
+			What the list holds, such as ``condition``.
+		"""
+		message = EMPTY_LIST_MESSAGE.format(item_name=item_name)
+		super().__init__(message)
+
+		self.item_name = item_name

numdaplot/errors/empty_region_error.py

@@ -0,0 +1,34 @@
+"""
+Error raised when a Region chooses neither rows nor columns.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+EMPTY_REGION_MESSAGE = "A Region needs rows, columns or both, got neither."
+
+
+class EmptyRegionError(NumdaplotError):
+	"""
+	Raised when a ``Region`` is created without rows and without columns, which would choose the whole object.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Region()
+	... except ndp.EmptyRegionError as error:
+	... 	print(error)
+	A Region needs rows, columns or both, got neither.
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Build the error message.
+
+		.. versionadded:: 0.1.0
+		"""
+		super().__init__(EMPTY_REGION_MESSAGE)

numdaplot/errors/empty_text_error.py

@@ -0,0 +1,34 @@
+"""
+Error raised when a searched text is empty.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+EMPTY_TEXT_MESSAGE = "Expected a non-empty text to search for."
+
+
+class EmptyTextError(NumdaplotError):
+	"""
+	Raised when a rule receives an empty text to search for, which every text would contain.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Contains("")
+	... except ndp.EmptyTextError as error:
+	... 	print(error)
+	Expected a non-empty text to search for.
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Build the error message.
+
+		.. versionadded:: 0.1.0
+		"""
+		super().__init__(EMPTY_TEXT_MESSAGE)

numdaplot/errors/empty_total_error.py

@@ -0,0 +1,62 @@
+"""
+Error raised when the values a chart shares out add up to 0.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+EMPTY_TOTAL_MESSAGE = "{chart_name} needs a positive total, the values of {column_name!r} add up to 0."
+
+
+class EmptyTotalError(NumdaplotError):
+	"""
+	Raised when the values of a ``PieChart`` add up to 0, which leaves nothing to share out.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart_name
+		Name of the chart class, such as ``PieChart``.
+	column_name
+		The column of the values.
+
+	Attributes
+	----------
+	chart_name
+		Name of the chart class, such as ``PieChart``.
+	column_name
+		The column of the values.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> sales = ndp.Array.from_list([0.0, 0.0])
+	>>> shares = ndp.Table.from_arrays({"city": cities, "sales": sales})
+	>>> chart = ndp.PieChart(labels="city", values="sales")
+	>>> try:
+	... 	ndp.Plot.pie(shares, chart)
+	... except ndp.EmptyTotalError as error:
+	... 	print(error)
+	PieChart needs a positive total, the values of 'sales' add up to 0.
+	"""
+
+	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 of the values.
+		"""
+		message = EMPTY_TOTAL_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/empty_values_error.py

@@ -0,0 +1,34 @@
+"""
+Error raised when a list of accepted values is empty.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+EMPTY_VALUES_MESSAGE = "Expected at least one accepted value, got an empty list."
+
+
+class EmptyValuesError(NumdaplotError):
+	"""
+	Raised when a rule receives an empty list of accepted values, which would never keep anything.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.IsIn([])
+	... except ndp.EmptyValuesError as error:
+	... 	print(error)
+	Expected at least one accepted value, got an empty list.
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Build the error message.
+
+		.. versionadded:: 0.1.0
+		"""
+		super().__init__(EMPTY_VALUES_MESSAGE)

numdaplot/errors/file_access_error.py

@@ -0,0 +1,70 @@
+"""
+Error raised when the file system refuses to read or to write a file.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+FILE_ACCESS_MESSAGE = "Cannot {operation} {path}: {reason}."
+
+
+class FileAccessError(NumdaplotError, OSError):
+	"""
+	Raised when a file cannot be read or written: missing folder, missing permission, full disk and so on.
+
+	It is also a Python ``OSError``. A missing file and an existing file have their own errors,
+	``FileNotFoundError`` and ``FileExistsError``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation
+		What was attempted: ``"read"`` or ``"write to"``.
+	path
+		The path of the file.
+	reason
+		Why it failed.
+
+	Attributes
+	----------
+	operation
+		What was attempted: ``"read"`` or ``"write to"``.
+	path
+		The path of the file.
+	reason
+		Why it failed.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])})
+	>>> try:
+	... 	prices.to_csv("missing_folder/prices.csv")
+	... except ndp.FileAccessError as error:
+	... 	print(error)
+	Cannot write to missing_folder/prices.csv: the folder missing_folder does not exist.
+	"""
+
+	def __init__(self, operation: str, path: str, reason: str) -> None:
+		"""
+		Build the error message from the operation, the path and the reason.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation
+			What was attempted: ``"read"`` or ``"write to"``.
+		path
+			The path of the file.
+		reason
+			Why it failed.
+		"""
+		message = FILE_ACCESS_MESSAGE.format(operation=operation, path=path, reason=reason)
+		super().__init__(message)
+
+		self.operation = operation
+		self.path = path
+		self.reason = reason

numdaplot/errors/file_exists_error.py

@@ -0,0 +1,62 @@
+"""
+Error raised when a Table would overwrite an existing file.
+
+.. versionadded:: 0.1.0
+"""
+
+import builtins
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+FILE_EXISTS_MESSAGE = "A file already exists at {path}, pass on_conflict=ndp.Conflict.REPLACE to overwrite it."
+
+
+class FileExistsError(NumdaplotError, builtins.FileExistsError):
+	"""
+	Raised when a Table is written to a path where a file exists and ``on_conflict`` is ``Conflict.ERROR``.
+
+	It is also a Python ``FileExistsError``, so code catching the Python error keeps working.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of the file, as given.
+
+	Attributes
+	----------
+	path
+		The path of the file, as given.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "prices.csv"
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])})
+	>>> prices.to_csv(path)
+	>>> try:
+	... 	prices.to_csv(path)
+	... except ndp.FileExistsError as error:
+	... 	print(error)  # doctest: +ELLIPSIS
+	A file already exists at .../prices.csv, pass on_conflict=ndp.Conflict.REPLACE to overwrite it.
+	>>> prices.to_csv(path, on_conflict=ndp.Conflict.REPLACE)
+	"""
+
+	def __init__(self, path: str) -> None:
+		"""
+		Build the error message from the path.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, as given.
+		"""
+		message = FILE_EXISTS_MESSAGE.format(path=path)
+		super().__init__(message)
+
+		self.path = path