numdaplot 0.1.0__py3-none-any.whl

numdaplot/dates/time_zone.py

@@ -0,0 +1,68 @@
+"""
+A time zone of the IANA database.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from numdaplot.errors.unknown_time_zone_error import UnknownTimeZoneError
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class TimeZone:
+	"""
+	A time zone of the IANA database, such as ``"Europe/Paris"`` or ``"UTC"``, used by ``TimeZoneChange``.
+
+	A zone follows the summer and winter time changes of its place. Fixed offsets such as ``"+01:00"``
+	are not time zones.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	name
+		The IANA name of the zone.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	UnknownTimeZoneError
+		When the name is not a known IANA name.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list([datetime(2026, 7, 1, 10, 30)])})
+	>>> paris = ndp.TimeZone("Europe/Paris")
+	>>> in_paris = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.ATTRIBUTE, zone=paris)
+	>>> paris_times = times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=in_paris))
+	>>> paris_times.column_time_zones
+	{'time': TimeZone(name='Europe/Paris')}
+	"""
+
+	name: str
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the name is a known IANA name.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		UnknownTimeZoneError
+			When the name is not a known IANA name.
+		"""
+		require_field_types(self)
+
+		try:
+			ZoneInfo(self.name)
+		except (ZoneInfoNotFoundError, ValueError) as error:
+			raise UnknownTimeZoneError(self.name) from error

numdaplot/dates/time_zone_change.py

@@ -0,0 +1,71 @@
+"""
+A change of the time zone of a datetime column.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.dates.time_zone import TimeZone
+from numdaplot.dates.time_zone_mode import TimeZoneMode
+from numdaplot.errors.invalid_time_zone_change_error import InvalidTimeZoneChangeError
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class TimeZoneChange:
+	"""
+	A change of the time zone of a datetime column, used by ``Conversion``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	mode
+		Whether a zone is given to datetimes without one, datetimes are moved to another zone, or their zone
+		is removed.
+	zone
+		The new zone, needed by ``TimeZoneMode.ATTRIBUTE`` and ``SHIFT``. ``REMOVE`` refuses it, so it is the only mode
+		used when omitted.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidTimeZoneChangeError
+		When ``ATTRIBUTE`` or ``SHIFT`` has no zone, or ``REMOVE`` has one.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list([datetime(2026, 7, 1, 10, 30)])})
+	>>> paris = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.ATTRIBUTE, zone=ndp.TimeZone("Europe/Paris"))
+	>>> times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=paris))
+	                       time
+	      DATETIME Europe/Paris
+	0 2026-07-01 10:30:00+02:00
+	"""
+
+	mode: TimeZoneMode
+	zone: TimeZone | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the zone is given exactly when the mode needs it.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidTimeZoneChangeError
+			When ``ATTRIBUTE`` or ``SHIFT`` has no zone, or ``REMOVE`` has one.
+		"""
+		require_field_types(self)
+
+		needs_zone = self.mode != TimeZoneMode.REMOVE
+		has_zone = self.zone is not None
+		if needs_zone != has_zone:
+			raise InvalidTimeZoneChangeError(self.mode.name, needs_zone)

numdaplot/dates/time_zone_mode.py

