numdaplot 0.1.0__py3-none-any.whl

numdaplot/data_types/type.py

@@ -0,0 +1,224 @@
+"""
+Types of the values stored in an Array or in a Table column.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Type(Enum):
+	"""
+	Type of the values stored in an Array or in a Table column.
+
+	Integers wrap around silently when a result exceeds their range, as in numpy:
+	with ``INT8``, ``127 + 1`` gives ``-128``. Prefer ``INT64`` unless memory matters.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, 2], dtype=ndp.Type.FLOAT32)
+	Array([1., 2.], dtype=FLOAT32)
+	>>> ndp.Array.from_list([1.5, 2.0]).dtype
+	<Type.FLOAT64: 10>
+	"""
+
+	INT8 = auto()
+	"""
+	Signed integer from -128 to 127, 1 byte per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, -2], dtype=ndp.Type.INT8)
+	Array([ 1, -2], dtype=INT8)
+	"""
+
+	INT16 = auto()
+	"""
+	Signed integer from -32 768 to 32 767, 2 bytes per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, -2], dtype=ndp.Type.INT16)
+	Array([ 1, -2], dtype=INT16)
+	"""
+
+	INT32 = auto()
+	"""
+	Signed integer of about +/- 2 billion, 4 bytes per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, -2], dtype=ndp.Type.INT32)
+	Array([ 1, -2], dtype=INT32)
+	"""
+
+	INT64 = auto()
+	"""
+	Signed integer of about +/- 9.2 * 10**18, 8 bytes per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, -2], dtype=ndp.Type.INT64)
+	Array([ 1, -2], dtype=INT64)
+	"""
+
+	UINT8 = auto()
+	"""
+	Unsigned integer from 0 to 255, 1 byte per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, 2], dtype=ndp.Type.UINT8)
+	Array([1, 2], dtype=UINT8)
+	"""
+
+	UINT16 = auto()
+	"""
+	Unsigned integer from 0 to 65 535, 2 bytes per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, 2], dtype=ndp.Type.UINT16)
+	Array([1, 2], dtype=UINT16)
+	"""
+
+	UINT32 = auto()
+	"""
+	Unsigned integer from 0 to about 4 billion, 4 bytes per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, 2], dtype=ndp.Type.UINT32)
+	Array([1, 2], dtype=UINT32)
+	"""
+
+	UINT64 = auto()
+	"""
+	Unsigned integer from 0 to about 1.8 * 10**19, 8 bytes per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1, 2], dtype=ndp.Type.UINT64)
+	Array([1, 2], dtype=UINT64)
+	"""
+
+	FLOAT32 = auto()
+	"""
+	Decimal number with about 7 significant digits, 4 bytes per value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1.5, 2.0], dtype=ndp.Type.FLOAT32)
+	Array([1.5, 2. ], dtype=FLOAT32)
+	"""
+
+	FLOAT64 = auto()
+	"""
+	Decimal number with about 16 significant digits, 8 bytes per value. Default decimal type.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([1.5, None], dtype=ndp.Type.FLOAT64)
+	Array([1.5, nan], dtype=FLOAT64)
+	"""
+
+	BOOL = auto()
+	"""
+	True or false.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([True, False], dtype=ndp.Type.BOOL)
+	Array([ True, False], dtype=BOOL)
+	"""
+
+	TEXT = auto()
+	"""
+	Text of any length.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list(["Paris", "Lyon"], dtype=ndp.Type.TEXT)
+	Array(['Paris', 'Lyon'], dtype=TEXT)
+	"""
+
+	CATEGORY = auto()
+	"""
+	Text taking a few repeated values, stored once per distinct value. Table columns only.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> categories = sales.convert(ndp.Conversion(column="city", dtype=ndp.Type.CATEGORY))
+	>>> categories.column_types["city"]
+	<Type.CATEGORY: 13>
+	"""
+
+	DATE = auto()
+	"""
+	A day, without time. Stored in days, but a calculation on it stays within 1677 to 2262, as ``DATETIME``.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([date(2026, 1, 31)]).dtype
+	<Type.DATE: 14>
+	"""
+
+	DATETIME = auto()
+	"""
+	A day and a time, with or without time zone, from 1677 to 2262.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([datetime(2026, 1, 31, 8, 30)]).dtype
+	<Type.DATETIME: 15>
+	"""
+
+	DURATION = auto()
+	"""
+	A gap between two dates or datetimes, of about 292 years at most, before or after zero.
+
+	Examples
+	--------
+	>>> from datetime import timedelta
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([timedelta(hours=2)]).dtype
+	<Type.DURATION: 16>
+	"""
+
+	TIME = auto()
+	"""
+	A time of day, from 00:00 to 23:59:59.999999, without date nor time zone. Stored as the time since midnight.
+
+	Two times give a ``DURATION`` when subtracted, a duration moves a time within its day, and a time added to a
+	``DATE`` gives a ``DATETIME``. Its hour, minute and second are read with ``DatePart``.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> import numdaplot as ndp
+	>>> ndp.Array.from_list([time(15, 35)]).dtype
+	<Type.TIME: 17>
+	"""

numdaplot/data_types/value_family.py

@@ -0,0 +1,149 @@
+"""
+Families of types whose values can be compared and combined together.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+from numdaplot.data_types.type import Type
+
+
+class ValueFamily(Enum):
+	"""
+	Family of types whose values can be compared and combined together.
+
+	An ``INT64`` and a ``FLOAT64`` are both numbers, while a number and a text cannot be compared.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_family import find_family
+	>>> find_family(ndp.Type.UINT8) == find_family(ndp.Type.FLOAT64)
+	True
+	>>> find_family(ndp.Type.CATEGORY)
+	<ValueFamily.TEXT: 3>
+	"""
+
+	NUMBER = auto()
+	"""
+	Signed and unsigned integers, and decimals.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_family import find_family
+	>>> find_family(ndp.Type.UINT8)
+	<ValueFamily.NUMBER: 1>
+	"""
+
+	BOOL = auto()
+	"""
+	True or false.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_family import find_family
+	>>> find_family(ndp.Type.BOOL)
+	<ValueFamily.BOOL: 2>
+	"""
+
+	TEXT = auto()
+	"""
+	Texts and categories.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_family import find_family
+	>>> find_family(ndp.Type.TEXT)
+	<ValueFamily.TEXT: 3>
+	"""
+
+	MOMENT = auto()
+	"""
+	Dates and datetimes.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_family import find_family
+	>>> find_family(ndp.Type.DATE)
+	<ValueFamily.MOMENT: 4>
+	"""
+
+	DURATION = auto()
+	"""
+	Gaps between two moments.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_family import find_family
+	>>> find_family(ndp.Type.DURATION)
+	<ValueFamily.DURATION: 5>
+	"""
+
+	TIME = auto()
+	"""
+	Times of day, compared only with each other.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_family import find_family
+	>>> find_family(ndp.Type.TIME)
+	<ValueFamily.TIME: 6>
+	"""
+
+
+FAMILIES_BY_TYPE = {
+	Type.INT8: ValueFamily.NUMBER,
+	Type.INT16: ValueFamily.NUMBER,
+	Type.INT32: ValueFamily.NUMBER,
+	Type.INT64: ValueFamily.NUMBER,
+	Type.UINT8: ValueFamily.NUMBER,
+	Type.UINT16: ValueFamily.NUMBER,
+	Type.UINT32: ValueFamily.NUMBER,
+	Type.UINT64: ValueFamily.NUMBER,
+	Type.FLOAT32: ValueFamily.NUMBER,
+	Type.FLOAT64: ValueFamily.NUMBER,
+	Type.BOOL: ValueFamily.BOOL,
+	Type.TEXT: ValueFamily.TEXT,
+	Type.CATEGORY: ValueFamily.TEXT,
+	Type.DATE: ValueFamily.MOMENT,
+	Type.DATETIME: ValueFamily.MOMENT,
+	Type.DURATION: ValueFamily.DURATION,
+	Type.TIME: ValueFamily.TIME,
+}
+
+
+def find_family(data_type: Type) -> ValueFamily:
+	"""
+	Return the family of a numdaplot type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data_type
+		The type to classify.
+
+	Returns
+	-------
+	ValueFamily
+		The family whose values can be compared with values of this type.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_family import find_family
+	>>> find_family(ndp.Type.DATETIME)
+	<ValueFamily.MOMENT: 4>
+	"""
+	family = FAMILIES_BY_TYPE[data_type]
+
+	return family

