numdaplot 0.1.0__py3-none-any.whl

numdaplot/dates/date_format.py

@@ -0,0 +1,120 @@
+"""
+Common orders in which dates are written as texts.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class DateFormat(Enum):
+	"""
+	Common orders in which dates are written as texts, used by ``Conversion``.
+
+	When reading, the day, the month and the year are separated by ``"/"``, ``"-"`` or ``"."``, the same one twice;
+	days and months may have one digit, years have four. A ``_TIME`` member also needs the time, as ``"14:30"``
+	or ``"14:30:15"``, after a space, or after a ``"T"`` for ``YEAR_MONTH_DAY_TIME``. When writing, ``"/"`` separates
+	the day-month and month-day orders and ``"-"`` the year-month-day order, and the time is written ``"14:30:15"``.
+
+	Use ``CustomDateFormat`` for any other way of writing dates.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Table.from_arrays({"day": ndp.Array.from_list(["31/12/2026", "1.2.2026"])})
+	>>> days.convert(ndp.Conversion(column="day", dtype=ndp.Type.DATE, format=ndp.DateFormat.DAY_MONTH_YEAR))
+	         day
+	        DATE
+	0 2026-12-31
+	1 2026-02-01
+	"""
+
+	DAY_MONTH_YEAR = auto()
+	"""
+	The day, the month, then the year: ``"31/12/2026"``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Table.from_arrays({"day": ndp.Array.from_list(["31/12/2026"])})
+	>>> days.convert(ndp.Conversion(column="day", dtype=ndp.Type.DATE, format=ndp.DateFormat.DAY_MONTH_YEAR))
+	         day
+	        DATE
+	0 2026-12-31
+	"""
+
+	MONTH_DAY_YEAR = auto()
+	"""
+	The month, the day, then the year: ``"12/31/2026"``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Table.from_arrays({"day": ndp.Array.from_list(["12/31/2026"])})
+	>>> days.convert(ndp.Conversion(column="day", dtype=ndp.Type.DATE, format=ndp.DateFormat.MONTH_DAY_YEAR))
+	         day
+	        DATE
+	0 2026-12-31
+	"""
+
+	YEAR_MONTH_DAY = auto()
+	"""
+	The year, the month, then the day: ``"2026-12-31"``. Read by default when no format is given.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> days = ndp.Table.from_arrays({"day": ndp.Array.from_list(["2026-12-31"])})
+	>>> days.convert(ndp.Conversion(column="day", dtype=ndp.Type.DATE, format=ndp.DateFormat.YEAR_MONTH_DAY))
+	         day
+	        DATE
+	0 2026-12-31
+	"""
+
+	DAY_MONTH_YEAR_TIME = auto()
+	"""
+	The day, the month, the year, then the time: ``"31/12/2026 14:30"``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list(["31/12/2026 14:30"])})
+	>>> day_first = ndp.DateFormat.DAY_MONTH_YEAR_TIME
+	>>> times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, format=day_first))
+	                 time
+	             DATETIME
+	0 2026-12-31 14:30:00
+	"""
+
+	MONTH_DAY_YEAR_TIME = auto()
+	"""
+	The month, the day, the year, then the time: ``"12/31/2026 14:30"``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list(["12/31/2026 14:30"])})
+	>>> month_first = ndp.DateFormat.MONTH_DAY_YEAR_TIME
+	>>> times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, format=month_first))
+	                 time
+	             DATETIME
+	0 2026-12-31 14:30:00
+	"""
+
+	YEAR_MONTH_DAY_TIME = auto()
+	"""
+	The year, the month, the day, then the time after a space or a ``"T"``: ``"2026-12-31 14:30"`` or
+	``"2026-12-31T14:30"``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> times = ndp.Table.from_arrays({"time": ndp.Array.from_list(["2026-12-31T14:30:15"])})
+	>>> year_first = ndp.DateFormat.YEAR_MONTH_DAY_TIME
+	>>> times.convert(ndp.Conversion(column="time", dtype=ndp.Type.DATETIME, format=year_first))
+	                 time
+	             DATETIME
+	0 2026-12-31 14:30:15
+	"""

numdaplot/dates/date_part.py

@@ -0,0 +1,59 @@
+"""
+A part of each date, such as its month.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.dates.date_part_unit import DatePartUnit
+from numdaplot.dates.time_function import TimeFunction
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class DatePart(TimeFunction):
+	"""
+	A part of each date, datetime or time of day, as a number: its month, its day of the week, its hour...
+
+	The result is a ``FLOAT64`` Array, so a missing date gives a missing part. Every January of every year
+	gives 1: use ``DatePeriod`` to tell January 2026 from January 2027.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	unit
+		The part to read. ``DatePartUnit.HOUR``, ``DatePartUnit.MINUTE`` and ``DatePartUnit.SECOND`` need datetimes
+		or times of day, the only parts a time of day has.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> import numdaplot as ndp
+	>>> days = ndp.Array.from_list([date(2026, 1, 5), None, date(2027, 1, 9)])
+	>>> days.apply(ndp.DatePart(unit=ndp.DatePartUnit.MONTH))
+	Array([ 1., nan,  1.], dtype=FLOAT64)
+	>>> days.apply(ndp.DatePart(unit=ndp.DatePartUnit.WEEKDAY))
+	Array([ 1., nan,  6.], dtype=FLOAT64)
+	"""
+
+	unit: DatePartUnit
+
+	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/dates/date_part_unit.py

