numdaplot 0.1.0__py3-none-any.whl

numdaplot/errors/unsupported_image_format_error.py

@@ -0,0 +1,56 @@
+"""
+Error raised when an image is saved with an extension numdaplot does not write.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+UNSUPPORTED_IMAGE_FORMAT_MESSAGE = "Cannot save an image as {extension!r}: use .png, .svg or .pdf."
+
+
+class UnsupportedImageFormatError(NumdaplotError):
+	"""
+	Raised when the path of an image does not end with ``.png``, ``.svg`` or ``.pdf``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	extension
+		The rejected extension, such as ``.jpg``, or an empty text when the path has none.
+
+	Attributes
+	----------
+	extension
+		The rejected extension, such as ``.jpg``, or an empty text when the path has none.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "prices.jpg"
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> plot = ndp.Plot.line(prices)
+	>>> try:
+	... 	plot.save(path)
+	... except ndp.UnsupportedImageFormatError as error:
+	... 	print(error)
+	Cannot save an image as '.jpg': use .png, .svg or .pdf.
+	"""
+
+	def __init__(self, extension: str) -> None:
+		"""
+		Build the error message from the rejected extension.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		extension
+			The rejected extension, such as ``.jpg``, or an empty text when the path has none.
+		"""
+		message = UNSUPPORTED_IMAGE_FORMAT_MESSAGE.format(extension=extension)
+		super().__init__(message)
+		self.extension = extension

numdaplot/errors/unsupported_index_error.py

@@ -0,0 +1,38 @@
+"""
+Error raised when a pandas DataFrame has an index holding information.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+UNSUPPORTED_INDEX_MESSAGE = (
+	"A Table has no index, call reset_index() on the pandas DataFrame first to keep its index as a column."
+)
+
+
+class UnsupportedIndexError(NumdaplotError):
+	"""
+	Raised by ``Table.from_pandas`` when the index of the pandas DataFrame is not the plain row numbers 0, 1, 2...
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import pandas
+	>>> frame = pandas.DataFrame({"price": [1, 2]}, index=["Paris", "Lyon"])
+	>>> try:
+	... 	ndp.Table.from_pandas(frame)
+	... except ndp.UnsupportedIndexError as error:
+	... 	print(error)
+	A Table has no index, call reset_index() on the pandas DataFrame first to keep its index as a column.
+	"""
+
+	def __init__(self) -> None:
+		"""
+		Build the error message.
+
+		.. versionadded:: 0.1.0
+		"""
+		super().__init__(UNSUPPORTED_INDEX_MESSAGE)

numdaplot/errors/unsupported_missing_error.py

