numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/files/encoding.py

@@ -0,0 +1,82 @@
+"""
+Text encodings of the files a Table reads and writes.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum
+
+
+class Encoding(Enum):
+	r"""
+	Text encoding of a file, used by the CSV, SAS and SAS transport options.
+
+	``CsvReadOptions``, ``CsvWriteOptions``, ``SasReadOptions`` and ``XptReadOptions`` take it.
+
+	The value of each member is the name Python gives to the encoding.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "cities.csv"
+	>>> _ = path.write_text("city\nB\u00e9ziers\n", encoding="latin-1")
+	>>> cities = ndp.Table.from_csv(path, ndp.CsvReadOptions(encoding=ndp.Encoding.LATIN_1))
+	>>> cities.column("city").to_list() == ["B\u00e9ziers"]
+	True
+	"""
+
+	UTF_8 = "utf-8"
+	r"""
+	UTF-8, the most common encoding. Default value.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "cities.csv"
+	>>> _ = path.write_text("city\nB\u00e9ziers\n", encoding="utf-8")
+	>>> cities = ndp.Table.from_csv(path, ndp.CsvReadOptions(encoding=ndp.Encoding.UTF_8))
+	>>> cities.column("city").to_list() == ["B\u00e9ziers"]
+	True
+	"""
+
+	UTF_8_BOM = "utf-8-sig"
+	r"""
+	UTF-8 starting with a byte order mark, as written by Excel when it saves a CSV file.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "cities.csv"
+	>>> _ = path.write_text("city\nB\u00e9ziers\n", encoding="utf-8-sig")
+	>>> cities = ndp.Table.from_csv(path, ndp.CsvReadOptions(encoding=ndp.Encoding.UTF_8_BOM))
+	>>> cities.column("city").to_list() == ["B\u00e9ziers"]
+	True
+	"""
+
+	LATIN_1 = "latin-1"
+	r"""
+	Latin-1 (ISO 8859-1), used by older software in Western Europe.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "cities.csv"
+	>>> _ = path.write_text("city\nB\u00e9ziers\n", encoding="latin-1")
+	>>> cities = ndp.Table.from_csv(path, ndp.CsvReadOptions(encoding=ndp.Encoding.LATIN_1))
+	>>> cities.column("city").to_list() == ["B\u00e9ziers"]
+	True
+	"""

numdaplot/tables/files/excel_file.py

@@ -0,0 +1,171 @@
+"""
+Reading and writing Excel files.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+from typing import Any, cast
+
+import pandas
+
+from numdaplot.tables.columns.column_names import require_column_names
+from numdaplot.tables.files.excel_read_options import ExcelReadOptions
+from numdaplot.tables.files.excel_time_cells import restore_time_columns
+from numdaplot.tables.files.excel_write_options import ExcelWriteOptions
+from numdaplot.tables.files.missing_texts import find_missing_settings
+from numdaplot.tables.files.optional_package import require_package
+from numdaplot.tables.files.pandas_backend import NULLABLE_DTYPE_BACKEND
+from numdaplot.tables.frames.time_zones import require_no_time_zone
+
+EXCEL_PACKAGE = "openpyxl"
+EXCEL_EXTRA = "excel"
+FIRST_SHEET = 0
+DEFAULT_SHEET_NAME = "Sheet1"
+HEADER_ROW_COUNT = 1
+NO_MISSING_TEXTS = list[str]()
+EXCEL_OPERATION = "An Excel file"
+
+
+def read_excel_file(path: Path, options: ExcelReadOptions) -> pandas.DataFrame:
+	"""
+	Return the columns of a sheet of an Excel file whose first row holds the column names.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing Excel file.
+	options
+		The sheet to read, the first one when omitted, and the texts read as missing.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns as pandas reads them, empty for an empty sheet. A column of time cells only, or of duration cells
+		only, holds Python times or durations.
+
+	Raises
+	------
+	MissingDependencyError
+		When ``openpyxl`` is not installed.
+	TimeZoneMismatchError
+		When a column holds datetimes with a time zone, which Excel files cannot store.
+	InvalidColumnNameError
+		When a cell of the first row is empty or is not a text.
+	DuplicateColumnError
+		When a column name appears twice.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.excel_file import read_excel_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.xlsx"
+	>>> pandas.DataFrame({"price": [1.5]}).to_excel(path, index=False)
+	>>> read_excel_file(path, ndp.ExcelReadOptions())
+	   price
+	0    1.5
+	"""
+	require_package(EXCEL_PACKAGE, EXCEL_EXTRA)
+	sheet = find_read_sheet(options)
+	# The pandas stubs leave the types of the Excel engines unknown.
+	excel_pandas = cast(Any, pandas)
+	# A column name is never a missing value, so the first row is read without any missing text.
+	header_settings = find_missing_settings(NO_MISSING_TEXTS)
+	raw_header_frame = excel_pandas.read_excel(
+		path, sheet_name=sheet, header=None, nrows=HEADER_ROW_COUNT, **header_settings
+	)
+	header_frame = cast(pandas.DataFrame, raw_header_frame)
+	if header_frame.empty:
+		empty_frame = pandas.DataFrame()
+		return empty_frame
+
+	header_row = header_frame.iloc[0]
+	header = header_row.tolist()
+	require_column_names(header)
+	missing_settings = find_missing_settings(options.missing_texts)
+	raw_frame = excel_pandas.read_excel(
+		path, sheet_name=sheet, dtype_backend=NULLABLE_DTYPE_BACKEND, **missing_settings
+	)
+	read_frame = cast(pandas.DataFrame, raw_frame)
+	frame = restore_time_columns(read_frame, path, sheet, missing_settings)
+
+	return frame
+
+
+def find_read_sheet(options: ExcelReadOptions) -> str | int:
+	"""
+	Return the sheet pandas reads: its name, or the position of the first sheet.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	options
+		The settings of the Excel file.
+
+	Returns
+	-------
+	str or int
+		The name of the sheet, or 0 when no sheet is named.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.excel_file import find_read_sheet
+	>>> find_read_sheet(ndp.ExcelReadOptions())
+	0
+	"""
+	if options.sheet is None:
+		return FIRST_SHEET
+
+	return options.sheet
+
+
+def write_excel_file(frame: pandas.DataFrame, path: Path, options: ExcelWriteOptions) -> None:
+	"""
+	Write the columns of a Table in a sheet of an Excel file, column names on the first row.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	path
+		The path of the file, replaced when it exists.
+	options
+		The name of the sheet, ``"Sheet1"`` when omitted.
+
+	Raises
+	------
+	MissingDependencyError
+		When ``openpyxl`` is not installed.
+	TimeZoneMismatchError
+		When a column holds datetimes with a time zone, which Excel files cannot store.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.excel_file import write_excel_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.xlsx"
+	>>> write_excel_file(pandas.DataFrame({"price": [1.5]}), path, ndp.ExcelWriteOptions(sheet="Sales"))
+	>>> pandas.ExcelFile(path).sheet_names
+	['Sales']
+	"""
+	require_no_time_zone(frame, EXCEL_OPERATION)
+	require_package(EXCEL_PACKAGE, EXCEL_EXTRA)
+	sheet_name = DEFAULT_SHEET_NAME
+	if options.sheet is not None:
+		sheet_name = options.sheet
+
+	# The pandas stubs leave the types of the Excel engines unknown.
+	excel_frame = cast(Any, frame)
+	excel_frame.to_excel(path, sheet_name=sheet_name, index=False)

