numdaplot 0.1.0__py3-none-any.whl

numdaplot/errors/invalid_position_error.py

@@ -0,0 +1,106 @@
+"""
+Error raised when a position is not a whole number inside its dimension.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_POSITION_MESSAGE = "Expected a whole position between {lowest} and {highest}, got {position}."
+DEFAULT_LOWEST_POSITION = 0
+MINIMUM_POSITION_MESSAGE = "Expected a whole position of at least {lowest}, got {position}."
+
+
+class InvalidPositionError(NumdaplotError):
+	"""
+	Raised when a position falls outside its dimension.
+
+	A dimension of size 5 accepts the positions from -5 to 4. Without a size, as when an ``Index`` or a ``Cell`` is
+	created, the message names the lowest accepted position.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	position
+		The rejected position.
+	size
+		Size of the dimension. When omitted, the size is not known yet, as when an ``Index`` is created.
+	lowest
+		The lowest accepted position, named when the size is not known, 0 by default.
+
+	Attributes
+	----------
+	position
+		The rejected position.
+	size
+		Size of the dimension, or None.
+	lowest
+		The lowest accepted position.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> array = ndp.Array.from_list([1, 2, 3])
+	>>> try:
+	... 	array.take(ndp.Region(rows=ndp.Index(5)))
+	... except ndp.InvalidPositionError as error:
+	... 	print(error)
+	Expected a whole position between -3 and 2, got 5.
+	"""
+
+	def __init__(self, position: object, size: int | None = None, lowest: int = DEFAULT_LOWEST_POSITION) -> None:
+		"""
+		Build the error message from the position, and the size or the lowest accepted position.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		position
+			The rejected position.
+		size
+			Size of the dimension. When omitted, the size is not known yet, as when an ``Index`` is created.
+		lowest
+			The lowest accepted position, named when the size is not known, 0 by default.
+		"""
+		message = build_position_message(position, size, lowest)
+		super().__init__(message)
+
+		self.position = position
+		self.size = size
+		self.lowest = lowest
+
+
+def build_position_message(position: object, size: int | None, lowest: int) -> str:
+	"""
+	Return the message of a rejected position, naming the accepted positions that are known.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	position
+		The rejected position.
+	size
+		Size of the dimension, or None.
+	lowest
+		The lowest accepted position.
+
+	Returns
+	-------
+	str
+		The message naming the accepted interval, or the lowest accepted position.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.invalid_position_error import build_position_message
+	>>> build_position_message(-1, None, 0)
+	'Expected a whole position of at least 0, got -1.'
+	"""
+	if size is not None:
+		highest_position = size - 1
+		message = INVALID_POSITION_MESSAGE.format(lowest=-size, highest=highest_position, position=position)
+		return message
+
+	return MINIMUM_POSITION_MESSAGE.format(lowest=lowest, position=position)

numdaplot/errors/invalid_resolution_error.py

@@ -0,0 +1,51 @@
+"""
+Error raised when an image resolution is lower than 1 dot per inch.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_RESOLUTION_MESSAGE = "Expected a resolution of at least 1 dot per inch, got {dpi}."
+
+
+class InvalidResolutionError(NumdaplotError):
+	"""
+	Raised when the ``dpi`` of ``ImageOptions`` is lower than 1.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	dpi
+		The rejected number of dots per inch.
+
+	Attributes
+	----------
+	dpi
+		The rejected number of dots per inch.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.ImageOptions(dpi=0)
+	... except ndp.InvalidResolutionError as error:
+	... 	print(error)
+	Expected a resolution of at least 1 dot per inch, got 0.
+	"""
+
+	def __init__(self, dpi: int) -> None:
+		"""
+		Build the error message from the rejected resolution.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		dpi
+			The rejected number of dots per inch.
+		"""
+		message = INVALID_RESOLUTION_MESSAGE.format(dpi=dpi)
+		super().__init__(message)
+		self.dpi = dpi

numdaplot/errors/invalid_rotation_error.py