@@ -0,0 +1,153 @@
+"""
+Parts of a date that DatePart reads.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class DatePartUnit(Enum):
+	"""
+	Parts of a date that ``DatePart`` reads, such as its month or its day of the week.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.MONTH))
+	Array([12.], dtype=FLOAT64)
+	"""
+
+	YEAR = auto()
+	"""
+	The year, such as 2026.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.YEAR))
+	Array([2026.], dtype=FLOAT64)
+	"""
+
+	QUARTER = auto()
+	"""
+	The quarter of the year, from 1 for January to March to 4 for October to December.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.QUARTER))
+	Array([4.], dtype=FLOAT64)
+	"""
+
+	MONTH = auto()
+	"""
+	The month, from 1 for January to 12 for December.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.MONTH))
+	Array([12.], dtype=FLOAT64)
+	"""
+
+	WEEK = auto()
+	"""
+	The ISO week number, from 1 to 53. Week 1 holds the first Thursday of the year.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.WEEK))
+	Array([53.], dtype=FLOAT64)
+	"""
+
+	DAY = auto()
+	"""
+	The day of the month, from 1 to 31.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.DAY))
+	Array([31.], dtype=FLOAT64)
+	"""
+
+	WEEKDAY = auto()
+	"""
+	The day of the week, from 1 for Monday to 7 for Sunday.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.WEEKDAY))
+	Array([4.], dtype=FLOAT64)
+	"""
+
+	DAY_OF_YEAR = auto()
+	"""
+	The day of the year, from 1 to 366.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.DAY_OF_YEAR))
+	Array([365.], dtype=FLOAT64)
+	"""
+
+	HOUR = auto()
+	"""
+	The hour, from 0 to 23. Datetimes and times of day only.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.HOUR))
+	Array([14.], dtype=FLOAT64)
+	"""
+
+	MINUTE = auto()
+	"""
+	The minute, from 0 to 59. Datetimes and times of day only.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.MINUTE))
+	Array([30.], dtype=FLOAT64)
+	"""
+
+	SECOND = auto()
+	"""
+	The second, from 0 to 59. Datetimes and times of day only.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30, 15)])
+	>>> times.apply(ndp.DatePart(unit=ndp.DatePartUnit.SECOND))
+	Array([15.], dtype=FLOAT64)
+	"""

numdaplot/dates/date_period.py

@@ -0,0 +1,57 @@
+"""
+The period holding each date, such as its month.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.dates.period_unit import PeriodUnit
+from numdaplot.dates.time_function import TimeFunction
+from numdaplot.settings.field_types import require_field_types
+
+
+@dataclass(frozen=True)
+class DatePeriod(TimeFunction):
+	"""
+	The period holding each date or datetime, given by its first day: its month, its week...
+
+	The result is a ``DATE`` Array, or a ``DATETIME`` Array for ``PeriodUnit.HOUR``. Add it to a Table with
+	``add_column``, then name it in ``group_by`` to compute one result per period.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	unit
+		The length of the periods. ``PeriodUnit.HOUR`` needs datetimes.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> import numdaplot as ndp
+	>>> days = ndp.Array.from_list([date(2026, 1, 5), date(2026, 1, 28), date(2027, 1, 9)])
+	>>> days.apply(ndp.DatePeriod(unit=ndp.PeriodUnit.MONTH))
+	Array(['2026-01-01', '2026-01-01', '2027-01-01'], dtype=DATE)
+	"""
+
+	unit: PeriodUnit
+
+	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/dates/duration_in.py