@@ -0,0 +1,81 @@
+"""
+How the time zone of a datetime column changes.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class TimeZoneMode(Enum):
+	"""
+	How the time zone of a datetime column changes, used by ``TimeZoneChange``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list([datetime(2026, 7, 1, 10, 30)])})
+	>>> paris = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.ATTRIBUTE, zone=ndp.TimeZone("Europe/Paris"))
+	>>> times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=paris))
+	                       time
+	      DATETIME Europe/Paris
+	0 2026-07-01 10:30:00+02:00
+	"""
+
+	ATTRIBUTE = auto()
+	"""
+	Gives a zone to datetimes without one: the clock time stays the same.
+
+	A time that does not exist in the zone, or exists twice when the clocks change, raises
+	``ValueConversionError``.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list([datetime(2026, 7, 1, 10, 30)])})
+	>>> paris = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.ATTRIBUTE, zone=ndp.TimeZone("Europe/Paris"))
+	>>> times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=paris))
+	                       time
+	      DATETIME Europe/Paris
+	0 2026-07-01 10:30:00+02:00
+	"""
+
+	SHIFT = auto()
+	"""
+	Moves datetimes with a zone to another zone: the instant stays the same, the clock time changes.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list([datetime(2026, 7, 1, 10, 30)])})
+	>>> utc = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.ATTRIBUTE, zone=ndp.TimeZone("UTC"))
+	>>> utc_times = times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=utc))
+	>>> paris = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.SHIFT, zone=ndp.TimeZone("Europe/Paris"))
+	>>> utc_times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=paris))
+	                       time
+	      DATETIME Europe/Paris
+	0 2026-07-01 12:30:00+02:00
+	"""
+
+	REMOVE = auto()
+	"""
+	Removes the zone of datetimes: the clock time stays the same.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list([datetime(2026, 7, 1, 10, 30)])})
+	>>> paris = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.ATTRIBUTE, zone=ndp.TimeZone("Europe/Paris"))
+	>>> paris_times = times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=paris))
+	>>> no_zone = ndp.TimeZoneChange(mode=ndp.TimeZoneMode.REMOVE)
+	>>> paris_times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, timezone=no_zone))
+	                 time
+	             DATETIME
+	0 2026-07-01 10:30:00
+	"""

numdaplot/dates/to_duration.py

@@ -0,0 +1,58 @@
+"""
+Each number read as a duration in a unit.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.dates.duration_unit import DurationUnit
+from numdaplot.dates.time_function import TimeFunction
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class ToDuration(TimeFunction):
+	"""
+	Each number read as a duration in a unit: 1.5 in days gives 36 hours.
+
+	The result is a ``DURATION`` Array, rounded to the nanosecond. Applies to integers and decimals, not to
+	booleans. ``DurationIn`` does the opposite.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	unit
+		The unit of the numbers.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	TimeOverflowError
+		When ``Array.apply`` meets a number that gives a duration beyond about 292 years.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> nights = ndp.Array.from_list([3, 10])
+	>>> nights.apply(ndp.ToDuration(unit=ndp.DurationUnit.DAY))
+	Array(['3 days 00:00:00', '10 days 00:00:00'], dtype=DURATION)
+	"""
+
+	unit: DurationUnit
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		"""
+		require_field_types(self)

numdaplot/errors/__init__.py

@@ -0,0 +1,7 @@
+"""
+Errors and warnings raised by numdaplot.
+
+Every error inherits ``NumdaplotError``, so ``except ndp.NumdaplotError`` catches all of them.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/errors/broadcast_warning.py

@@ -0,0 +1,36 @@
+"""
+Warning emitted when two Arrays of different shapes are combined.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_warning import NumdaplotWarning
+
+
+class BroadcastWarning(NumdaplotWarning):
+	"""
+	Emitted when an operation stretches an Array to match the shape of another one.
+
+	The operation still runs, as in numpy. The warning only signals that the shapes differ,
+	which is often a mistake. It is never emitted when an Array is combined with a single value.
+
+	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
+	>>> grid = ndp.Array.from_list([[1, 2], [3, 4]])
+	>>> row = ndp.Array.from_list([10, 20])
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	sums = grid + row
+	>>> sums
+	Array([[11, 22],
+	       [13, 24]], dtype=INT64)
+	>>> print(caught_warnings[0].message)
+	Shapes (2, 2) and (2,) differ, values are repeated to match.
+	"""

numdaplot/errors/calculation_warning.py

@@ -0,0 +1,35 @@
+"""
+Warning emitted when a calculation on decimals gives NaN or an infinite value.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_warning import NumdaplotWarning
+
+
+class CalculationWarning(NumdaplotWarning):
+	"""
+	Emitted when values of a calculation on decimals have no defined result or do not fit their type.
+
+	The calculation still runs: these values become NaN or an infinite value. The warning points at the line of
+	the calculation in the calling code.
+
+	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
+	>>> distances = ndp.Array.from_list([0.0, 3.0])
+	>>> hours = ndp.Array.from_list([0.0, 2.0])
+	>>> with warnings.catch_warnings(record=True) as caught_warnings:
+	... 	warnings.simplefilter("always")
+	... 	speeds = distances / hours
+	>>> speeds
+	Array([nan, 1.5], dtype=FLOAT64)
+	>>> print(caught_warnings[0].message)
+	The operation / has values without a defined result, such as 0 / 0: they became NaN.
+	"""