numdaplot/data_types/value_type.py

@@ -0,0 +1,147 @@
+"""
+Type of single Python values, and the common type of several values.
+
+.. versionadded:: 0.1.0
+"""
+
+from datetime import date, datetime, time, timedelta
+
+import numpy
+
+from numdaplot.data_types.library import Library
+from numdaplot.data_types.type import Type
+from numdaplot.data_types.value_family import find_family
+from numdaplot.errors.incompatible_types_error import IncompatibleTypesError
+from numdaplot.errors.time_zone_mismatch_error import TimeZoneMismatchError
+from numdaplot.errors.unsupported_type_error import UnsupportedTypeError
+
+# bool comes before int and datetime before date, since each one is a subclass of the next.
+PYTHON_TYPES = (
+	((bool, numpy.bool_), Type.BOOL),
+	((int, numpy.integer), Type.INT64),
+	((float, numpy.floating), Type.FLOAT64),
+	((str,), Type.TEXT),
+	((datetime,), Type.DATETIME),
+	((date,), Type.DATE),
+	((timedelta,), Type.DURATION),
+	((time,), Type.TIME),
+)
+ARRAY_OPERATION = "An Array"
+TYPE_WIDTHS = {
+	Type.FLOAT64: 1,
+	Type.DATETIME: 1,
+}
+NARROWEST_WIDTH = 0
+
+
+def find_value_type(value: object) -> Type:
+	"""
+	Return the numdaplot type of a single Python value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	value
+		A boolean, a number, a text, a date, a datetime, a duration or a time of day.
+
+	Returns
+	-------
+	Type
+		``BOOL``, ``INT64``, ``FLOAT64``, ``TEXT``, ``DATETIME``, ``DATE``, ``DURATION`` or ``TIME``.
+
+	Raises
+	------
+	UnsupportedTypeError
+		When the value has no numdaplot type, such as a complex number or a tuple.
+	TimeZoneMismatchError
+		When the value is a datetime or a time of day with a time zone, which an Array cannot hold.
+
+	Examples
+	--------
+	>>> from numdaplot.data_types.value_type import find_value_type
+	>>> find_value_type(2.5)
+	<Type.FLOAT64: 10>
+	"""
+	has_time_zone = isinstance(value, (datetime, time)) and value.tzinfo is not None
+	if has_time_zone:
+		raise TimeZoneMismatchError(ARRAY_OPERATION, False)
+
+	for python_types, data_type in PYTHON_TYPES:
+		if isinstance(value, python_types):
+			return data_type
+
+	value_class = type(value)
+	raise UnsupportedTypeError(value_class.__name__, Library.NUMPY)
+
+
+def find_type_width(data_type: Type) -> int:
+	"""
+	Return the width of a type inside its family, the widest type holding every value of the others.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data_type
+		A type returned by ``find_value_type``.
+
+	Returns
+	-------
+	int
+		1 for ``FLOAT64`` and ``DATETIME``, 0 for every other type.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_type import find_type_width
+	>>> find_type_width(ndp.Type.INT64) < find_type_width(ndp.Type.FLOAT64)
+	True
+	"""
+	width = TYPE_WIDTHS.get(data_type, NARROWEST_WIDTH)
+
+	return width
+
+
+def find_common_type(data_types: list[Type], operation: str) -> Type:
+	"""
+	Return the type that holds every value of several types of one family.
+
+	Integers and decimals give ``FLOAT64``, dates and datetimes give ``DATETIME``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data_types
+		At least one type returned by ``find_value_type``.
+	operation
+		Name of the operation needing the common type, shown in the error message.
+
+	Returns
+	-------
+	Type
+		The widest of the given types.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the types belong to several families, such as a number and a text.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.value_type import find_common_type
+	>>> find_common_type([ndp.Type.INT64, ndp.Type.FLOAT64], "from_list")
+	<Type.FLOAT64: 10>
+	"""
+	distinct_types = set(data_types)
+	families = {find_family(data_type) for data_type in distinct_types}
+	family_count = len(families)
+	if family_count > 1:
+		type_names = sorted(data_type.name for data_type in distinct_types)
+		raise IncompatibleTypesError(operation, type_names)
+
+	common_type = max(distinct_types, key=find_type_width)
+
+	return common_type

