numdaplot 0.1.0__py3-none-any.whl

numdaplot/errors/file_not_found_error.py

@@ -0,0 +1,56 @@
+"""
+Error raised when a file to read does not exist.
+
+.. versionadded:: 0.1.0
+"""
+
+import builtins
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+FILE_NOT_FOUND_MESSAGE = "No file found at {path}."
+
+
+class FileNotFoundError(NumdaplotError, builtins.FileNotFoundError):
+	"""
+	Raised when a Table is read from a path where there is no file.
+
+	It is also a Python ``FileNotFoundError``, 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 numdaplot as ndp
+	>>> try:
+	... 	ndp.Table.from_csv("missing.csv")
+	... except ndp.FileNotFoundError as error:
+	... 	print(error)
+	No file found at missing.csv.
+	"""
+
+	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_NOT_FOUND_MESSAGE.format(path=path)
+		super().__init__(message)
+
+		self.path = path

numdaplot/errors/incompatible_charts_error.py

@@ -0,0 +1,80 @@
+"""
+Error raised when a chart cannot be added to a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INCOMPATIBLE_CHARTS_MESSAGE = "A {chart_name} with {chart_positions} cannot be added to a Plot with {plot_positions}."
+
+
+class IncompatibleChartsError(NumdaplotError):
+	"""
+	Raised when a chart added to a Plot does not have the kind of values of an axis it shares with the Plot.
+
+	Its ``x`` values are numbers, dates, texts or times of day while the Plot has another kind, or it measures numbers
+	on an axis of times of day, or the reverse.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart_name
+		Name of the chart class added, such as ``LineChart``.
+	chart_positions
+		What the added chart has on the shared axis: ``numbers``, ``dates``, ``texts`` or ``times of day`` as ``x``
+		values, or ``numbers on the left axis`` or ``times of day on the left axis`` as values.
+	plot_positions
+		What the Plot has on the shared axis.
+
+	Attributes
+	----------
+	chart_name
+		Name of the chart class added, such as ``LineChart``.
+	chart_positions
+		What the added chart has on the shared axis: ``numbers``, ``dates``, ``texts`` or ``times of day`` as ``x``
+		values, or ``numbers on the left axis`` or ``times of day on the left axis`` as values.
+	plot_positions
+		What the Plot has on the shared axis.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+	>>> days = ndp.Array.from_list([date(2026, 1, 1), date(2026, 1, 2)])
+	>>> sales = ndp.Array.from_list([120.0, 80.0])
+	>>> shops = ndp.Table.from_arrays({"city": cities, "day": days, "sales": sales})
+	>>> plot = ndp.Plot.bar(shops, ndp.BarChart(x="city", y=["sales"]))
+	>>> line = ndp.LineChart(x="day", y=["sales"])
+	>>> try:
+	... 	plot.add_line(shops, line)
+	... except ndp.IncompatibleChartsError as error:
+	... 	print(error)
+	A LineChart with dates cannot be added to a Plot with texts.
+	"""
+
+	def __init__(self, chart_name: str, chart_positions: str, plot_positions: str) -> None:
+		"""
+		Build the error message from the chart and what each one has on the shared axis.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		chart_name
+			Name of the chart class added, such as ``LineChart``.
+		chart_positions
+			What the added chart has on the shared axis: ``numbers``, ``dates``, ``texts`` or ``times of day`` as ``x``
+			values, or ``numbers on the left axis`` or ``times of day on the left axis`` as values.
+		plot_positions
+			What the Plot has on the shared axis.
+		"""
+		message = INCOMPATIBLE_CHARTS_MESSAGE.format(
+			chart_name=chart_name, chart_positions=chart_positions, plot_positions=plot_positions
+		)
+		super().__init__(message)
+		self.chart_name = chart_name
+		self.chart_positions = chart_positions
+		self.plot_positions = plot_positions

numdaplot/errors/incompatible_types_error.py

@@ -0,0 +1,104 @@
+"""
+Error raised when an operation does not apply to the types of its values.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+TYPE_NAME_SEPARATOR = " and "
+INCOMPATIBLE_TYPES_MESSAGE = "Cannot apply {operation} to {type_names}."
+COLUMN_TYPE_NAME = "the {type_name} column {column_name!r}"
+
+
+class IncompatibleTypesError(NumdaplotError):
+	"""
+	Raised when an operation, a rule, a statistic or a math function does not apply to the types it receives.
+
+	For example, a number cannot be added to a text, and ``Contains`` only applies to text.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation
+		Name of the operation: an operator such as ``"+"``, or a rule, statistic or function name.
+	type_names
+		Names of the ``ndp.Type`` members the operation received, in order.
+
+	Attributes
+	----------
+	operation
+		Name of the operation: an operator such as ``"+"``, or a rule, statistic or function name.
+	type_names
+		Names of the ``ndp.Type`` members the operation received, in order.
+	column_name
+		Name of the Table column holding the first type, or ``None`` for an Array or a type alone.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> array = ndp.Array.from_list([1, 2])
+	>>> try:
+	... 	array + "euros"
+	... except ndp.IncompatibleTypesError as error:
+	... 	print(error)
+	Cannot apply + to INT64 and TEXT.
+	>>> sales = ndp.Table.from_arrays({"city": ndp.Array.from_list(["Paris"])})
+	>>> mean_city = ndp.Calculation(column="city", function=ndp.Mean())
+	>>> try:
+	... 	sales.aggregate(ndp.Aggregation(calculations=[mean_city]))
+	... except ndp.IncompatibleTypesError as error:
+	... 	print(error)
+	Cannot apply Mean to the TEXT column 'city'.
+	"""
+
+	def __init__(self, operation: str, type_names: list[str]) -> None:
+		"""
+		Build the error message from the operation and the type names.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation
+			Name of the operation: an operator such as ``"+"``, or a rule, statistic or function name.
+		type_names
+			Names of the ``ndp.Type`` members the operation received, in order.
+		"""
+		joined_type_names = TYPE_NAME_SEPARATOR.join(type_names)
+		message = INCOMPATIBLE_TYPES_MESSAGE.format(operation=operation, type_names=joined_type_names)
+		super().__init__(message)
+
+		self.operation = operation
+		self.type_names = list(type_names)
+		self.column_name: str | None = None
+
+	def name_column(self, column_name: str) -> None:
+		"""
+		Name the Table column holding the first type in the message, unless a column is already named.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_name
+			The name of the column.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> error = ndp.IncompatibleTypesError("Greater", ["DATETIME", "INT64"])
+		>>> error.name_column("day")
+		>>> print(error)
+		Cannot apply Greater to the DATETIME column 'day' and INT64.
+		"""
+		if self.column_name is not None:
+			return
+
+		self.column_name = column_name
+		first_type_name, *other_type_names = self.type_names
+		named_type = COLUMN_TYPE_NAME.format(type_name=first_type_name, column_name=column_name)
+		joined_type_names = TYPE_NAME_SEPARATOR.join([named_type, *other_type_names])
+		message = INCOMPATIBLE_TYPES_MESSAGE.format(operation=self.operation, type_names=joined_type_names)
+		self.args = (message,)