numdaplot/tables/files/excel_read_options.py

@@ -0,0 +1,79 @@
+r"""
+Settings of the Excel files a Table reads.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.files.column_names import ColumnNames
+from numdaplot.tables.files.excel_sheet import require_sheet_name
+
+
+@dataclass(frozen=True)
+class ExcelReadOptions:
+	r"""
+	Settings of an Excel file read by ``Table.from_excel``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	sheet
+		The name of the sheet read, the first sheet when omitted.
+	column_names
+		Whether the column names are cleaned, ``ColumnNames.CLEANED`` by default: the spaces, tabs and line breaks at
+		the start and the end of each name are removed. ``ColumnNames.KEPT`` keeps the names as written.
+	missing_texts
+		The texts read as missing values, compared with the whole value of each cell. When omitted, the texts pandas
+		reads as missing: ``""``, ``"#N/A"``, ``"#N/A N/A"``, ``"#NA"``, ``"-1.#IND"``, ``"-1.#QNAN"``, ``"-NaN"``,
+		``"-nan"``, ``"1.#IND"``, ``"1.#QNAN"``, ``"<NA>"``, ``"N/A"``, ``"NA"``, ``"NULL"``, ``"NaN"``, ``"None"``,
+		``"n/a"``, ``"nan"`` and ``"null"``. A given list replaces them: ``[]`` reads no value as missing, not even
+		an empty one: an empty cell is then read as an empty text.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidSheetNameError
+		When the name is empty, longer than 31 characters, or holds ``[ ] : * ? / \``, which Excel refuses.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "sales.xlsx"
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])})
+	>>> prices.to_excel(path, ndp.ExcelWriteOptions(sheet="Sales"))
+	>>> ndp.Table.from_excel(path, ndp.ExcelReadOptions(sheet="Sales"))
+	    price
+	  FLOAT64
+	0     1.5
+	"""
+
+	sheet: str | None = None
+	column_names: ColumnNames = ColumnNames.CLEANED
+	missing_texts: list[str] | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting, and that Excel accepts the sheet name.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidSheetNameError
+			When the name is empty, longer than 31 characters, or holds a character Excel refuses.
+		"""
+		require_field_types(self)
+
+		require_sheet_name(self.sheet)
+
+		if self.missing_texts is not None:
+			missing_texts_copy = list(self.missing_texts)
+			object.__setattr__(self, "missing_texts", missing_texts_copy)

