numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/frames/time_range_errors.py

@@ -0,0 +1,117 @@
+"""
+Refusal of the dates and durations pandas cannot store in a Table column.
+
+.. versionadded:: 0.1.0
+"""
+
+from types import TracebackType
+
+import pandas
+
+from numdaplot.data_types.type import Type
+from numdaplot.errors.time_overflow_error import TimeOverflowError
+
+
+class TimeRangeErrors:
+	"""
+	Context giving the out of range errors of pandas in a block as ``TimeOverflowError``, naming the column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation_name
+		The operation shown in the message.
+	column_name
+		The name of the column the block works on.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.frames.time_range_errors import TimeRangeErrors
+	>>> far_moments = pandas.Series(numpy.array(["3000-01-01"], dtype="datetime64[s]"))
+	>>> try:
+	... 	with TimeRangeErrors("from_arrays", "day"):
+	... 		far_moments.astype("datetime64[ns]")
+	... except ndp.TimeOverflowError as error:
+	... 	print(error)
+	The operation from_arrays gives values of the column 'day' outside the range of DATETIME, from 1677 to 2262.
+	"""
+
+	def __init__(self, operation_name: str, column_name: str) -> None:
+		"""
+		Keep the operation and the column of the block.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation_name
+			The operation shown in the message.
+		column_name
+			The name of the column the block works on.
+		"""
+		self.operation_name = operation_name
+		self.column_name = column_name
+
+	def __enter__(self) -> None:
+		"""
+		Start the block.
+
+		.. versionadded:: 0.1.0
+		"""
+
+	def __exit__(
+		self,
+		error_type: type[BaseException] | None,
+		error: BaseException | None,
+		traceback: TracebackType | None,
+	) -> None:
+		"""
+		Replace an out of range error of pandas raised by the block.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		error_type
+			The type of the error raised by the block, or None.
+		error
+			The error raised by the block, or None.
+		traceback
+			Its traceback, or None.
+
+		Raises
+		------
+		TimeOverflowError
+			When the block raised ``OutOfBoundsDatetime`` or ``OutOfBoundsTimedelta``.
+		"""
+		if isinstance(error, pandas.errors.OutOfBoundsDatetime):
+			self.raise_overflow(Type.DATETIME, error)
+
+		if isinstance(error, pandas.errors.OutOfBoundsTimedelta):
+			self.raise_overflow(Type.DURATION, error)
+
+	def raise_overflow(self, data_type: Type, error: BaseException) -> None:
+		"""
+		Raise the error of a value out of the range of a type.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		data_type
+			The type that cannot hold the value.
+		error
+			The error of pandas.
+
+		Raises
+		------
+		TimeOverflowError
+			Always.
+		"""
+		overflow_error = TimeOverflowError(self.operation_name, data_type.name)
+		overflow_error.name_column(self.column_name)
+		raise overflow_error from error

numdaplot/tables/frames/time_zones.py