numdaplot/errors/cell_out_of_range_error.py

@@ -0,0 +1,77 @@
+"""
+Error raised when a cell is outside the Layout of a Figure.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+CELL_OUT_OF_RANGE_MESSAGE = "Cell ({row}, {column}) is outside a Layout of {row_count} rows and {column_count} columns."
+
+
+class CellOutOfRangeError(NumdaplotError):
+	"""
+	Raised when a ``Cell``, or a cell it spans, is beyond the rows or the columns of the ``Layout`` of a ``Figure``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	row
+		The row of the cell, from 0.
+	column
+		The column of the cell, from 0.
+	row_count
+		The number of rows of the Layout.
+	column_count
+		The number of columns of the Layout.
+
+	Attributes
+	----------
+	row
+		The row of the cell, from 0.
+	column
+		The column of the cell, from 0.
+	row_count
+		The number of rows of the Layout.
+	column_count
+		The number of columns of the Layout.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([12.0, 15.5, 14.0])
+	>>> plot = ndp.Plot.line(prices)
+	>>> figure = ndp.Figure(ndp.Layout(rows=2, columns=2))
+	>>> try:
+	... 	figure.place(plot, ndp.Cell(row=2, column=0))
+	... except ndp.CellOutOfRangeError as error:
+	... 	print(error)
+	Cell (2, 0) is outside a Layout of 2 rows and 2 columns.
+	"""
+
+	def __init__(self, row: int, column: int, row_count: int, column_count: int) -> None:
+		"""
+		Build the error message from the cell and the size of the Layout.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		row
+			The row of the cell, from 0.
+		column
+			The column of the cell, from 0.
+		row_count
+			The number of rows of the Layout.
+		column_count
+			The number of columns of the Layout.
+		"""
+		message = CELL_OUT_OF_RANGE_MESSAGE.format(
+			row=row, column=column, row_count=row_count, column_count=column_count
+		)
+		super().__init__(message)
+		self.row = row
+		self.column = column
+		self.row_count = row_count
+		self.column_count = column_count

numdaplot/errors/column_not_found_error.py

@@ -0,0 +1,64 @@
+"""
+Error raised when a Table has no column of a given name.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+COLUMN_NOT_FOUND_MESSAGE = "No column is named {column_name!r}."
+TABLE_COLUMN_NOT_FOUND_MESSAGE = "No column of {table_name} is named {column_name!r}."
+
+
+class ColumnNotFoundError(NumdaplotError):
+	"""
+	Raised when an operation names a column that the Table does not have.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column_name
+		The name that matches no column.
+	table_name
+		The Table searched, such as ``"the other Table"`` of a join. When omitted, only one Table is involved.
+
+	Attributes
+	----------
+	column_name
+		The name that matches no column.
+	table_name
+		The Table searched, or None.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([1, 2])})
+	>>> try:
+	... 	table.column("prise")
+	... except ndp.ColumnNotFoundError as error:
+	... 	print(error)
+	No column is named 'prise'.
+	"""
+
+	def __init__(self, column_name: str, table_name: str | None = None) -> None:
+		"""
+		Build the error message from the column name, and from the Table searched when it is given.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_name
+			The name that matches no column.
+		table_name
+			The Table searched. When omitted, only one Table is involved.
+		"""
+		message = COLUMN_NOT_FOUND_MESSAGE.format(column_name=column_name)
+		if table_name is not None:
+			message = TABLE_COLUMN_NOT_FOUND_MESSAGE.format(table_name=table_name, column_name=column_name)
+
+		super().__init__(message)
+
+		self.column_name = column_name
+		self.table_name = table_name