@@ -0,0 +1,53 @@
+"""
+Error raised when a rotation is outside the accepted angles.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_ROTATION_MESSAGE = "Expected a rotation from -90 to 90 degrees, got {rotation}."
+
+
+class InvalidRotationError(NumdaplotError):
+	"""
+	Raised when the ``x_tick_rotation`` or the ``y_tick_rotation`` of a ``PlotStyle`` is outside -90 to 90 degrees.
+
+	Beyond these angles, the labels would be written upside down.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	rotation
+		The rotation given.
+
+	Attributes
+	----------
+	rotation
+		The rotation given.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.PlotStyle(x_tick_rotation=120)
+	... except ndp.InvalidRotationError as error:
+	... 	print(error)
+	Expected a rotation from -90 to 90 degrees, got 120.
+	"""
+
+	def __init__(self, rotation: float) -> None:
+		"""
+		Build the error message from the rotation.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		rotation
+			The rotation given.
+		"""
+		message = INVALID_ROTATION_MESSAGE.format(rotation=rotation)
+		super().__init__(message)
+		self.rotation = rotation

numdaplot/errors/invalid_seed_error.py

@@ -0,0 +1,53 @@
+"""
+Error raised when a random seed is negative.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_SEED_MESSAGE = "Expected a seed of at least 0, got {seed}."
+
+
+class InvalidSeedError(NumdaplotError):
+	"""
+	Raised when a random draw is given a negative seed.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	seed
+		The rejected seed.
+
+	Attributes
+	----------
+	seed
+		The rejected seed.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> dice = ndp.RandomIntegers(low=1, high=6)
+	>>> try:
+	... 	ndp.Array.random(dice, shape=ndp.Shape([3]), seed=-1)
+	... except ndp.InvalidSeedError as error:
+	... 	print(error)
+	Expected a seed of at least 0, got -1.
+	"""
+
+	def __init__(self, seed: int) -> None:
+		"""
+		Build the error message from the seed.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		seed
+			The rejected seed.
+		"""
+		message = INVALID_SEED_MESSAGE.format(seed=seed)
+		super().__init__(message)
+
+		self.seed = seed

numdaplot/errors/invalid_separator_error.py

@@ -0,0 +1,52 @@
+"""
+Error raised when a CSV separator is not exactly one character.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_SEPARATOR_MESSAGE = "Expected a separator of exactly one character, got {separator!r}."
+
+
+class InvalidSeparatorError(NumdaplotError):
+	"""
+	Raised when the separator of ``CsvReadOptions`` or ``CsvWriteOptions`` is empty or longer than one character.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	separator
+		The rejected separator.
+
+	Attributes
+	----------
+	separator
+		The rejected separator.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.CsvReadOptions(separator=";;")
+	... except ndp.InvalidSeparatorError as error:
+	... 	print(error)
+	Expected a separator of exactly one character, got ';;'.
+	"""
+
+	def __init__(self, separator: str) -> None:
+		"""
+		Build the error message from the separator.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		separator
+			The rejected separator.
+		"""
+		message = INVALID_SEPARATOR_MESSAGE.format(separator=separator)
+		super().__init__(message)
+
+		self.separator = separator

numdaplot/errors/invalid_shape_error.py

@@ -0,0 +1,52 @@
+"""
+Error raised when a shape has no dimension or a negative dimension.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_SHAPE_MESSAGE = "Expected at least one dimension and no negative dimension, got {dimensions}."
+
+
+class InvalidShapeError(NumdaplotError):
+	"""
+	Raised when a shape has no dimension at all, or a dimension lower than 0.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	dimensions
+		The rejected dimensions.
+
+	Attributes
+	----------
+	dimensions
+		The rejected dimensions.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Shape([3, -1])
+	... except ndp.InvalidShapeError as error:
+	... 	print(error)
+	Expected at least one dimension and no negative dimension, got [3, -1].
+	"""
+
+	def __init__(self, dimensions: list[int]) -> None:
+		"""
+		Build the error message from the dimensions.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		dimensions
+			The rejected dimensions.
+		"""
+		message = INVALID_SHAPE_MESSAGE.format(dimensions=dimensions)
+		super().__init__(message)
+
+		self.dimensions = dimensions