@@ -0,0 +1,271 @@
+"""
+Time zones of the datetime columns of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import cast
+
+import pandas
+
+from numdaplot.data_types.library import Library
+from numdaplot.data_types.type import Type
+from numdaplot.dates.time_zone import TimeZone
+from numdaplot.errors.time_zone_mismatch_error import TimeZoneMismatchError
+from numdaplot.errors.unknown_time_zone_error import UnknownTimeZoneError
+from numdaplot.errors.unsupported_type_error import UnsupportedTypeError
+from numdaplot.tables.frames.column import Column
+
+UTC_ZONE_NAME = "UTC"
+NANOSECOND_UNIT = "ns"
+TYPE_AND_ZONE = "{type_name} {zone_name}"
+DATETIME_KIND = "M"
+
+
+def find_column_time_zone(column: Column) -> TimeZone | None:
+	"""
+	Return the time zone of a Table column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+
+	Returns
+	-------
+	TimeZone or None
+		The zone of a datetime column with a time zone, ``None`` for any other column.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_zones import find_column_time_zone
+	>>> find_column_time_zone(pandas.Series(pandas.to_datetime(["2026-07-01 10:30"])).dt.tz_localize("Europe/Paris"))
+	TimeZone(name='Europe/Paris')
+	"""
+	column_dtype = column.dtype
+	if not isinstance(column_dtype, pandas.DatetimeTZDtype):
+		return None
+
+	zone_name = str(column_dtype.tz)
+	time_zone = TimeZone(zone_name)
+
+	return time_zone
+
+
+def name_column_type(column: Column, column_type: Type) -> str:
+	"""
+	Return the type shown under the name of a Table column, followed by its time zone when it has one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+	column_type
+		The numdaplot type of the column.
+
+	Returns
+	-------
+	str
+		The name of the type, such as ``"FLOAT64"`` or ``"DATETIME Europe/Paris"``.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.frames.time_zones import name_column_type
+	>>> name_column_type(pandas.Series([1.5]), ndp.Type.FLOAT64)
+	'FLOAT64'
+	"""
+	time_zone = find_column_time_zone(column)
+	if time_zone is None:
+		return column_type.name
+
+	type_and_zone = TYPE_AND_ZONE.format(type_name=column_type.name, zone_name=time_zone.name)
+
+	return type_and_zone
+
+
+def normalize_time_zone_column(column: Column) -> Column:
+	"""
+	Return a datetime column with a time zone, counted in nanoseconds, its zone named by its IANA name.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A pandas column of datetimes with a time zone.
+
+	Returns
+	-------
+	pandas.Series
+		The same instants in the same zone.
+
+	Raises
+	------
+	UnsupportedTypeError
+		When the zone is not an IANA time zone, such as a fixed offset of one hour.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_zones import normalize_time_zone_column
+	>>> times = pandas.Series(pandas.to_datetime(["2026-07-01 10:30"])).dt.tz_localize("UTC").dt.as_unit("s")
+	>>> str(normalize_time_zone_column(times).dtype)
+	'datetime64[ns, UTC]'
+	"""
+	column_dtype = cast(pandas.DatetimeTZDtype, column.dtype)
+	zone_name = str(column_dtype.tz)
+	try:
+		TimeZone(zone_name)
+	except UnknownTimeZoneError as error:
+		dtype_name = str(column_dtype)
+		raise UnsupportedTypeError(dtype_name, Library.PANDAS) from error
+
+	nanosecond_column = column.dt.as_unit(NANOSECOND_UNIT)
+	named_column = nanosecond_column.dt.tz_convert(zone_name)
+
+	return named_column
+
+
+def remove_utc_zone(column: Column) -> Column:
+	"""
+	Return the instants of a datetime column with a time zone as datetimes without zone, in UTC.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column of datetimes with a time zone.
+
+	Returns
+	-------
+	pandas.Series
+		The UTC clock time of each instant, without time zone.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_zones import remove_utc_zone
+	>>> times = pandas.Series(pandas.to_datetime(["2026-07-01 10:30"])).dt.tz_localize("Europe/Paris")
+	>>> remove_utc_zone(times).tolist()
+	[Timestamp('2026-07-01 08:30:00')]
+	"""
+	utc_column = column.dt.tz_convert(UTC_ZONE_NAME)
+	naive_column = utc_column.dt.tz_localize(None)
+
+	return naive_column
+
+
+def attribute_utc_results(column: Column, time_zone: TimeZone) -> Column:
+	"""
+	Return datetimes computed in UTC without zone as the same instants in a time zone.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column of datetimes without time zone, holding UTC clock times.
+	time_zone
+		The zone to show the instants in.
+
+	Returns
+	-------
+	pandas.Series
+		The instants in the zone.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.frames.time_zones import attribute_utc_results
+	>>> times = pandas.Series(pandas.to_datetime(["2026-07-01 08:30"]))
+	>>> attribute_utc_results(times, ndp.TimeZone("Europe/Paris")).tolist()
+	[Timestamp('2026-07-01 10:30:00+0200', tz='Europe/Paris')]
+	"""
+	utc_column = column.dt.tz_localize(UTC_ZONE_NAME)
+	zone_column = utc_column.dt.tz_convert(time_zone.name)
+
+	return zone_column
+
+
+def attribute_source_time_zone(results: Column, source: Column) -> Column:
+	"""
+	Return statistics of a column in the time zone of that column, when they are datetimes and it has one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	results
+		Statistics computed on the UTC clock times of ``source``.
+	source
+		The column the statistics are computed on.
+
+	Returns
+	-------
+	pandas.Series
+		The datetime results in the zone of the source column, or the results themselves otherwise.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.frames.time_zones import attribute_source_time_zone
+	>>> source = pandas.Series(pandas.to_datetime(["2026-07-01 10:30"])).dt.tz_localize("Europe/Paris")
+	>>> attribute_source_time_zone(pandas.Series(pandas.to_datetime(["2026-07-01 08:30"])), source).tolist()
+	[Timestamp('2026-07-01 10:30:00+0200', tz='Europe/Paris')]
+	"""
+	time_zone = find_column_time_zone(source)
+	if time_zone is None:
+		return results
+
+	is_datetime_result = results.dtype.kind == DATETIME_KIND
+	if not is_datetime_result:
+		return results
+
+	zone_results = attribute_utc_results(results, time_zone)
+
+	return zone_results
+
+
+def require_no_time_zone(frame: pandas.DataFrame, operation: str) -> None:
+	"""
+	Check that no column of a Table holds datetimes with a time zone.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	operation
+		What needs datetimes without zone, shown in the error message, such as ``"An Excel file"``.
+
+	Raises
+	------
+	TimeZoneMismatchError
+		When a column holds datetimes with a time zone.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.frames.time_zones import require_no_time_zone
+	>>> times = pandas.Series(pandas.to_datetime(["2026-07-01 10:30"])).dt.tz_localize("UTC")
+	>>> try:
+	... 	require_no_time_zone(pandas.DataFrame({"time": times}), "An Excel file")
+	... except ndp.TimeZoneMismatchError as error:
+	... 	print(error)
+	An Excel file needs datetimes without a time zone.
+	"""
+	for _, column in frame.items():
+		time_zone = find_column_time_zone(column)
+		if time_zone is not None:
+			raise TimeZoneMismatchError(operation, False)

numdaplot/tables/joining/__init__.py

@@ -0,0 +1,5 @@
+"""
+Join of two Tables on the values of key columns.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/joining/join.py

