numdaplot 0.1.0__py3-none-any.whl

numdaplot/errors/invalid_column_name_error.py

@@ -0,0 +1,52 @@
+"""
+Error raised when a column name is not a non-empty text.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_COLUMN_NAME_MESSAGE = "Expected a column name as a non-empty text, got {column_name!r}."
+
+
+class InvalidColumnNameError(NumdaplotError):
+	"""
+	Raised when a column name is empty or is not a text, such as a number in a pandas DataFrame.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column_name
+		The rejected name.
+
+	Attributes
+	----------
+	column_name
+		The rejected name.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.NameChange(old_name="price", new_name="")
+	... except ndp.InvalidColumnNameError as error:
+	... 	print(error)
+	Expected a column name as a non-empty text, got ''.
+	"""
+
+	def __init__(self, column_name: object) -> None:
+		"""
+		Build the error message from the column name.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_name
+			The rejected name.
+		"""
+		message = INVALID_COLUMN_NAME_MESSAGE.format(column_name=column_name)
+		super().__init__(message)
+
+		self.column_name = column_name

numdaplot/errors/invalid_conversion_error.py

@@ -0,0 +1,119 @@
+"""
+Error raised when a setting of a conversion does not apply to it.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_CONVERSION_MESSAGE = (
+	"The setting {setting_name} does not apply to a conversion from {source_type_name} to {target_type_name}."
+)
+DATE_FORMAT_ON_TIME_MESSAGE = (
+	"The format {date_format_name} has a date, which TIME cannot hold. Give a CustomDateFormat of a time only, "
+	'such as "%H:%M".'
+)
+TIME_TYPE_NAME = "TIME"
+TIME_FORMAT_ON_DATE_MESSAGE = (
+	"The format {date_format_name} has a time, which DATE cannot hold. "
+	"Convert the column to DATETIME first, then to {target_type_name}."
+)
+
+
+class InvalidConversionError(NumdaplotError):
+	"""
+	Raised when a setting of a ``Conversion`` does not apply to the types it converts.
+
+	For example, a date format given to a conversion between numbers, a format with a time given to
+	a ``DATE`` column, or a time zone change given to a conversion from texts.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	setting_name
+		Name of the setting, such as ``"format"``.
+	source_type_name
+		Name of the ``ndp.Type`` member of the column.
+	target_type_name
+		Name of the ``ndp.Type`` member it is converted to.
+	date_format_name
+		The name or the pattern of a format with a time, when dates are read or written with it. When omitted, the
+		message names the setting and the types.
+
+	Attributes
+	----------
+	setting_name
+		Name of the setting.
+	source_type_name
+		Name of the ``ndp.Type`` member of the column.
+	target_type_name
+		Name of the ``ndp.Type`` member it is converted to.
+	date_format_name
+		The name or the pattern of a format with a time used on dates, ``None`` for other conversions.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([12.5])})
+	>>> day_first = ndp.DateFormat.DAY_MONTH_YEAR
+	>>> try:
+	... 	prices.convert(ndp.Conversion(column="price", dtype=ndp.Type.TEXT, format=day_first))
+	... except ndp.InvalidConversionError as error:
+	... 	print(error)
+	The setting format does not apply to a conversion from FLOAT64 to TEXT.
+	>>> days = ndp.Table.from_arrays({"day": ndp.Array.from_list(["31/12/2026 14:30"])})
+	>>> day_and_time = ndp.DateFormat.DAY_MONTH_YEAR_TIME
+	>>> try:
+	... 	days.convert(ndp.Conversion(column="day", dtype=ndp.Type.DATE, format=day_and_time))
+	... except ndp.InvalidConversionError as error:
+	... 	print(error)
+	The format DAY_MONTH_YEAR_TIME has a time, which DATE cannot hold.
+	Convert the column to DATETIME first, then to DATE.
+	"""
+
+	def __init__(
+		self,
+		setting_name: str,
+		source_type_name: str,
+		target_type_name: str,
+		date_format_name: str | None = None,
+	) -> None:
+		"""
+		Build the error message from the setting and the types of the conversion.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		setting_name
+			Name of the setting.
+		source_type_name
+			Name of the ``ndp.Type`` member of the column.
+		target_type_name
+			Name of the ``ndp.Type`` member it is converted to.
+		date_format_name
+			The name or the pattern of a format with a time, when dates are read or written with it, or of a format with
+			a date, when times of day are read or written with it. When omitted, the message names the setting and the
+			types.
+		"""
+		message = INVALID_CONVERSION_MESSAGE.format(
+			setting_name=setting_name,
+			source_type_name=source_type_name,
+			target_type_name=target_type_name,
+		)
+		converts_times = TIME_TYPE_NAME in (source_type_name, target_type_name)
+		if date_format_name is not None and converts_times:
+			message = DATE_FORMAT_ON_TIME_MESSAGE.format(date_format_name=date_format_name)
+
+		if date_format_name is not None and not converts_times:
+			message = TIME_FORMAT_ON_DATE_MESSAGE.format(
+				date_format_name=date_format_name,
+				target_type_name=target_type_name,
+			)
+
+		super().__init__(message)
+		self.setting_name = setting_name
+		self.source_type_name = source_type_name
+		self.target_type_name = target_type_name
+		self.date_format_name = date_format_name

