numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/files/file_access.py

@@ -0,0 +1,152 @@
+"""
+Errors of the file system while reading or writing a file.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+from types import TracebackType
+
+from numdaplot.errors.file_access_error import FileAccessError
+from numdaplot.errors.numdaplot_error import NumdaplotError
+
+READ_OPERATION = "read"
+WRITE_OPERATION = "write to"
+PERMISSION_REASON = "permission denied"
+MISSING_FOLDER_REASON = "the folder {folder} does not exist"
+FOLDER_IS_FILE_REASON = "the folder {folder} is a file"
+
+
+class FileAccessErrors:
+	"""
+	Context turning an error of the file system during a block into a ``FileAccessError``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	operation
+		What the block does: ``READ_OPERATION`` or ``WRITE_OPERATION``.
+	path
+		The path of the file.
+
+	Examples
+	--------
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.file_access import FileAccessErrors, WRITE_OPERATION
+	>>> path = Path("missing_folder/sales.csv")
+	>>> try:
+	... 	with FileAccessErrors(WRITE_OPERATION, path):
+	... 		path.write_text("sales")
+	... except ndp.FileAccessError as error:
+	... 	print(error)
+	Cannot write to missing_folder/sales.csv: the folder missing_folder does not exist.
+	"""
+
+	def __init__(self, operation: str, path: Path) -> None:
+		"""
+		Keep the operation and the path of the block.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		operation
+			What the block does: ``READ_OPERATION`` or ``WRITE_OPERATION``.
+		path
+			The path of the file.
+		"""
+		self.operation = operation
+		self.path = path
+
+	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:
+		"""
+		Raise a ``FileAccessError`` for an error of the file system. Any other error goes on unchanged.
+
+		.. 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
+		------
+		FileAccessError
+			When the block raised an ``OSError`` that is not already an error of numdaplot.
+		"""
+		if not isinstance(error, OSError):
+			return
+
+		if isinstance(error, NumdaplotError):
+			return
+
+		reason = find_access_reason(self.path, error)
+		path_text = str(self.path)
+		raise FileAccessError(self.operation, path_text, reason) from error
+
+
+def find_access_reason(path: Path, error: OSError) -> str:
+	"""
+	Return why the file system refused a file.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of the file.
+	error
+		The error of the file system.
+
+	Returns
+	-------
+	str
+		A missing permission or a wrong folder in words, else what the system says.
+
+	Examples
+	--------
+	>>> from pathlib import Path
+	>>> from numdaplot.tables.files.file_access import find_access_reason
+	>>> find_access_reason(Path("missing_folder/sales.csv"), OSError("Disk is full"))
+	'the folder missing_folder does not exist'
+	>>> find_access_reason(Path("sales.csv"), OSError(28, "No space left on device"))
+	'No space left on device'
+	"""
+	if isinstance(error, PermissionError):
+		return PERMISSION_REASON
+
+	folder = path.parent
+	folder_exists = folder.exists()
+	if not folder_exists:
+		missing_folder_reason = MISSING_FOLDER_REASON.format(folder=folder)
+		return missing_folder_reason
+
+	folder_is_folder = folder.is_dir()
+	if not folder_is_folder:
+		folder_is_file_reason = FOLDER_IS_FILE_REASON.format(folder=folder)
+		return folder_is_file_reason
+
+	if error.strerror is not None:
+		return error.strerror
+
+	system_reason = str(error)
+
+	return system_reason

numdaplot/tables/files/file_paths.py

@@ -0,0 +1,106 @@
+"""
+Paths of the files a Table reads and writes.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+
+from numdaplot.errors.file_exists_error import FileExistsError
+from numdaplot.errors.file_not_found_error import FileNotFoundError
+from numdaplot.tables.conflict import Conflict
+
+type FilePath = str | Path
+"""
+The path of a file, as a text or a ``pathlib.Path``.
+
+It is a name used by the documentation and the annotations, not an object to create: pass the value itself,
+such as ``"sales.csv"`` or ``Path("data/sales.csv")``.
+
+.. versionadded:: 0.1.0
+
+Examples
+--------
+>>> from pathlib import Path
+>>> from tempfile import TemporaryDirectory
+>>> import numdaplot as ndp
+>>> cities = ndp.Array.from_list(["Paris", "Lyon"])
+>>> sales = ndp.Table.from_arrays({"city": cities})
+>>> with TemporaryDirectory() as folder:
+... 	sales.to_csv(Path(folder) / "sales.csv")
+... 	ndp.Table.from_csv(Path(folder) / "sales.csv").column("city").to_list()
+['Paris', 'Lyon']
+"""
+
+
+def require_existing_file(path: Path) -> None:
+	"""
+	Check that a file exists at a path.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of the file to read.
+
+	Raises
+	------
+	FileNotFoundError
+		When there is no file at the path, the numdaplot error that is also the Python one.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from pathlib import Path
+	>>> from numdaplot.tables.files.file_paths import require_existing_file
+	>>> try:
+	... 	require_existing_file(Path("missing.csv"))
+	... except ndp.FileNotFoundError as error:
+	... 	print(error)
+	No file found at missing.csv.
+	"""
+	is_file = path.is_file()
+	if not is_file:
+		path_text = str(path)
+		raise FileNotFoundError(path_text)
+
+
+def require_free_path(path: Path, on_conflict: Conflict) -> None:
+	"""
+	Check that a file can be written at a path.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of the file to write.
+	on_conflict
+		``ERROR`` refuses to overwrite an existing file, ``REPLACE`` allows it.
+
+	Raises
+	------
+	FileExistsError
+		When a file exists at the path and ``on_conflict`` is ``ERROR``.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.file_paths import require_free_path
+	>>> with tempfile.NamedTemporaryFile(suffix=".csv") as file:
+	... 	path = Path(file.name)
+	... 	require_free_path(path, ndp.Conflict.REPLACE)
+	... 	try:
+	... 		require_free_path(path, ndp.Conflict.ERROR)
+	... 	except ndp.FileExistsError:
+	... 		print("refused")
+	refused
+	"""
+	file_exists = path.exists()
+	refuses_existing_file = file_exists and on_conflict == Conflict.ERROR
+	if refuses_existing_file:
+		path_text = str(path)
+		raise FileExistsError(path_text)