@@ -0,0 +1,110 @@
+"""
+Settings of a join of two Tables.
+
+.. versionadded:: 0.1.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from numdaplot.errors.empty_list_error import EmptyListError
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_names import require_column_names
+from numdaplot.tables.joining.join_mode import JoinMode
+from numdaplot.tables.joining.join_suffixes import JoinSuffixes
+from numdaplot.tables.joining.key_types import KeyTypes
+from numdaplot.tables.joining.relation import Relation
+
+if TYPE_CHECKING:
+	from numdaplot.tables.table import Table
+
+KEY_ITEM_NAME = "key"
+
+
+# eq=False because comparing two settings would compare their Tables with ==, which they refuse.
+@dataclass(frozen=True, eq=False)
+class Join:
+	"""
+	Settings of a join of two Tables on the values of key columns, used by ``Table.join``.
+
+	Each row of the joined Table meets each row of the other Table having the same keys. A missing key never matches,
+	as in SQL. The rows of the joined Table come first, in their order, then the unmatched rows of the other Table.
+	The columns are the keys, then the other columns of the joined Table, then those of the other Table.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	other
+		The Table joined to this one.
+	keys
+		The names of the key columns, which both Tables have: rename them with ``Table.rename`` first when they differ.
+		Several keys match on their combination. The join keeps its own copy of the list.
+	mode
+		Which rows are kept, ``JoinMode.INNER`` by default: only the rows whose keys match.
+	suffixes
+		The suffixes of the columns both Tables have besides the keys. When omitted, such a column raises
+		``DuplicateColumnError``.
+	key_types
+		How close the types of each key must be, ``KeyTypes.SAME_FAMILY`` by default: ``INT64`` matches ``FLOAT64``.
+	relation
+		How many times each key may appear in this Table, the left one, and in the other Table, the right one,
+		``Relation.MANY_TO_MANY`` by default, which checks nothing.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``keys`` is an empty list.
+	InvalidColumnNameError
+		When a name in ``keys`` is an empty text.
+	DuplicateColumnError
+		When a name appears twice in ``keys``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> accidents = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 2]), "dep": ndp.Array.from_list(["75", "69"])})
+	>>> users = ndp.Table.from_arrays({"id": ndp.Array.from_list([1, 1]), "age": ndp.Array.from_list([34, 8])})
+	>>> accidents.join(ndp.Join(other=users, keys=["id"]))
+	     id  dep   age
+	  INT64 TEXT INT64
+	0     1   75    34
+	1     1   75     8
+	"""
+
+	other: Table
+	keys: list[str]
+	mode: JoinMode = JoinMode.INNER
+	suffixes: JoinSuffixes | None = None
+	key_types: KeyTypes = KeyTypes.SAME_FAMILY
+	relation: Relation = Relation.MANY_TO_MANY
+
+	def __post_init__(self) -> None:
+		"""
+		Check the keys and replace them with a copy that only the join holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``keys`` is an empty list.
+		InvalidColumnNameError
+			When a name in ``keys`` is an empty text.
+		DuplicateColumnError
+			When a name appears twice in ``keys``.
+		"""
+		require_field_types(self)
+
+		if self.keys == []:
+			raise EmptyListError(KEY_ITEM_NAME)
+
+		require_column_names(self.keys)
+		keys_copy = list(self.keys)
+		object.__setattr__(self, "keys", keys_copy)