numdaplot/errors/invalid_count_error.py

@@ -0,0 +1,61 @@
+"""
+Error raised when a count of values is too low.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_COUNT_MESSAGE = "Expected a count of at least {minimum}, got {count}."
+
+
+class InvalidCountError(NumdaplotError):
+	"""
+	Raised when a count of values is lower than the minimum it needs.
+
+	``Spacing`` needs at least 2 values when both bounds are included, and at least 1 otherwise.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	count
+		The rejected count.
+	minimum
+		The lowest accepted count.
+
+	Attributes
+	----------
+	count
+		The rejected count.
+	minimum
+		The lowest accepted count.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Spacing(start=0, stop=1, count=0)
+	... except ndp.InvalidCountError as error:
+	... 	print(error)
+	Expected a count of at least 2, got 0.
+	"""
+
+	def __init__(self, count: int, minimum: int) -> None:
+		"""
+		Build the error message from the count and the minimum.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		count
+			The rejected count.
+		minimum
+			The lowest accepted count.
+		"""
+		message = INVALID_COUNT_MESSAGE.format(count=count, minimum=minimum)
+		super().__init__(message)
+
+		self.count = count
+		self.minimum = minimum

numdaplot/errors/invalid_date_format_error.py

@@ -0,0 +1,51 @@
+"""
+Error raised when a custom date pattern cannot read dates.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_DATE_FORMAT_MESSAGE = "Expected a pattern with a date or a time code and no time zone code, got {pattern!r}."
+
+
+class InvalidDateFormatError(NumdaplotError):
+	"""
+	Raised when a custom pattern has no date nor time code, or has a time zone code.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	pattern
+		The rejected pattern.
+
+	Attributes
+	----------
+	pattern
+		The rejected pattern.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.CustomDateFormat("%d/%m/%Y %z")
+	... except ndp.InvalidDateFormatError as error:
+	... 	print(error)
+	Expected a pattern with a date or a time code and no time zone code, got '%d/%m/%Y %z'.
+	"""
+
+	def __init__(self, pattern: str) -> None:
+		"""
+		Build the error message from the rejected pattern.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		pattern
+			The rejected pattern.
+		"""
+		message = INVALID_DATE_FORMAT_MESSAGE.format(pattern=pattern)
+		super().__init__(message)
+		self.pattern = pattern

numdaplot/errors/invalid_deviation_error.py