numdaplot/errors/conflicting_settings_error.py

@@ -0,0 +1,60 @@
+"""
+Error raised when two settings that exclude each other are both given.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+CONFLICTING_SETTINGS_MESSAGE = "{first_name} and {second_name} cannot be given together."
+
+
+class ConflictingSettingsError(NumdaplotError):
+	"""
+	Raised when two settings that exclude each other are both given.
+
+	For example, a ``ScatterChart`` colors its points with one ``color`` or by the values of ``color_by``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	first_name
+		Name of the first setting.
+	second_name
+		Name of the second setting.
+
+	Attributes
+	----------
+	first_name
+		Name of the first setting.
+	second_name
+		Name of the second setting.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.ScatterChart(x="surface", y="price", color=ndp.Color.RED, color_by="city")
+	... except ndp.ConflictingSettingsError as error:
+	... 	print(error)
+	color and color_by cannot be given together.
+	"""
+
+	def __init__(self, first_name: str, second_name: str) -> None:
+		"""
+		Build the error message from the two setting names.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		first_name
+			Name of the first setting.
+		second_name
+			Name of the second setting.
+		"""
+		message = CONFLICTING_SETTINGS_MESSAGE.format(first_name=first_name, second_name=second_name)
+		super().__init__(message)
+		self.first_name = first_name
+		self.second_name = second_name

numdaplot/errors/dimension_error.py

@@ -0,0 +1,62 @@
+"""
+Error raised when an operation does not apply to the number of dimensions of an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+DIMENSION_MESSAGE = "{operation} does not apply to an Array of {dimension_count} dimension(s)."
+
+
+class DimensionError(NumdaplotError):
+	"""
+	Raised when an operation does not apply to the number of dimensions of an Array.
+
+	For example, an axis only applies to a two-dimensional Array, and a one-dimensional Array has no columns.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation
+		Description of the rejected operation.
+	dimension_count
+		Number of dimensions of the Array.
+
+	Attributes
+	----------
+	operation
+		Description of the rejected operation.
+	dimension_count
+		Number of dimensions of the Array.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> array = ndp.Array.from_list([1, 2, 3])
+	>>> try:
+	... 	array.compute(ndp.Sum(), axis=ndp.Axis.EACH_ROW)
+	... except ndp.DimensionError as error:
+	... 	print(error)
+	An axis does not apply to an Array of 1 dimension(s).
+	"""
+
+	def __init__(self, operation: str, dimension_count: int) -> None:
+		"""
+		Build the error message from the operation and the dimension count.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation
+			Description of the rejected operation.
+		dimension_count
+			Number of dimensions of the Array.
+		"""
+		message = DIMENSION_MESSAGE.format(operation=operation, dimension_count=dimension_count)
+		super().__init__(message)
+
+		self.operation = operation
+		self.dimension_count = dimension_count

numdaplot/errors/display_warning.py

@@ -0,0 +1,32 @@
+"""
+Warning emitted when a Plot or a Figure cannot be shown in a window.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_warning import NumdaplotWarning
+
+
+class DisplayWarning(NumdaplotWarning):
+	"""
+	Emitted when ``show`` cannot open a window, because matplotlib has no graphical backend.
+
+	This happens outside a Jupyter notebook when Python has no ``tkinter``, or on a server or in a container without
+	a screen. Nothing is shown. The warning points at the line calling ``show`` in the calling code, and suggests
+	installing ``tkinter`` or saving the image with ``save``: ``No window can be opened, matplotlib has no graphical
+	backend here. Install tkinter (python3-tk on Debian and Ubuntu) to see the plot, or save it with Plot.save.``
+
+	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
+	>>> plot = ndp.Plot.bar(ndp.Array.from_list([12.0, 15.5]))
+	>>> with warnings.catch_warnings():
+	... 	warnings.simplefilter("ignore", ndp.DisplayWarning)
+	... 	plot.show()
+	"""