numdaplot/errors/integer_overflow_error.py

@@ -0,0 +1,61 @@
+"""
+Error raised when the result of a calculation does not fit an integer type.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INTEGER_OVERFLOW_MESSAGE = (
+	"The operation {operation_name} gives values too large for {type_name}. Convert the values to FLOAT64 first."
+)
+
+
+class IntegerOverflowError(NumdaplotError):
+	"""
+	Raised when an integer result does not fit its type, which would otherwise wrap around to a wrong number.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation_name
+		The operator or the statistic, such as ``*`` or ``Sum``.
+	type_name
+		Name of the ``ndp.Type`` member that cannot hold the result.
+
+	Attributes
+	----------
+	operation_name
+		The operator or the statistic, such as ``*`` or ``Sum``.
+	type_name
+		Name of the ``ndp.Type`` member that cannot hold the result.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Array.from_list([2**62]) * 4
+	... except ndp.IntegerOverflowError as error:
+	... 	print(error)
+	The operation * gives values too large for INT64. Convert the values to FLOAT64 first.
+	"""
+
+	def __init__(self, operation_name: str, type_name: str) -> None:
+		"""
+		Build the error message from the operation and the type names.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation_name
+			The operator or the statistic, such as ``*`` or ``Sum``.
+		type_name
+			Name of the ``ndp.Type`` member that cannot hold the result.
+		"""
+		message = INTEGER_OVERFLOW_MESSAGE.format(operation_name=operation_name, type_name=type_name)
+		super().__init__(message)
+
+		self.operation_name = operation_name
+		self.type_name = type_name

numdaplot/errors/invalid_base_error.py

@@ -0,0 +1,52 @@
+"""
+Error raised when a logarithm base is not usable.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_BASE_MESSAGE = "Expected a logarithm base greater than 0 and different from 1, got {base}."
+
+
+class InvalidBaseError(NumdaplotError):
+	"""
+	Raised when a logarithm base is lower than or equal to 0, or equal to 1.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	base
+		The rejected base.
+
+	Attributes
+	----------
+	base
+		The rejected base.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Logarithm(base=1)
+	... except ndp.InvalidBaseError as error:
+	... 	print(error)
+	Expected a logarithm base greater than 0 and different from 1, got 1.
+	"""
+
+	def __init__(self, base: float) -> None:
+		"""
+		Build the error message from the base.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		base
+			The rejected base.
+		"""
+		message = INVALID_BASE_MESSAGE.format(base=base)
+		super().__init__(message)
+
+		self.base = base