@@ -0,0 +1,52 @@
+"""
+Error raised when a standard deviation is negative.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_DEVIATION_MESSAGE = "Expected a deviation of at least 0, got {deviation}."
+
+
+class InvalidDeviationError(NumdaplotError):
+	"""
+	Raised when a normal distribution is given a negative standard deviation.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	deviation
+		The rejected standard deviation.
+
+	Attributes
+	----------
+	deviation
+		The rejected standard deviation.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Normal(mean=0, deviation=-1)
+	... except ndp.InvalidDeviationError as error:
+	... 	print(error)
+	Expected a deviation of at least 0, got -1.
+	"""
+
+	def __init__(self, deviation: float) -> None:
+		"""
+		Build the error message from the deviation.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		deviation
+			The rejected standard deviation.
+		"""
+		message = INVALID_DEVIATION_MESSAGE.format(deviation=deviation)
+		super().__init__(message)
+
+		self.deviation = deviation

numdaplot/errors/invalid_fraction_error.py

@@ -0,0 +1,51 @@
+"""
+Error raised when a fraction is outside 0 to 1.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_FRACTION_MESSAGE = "Expected a fraction between 0 and 1, got {value}."
+
+
+class InvalidFractionError(NumdaplotError):
+	"""
+	Raised when a value expected to be a fraction is lower than 0, greater than 1 or not a number.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		The rejected value.
+
+	Attributes
+	----------
+	value
+		The rejected value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Quantile(1.5)
+	... except ndp.InvalidFractionError as error:
+	... 	print(error)
+	Expected a fraction between 0 and 1, got 1.5.
+	"""
+
+	def __init__(self, value: float) -> None:
+		"""
+		Build the error message from the rejected value.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		value
+			The rejected value.
+		"""
+		message = INVALID_FRACTION_MESSAGE.format(value=value)
+		super().__init__(message)
+		self.value = value

numdaplot/errors/invalid_label_count_error.py

@@ -0,0 +1,61 @@
+"""
+Error raised when Brackets are not given exactly one label per bracket.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_LABEL_COUNT_MESSAGE = "Expected {bracket_count} labels, one per bracket, got {label_count}."
+
+
+class InvalidLabelCountError(NumdaplotError):
+	"""
+	Raised when the labels of ``Brackets`` are not exactly one per bracket.
+
+	There is one bracket between two limits, plus one for each open end.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	bracket_count
+		The number of brackets.
+	label_count
+		The number of labels given.
+
+	Attributes
+	----------
+	bracket_count
+		The number of brackets.
+	label_count
+		The number of labels given.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Brackets(limits=[0, 18, 65], labels=["child", "adult", "senior"])
+	... except ndp.InvalidLabelCountError as error:
+	... 	print(error)
+	Expected 2 labels, one per bracket, got 3.
+	"""
+
+	def __init__(self, bracket_count: int, label_count: int) -> None:
+		"""
+		Build the error message from the two counts.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		bracket_count
+			The number of brackets.
+		label_count
+			The number of labels given.
+		"""
+		message = INVALID_LABEL_COUNT_MESSAGE.format(bracket_count=bracket_count, label_count=label_count)
+		super().__init__(message)
+
+		self.bracket_count = bracket_count
+		self.label_count = label_count

numdaplot/errors/invalid_limits_error.py

@@ -0,0 +1,111 @@
+"""
+Error raised when the limits of Brackets do not form valid brackets.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+TOO_FEW_LIMITS_MESSAGE = "Expected at least 2 limits, or 1 with an open first or last bracket, got {limit_count}."
+UNORDERED_LIMITS_MESSAGE = "Expected limits in strictly increasing order, got {later_limit} after {earlier_limit}."
+EMPTY_BRACKET_MESSAGE = "The bracket from {low} to {high} holds no integer."
+
+
+class InvalidLimitsError(NumdaplotError):
+	"""
+	Raised when the limits of ``Brackets`` do not form valid brackets.
+
+	The limits must strictly increase, and form at least one bracket. On a column of integers, each bracket between two
+	limits must hold an integer.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	limits
+		The limits of the brackets.
+	empty_bracket
+		The low and the high limit of a bracket holding no integer, when the limits are valid but that bracket is not.
+		When omitted, the limits themselves are wrong.
+
+	Attributes
+	----------
+	limits
+		The limits of the brackets.
+	empty_bracket
+		The limits of the bracket holding no integer, ``None`` when the limits themselves are wrong.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Brackets(limits=[0, 10, 10])
+	... except ndp.InvalidLimitsError as error:
+	... 	print(error)
+	Expected limits in strictly increasing order, got 10 after 10.
+	>>> try:
+	... 	ndp.Brackets(limits=[0])
+	... except ndp.InvalidLimitsError as error:
+	... 	print(error)
+	Expected at least 2 limits, or 1 with an open first or last bracket, got 1.
+	"""
+
+	def __init__(self, limits: list[int | float], empty_bracket: list[int | float] | None = None) -> None:
+		"""
+		Build the error message from the first problem of the limits.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		limits
+			The limits of the brackets.
+		empty_bracket
+			The low and the high limit of a bracket holding no integer. When omitted, the limits themselves are wrong.
+		"""
+		message = write_limits_message(limits, empty_bracket)
+		super().__init__(message)
+
+		self.limits = limits
+		self.empty_bracket = empty_bracket
+
+
+def write_limits_message(limits: list[int | float], empty_bracket: list[int | float] | None) -> str:
+	"""
+	Return the message naming the first problem of the limits of brackets.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	limits
+		The limits of the brackets.
+	empty_bracket
+		The low and the high limit of a bracket holding no integer, or None.
+
+	Returns
+	-------
+	str
+		The empty bracket, else the first limit not greater than the previous one, else the number of limits.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.invalid_limits_error import write_limits_message
+	>>> write_limits_message([5.2, 5.8], [5.2, 5.8])
+	'The bracket from 5.2 to 5.8 holds no integer.'
+	"""
+	if empty_bracket is not None:
+		low, high = empty_bracket
+		empty_message = EMPTY_BRACKET_MESSAGE.format(low=low, high=high)
+		return empty_message
+
+	for earlier_limit, later_limit in zip(limits, limits[1:], strict=False):
+		is_greater = later_limit > earlier_limit
+		if not is_greater:
+			unordered_message = UNORDERED_LIMITS_MESSAGE.format(earlier_limit=earlier_limit, later_limit=later_limit)
+			return unordered_message
+
+	limit_count = len(limits)
+	too_few_message = TOO_FEW_LIMITS_MESSAGE.format(limit_count=limit_count)
+
+	return too_few_message

