numdaplot 0.1.0__py3-none-any.whl

numdaplot/errors/readability_warning.py

@@ -0,0 +1,35 @@
+"""
+Warning emitted when a chart is likely to be hard to read.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_warning import NumdaplotWarning
+
+
+class ReadabilityWarning(NumdaplotWarning):
+	"""
+	Emitted when a chart is likely to be hard to read, such as a ``PieChart`` of more than 5 slices.
+
+	The Plot is still created. The warning suggests a chart that shows the same values more clearly, or a larger
+	size when only some of the labels naming the values of a chart can be shown.
+
+	Silence it with the standard ``warnings`` module, for one block of code or for a whole script, alone or with every
+	``NumdaplotWarning``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import warnings
+	>>> fruits = ndp.Array.from_list(["apple", "pear", "plum", "fig", "kiwi", "lime"])
+	>>> sales = ndp.Array.from_list([30.0, 25.0, 15.0, 12.0, 10.0, 8.0])
+	>>> shares = ndp.Table.from_arrays({"fruit": fruits, "sales": sales})
+	>>> chart = ndp.PieChart(labels="fruit", values="sales")
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	plot = ndp.Plot.pie(shares, chart)
+	>>> print(caught_warnings[0].message)
+	A PieChart with 6 slices is hard to read. Try ndp.Plot.bar with a BarChart, it may compare them better.
+	"""

numdaplot/errors/refused_operation_error.py

@@ -0,0 +1,64 @@
+"""
+Error raised when an operation is not available on an Array, a Table or a Plot.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+REFUSED_OPERATION_MESSAGE = "{operation} is not available, use {alternative} instead."
+
+
+class RefusedOperationError(NumdaplotError):
+	"""
+	Raised when a Python operation is not available on an Array, a Table or a Plot, such as ``<`` or ``len``.
+
+	Calling the constructor of an Array, a Table or a Plot raises it too.
+
+	The message names the numdaplot method to use instead.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation
+		Description of the refused operation, naming what it applies to.
+	alternative
+		Description of what to use instead.
+
+	Attributes
+	----------
+	operation
+		Description of the refused operation, naming what it applies to.
+	alternative
+		Description of what to use instead.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> array = ndp.Array.from_list([1, 2])
+	>>> try:
+	... 	array < 2
+	... except ndp.RefusedOperationError as error:
+	... 	print(error)
+	Comparing an Array with < is not available, use select or check with a rule such as ndp.Less instead.
+	"""
+
+	def __init__(self, operation: str, alternative: str) -> None:
+		"""
+		Build the error message from the operation and the alternative.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation
+			Description of the refused operation, naming what it applies to.
+		alternative
+			Description of what to use instead.
+		"""
+		message = REFUSED_OPERATION_MESSAGE.format(operation=operation, alternative=alternative)
+		super().__init__(message)
+
+		self.operation = operation
+		self.alternative = alternative

numdaplot/errors/refused_setting_error.py

@@ -0,0 +1,60 @@
+"""
+Error raised when a setting is given to an object that does not accept it.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+REFUSED_SETTING_MESSAGE = "{owner_name} does not accept {setting_name}."
+
+
+class RefusedSettingError(NumdaplotError):
+	"""
+	Raised when a setting is given to an object that does not accept it.
+
+	For example, a ``ScatterChart`` always draws a marker, and only PNG images have a resolution.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	setting_name
+		The refused setting, such as ``MarkerShape.NONE``.
+	owner_name
+		What refuses it, such as ``ScatterChart``.
+
+	Attributes
+	----------
+	setting_name
+		The refused setting, such as ``MarkerShape.NONE``.
+	owner_name
+		What refuses it, such as ``ScatterChart``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.ScatterChart(x="surface", y="price", marker=ndp.MarkerShape.NONE)
+	... except ndp.RefusedSettingError as error:
+	... 	print(error)
+	ScatterChart does not accept MarkerShape.NONE.
+	"""
+
+	def __init__(self, setting_name: str, owner_name: str) -> None:
+		"""
+		Build the error message from the setting and what refuses it.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		setting_name
+			The refused setting, such as ``MarkerShape.NONE``.
+		owner_name
+			What refuses it, such as ``ScatterChart``.
+		"""
+		message = REFUSED_SETTING_MESSAGE.format(setting_name=setting_name, owner_name=owner_name)
+		super().__init__(message)
+		self.setting_name = setting_name
+		self.owner_name = owner_name

numdaplot/errors/rejected_dates.py

@@ -0,0 +1,60 @@
+"""
+Date parts that cannot form a date, given to ValueConversionError.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RejectedDatePart:
+	"""
+	A part of a date that is not a whole number, such as the day 3.5.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	part_name
+		``"year"``, ``"month"`` or ``"day"``.
+	value
+		The rejected number.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.rejected_dates import RejectedDatePart
+	>>> RejectedDatePart("day", 3.5).value
+	3.5
+	"""
+
+	part_name: str
+	value: float
+
+
+@dataclass(frozen=True)
+class RejectedDate:
+	"""
+	A year, a month and a day that form no date, such as the 31st of February.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	year
+		The year.
+	month
+		The month.
+	day
+		The day.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.rejected_dates import RejectedDate
+	>>> RejectedDate(2025, 2, 31).day
+	31
+	"""
+
+	year: int
+	month: int
+	day: int