numdaplot/errors/invalid_bin_width_error.py

@@ -0,0 +1,66 @@
+"""
+Error raised when the bins of a histogram have a width of 0 or less, or a duration beyond a day.
+
+.. versionadded:: 0.1.0
+"""
+
+from datetime import timedelta
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_BIN_WIDTH_MESSAGE = "Expected a bin width above 0, got {width}."
+INVALID_BIN_DURATION_MESSAGE = "Expected a bin width above 0 and at most 1 day, got {width}."
+
+
+class InvalidBinWidthError(NumdaplotError):
+	"""
+	Raised when a ``BinWidth`` is 0 or negative, or a duration beyond a day.
+
+	Such a width would never cover the values, or be wider than every time of day.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	width
+		The rejected width.
+
+	Attributes
+	----------
+	width
+		The rejected width.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.BinWidth(-5.0)
+	... except ndp.InvalidBinWidthError as error:
+	... 	print(error)
+	Expected a bin width above 0, got -5.0.
+	>>> from datetime import timedelta
+	>>> try:
+	... 	ndp.BinWidth(timedelta(days=2))
+	... except ndp.InvalidBinWidthError as error:
+	... 	print(error)
+	Expected a bin width above 0 and at most 1 day, got 2 days, 0:00:00.
+	"""
+
+	def __init__(self, width: float | timedelta) -> None:
+		"""
+		Build the error message from the width.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		width
+			The rejected width.
+		"""
+		message_format = INVALID_BIN_WIDTH_MESSAGE
+		if isinstance(width, timedelta):
+			message_format = INVALID_BIN_DURATION_MESSAGE
+
+		message = message_format.format(width=width)
+		super().__init__(message)
+		self.width = width

numdaplot/errors/invalid_bounds_error.py