numdaplot/errors/invalid_opacity_error.py

@@ -0,0 +1,52 @@
+"""
+Error raised when an opacity is outside what can be drawn.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_OPACITY_MESSAGE = "Expected an opacity above 0 and up to 1, got {opacity}."
+
+
+class InvalidOpacityError(NumdaplotError):
+	"""
+	Raised when an opacity is 0 or lower, which would draw nothing, greater than 1, or not a number.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	opacity
+		The rejected opacity.
+
+	Attributes
+	----------
+	opacity
+		The rejected opacity.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.ScatterChart(opacity=0.0)
+	... except ndp.InvalidOpacityError as error:
+	... 	print(error)
+	Expected an opacity above 0 and up to 1, got 0.0.
+	"""
+
+	def __init__(self, opacity: float) -> None:
+		"""
+		Build the error message from the opacity.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		opacity
+			The rejected opacity.
+		"""
+		message = INVALID_OPACITY_MESSAGE.format(opacity=opacity)
+		super().__init__(message)
+
+		self.opacity = opacity

numdaplot/errors/invalid_point_size_error.py

@@ -0,0 +1,52 @@
+"""
+Error raised when the size of a point cannot be drawn.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_POINT_SIZE_MESSAGE = "Expected a point size above 0, got {point_size}."
+
+
+class InvalidPointSizeError(NumdaplotError):
+	"""
+	Raised when the size of a point is 0 or lower, infinite, or not a number.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	point_size
+		The rejected size.
+
+	Attributes
+	----------
+	point_size
+		The rejected size.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.ScatterChart(point_size=-1.0)
+	... except ndp.InvalidPointSizeError as error:
+	... 	print(error)
+	Expected a point size above 0, got -1.0.
+	"""
+
+	def __init__(self, point_size: float) -> None:
+		"""
+		Build the error message from the size.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		point_size
+			The rejected size.
+		"""
+		message = INVALID_POINT_SIZE_MESSAGE.format(point_size=point_size)
+		super().__init__(message)
+
+		self.point_size = point_size