@@ -0,0 +1,58 @@
+"""
+Each duration counted 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 DurationIn(TimeFunction):
+	"""
+	Each duration counted in a unit, as a decimal number: 36 hours in days gives 1.5.
+
+	The result is a ``FLOAT64`` Array. ``ToDuration`` does the opposite.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	unit
+		The unit to count in.
+
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> import numdaplot as ndp
+	>>> arrivals = ndp.Array.from_list([date(2026, 1, 1), date(2026, 1, 10)])
+	>>> departures = ndp.Array.from_list([date(2026, 1, 4), date(2026, 1, 20)])
+	>>> stays = departures - arrivals
+	>>> stays.apply(ndp.DurationIn(unit=ndp.DurationUnit.DAY))
+	Array([ 3., 10.], dtype=FLOAT64)
+	"""
+
+	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/dates/duration_unit.py

@@ -0,0 +1,90 @@
+"""
+Units in which durations are counted.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class DurationUnit(Enum):
+	"""
+	Units in which durations are counted, used by ``DurationIn`` and ``ToDuration``.
+
+	Months and years have no fixed length, so they are not duration units.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> from datetime import timedelta
+	>>> import numdaplot as ndp
+	>>> stays = ndp.Array.from_list([timedelta(days=14)])
+	>>> stays.apply(ndp.DurationIn(unit=ndp.DurationUnit.DAY))
+	Array([14.], dtype=FLOAT64)
+	"""
+
+	WEEK = auto()
+	"""
+	A week, 7 days.
+
+	Examples
+	--------
+	>>> from datetime import timedelta
+	>>> import numdaplot as ndp
+	>>> stays = ndp.Array.from_list([timedelta(days=14)])
+	>>> stays.apply(ndp.DurationIn(unit=ndp.DurationUnit.WEEK))
+	Array([2.], dtype=FLOAT64)
+	"""
+
+	DAY = auto()
+	"""
+	A day, 24 hours.
+
+	Examples
+	--------
+	>>> from datetime import timedelta
+	>>> import numdaplot as ndp
+	>>> stays = ndp.Array.from_list([timedelta(days=14)])
+	>>> stays.apply(ndp.DurationIn(unit=ndp.DurationUnit.DAY))
+	Array([14.], dtype=FLOAT64)
+	"""
+
+	HOUR = auto()
+	"""
+	An hour, 60 minutes.
+
+	Examples
+	--------
+	>>> from datetime import timedelta
+	>>> import numdaplot as ndp
+	>>> stays = ndp.Array.from_list([timedelta(days=14)])
+	>>> stays.apply(ndp.DurationIn(unit=ndp.DurationUnit.HOUR))
+	Array([336.], dtype=FLOAT64)
+	"""
+
+	MINUTE = auto()
+	"""
+	A minute, 60 seconds.
+
+	Examples
+	--------
+	>>> from datetime import timedelta
+	>>> import numdaplot as ndp
+	>>> stays = ndp.Array.from_list([timedelta(days=14)])
+	>>> stays.apply(ndp.DurationIn(unit=ndp.DurationUnit.MINUTE))
+	Array([20160.], dtype=FLOAT64)
+	"""
+
+	SECOND = auto()
+	"""
+	A second.
+
+	Examples
+	--------
+	>>> from datetime import timedelta
+	>>> import numdaplot as ndp
+	>>> stays = ndp.Array.from_list([timedelta(days=14)])
+	>>> stays.apply(ndp.DurationIn(unit=ndp.DurationUnit.SECOND))
+	Array([1209600.], dtype=FLOAT64)
+	"""

numdaplot/dates/period_unit.py