numdaplot/dates/__init__.py

@@ -0,0 +1,5 @@
+"""
+Dates, datetimes and durations: formats, time zones, parts, periods and duration units.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/dates/custom_date_format.py

@@ -0,0 +1,83 @@
+"""
+A pattern describing how dates are written as texts.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.invalid_date_format_error import InvalidDateFormatError
+from numdaplot.settings.field_types import require_field_types
+
+DATE_CODES = ("%d", "%m", "%Y", "%y", "%b", "%B", "%j")
+TIME_ZONE_CODES = ("%z", "%Z")
+TIME_CODES = ("%H", "%I", "%M", "%S", "%f", "%p")
+
+
+@dataclass(frozen=True)
+class CustomDateFormat:
+	"""
+	A pattern describing how dates, datetimes or times of day are written as texts, used by ``Conversion``.
+
+	It serves when no ``DateFormat`` fits, and for times of day. The pattern uses the codes of Python
+	``datetime.strptime``: ``%d`` day, ``%m`` month, ``%Y`` year,
+	``%b`` short month name, ``%B`` full month name, ``%H`` hour, ``%M`` minute, ``%S`` second.
+	Month names are in English.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	pattern
+		The pattern, such as ``"%d %b %Y"`` for ``"31 Dec 2026"``.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidDateFormatError
+		When the pattern has no date code (day, month, year) nor time code (hour, minute, second), or has a time
+		zone code (``%z``, ``%Z``). A pattern without date only reads or writes ``TIME``, and a pattern with a date
+		never does.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Table.from_arrays({"day": ndp.Array.from_list(["31 Dec 2026", "1 Feb 2026"])})
+	>>> days.convert(ndp.Conversion(column="day", dtype=ndp.Type.DATE, format=ndp.CustomDateFormat("%d %b %Y")))
+	         day
+	        DATE
+	0 2026-12-31
+	1 2026-02-01
+	>>> hours = ndp.Table.from_arrays({"hrmn": ndp.Array.from_list(["1535", "0805"])})
+	>>> hours.convert(ndp.Conversion(column="hrmn", dtype=ndp.Type.TIME, format=ndp.CustomDateFormat("%H%M")))
+	       hrmn
+	       TIME
+	0  15:35:00
+	1  08:05:00
+	"""
+
+	pattern: str
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the pattern reads a date or a time of day, and no time zone.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidDateFormatError
+			When the pattern has no date nor time code, or has a time zone code.
+		"""
+		require_field_types(self)
+
+		has_date_code = any(date_code in self.pattern for date_code in DATE_CODES)
+		has_time_code = any(time_code in self.pattern for time_code in TIME_CODES)
+		has_time_zone_code = any(zone_code in self.pattern for zone_code in TIME_ZONE_CODES)
+		reads_something = has_date_code or has_time_code
+		is_rejected = has_time_zone_code or not reads_something
+		if is_rejected:
+			raise InvalidDateFormatError(self.pattern)