numdaplot/tables/files/excel_sheet.py

@@ -0,0 +1,50 @@
+r"""
+Check of the name of an Excel sheet.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.invalid_sheet_name_error import InvalidSheetNameError
+
+MAXIMUM_SHEET_LENGTH = 31
+FORBIDDEN_SHEET_CHARACTERS = frozenset("[]:*?/\\")
+
+
+def require_sheet_name(sheet: str | None) -> None:
+	r"""
+	Check that Excel accepts a sheet name, when it is given.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	sheet
+		The name of the sheet, or None for the default sheet.
+
+	Raises
+	------
+	InvalidSheetNameError
+		When the name is empty, longer than 31 characters, or holds ``[ ] : * ? / \``, which Excel refuses.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.excel_sheet import require_sheet_name
+	>>> try:
+	... 	require_sheet_name("Sales/2026")
+	... except ndp.InvalidSheetNameError as error:
+	... 	print(error)
+	Expected a sheet name of 1 to 31 characters without [ ] : * ? / \, got 'Sales/2026'.
+	"""
+	if sheet is None:
+		return
+
+	sheet_length = len(sheet)
+	has_valid_length = 0 < sheet_length <= MAXIMUM_SHEET_LENGTH
+	sheet_characters = set(sheet)
+	forbidden_characters = sheet_characters & FORBIDDEN_SHEET_CHARACTERS
+	forbidden_count = len(forbidden_characters)
+	has_forbidden_character = forbidden_count > 0
+	is_valid = has_valid_length and not has_forbidden_character
+	if not is_valid:
+		raise InvalidSheetNameError(sheet)

numdaplot/tables/files/excel_time_cells.py

@@ -0,0 +1,146 @@
+"""
+Time and duration cells of an Excel file, which pandas reads as texts.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+from typing import Any, cast
+
+import pandas
+from pandas.api.types import infer_dtype
+
+PYTHON_OBJECT_DTYPE = object
+TIME_KINDS = frozenset({"time", "timedelta"})
+
+
+def restore_time_columns(
+	frame: pandas.DataFrame, path: Path, sheet: str | int, missing_settings: dict[str, Any]
+) -> pandas.DataFrame:
+	"""
+	Return the columns of a sheet with the columns of time or duration cells read again as Python values.
+
+	The types of pandas that accept missing values write a time or a duration cell as a text. Only the text columns
+	are read again, as Python values: a column of times of day only, or of durations only, keeps them, and becomes a
+	``TIME`` or a ``DURATION`` column. The other columns are kept as read.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of the sheet, read with the types of pandas that accept missing values.
+	path
+		The path of the Excel file.
+	sheet
+		The name or the position of the sheet.
+	missing_settings
+		The settings of pandas reading the missing values, the same as for ``frame``.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The same columns, a column of times or durations holding Python values.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from datetime import time
+	>>> from pathlib import Path
+	>>> import openpyxl
+	>>> import pandas
+	>>> from numdaplot.tables.files.excel_time_cells import restore_time_columns
+	>>> path = Path(tempfile.mkdtemp()) / "hours.xlsx"
+	>>> book = openpyxl.Workbook()
+	>>> book.active.append(["hrmn"])
+	>>> book.active.append([time(15, 35)])
+	>>> book.save(path)
+	>>> frame = pandas.read_excel(path, dtype_backend="numpy_nullable")
+	>>> restore_time_columns(frame, path, 0, {})["hrmn"].tolist()
+	[datetime.time(15, 35)]
+	"""
+	text_names = find_text_columns(frame)
+	if text_names == []:
+		return frame
+
+	# The pandas stubs leave the types of the Excel engines unknown.
+	excel_pandas = cast(Any, pandas)
+	raw_object_frame = excel_pandas.read_excel(
+		path, sheet_name=sheet, dtype=PYTHON_OBJECT_DTYPE, usecols=text_names, **missing_settings
+	)
+	object_frame = cast(pandas.DataFrame, raw_object_frame)
+	restored_frame = frame.copy()
+
+	for text_name in text_names:
+		object_column = object_frame[text_name]
+		holds_time_cells = holds_only_time_cells(object_column)
+		if holds_time_cells:
+			restored_frame[text_name] = object_column
+
+	return restored_frame
+
+
+def find_text_columns(frame: pandas.DataFrame) -> list[str]:
+	"""
+	Return the names of the text columns of a sheet read with the types of pandas that accept missing values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a sheet.
+
+	Returns
+	-------
+	list[str]
+		The names of the columns of texts, in their order.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.files.excel_time_cells import find_text_columns
+	>>> frame = pandas.DataFrame({"city": pandas.Series(["Pau"], dtype="string"), "count": [1]})
+	>>> find_text_columns(frame)
+	['city']
+	"""
+	text_names = list[str]()
+
+	for column_name, column in frame.items():
+		if isinstance(column.dtype, pandas.StringDtype):
+			text_names.append(str(column_name))
+
+	return text_names
+
+
+def holds_only_time_cells(column: pandas.Series) -> bool:
+	"""
+	Return whether a column of Python values holds times of day only, or durations only, besides missing values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A column read as Python values.
+
+	Returns
+	-------
+	bool
+		True for ``datetime.time`` values only or ``datetime.timedelta`` values only, False for a mix with texts or
+		an empty column.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> import pandas
+	>>> from numdaplot.tables.files.excel_time_cells import holds_only_time_cells
+	>>> holds_only_time_cells(pandas.Series([time(8), None], dtype=object))
+	True
+	>>> holds_only_time_cells(pandas.Series([time(8), "unknown"], dtype=object))
+	False
+	"""
+	inferred_kind = infer_dtype(column, skipna=True)
+	is_time_kind = inferred_kind in TIME_KINDS
+
+	return is_time_kind

numdaplot/tables/files/excel_write_options.py

@@ -0,0 +1,63 @@
+r"""
+Settings of the Excel files a Table writes.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.files.excel_sheet import require_sheet_name
+
+
+@dataclass(frozen=True)
+class ExcelWriteOptions:
+	r"""
+	Settings of an Excel file written by ``Table.to_excel``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	sheet
+		The name of the written sheet, ``"Sheet1"`` when omitted.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidSheetNameError
+		When the name is empty, longer than 31 characters, or holds ``[ ] : * ? / \``, which Excel refuses.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "sales.xlsx"
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])})
+	>>> prices.to_excel(path, ndp.ExcelWriteOptions(sheet="Sales"))
+	>>> ndp.Table.from_excel(path, ndp.ExcelReadOptions(sheet="Sales"))
+	    price
+	  FLOAT64
+	0     1.5
+	"""
+
+	sheet: str | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting, and that Excel accepts the sheet name.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidSheetNameError
+			When the name is empty, longer than 31 characters, or holds a character Excel refuses.
+		"""
+		require_field_types(self)
+
+		require_sheet_name(self.sheet)