numdaplot/errors/repeated_key.py

@@ -0,0 +1,36 @@
+"""
+Key repeated in a Table where a join expects each key once, given to JoinRelationError.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class RepeatedKey:
+	"""
+	The first key repeated in a Table, the combination of its values for several key columns.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	key_names
+		The names of the key columns.
+	key_values
+		The value of each key column, in the same order.
+	count
+		The number of rows having these values.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.repeated_key import RepeatedKey
+	>>> RepeatedKey(["Num_Acc"], [202500000001], 3).count
+	3
+	"""
+
+	key_names: list[str]
+	key_values: list[Any]
+	count: int

numdaplot/errors/shape_mismatch_error.py

@@ -0,0 +1,67 @@
+"""
+Error raised when two shapes do not match.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Sequence
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+SHAPE_MISMATCH_MESSAGE = "Expected matching shapes, got {left_dimensions} and {right_dimensions}."
+
+
+class ShapeMismatchError(NumdaplotError):
+	"""
+	Raised when two shapes do not match.
+
+	Two Arrays cannot be combined, a replacement does not fit its region, or a reshape targets a shape
+	holding another number of values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	left_dimensions
+		Dimensions of the first shape.
+	right_dimensions
+		Dimensions of the second shape.
+
+	Attributes
+	----------
+	left_dimensions
+		Dimensions of the first shape, as a list.
+	right_dimensions
+		Dimensions of the second shape, as a list.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> array = ndp.Array.from_list([1, 2, 3])
+	>>> try:
+	... 	array.reshape(ndp.Shape([2, 2]))
+	... except ndp.ShapeMismatchError as error:
+	... 	print(error)
+	Expected matching shapes, got [3] and [2, 2].
+	"""
+
+	def __init__(self, left_dimensions: Sequence[int], right_dimensions: Sequence[int]) -> None:
+		"""
+		Build the error message from the left dimensions and the right dimensions.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		left_dimensions
+			Dimensions of the first shape.
+		right_dimensions
+			Dimensions of the second shape.
+		"""
+		left_list = list(left_dimensions)
+		right_list = list(right_dimensions)
+		message = SHAPE_MISMATCH_MESSAGE.format(left_dimensions=left_list, right_dimensions=right_list)
+		super().__init__(message)
+
+		self.left_dimensions = left_list
+		self.right_dimensions = right_list

numdaplot/errors/time_overflow_error.py