@@ -0,0 +1,129 @@
+"""
+Error raised when a missing value is given for a type that cannot hold one.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+BOOL_TYPE_NAME = "BOOL"
+LIST_MESSAGE = "{type_name} values cannot be missing in an Array. {advice}"
+COLUMN_MESSAGE = (
+	"The column {column_name!r} has missing values, which {article} {type_name} Array cannot hold. {advice}"
+)
+ARTICLE_BEFORE_VOWEL = "an"
+ARTICLE = "a"
+VOWELS = "AEIOU"
+LIST_ADVICE = "Remove them."
+LIST_DECIMAL_ADVICE = "Remove them, or give dtype=ndp.Type.FLOAT64."
+COLUMN_ADVICE = "Remove them with drop_missing."
+COLUMN_DECIMAL_ADVICE = "Remove them with drop_missing, or convert the column to FLOAT64."
+
+
+class UnsupportedMissingError(NumdaplotError):
+	"""
+	Raised when a missing value (``None``) is given for a type that cannot hold one in an Array.
+
+	Only integers and booleans cannot be missing in an Array. A Table accepts their missing values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	type_name
+		Name of the ``ndp.Type`` member that cannot hold a missing value.
+	column_name
+		Name of the Table column holding the missing values. When omitted, the values were given to an Array.
+	advice
+		What to do instead, for values given to an Array by an operation that has its own solution. When omitted,
+		the advice of ``Array.from_list``.
+
+	Attributes
+	----------
+	type_name
+		Name of the ``ndp.Type`` member that cannot hold a missing value.
+	column_name
+		Name of the Table column holding the missing values, or ``None`` for values given to an Array.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Array.from_list([1, None])
+	... except ndp.UnsupportedMissingError as error:
+	... 	print(error)
+	INT64 values cannot be missing in an Array. Remove them, or give dtype=ndp.Type.FLOAT64.
+	"""
+
+	def __init__(self, type_name: str, column_name: str | None = None, advice: str | None = None) -> None:
+		"""
+		Build the error message from the type name, the column name and the advice.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		type_name
+			Name of the ``ndp.Type`` member that cannot hold a missing value.
+		column_name
+			Name of the Table column holding the missing values. When omitted, the values were given to an Array.
+		advice
+			What to do instead, for values given to an Array. When omitted, the advice of ``Array.from_list``.
+		"""
+		message = write_missing_message(type_name, column_name, advice)
+		super().__init__(message)
+
+		self.type_name = type_name
+		self.column_name = column_name
+
+
+def write_missing_message(type_name: str, column_name: str | None, advice: str | None = None) -> str:
+	"""
+	Return the message of the error, with the solutions that apply to the type.
+
+	Whole numbers can become decimals, which hold missing values. Booleans cannot.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	type_name
+		Name of the ``ndp.Type`` member that cannot hold a missing value.
+	column_name
+		Name of the Table column holding the missing values, or ``None`` for values given to an Array.
+	advice
+		What to do instead, for values given to an Array. When omitted, the advice of ``Array.from_list``.
+
+	Returns
+	-------
+	str
+		The message.
+
+	Examples
+	--------
+	>>> from numdaplot.errors.unsupported_missing_error import write_missing_message
+	>>> write_missing_message("BOOL", None)
+	'BOOL values cannot be missing in an Array. Remove them.'
+	>>> write_missing_message("BOOL", "paid")
+	"The column 'paid' has missing values, which a BOOL Array cannot hold. Remove them with drop_missing."
+	"""
+	converts_to_decimal = type_name != BOOL_TYPE_NAME
+	if column_name is None:
+		list_advice = LIST_DECIMAL_ADVICE if converts_to_decimal else LIST_ADVICE
+		if advice is not None:
+			list_advice = advice
+
+		list_message = LIST_MESSAGE.format(type_name=type_name, advice=list_advice)
+		return list_message
+
+	column_advice = COLUMN_DECIMAL_ADVICE if converts_to_decimal else COLUMN_ADVICE
+	first_letter = type_name[0]
+	article = ARTICLE_BEFORE_VOWEL if first_letter in VOWELS else ARTICLE
+	column_message = COLUMN_MESSAGE.format(
+		column_name=column_name,
+		article=article,
+		type_name=type_name,
+		advice=column_advice,
+	)
+
+	return column_message

numdaplot/errors/unsupported_type_error.py

@@ -0,0 +1,62 @@
+"""
+Error raised when a type has no equivalent between numdaplot and an underlying library.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.data_types.library import Library
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+UNSUPPORTED_TYPE_MESSAGE = "The type {type_name} has no equivalent between numdaplot and {library_name}."
+
+
+class UnsupportedTypeError(NumdaplotError):
+	"""
+	Raised when a type cannot be converted between numdaplot and numpy or pandas.
+
+	For example, numpy has no ``CATEGORY`` type, and numdaplot has no complex number type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	type_name
+		Name of the type that cannot be converted.
+	library
+		Library on the other side of the conversion, ``Library.NUMPY`` or ``Library.PANDAS``.
+
+	Attributes
+	----------
+	type_name
+		Name of the type that cannot be converted.
+	library
+		Library on the other side of the conversion, ``Library.NUMPY`` or ``Library.PANDAS``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> import numpy
+	>>> try:
+	... 	ndp.Array.from_numpy(numpy.array([1 + 2j]))
+	... except ndp.UnsupportedTypeError as error:
+	... 	print(error)
+	The type complex128 has no equivalent between numdaplot and numpy.
+	"""
+
+	def __init__(self, type_name: str, library: Library) -> None:
+		"""
+		Build the error message from the type and the library.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		type_name
+			Name of the type that cannot be converted.
+		library
+			Library on the other side of the conversion, ``Library.NUMPY`` or ``Library.PANDAS``.
+		"""
+		message = UNSUPPORTED_TYPE_MESSAGE.format(type_name=type_name, library_name=library.value)
+		super().__init__(message)
+		self.type_name = type_name
+		self.library = library