@@ -0,0 +1,101 @@
+"""
+Lengths of the periods DatePeriod groups dates by.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class PeriodUnit(Enum):
+	"""
+	Lengths of the periods ``DatePeriod`` groups dates by, such as the month or the week.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30)])
+	>>> times.apply(ndp.DatePeriod(unit=ndp.PeriodUnit.MONTH))
+	Array(['2026-12-01'], dtype=DATE)
+	"""
+
+	YEAR = auto()
+	"""
+	The year, starting on January 1.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30)])
+	>>> times.apply(ndp.DatePeriod(unit=ndp.PeriodUnit.YEAR))
+	Array(['2026-01-01'], dtype=DATE)
+	"""
+
+	QUARTER = auto()
+	"""
+	The quarter, starting on January 1, April 1, July 1 or October 1.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30)])
+	>>> times.apply(ndp.DatePeriod(unit=ndp.PeriodUnit.QUARTER))
+	Array(['2026-10-01'], dtype=DATE)
+	"""
+
+	MONTH = auto()
+	"""
+	The month, starting on its first day.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30)])
+	>>> times.apply(ndp.DatePeriod(unit=ndp.PeriodUnit.MONTH))
+	Array(['2026-12-01'], dtype=DATE)
+	"""
+
+	WEEK = auto()
+	"""
+	The week, starting on Monday.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30)])
+	>>> times.apply(ndp.DatePeriod(unit=ndp.PeriodUnit.WEEK))
+	Array(['2026-12-28'], dtype=DATE)
+	"""
+
+	DAY = auto()
+	"""
+	The day.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30)])
+	>>> times.apply(ndp.DatePeriod(unit=ndp.PeriodUnit.DAY))
+	Array(['2026-12-31'], dtype=DATE)
+	"""
+
+	HOUR = auto()
+	"""
+	The hour, starting at minute 0. Datetimes only, the result is a ``DATETIME``.
+
+	Examples
+	--------
+	>>> from datetime import datetime
+	>>> import numdaplot as ndp
+	>>> times = ndp.Array.from_list([datetime(2026, 12, 31, 14, 30)])
+	>>> times.apply(ndp.DatePeriod(unit=ndp.PeriodUnit.HOUR))
+	Array(['2026-12-31 14:00:00'], dtype=DATETIME)
+	"""

numdaplot/dates/time_function.py

@@ -0,0 +1,56 @@
+"""
+Base class of every function reading or building dates and durations.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.refused_operation_error import RefusedOperationError
+
+CONSTRUCTOR_OPERATION = "Creating a TimeFunction with ndp.TimeFunction()"
+CONSTRUCTOR_ALTERNATIVE = "a time function such as ndp.DatePart"
+
+
+class TimeFunction:
+	"""
+	Base class of every function reading or building dates and durations, applied by ``Array.apply``.
+
+	A time function is immutable. Missing values stay missing.
+
+	Only its subclasses are created: calling ``ndp.TimeFunction()`` raises ``RefusedOperationError``.
+
+	Every time function, passed to ``Array.apply``:
+
+	|Time function|What it gives for each value|Example|
+	|---|---|---|
+	|``DatePart``|A part of a date or datetime, as a number|``ndp.DatePart(unit=ndp.DatePartUnit.MONTH)``|
+	|``DatePeriod``|The first day of the period holding it|``ndp.DatePeriod(unit=ndp.PeriodUnit.MONTH)``|
+	|``ToDuration``|A number read as a duration in a unit|``ndp.ToDuration(unit=ndp.DurationUnit.DAY)``|
+	|``DurationIn``|A duration counted in a unit, as a decimal|``ndp.DurationIn(unit=ndp.DurationUnit.DAY)``|
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> from datetime import date
+	>>> import numdaplot as ndp
+	>>> days = ndp.Array.from_list([date(2026, 12, 31)])
+	>>> for function in [ndp.DatePart(unit=ndp.DatePartUnit.MONTH), ndp.DatePeriod(unit=ndp.PeriodUnit.YEAR)]:
+	... 	print(days.apply(function))
+	Array([12.], dtype=FLOAT64)
+	Array(['2026-01-01'], dtype=DATE)
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Refuse the creation of the base class itself, and let a subclass be created.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		RefusedOperationError
+			When the created object is a TimeFunction and not one of its subclasses.
+		"""
+		created_class = type(self)
+		if created_class is TimeFunction:
+			raise RefusedOperationError(CONSTRUCTOR_OPERATION, CONSTRUCTOR_ALTERNATIVE)