numdaplot/errors/invalid_sheet_name_error.py

@@ -0,0 +1,54 @@
+"""
+Error raised when an Excel sheet name is not accepted by Excel.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_SHEET_NAME_MESSAGE = "Expected a sheet name of 1 to 31 characters without [ ] : * ? / \\, got {sheet!r}."
+
+
+class InvalidSheetNameError(NumdaplotError):
+	r"""
+	Raised when Excel would refuse the sheet name of ``ExcelReadOptions`` or ``ExcelWriteOptions``.
+
+	The name is empty, longer than 31 characters, or holds ``[ ] : * ? / \``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	sheet
+		The rejected sheet name.
+
+	Attributes
+	----------
+	sheet
+		The rejected sheet name.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.ExcelWriteOptions(sheet="Sales/2026")
+	... except ndp.InvalidSheetNameError as error:
+	... 	print(error)
+	Expected a sheet name of 1 to 31 characters without [ ] : * ? / \, got 'Sales/2026'.
+	"""
+
+	def __init__(self, sheet: str) -> None:
+		"""
+		Build the error message from the sheet name.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		sheet
+			The rejected sheet name.
+		"""
+		message = INVALID_SHEET_NAME_MESSAGE.format(sheet=sheet)
+		super().__init__(message)
+
+		self.sheet = sheet

numdaplot/errors/invalid_size_error.py

@@ -0,0 +1,58 @@
+"""
+Error raised when a size is not positive.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_SIZE_MESSAGE = "Expected a positive width and height, got {width} and {height}."
+
+
+class InvalidSizeError(NumdaplotError):
+	"""
+	Raised when the width or the height of a ``Size`` is zero or negative.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	width
+		The width given.
+	height
+		The height given.
+
+	Attributes
+	----------
+	width
+		The width given.
+	height
+		The height given.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Size(width=0, height=4.8)
+	... except ndp.InvalidSizeError as error:
+	... 	print(error)
+	Expected a positive width and height, got 0 and 4.8.
+	"""
+
+	def __init__(self, width: float, height: float) -> None:
+		"""
+		Build the error message from the width and the height.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		width
+			The width given.
+		height
+			The height given.
+		"""
+		message = INVALID_SIZE_MESSAGE.format(width=width, height=height)
+		super().__init__(message)
+		self.width = width
+		self.height = height

numdaplot/errors/invalid_step_error.py