@@ -0,0 +1,58 @@
+"""
+Error raised when the bounds of an interval are reversed or not comparable.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_BOUNDS_MESSAGE = "Expected comparable bounds with low <= high, got low={low!r} and high={high!r}."
+
+
+class InvalidBoundsError(NumdaplotError):
+	"""
+	Raised when the low bound is greater than the high bound, or when both cannot be compared.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	low
+		The rejected low bound.
+	high
+		The rejected high bound.
+
+	Attributes
+	----------
+	low
+		The rejected low bound.
+	high
+		The rejected high bound.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Between(low=20, high=10)
+	... except ndp.InvalidBoundsError as error:
+	... 	print(error)
+	Expected comparable bounds with low <= high, got low=20 and high=10.
+	"""
+
+	def __init__(self, low: object, high: object) -> None:
+		"""
+		Build the error message from the rejected bounds.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		low
+			The rejected low bound.
+		high
+			The rejected high bound.
+		"""
+		message = INVALID_BOUNDS_MESSAGE.format(low=low, high=high)
+		super().__init__(message)
+		self.low = low
+		self.high = high

numdaplot/errors/invalid_chart_data_error.py

@@ -0,0 +1,81 @@
+"""
+Error raised when the columns given to a chart do not fit the data it draws.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+MISSING_SETTING_MESSAGE = "{chart_name} needs {setting_name} for {data_name}."
+EXTRA_SETTING_MESSAGE = "{chart_name} takes no {setting_name} for {data_name}."
+
+
+class InvalidChartDataError(NumdaplotError):
+	"""
+	Raised when a chart misses a column setting a Table needs, or has one an Array does not use.
+
+	A Table needs the ``y`` columns of a chart, while an Array draws each of its columns and takes no column name.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart_name
+		Name of the chart class, such as ``LineChart``.
+	setting_name
+		Name of the setting, such as ``y``.
+	data_name
+		The data drawn: ``a Table`` or ``an Array``.
+	needs_setting
+		True when the setting is missing, False when it is given but not used.
+
+	Attributes
+	----------
+	chart_name
+		Name of the chart class, such as ``LineChart``.
+	setting_name
+		Name of the setting, such as ``y``.
+	data_name
+		The data drawn: ``a Table`` or ``an Array``.
+	needs_setting
+		True when the setting is missing, False when it is given but not used.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> chart = ndp.LineChart(y=["price"])
+	>>> try:
+	... 	ndp.Plot.line(prices, chart)
+	... except ndp.InvalidChartDataError as error:
+	... 	print(error)
+	LineChart takes no y for an Array.
+	"""
+
+	def __init__(self, chart_name: str, setting_name: str, data_name: str, needs_setting: bool) -> None:
+		"""
+		Build the error message from the chart, the setting and whether it is missing or extra.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		chart_name
+			Name of the chart class, such as ``LineChart``.
+		setting_name
+			Name of the setting, such as ``y``.
+		data_name
+			The data drawn: ``a Table`` or ``an Array``.
+		needs_setting
+			True when the setting is missing, False when it is given but not used.
+		"""
+		message_template = EXTRA_SETTING_MESSAGE
+		if needs_setting:
+			message_template = MISSING_SETTING_MESSAGE
+
+		message = message_template.format(chart_name=chart_name, setting_name=setting_name, data_name=data_name)
+		super().__init__(message)
+		self.chart_name = chart_name
+		self.setting_name = setting_name
+		self.data_name = data_name
+		self.needs_setting = needs_setting

numdaplot/errors/invalid_color_count_error.py

@@ -0,0 +1,63 @@
+"""
+Error raised when a chart does not have one color per series.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_COLOR_COUNT_MESSAGE = "Expected one color per series, {series_count} series and {color_count} color(s) given."
+
+
+class InvalidColorCountError(NumdaplotError):
+	"""
+	Raised when the colors of a chart are not exactly one per series.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	color_count
+		The number of colors given.
+	series_count
+		The number of series drawn.
+
+	Attributes
+	----------
+	color_count
+		The number of colors given.
+	series_count
+		The number of series drawn.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Array.from_list([1, 2])
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> costs = ndp.Array.from_list([8.0, 9.0])
+	>>> sales = ndp.Table.from_arrays({"day": days, "price": prices, "cost": costs})
+	>>> chart = ndp.LineChart(x="day", y=["price", "cost"], colors=[ndp.Color.BLUE])
+	>>> try:
+	... 	ndp.Plot.line(sales, chart)
+	... except ndp.InvalidColorCountError as error:
+	... 	print(error)
+	Expected one color per series, 2 series and 1 color(s) given.
+	"""
+
+	def __init__(self, color_count: int, series_count: int) -> None:
+		"""
+		Build the error message from the two counts.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		color_count
+			The number of colors given.
+		series_count
+			The number of series drawn.
+		"""
+		message = INVALID_COLOR_COUNT_MESSAGE.format(color_count=color_count, series_count=series_count)
+		super().__init__(message)
+		self.color_count = color_count
+		self.series_count = series_count

numdaplot/errors/invalid_color_error.py

@@ -0,0 +1,51 @@
+"""
+Error raised when a custom color is not written as ``#rrggbb``.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_COLOR_MESSAGE = "Expected a color written as #rrggbb, got {text!r}."
+
+
+class InvalidColorError(NumdaplotError):
+	"""
+	Raised when the text of a ``CustomColor`` is not ``#`` followed by six hexadecimal digits.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	text
+		The rejected text.
+
+	Attributes
+	----------
+	text
+		The rejected text.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.CustomColor("#ff88")
+	... except ndp.InvalidColorError as error:
+	... 	print(error)
+	Expected a color written as #rrggbb, got '#ff88'.
+	"""
+
+	def __init__(self, text: str) -> None:
+		"""
+		Build the error message from the rejected text.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		text
+			The rejected text.
+		"""
+		message = INVALID_COLOR_MESSAGE.format(text=text)
+		super().__init__(message)
+		self.text = text