numdaplot/tables/files/json_decimals.py

@@ -0,0 +1,387 @@
+"""
+Exact writing of the decimal columns of a Table in a JSON file.
+
+pandas writes decimals with 10 digits after the point at most, which changes values such as ``1 / 3``.
+
+.. versionadded:: 0.1.0
+"""
+
+import json
+from typing import Any, cast
+
+import numpy
+import pandas
+from numpy.typing import NDArray
+
+from numdaplot.data_types.numpy_mapping import from_numpy_dtype
+from numdaplot.errors.value_conversion_error import ValueConversionError
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.named_column_errors import NamedColumnErrors
+
+DECIMAL_KIND = "f"
+DOUBLE_DTYPE = numpy.dtype(numpy.float64)
+JSON_FORMAT_NAME = "JSON"
+JSON_NULL = "null"
+NAN_TEXT = "nan"
+DECIMAL_FORMAT = "%.{decimals}f"
+CELL_SEPARATOR = ":"
+CELL_JOINER = ","
+OBJECT_START = "{"
+OBJECT_END = "}"
+LINE_END = "\n"
+RECORDS_ORIENTATION = "records"
+ISO_DATE_FORMAT = "iso"
+FIRST_CHARACTER_AFTER_BRACE = 1
+LAST_CHARACTER_BEFORE_BRACE = -1
+
+
+def is_decimal_column(column: Column) -> bool:
+	"""
+	Return whether a column holds decimals, stored by pandas with or without missing values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A column.
+
+	Returns
+	-------
+	bool
+		True for a column of 32 or 64 bit decimals.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.files.json_decimals import is_decimal_column
+	>>> is_decimal_column(pandas.Series([1.5], dtype="Float64")), is_decimal_column(pandas.Series([1]))
+	(True, False)
+	"""
+	is_decimal = column.dtype.kind == DECIMAL_KIND
+
+	return is_decimal
+
+
+def read_decimals(column: Column) -> NDArray[Any]:
+	"""
+	Return the decimals of a column, in their number of bits, NaN for a missing value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A decimal column.
+
+	Returns
+	-------
+	NDArray
+		The values.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.files.json_decimals import read_decimals
+	>>> read_decimals(pandas.Series([1.5, None], dtype="Float32"))
+	array([1.5, nan], dtype=float32)
+	"""
+	dtype_name = str(column.dtype)
+	numpy_dtype = numpy.dtype(dtype_name.lower())
+	values = column.to_numpy(dtype=numpy_dtype, na_value=numpy.nan)
+
+	return values
+
+
+def has_decimal_column(frame: pandas.DataFrame) -> bool:
+	"""
+	Return whether a frame holds a column of decimals.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+
+	Returns
+	-------
+	bool
+		True when at least one column holds decimals.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.files.json_decimals import has_decimal_column
+	>>> has_decimal_column(pandas.DataFrame({"count": [1], "price": [1.5]}))
+	True
+	"""
+	column_names = list[str](frame.columns)
+
+	for column_name in column_names:
+		column = frame[column_name]
+		is_decimal = is_decimal_column(column)
+		if is_decimal:
+			return True
+
+	return False
+
+
+def require_finite_values(values: NDArray[Any]) -> None:
+	"""
+	Check that decimals hold no infinite value, which JSON cannot write.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The decimals, NaN for a missing value.
+
+	Raises
+	------
+	ValueConversionError
+		At the first infinite value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.json_decimals import require_finite_values
+	>>> try:
+	... 	require_finite_values(numpy.array([1.5, numpy.inf]))
+	... except ndp.ValueConversionError as error:
+	... 	print(error)
+	Cannot store the FLOAT64 value inf as JSON without losing information.
+	"""
+	is_infinite = numpy.isinf(values)
+	has_infinite = bool(is_infinite.any())
+	if not has_infinite:
+		return
+
+	infinite_values = values[is_infinite]
+	first_infinite = float(infinite_values[0])
+	column_type = from_numpy_dtype(values.dtype)
+	raise ValueConversionError(column_type.name, JSON_FORMAT_NAME, first_infinite)
+
+
+def write_shortest_texts(values: NDArray[Any]) -> list[str]:
+	"""
+	Return decimals as the shortest texts giving the same values in their number of bits.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The finite decimals, NaN for a missing value.
+
+	Returns
+	-------
+	list[str]
+		One JSON number per value, ``null`` for a missing value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.files.json_decimals import write_shortest_texts
+	>>> write_shortest_texts(numpy.array([1 / 3, numpy.nan]))
+	['0.3333333333333333', 'null']
+	>>> write_shortest_texts(numpy.array([0.1], dtype="float32"))
+	['0.1']
+	"""
+	if values.dtype == DOUBLE_DTYPE:
+		python_values = cast(list[float], values.tolist())
+		texts = list(map(repr, python_values))
+	else:
+		# A Python float would write the value of a 32 bit decimal widened to 64 bits, such as 0.10000000149011612.
+		numpy_texts = values.astype(str)
+		texts = cast(list[str], numpy_texts.tolist())
+
+	missing_positions = numpy.flatnonzero(numpy.isnan(values))
+	for position in missing_positions:
+		missing_position = int(position)
+		texts[missing_position] = JSON_NULL
+
+	return texts
+
+
+def write_rounded_texts(values: NDArray[Any], decimals: int) -> list[str]:
+	"""
+	Return decimals rounded to a number of decimals, keeping their zeros as in a CSV file.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		The finite decimals, NaN for a missing value.
+	decimals
+		The number of decimals.
+
+	Returns
+	-------
+	list[str]
+		One JSON number per value, ``null`` for a missing value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.tables.files.json_decimals import write_rounded_texts
+	>>> write_rounded_texts(numpy.array([1.5, numpy.nan]), 2)
+	['1.50', 'null']
+	"""
+	decimal_format = DECIMAL_FORMAT.format(decimals=decimals)
+	python_values = cast(list[float], values.tolist())
+	rounded_texts = [JSON_NULL if value != value else decimal_format % value for value in python_values]
+
+	return rounded_texts
+
+
+def write_decimal_cells(column: Column, column_name: str, decimals: int | None) -> list[str]:
+	"""
+	Return the name and the value of a decimal column, as they appear in each object of a JSON file.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A decimal column.
+	column_name
+		The name of the column.
+	decimals
+		The number of decimals written, every digit of each value when ``None``.
+
+	Returns
+	-------
+	list[str]
+		One text per row.
+
+	Raises
+	------
+	ValueConversionError
+		At the first infinite value.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.files.json_decimals import write_decimal_cells
+	>>> write_decimal_cells(pandas.Series([0.1 + 0.2]), "price", None)
+	['"price":0.30000000000000004']
+	"""
+	values = read_decimals(column)
+	with NamedColumnErrors(column):
+		require_finite_values(values)
+
+	if decimals is None:
+		value_texts = write_shortest_texts(values)
+	else:
+		value_texts = write_rounded_texts(values, decimals)
+
+	name_text = json.dumps(column_name, ensure_ascii=False)
+	cell_start = name_text + CELL_SEPARATOR
+	cells = [cell_start + value_text for value_text in value_texts]
+
+	return cells
+
+
+def write_other_cells(frame: pandas.DataFrame) -> list[str]:
+	"""
+	Return the names and the values of columns without decimals, as they appear in each object of a JSON file.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		Columns without decimals.
+
+	Returns
+	-------
+	list[str]
+		One text per row, written by pandas: ``null``, ISO 8601 dates and durations.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.files.json_decimals import write_other_cells
+	>>> write_other_cells(pandas.DataFrame({"city": ["Paris", None], "count": [1, 2]}))
+	['"city":"Paris","count":1', '"city":null,"count":2']
+	"""
+	# Some versions of the pandas stubs leave the parameter types of to_json unknown.
+	json_frame = cast(Any, frame)
+	lines_text = cast(
+		str,
+		json_frame.to_json(orient=RECORDS_ORIENTATION, lines=True, force_ascii=False, date_format=ISO_DATE_FORMAT),
+	)
+	stripped_text = lines_text.removesuffix(LINE_END)
+	# JSON writes a line break inside a text as an escape, so each line is one object.
+	lines = stripped_text.split(LINE_END)
+	cells = [line[FIRST_CHARACTER_AFTER_BRACE:LAST_CHARACTER_BEFORE_BRACE] for line in lines]
+
+	return cells
+
+
+def write_exact_objects(frame: pandas.DataFrame, decimals: int | None) -> list[str]:
+	"""
+	Return one JSON object per row, the columns staying in their order.
+
+	Neighbor columns without decimals are written together by pandas, which is much faster than one by one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table, at least one holding decimals.
+	decimals
+		The number of decimals written, every digit of each value when ``None``.
+
+	Returns
+	-------
+	list[str]
+		One object per row.
+
+	Raises
+	------
+	ValueConversionError
+		At the first infinite value.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.files.json_decimals import write_exact_objects
+	>>> write_exact_objects(pandas.DataFrame({"city": ["Paris"], "price": [1 / 3]}), None)
+	['{"city":"Paris","price":0.3333333333333333}']
+	"""
+	if frame.empty:
+		return []
+
+	cell_groups = list[list[str]]()
+	other_names = list[str]()
+
+	for column_name in list[str](frame.columns):
+		column = frame[column_name]
+		is_decimal = is_decimal_column(column)
+		if not is_decimal:
+			other_names.append(column_name)
+			continue
+
+		if other_names != []:
+			other_cells = write_other_cells(frame[other_names])
+			cell_groups.append(other_cells)
+			other_names = list[str]()
+
+		decimal_cells = write_decimal_cells(column, column_name, decimals)
+		cell_groups.append(decimal_cells)
+
+	if other_names != []:
+		last_cells = write_other_cells(frame[other_names])
+		cell_groups.append(last_cells)
+
+	row_cells = zip(*cell_groups, strict=True)
+	rows = map(CELL_JOINER.join, row_cells)
+	objects = [OBJECT_START + row + OBJECT_END for row in rows]
+
+	return objects