numdaplot/errors/value_conversion_error.py

@@ -0,0 +1,215 @@
+"""
+Error raised when values cannot be stored in a type without losing information, or texts cannot be read as dates.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.numdaplot_error import NumdaplotError
+from numdaplot.errors.rejected_dates import RejectedDate, RejectedDatePart
+
+VALUE_CONVERSION_MESSAGE = (
+	"Cannot store {source_type_name} values{column_text} as {target_type_name} without losing information."
+)
+REJECTED_VALUE_MESSAGE = (
+	"Cannot store the {source_type_name} value {rejected_value!r}{column_text} as {target_type_name} "
+	"without losing information."
+)
+UNREADABLE_DATE_MESSAGE = (
+	"Cannot read the {source_type_name} value {rejected_value!r}{column_text} as {target_type_name} with the format "
+	"{date_format_name}. Give the format of the column with format=, using DateFormat or CustomDateFormat."
+)
+NOT_WHOLE_PART_MESSAGE = (
+	"Cannot use the {source_type_name} value {rejected_value.value!r} as a {rejected_value.part_name}: "
+	"date parts must be whole numbers."
+)
+IMPOSSIBLE_DATE_MESSAGE = (
+	"Cannot build a {target_type_name} from the year {rejected_value.year}, the month {rejected_value.month} and the "
+	"day {rejected_value.day}."
+)
+UNREADABLE_TIME_MESSAGE = (
+	"Cannot read the {source_type_name} value {rejected_value!r}{column_text} as {target_type_name} with the format "
+	"{date_format_name}. Give the format of the column with format=, using a CustomDateFormat of a time only."
+)
+TIME_TYPE_NAME = "TIME"
+COLUMN_TEXT = " of the column {column_name!r}"
+NO_COLUMN_TEXT = ""
+
+
+class ValueConversionError(NumdaplotError):
+	"""
+	Raised when values cannot be stored in a type without losing information, or texts cannot be read as dates.
+
+	For example, decimals stored as integers, a text stored as a number, a text that does not follow the date
+	format, or date parts that form no date. When the first rejected value is known, the message shows it.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	source_type_name
+		Name of the ``ndp.Type`` member of the given values.
+	target_type_name
+		Name of the ``ndp.Type`` member they should be stored as, or ``JSON`` for a value JSON cannot write.
+	rejected_value
+		The first value that cannot be stored. When omitted, the message names no value. A ``RejectedDatePart`` or
+		a ``RejectedDate``, with the year, the month and the day, names the date parts that form no date.
+	date_format_name
+		The name or the pattern of the date format a rejected text was read with. When omitted, or without
+		``rejected_value``, the message names no format.
+
+	Attributes
+	----------
+	source_type_name
+		Name of the ``ndp.Type`` member of the given values.
+	target_type_name
+		Name of the ``ndp.Type`` member they should be stored as.
+	rejected_value
+		The first value that cannot be stored, or ``None`` when it is not known.
+	date_format_name
+		The name or the pattern of the date format a rejected text was read with, ``None`` for other values.
+	column_name
+		Name of the Table column holding the values, or ``None`` for values given to an Array.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> try:
+	... 	ndp.Array.from_list([1.5, 2.5], dtype=ndp.Type.INT64)
+	... except ndp.ValueConversionError as error:
+	... 	print(error)
+	Cannot store FLOAT64 values as INT64 without losing information.
+	>>> days = ndp.Table.from_arrays({"day": ndp.Array.from_list(["31/12/2026"])})
+	>>> try:
+	... 	days.convert(ndp.Conversion(column="day", dtype=ndp.Type.DATE))
+	... except ndp.ValueConversionError as error:
+	... 	print(error)
+	Cannot read the TEXT value '31/12/2026' of the column 'day' as DATE with the format YEAR_MONTH_DAY.
+	Give the format of the column with format=, using DateFormat or CustomDateFormat.
+	"""
+
+	def __init__(
+		self,
+		source_type_name: str,
+		target_type_name: str,
+		rejected_value: object = None,
+		date_format_name: str | None = None,
+	) -> None:
+		"""
+		Build the error message from the type names, and the rejected value and the date format when they are known.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		source_type_name
+			Name of the ``ndp.Type`` member of the given values.
+		target_type_name
+			Name of the ``ndp.Type`` member they should be stored as.
+		rejected_value
+			The first value that cannot be stored. When omitted, the message names no value.
+		date_format_name
+			The name or the pattern of the date format a rejected text was read with. When omitted, or without
+			``rejected_value``, the message names no format.
+		"""
+		self.source_type_name = source_type_name
+		self.target_type_name = target_type_name
+		self.rejected_value = rejected_value
+		self.date_format_name = date_format_name
+		self.column_name: str | None = None
+		message = self.write_message(NO_COLUMN_TEXT)
+		super().__init__(message)
+
+	def write_message(self, column_text: str) -> str:
+		"""
+		Return the message, with the rejected value and the date format when they are known.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_text
+			The words naming the column after the values, or an empty text.
+
+		Returns
+		-------
+		str
+			The message.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> ndp.ValueConversionError("FLOAT64", "INT64").write_message("")
+		'Cannot store FLOAT64 values as INT64 without losing information.'
+		"""
+		message_format = self.choose_message_format()
+		message = message_format.format(
+			source_type_name=self.source_type_name,
+			target_type_name=self.target_type_name,
+			rejected_value=self.rejected_value,
+			date_format_name=self.date_format_name,
+			column_text=column_text,
+		)
+
+		return message
+
+	def choose_message_format(self) -> str:
+		"""
+		Return the message format fitting what is known of the rejected value.
+
+		.. versionadded:: 0.1.0
+
+		Returns
+		-------
+		str
+			The format for date parts, a text read with a date format, a known value, or values in general.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> from numdaplot.errors.rejected_dates import RejectedDate
+		>>> print(ndp.ValueConversionError("INT64", "DATE", RejectedDate(2025, 2, 31)))
+		Cannot build a DATE from the year 2025, the month 2 and the day 31.
+		"""
+		if isinstance(self.rejected_value, RejectedDatePart):
+			return NOT_WHOLE_PART_MESSAGE
+
+		if isinstance(self.rejected_value, RejectedDate):
+			return IMPOSSIBLE_DATE_MESSAGE
+
+		if self.rejected_value is None:
+			return VALUE_CONVERSION_MESSAGE
+
+		if self.date_format_name is None:
+			return REJECTED_VALUE_MESSAGE
+
+		if self.target_type_name == TIME_TYPE_NAME:
+			return UNREADABLE_TIME_MESSAGE
+
+		return UNREADABLE_DATE_MESSAGE
+
+	def name_column(self, column_name: str) -> None:
+		"""
+		Name the Table column holding the values in the message, unless a column is already named.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		column_name
+			The name of the column.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> error = ndp.ValueConversionError("TEXT", "FLOAT64", "abc")
+		>>> error.name_column("payment")
+		>>> print(error)
+		Cannot store the TEXT value 'abc' of the column 'payment' as FLOAT64 without losing information.
+		"""
+		if self.column_name is not None:
+			return
+
+		self.column_name = column_name
+		column_text = COLUMN_TEXT.format(column_name=column_name)
+		message = self.write_message(column_text)
+		self.args = (message,)

numdaplot/ordering/__init__.py

@@ -0,0 +1,5 @@
+"""
+Sort settings shared by Array and Table: order and place of missing values.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/ordering/missing_position.py