@@ -0,0 +1,77 @@
+"""
+Error raised when the step of a range is zero, or goes away from its stop.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_STEP_MESSAGE = "Expected a non-zero step, got {step}."
+WRONG_DIRECTION_MESSAGE = "Expected a step going from start to stop, got step {step} from {start} to {stop}."
+
+
+class InvalidStepError(NumdaplotError):
+	"""
+	Raised when a range is given a step of zero, or a step going away from its stop, which never reach the stop.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	step
+		The rejected step.
+	start
+		The start of the range when the step goes away from the stop. When omitted, the message is about a step of zero.
+	stop
+		The stop of the range when the step goes away from it. When omitted, the message is about a step of zero.
+
+	Attributes
+	----------
+	step
+		The rejected step.
+	start
+		The start of the range, or None for a step of zero.
+	stop
+		The stop of the range, or None for a step of zero.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Range(start=0, stop=10, step=0)
+	... except ndp.InvalidStepError as error:
+	... 	print(error)
+	Expected a non-zero step, got 0.
+	>>> try:
+	... 	ndp.Range(start=5, stop=1)
+	... except ndp.InvalidStepError as error:
+	... 	print(error)
+	Expected a step going from start to stop, got step 1 from 5 to 1.
+	"""
+
+	def __init__(self, step: float, start: float | None = None, stop: float | None = None) -> None:
+		"""
+		Build the error message from the rejected step, and the start and the stop when the step goes away.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		step
+			The rejected step.
+		start
+			The start of the range when the step goes away from the stop. When omitted, the message is about a step of
+			zero.
+		stop
+			The stop of the range when the step goes away from it. When omitted, the message is about a step of zero.
+		"""
+		if start is None or stop is None:
+			message = INVALID_STEP_MESSAGE.format(step=step)
+		else:
+			message = WRONG_DIRECTION_MESSAGE.format(step=step, start=start, stop=stop)
+
+		super().__init__(message)
+
+		self.step = step
+		self.start = start
+		self.stop = stop

numdaplot/errors/invalid_suffixes_error.py

@@ -0,0 +1,61 @@
+"""
+Error raised when the suffixes of a join are empty or the same.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+INVALID_SUFFIXES_MESSAGE = "Expected two different non-empty suffixes, got {left!r} and {right!r}."
+
+
+class InvalidSuffixesError(NumdaplotError):
+	"""
+	Raised when a ``JoinSuffixes`` has an empty suffix, or the same suffix on both sides.
+
+	Either would leave two columns of a join with the same name.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	left
+		The suffix of the columns of the joined Table.
+	right
+		The suffix of the columns of the other Table.
+
+	Attributes
+	----------
+	left
+		The suffix of the columns of the joined Table.
+	right
+		The suffix of the columns of the other Table.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.JoinSuffixes(left="_2025", right="_2025")
+	... except ndp.InvalidSuffixesError as error:
+	... 	print(error)
+	Expected two different non-empty suffixes, got '_2025' and '_2025'.
+	"""
+
+	def __init__(self, left: str, right: str) -> None:
+		"""
+		Build the error message from the two suffixes.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		left
+			The suffix of the columns of the joined Table.
+		right
+			The suffix of the columns of the other Table.
+		"""
+		message = INVALID_SUFFIXES_MESSAGE.format(left=left, right=right)
+		super().__init__(message)
+
+		self.left = left
+		self.right = right

numdaplot/errors/invalid_time_zone_change_error.py

@@ -0,0 +1,63 @@
+"""
+Error raised when a time zone change has a zone it does not use, or misses the zone it needs.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+MISSING_ZONE_MESSAGE = "TimeZoneMode.{mode_name} needs a zone."
+EXTRA_ZONE_MESSAGE = "TimeZoneMode.{mode_name} takes no zone."
+
+
+class InvalidTimeZoneChangeError(NumdaplotError):
+	"""
+	Raised when ``TimeZoneMode.ATTRIBUTE`` or ``SHIFT`` has no zone, or ``TimeZoneMode.REMOVE`` has one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	mode_name
+		Name of the ``TimeZoneMode`` member of the change.
+	needs_zone
+		True when the mode needs a zone that is missing, False when it has a zone it does not use.
+
+	Attributes
+	----------
+	mode_name
+		Name of the ``TimeZoneMode`` member of the change.
+	needs_zone
+		True when the mode needs a zone that is missing, False when it has a zone it does not use.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.TimeZoneChange(mode=ndp.TimeZoneMode.SHIFT)
+	... except ndp.InvalidTimeZoneChangeError as error:
+	... 	print(error)
+	TimeZoneMode.SHIFT needs a zone.
+	"""
+
+	def __init__(self, mode_name: str, needs_zone: bool) -> None:
+		"""
+		Build the error message from the mode and whether its zone is missing or extra.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		mode_name
+			Name of the ``TimeZoneMode`` member of the change.
+		needs_zone
+			True when the mode needs a zone that is missing, False when it has a zone it does not use.
+		"""
+		message_template = EXTRA_ZONE_MESSAGE
+		if needs_zone:
+			message_template = MISSING_ZONE_MESSAGE
+
+		message = message_template.format(mode_name=mode_name)
+		super().__init__(message)
+		self.mode_name = mode_name
+		self.needs_zone = needs_zone