@@ -0,0 +1,131 @@
+"""
+Error raised when dates, datetimes or durations leave the range a count of nanoseconds can hold.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+TIME_OVERFLOW_MESSAGE = "The operation {operation_name} gives values{column_text} outside the range of {range_text}."
+COLUMN_TEXT = " of the column {column_name!r}"
+NO_COLUMN_TEXT = ""
+TYPE_RANGES = {
+	"DATE": "DATE, from 1677 to 2262 in a calculation",
+	"DATETIME": "DATETIME, from 1677 to 2262",
+	"DURATION": "DURATION, about 292 years before or after zero",
+	"TIME": "TIME, from 00:00 to 23:59:59.999999",
+}
+
+
+class TimeOverflowError(NumdaplotError):
+	"""
+	Raised when a value does not fit the nanoseconds counting datetimes and durations.
+
+	Without it, the value would become a wrong date or duration without any notice. A ``DATE`` is stored
+	in days and can be outside this range, but a calculation on it cannot.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation_name
+		The operator or the function, such as ``*``, ``from_list`` or ``ToDuration``.
+	type_name
+		Name of the ``ndp.Type`` member that cannot hold the result: ``DATE``, ``DATETIME``, ``DURATION`` or ``TIME``.
+
+	Attributes
+	----------
+	operation_name
+		The operator or the function, such as ``*``, ``from_list`` or ``ToDuration``.
+	type_name
+		Name of the ``ndp.Type`` member that cannot hold the result.
+	column_name
+		Name of the Table column holding the values, or ``None`` for values given to an Array.
+
+	Examples
+	--------
+	>>> from datetime import timedelta
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Array.from_list([timedelta(days=1)]) * 200000
+	... except ndp.TimeOverflowError as error:
+	... 	print(error)
+	The operation * gives values outside the range of DURATION, about 292 years before or after zero.
+	"""
+
+	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 function, such as ``*``, ``from_list`` or ``ToDuration``.
+		type_name
+			Name of the ``ndp.Type`` member that cannot hold the result.
+		"""
+		self.operation_name = operation_name
+		self.type_name = type_name
+		self.column_name: str | None = None
+		message = self.write_message(NO_COLUMN_TEXT)
+		super().__init__(message)
+
+	def write_message(self, column_text: str) -> str:
+		"""
+		Return the message, with the range of the type.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_text
+			The words naming the column after the values, or an empty text.
+
+		Returns
+		-------
+		str
+			The message.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.TimeOverflowError("+", "DATETIME").write_message("")
+		'The operation + gives values outside the range of DATETIME, from 1677 to 2262.'
+		"""
+		range_text = TYPE_RANGES[self.type_name]
+		message = TIME_OVERFLOW_MESSAGE.format(
+			operation_name=self.operation_name,
+			column_text=column_text,
+			range_text=range_text,
+		)
+
+		return message
+
+	def name_column(self, column_name: str) -> None:
+		"""
+		Name the Table column holding the values 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.TimeOverflowError("convert", "DATETIME")
+		>>> error.name_column("day")
+		>>> print(error)
+		The operation convert gives values of the column 'day' outside the range of DATETIME, from 1677 to 2262.
+		"""
+		if self.column_name is not None:
+			return
+
+		self.column_name = column_name
+		column_text = COLUMN_TEXT.format(column_name=column_name)
+		message = self.write_message(column_text)
+		self.args = (message,)

numdaplot/errors/time_zone_mismatch_error.py

@@ -0,0 +1,83 @@
+"""
+Error raised when datetimes with a time zone meet datetimes without one, or of another time zone.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+TIME_ZONE_MISMATCH_MESSAGE = "{operation} needs datetimes {state} a time zone."
+TIME_ZONE_PAIR_MESSAGE = "{operation} needs datetimes in one time zone, got {zone_names}."
+ZONE_NAME_SEPARATOR = " and "
+WITH_TIME_ZONE = "with"
+WITHOUT_TIME_ZONE = "without"
+
+
+class TimeZoneMismatchError(NumdaplotError):
+	"""
+	Raised when datetimes with a time zone meet datetimes without one, or datetimes of another time zone.
+
+	For example, a rule compares a datetime column with a time zone to a datetime without one,
+	or ``TimeZoneMode.SHIFT`` is asked for datetimes that have no time zone.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation
+		What was attempted, such as ``"Shifting to another time zone"``.
+	expects_time_zone
+		True when the operation needs datetimes with a time zone, False when it needs datetimes without one.
+	zone_names
+		The two time zones met, such as ``["Europe/Paris", "UTC"]``. When omitted, one side has no time zone.
+
+	Attributes
+	----------
+	operation
+		What was attempted.
+	expects_time_zone
+		True when the operation needs datetimes with a time zone, False when it needs datetimes without one.
+	zone_names
+		The two time zones met, or None.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list([datetime(2026, 1, 2, 10, 30)])})
+	>>> paris = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.SHIFT, zone=ndp.TimeZone("Europe/Paris"))
+	>>> try:
+	... 	times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=paris))
+	... except ndp.TimeZoneMismatchError as error:
+	... 	print(error)
+	Shifting to another time zone needs datetimes with a time zone.
+	"""
+
+	def __init__(self, operation: str, expects_time_zone: bool, zone_names: list[str] | None = None) -> None:
+		"""
+		Build the error message from the operation and the time zone state it needs, or the two zones met.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation
+			What was attempted.
+		expects_time_zone
+			True when the operation needs datetimes with a time zone, False when it needs datetimes without one.
+		zone_names
+			The two time zones met. When omitted, one side has no time zone.
+		"""
+		state = WITHOUT_TIME_ZONE
+		if expects_time_zone:
+			state = WITH_TIME_ZONE
+
+		message = TIME_ZONE_MISMATCH_MESSAGE.format(operation=operation, state=state)
+		if zone_names is not None:
+			joined_names = ZONE_NAME_SEPARATOR.join(zone_names)
+			message = TIME_ZONE_PAIR_MESSAGE.format(operation=operation, zone_names=joined_names)
+
+		super().__init__(message)
+		self.operation = operation
+		self.expects_time_zone = expects_time_zone
+		self.zone_names = zone_names

numdaplot/errors/unknown_time_zone_error.py

@@ -0,0 +1,51 @@
+"""
+Error raised when a time zone name is not a known IANA name.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+UNKNOWN_TIME_ZONE_MESSAGE = "Unknown time zone {name!r}, expected an IANA name such as 'Europe/Paris' or 'UTC'."
+
+
+class UnknownTimeZoneError(NumdaplotError):
+	"""
+	Raised when a time zone name is not a known IANA name, such as ``"Paris"`` or ``"+01:00"``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	name
+		The rejected name.
+
+	Attributes
+	----------
+	name
+		The rejected name.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.TimeZone("Paris")
+	... except ndp.UnknownTimeZoneError as error:
+	... 	print(error)
+	Unknown time zone 'Paris', expected an IANA name such as 'Europe/Paris' or 'UTC'.
+	"""
+
+	def __init__(self, name: str) -> None:
+		"""
+		Build the error message from the rejected name.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		name
+			The rejected name.
+		"""
+		message = UNKNOWN_TIME_ZONE_MESSAGE.format(name=name)
+		super().__init__(message)
+		self.name = name