@@ -0,0 +1,46 @@
+"""
+Place of missing values in a sort.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class MissingPosition(Enum):
+	"""
+	Place of missing values in a sort, whatever the order.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([20.0, None, 10.0])
+	>>> prices.sort(ndp.ArraySorting(missing=ndp.MissingPosition.FIRST))
+	Array([nan, 10., 20.], dtype=FLOAT64)
+	"""
+
+	FIRST = auto()
+	"""
+	Missing values come before every other value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([20.0, None, 10.0])
+	>>> prices.sort(ndp.ArraySorting(missing=ndp.MissingPosition.FIRST))
+	Array([nan, 10., 20.], dtype=FLOAT64)
+	"""
+
+	LAST = auto()
+	"""
+	Missing values come after every other value, as in pandas. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([20.0, None, 10.0])
+	>>> prices.sort(ndp.ArraySorting(missing=ndp.MissingPosition.LAST))
+	Array([10., 20., nan], dtype=FLOAT64)
+	"""

numdaplot/ordering/order.py

@@ -0,0 +1,46 @@
+"""
+Direction of a sort.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Order(Enum):
+	"""
+	Direction of a sort.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([20, 30, 10])
+	>>> prices.sort(ndp.ArraySorting(order=ndp.Order.DESCENDING))
+	Array([30, 20, 10], dtype=INT64)
+	"""
+
+	ASCENDING = auto()
+	"""
+	From the smallest to the largest value. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([20, 30, 10])
+	>>> prices.sort(ndp.ArraySorting(order=ndp.Order.ASCENDING))
+	Array([10, 20, 30], dtype=INT64)
+	"""
+
+	DESCENDING = auto()
+	"""
+	From the largest to the smallest value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([20, 30, 10])
+	>>> prices.sort(ndp.ArraySorting(order=ndp.Order.DESCENDING))
+	Array([30, 20, 10], dtype=INT64)
+	"""