numdaplot/errors/unmatched_value_error.py

@@ -0,0 +1,81 @@
+"""
+Error raised when a value has no new value in a ValueMapping, or is in no bracket of Brackets.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+VALUE_MAPPING_NAME = "ValueMapping"
+BRACKETS_NAME = "Brackets"
+UNMATCHED_MESSAGES = {
+	VALUE_MAPPING_NAME: (
+		"The value {value!r} has no ValueChange. Add one, or give others=Unmatched.MISSING to make it missing."
+	),
+	BRACKETS_NAME: (
+		"The value {value!r} is in no bracket. Open the first or the last bracket, or give others=Unmatched.MISSING "
+		"to make it missing."
+	),
+}
+
+
+class UnmatchedValueError(NumdaplotError):
+	"""
+	Raised when a value has no new value in a ``ValueMapping``, or is in no bracket of ``Brackets``.
+
+	Both raise it while their ``others`` is ``Unmatched.ERROR``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The first value without new value or bracket.
+	setting_name
+		``"ValueMapping"`` by default, or ``"Brackets"``: the setting that found no match, which chooses the advice.
+
+	Attributes
+	----------
+	value
+		The first value without new value or bracket.
+	setting_name
+		The setting that found no match.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> sexes = ndp.Array.from_list([1, 2, 3])
+	>>> try:
+	... 	sexes.apply(ndp.ValueMapping(changes=[ndp.ValueChange(1, "Homme"), ndp.ValueChange(2, "Femme")]))
+	... except ndp.UnmatchedValueError as error:
+	... 	print(error)
+	The value 3 has no ValueChange. Add one, or give others=Unmatched.MISSING to make it missing.
+	>>> ages = ndp.Table.from_arrays({"age": ndp.Array.from_list([5, 105])})
+	>>> brackets = ndp.Brackets(limits=[0, 18, 100])
+	>>> try:
+	... 	ages.convert(ndp.Conversion(column="age", dtype=ndp.Type.CATEGORY, format=brackets))
+	... except ndp.UnmatchedValueError as error:
+	... 	print(error)
+	The value 105 is in no bracket. Open the first or the last bracket,
+	or give others=Unmatched.MISSING to make it missing.
+	"""
+
+	def __init__(self, value: object, setting_name: str = VALUE_MAPPING_NAME) -> None:
+		"""
+		Build the error message from the value and the setting that found no match.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		value
+			The first value without new value or bracket.
+		setting_name
+			The setting that found no match, ``"ValueMapping"`` by default.
+		"""
+		message_template = UNMATCHED_MESSAGES[setting_name]
+		message = message_template.format(value=value)
+		super().__init__(message)
+
+		self.value = value
+		self.setting_name = setting_name