numdaplot/package_version.py

@@ -0,0 +1,36 @@
+"""
+Version of the installed package.
+
+.. versionadded:: 0.1.0
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+PACKAGE_NAME = "numdaplot"
+UNKNOWN_VERSION = "0+unknown"
+
+
+def find_package_version() -> str:
+	"""
+	Return the version of numdaplot, as written in the information of the installed package.
+
+	.. versionadded:: 0.1.0
+
+	Returns
+	-------
+	str
+		The version, or ``0+unknown`` for a code that runs without being installed.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.package_version import find_package_version
+	>>> find_package_version() == ndp.__version__
+	True
+	"""
+	try:
+		package_version = version(PACKAGE_NAME)
+	except PackageNotFoundError:
+		return UNKNOWN_VERSION
+
+	return package_version

numdaplot/plots/__init__.py

@@ -0,0 +1,5 @@
+"""
+Plots of Tables and Arrays: charts, style, image files and display.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/plots/chart_layer.py

@@ -0,0 +1,47 @@
+"""
+A chart and the values it draws.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.plots.charts.chart import Chart
+from numdaplot.plots.charts.value_axis import ValueAxis
+from numdaplot.plots.data.chart_values import ChartValues
+from numdaplot.plots.data.point_values import PointValues
+from numdaplot.plots.data.sample_values import SampleValues
+
+
+@dataclass(frozen=True, eq=False)
+class ChartLayer:
+	"""
+	A chart and the values it draws, read when the Plot is created.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	chart
+		The chart settings.
+	values
+		The positions and the series, or for a ``HistogramChart`` and a ``BoxChart`` the columns and their groups.
+	points
+		The values coloring and sizing the points of a ``ScatterChart``, None for other charts.
+	value_axis
+		The vertical axis the chart is measured on, ``ValueAxis.LEFT`` unless added on the right.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.plots.chart_layer import ChartLayer
+	>>> from numdaplot.plots.data.array_values import read_array_values
+	>>> prices = ndp.Array.from_list([12.0, 15.5])
+	>>> ChartLayer(ndp.LineChart(), read_array_values(prices, "LineChart")).points is None
+	True
+	"""
+
+	chart: Chart
+	values: ChartValues | SampleValues
+	points: PointValues | None = None
+	value_axis: ValueAxis = ValueAxis.LEFT

numdaplot/plots/charts/__init__.py

@@ -0,0 +1,5 @@
+"""
+Charts drawn by a Plot and the look of their series.
+
+.. versionadded:: 0.1.0
+"""