numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/files/json_file.py

@@ -0,0 +1,203 @@
+"""
+Reading and writing JSON files.
+
+.. versionadded:: 0.1.0
+"""
+
+import json
+from pathlib import Path
+from typing import Any, cast
+
+import pandas
+
+from numdaplot.tables.files.json_decimals import has_decimal_column, write_exact_objects
+from numdaplot.tables.files.json_layout import JsonLayout
+from numdaplot.tables.files.json_read_options import JsonReadOptions
+from numdaplot.tables.files.json_write_options import JsonWriteOptions
+
+JSON_ENCODING = "utf-8"
+RECORDS_ORIENTATION = "records"
+ISO_DATE_FORMAT = "iso"
+PYTHON_OBJECT_DTYPE = object
+WRITE_MODE = "w"
+LINE_END = "\n"
+OBJECT_SEPARATOR = ","
+LIST_FORMAT = "[{objects}]"
+UNCHANGED_NEWLINES = ""
+EMPTY_LINES_TEXT = ""
+
+
+def read_json_file(path: Path, options: JsonReadOptions) -> pandas.DataFrame:
+	"""
+	Return the columns of a JSON file holding one object per row.
+
+	The values are kept as Python objects, so a Table guesses each type from the values of the file
+	only: a text that looks like a number or a date stays a text.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing JSON file, in UTF-8.
+	options
+		The layout of the rows.
+
+	Returns
+	-------
+	pandas.DataFrame
+		One column per name found in the objects, holding Python objects.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.json_file import read_json_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.json"
+	>>> _ = path.write_text('[{"city": "Paris", "count": 2}]')
+	>>> read_json_file(path, ndp.JsonReadOptions())
+	    city count
+	0  Paris     2
+	"""
+	with path.open(encoding=JSON_ENCODING) as file:
+		if options.layout == JsonLayout.LINES:
+			content = file.read()
+			records = read_json_lines(content)
+		else:
+			records = json.load(file)
+
+	frame = pandas.DataFrame(records, dtype=PYTHON_OBJECT_DTYPE)
+
+	return frame
+
+
+def read_json_lines(content: str) -> list[Any]:
+	r"""
+	Return the objects of a JSON Lines text, one per line, skipping blank lines.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	content
+		The whole text of the file.
+
+	Returns
+	-------
+	list[Any]
+		One decoded object per line that is not blank.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.files.json_file import read_json_lines
+	>>> read_json_lines('{"price": 1}\n\n{"price": 2}\n')
+	[{'price': 1}, {'price': 2}]
+	"""
+	lines = content.splitlines()
+	records = list[Any]()
+
+	for line in lines:
+		stripped_line = line.strip()
+		if stripped_line == "":
+			continue
+
+		record = json.loads(stripped_line)
+		records.append(record)
+
+	return records
+
+
+def write_json_file(frame: pandas.DataFrame, path: Path, options: JsonWriteOptions) -> None:
+	"""
+	Write the columns of a Table in a JSON file, one object per row, in UTF-8.
+
+	Missing values are written as ``null``, dates and durations in the ISO 8601 format, and decimals with every
+	digit of their value unless ``options`` gives their number.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	path
+		The path of the file, replaced when it exists.
+	options
+		The layout of the rows and the number of decimals.
+
+	Raises
+	------
+	ValueConversionError
+		At the first infinite value of a decimal column, which JSON cannot write.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.json_file import write_json_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.json"
+	>>> write_json_file(pandas.DataFrame({"price": [1.5]}), path, ndp.JsonWriteOptions())
+	>>> path.read_text()
+	'[{"price":1.5}]'
+	"""
+	writes_lines = options.layout == JsonLayout.LINES
+	has_decimals = has_decimal_column(frame)
+	if has_decimals:
+		objects = write_exact_objects(frame, options.decimals)
+		file_text = join_objects(objects, writes_lines)
+		with path.open(WRITE_MODE, encoding=JSON_ENCODING, newline=UNCHANGED_NEWLINES) as file:
+			file.write(file_text)
+
+		return
+
+	# Some versions of the pandas stubs leave the parameter types of to_json unknown.
+	json_frame = cast(Any, frame)
+	json_frame.to_json(
+		path,
+		orient=RECORDS_ORIENTATION,
+		lines=writes_lines,
+		force_ascii=False,
+		date_format=ISO_DATE_FORMAT,
+	)
+
+
+def join_objects(objects: list[str], writes_lines: bool) -> str:
+	r"""
+	Return the whole text of a JSON file from its objects.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	objects
+		One JSON object per row.
+	writes_lines
+		True for one object per line, False for one list holding them.
+
+	Returns
+	-------
+	str
+		The text of the file, each line ending with a line break in the layout of one object per line.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.files.json_file import join_objects
+	>>> join_objects(['{"a":1}', '{"a":2}'], False)
+	'[{"a":1},{"a":2}]'
+	>>> join_objects(['{"a":1}', '{"a":2}'], True)
+	'{"a":1}\n{"a":2}\n'
+	"""
+	if not writes_lines:
+		joined_objects = OBJECT_SEPARATOR.join(objects)
+		list_text = LIST_FORMAT.format(objects=joined_objects)
+		return list_text
+
+	if objects == []:
+		return EMPTY_LINES_TEXT
+
+	lines_text = LINE_END.join(objects) + LINE_END
+
+	return lines_text

numdaplot/tables/files/json_layout.py

@@ -0,0 +1,63 @@
+"""
+Layouts of the rows of a JSON file.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class JsonLayout(Enum):
+	"""
+	Layout of the rows of a JSON file, used by ``JsonReadOptions`` and ``JsonWriteOptions``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "sales.jsonl"
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])})
+	>>> prices.to_json(path, ndp.JsonWriteOptions(layout=ndp.JsonLayout.LINES))
+	>>> print(path.read_text())
+	{"price":1.5}
+	{"price":8.0}
+	"""
+
+	RECORDS = auto()
+	"""
+	One list holding one object per row: ``[{"city": "Paris"}, {"city": "Lyon"}]``. Default value.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "prices.json"
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])})
+	>>> prices.to_json(path, ndp.JsonWriteOptions(layout=ndp.JsonLayout.RECORDS))
+	>>> print(path.read_text())
+	[{"price":1.5},{"price":8.0}]
+	"""
+
+	LINES = auto()
+	"""
+	One object per line, without enclosing list, also called JSON Lines.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "prices.json"
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])})
+	>>> prices.to_json(path, ndp.JsonWriteOptions(layout=ndp.JsonLayout.LINES))
+	>>> print(path.read_text())
+	{"price":1.5}
+	{"price":8.0}
+	"""

numdaplot/tables/files/json_read_options.py

@@ -0,0 +1,64 @@
+"""
+Settings of the JSON 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.json_layout import JsonLayout
+
+
+@dataclass(frozen=True)
+class JsonReadOptions:
+	r"""
+	Settings of a JSON file read by ``Table.from_json``.
+
+	JSON files are always read in UTF-8.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	layout
+		The layout of the rows, one list of objects by default.
+	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.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "sales.jsonl"
+	>>> _ = path.write_text('{"city": "Paris", "count": 2}\n{"city": "Lyon", "count": 5}\n')
+	>>> ndp.Table.from_json(path, ndp.JsonReadOptions(layout=ndp.JsonLayout.LINES))
+	    city count
+	    TEXT INT64
+	0  Paris     2
+	1   Lyon     5
+	"""
+
+	layout: JsonLayout = JsonLayout.RECORDS
+	column_names: ColumnNames = ColumnNames.CLEANED
+
+	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/tables/files/json_write_options.py

@@ -0,0 +1,71 @@
+"""
+Settings of the JSON 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.decimal_count import require_decimal_count
+from numdaplot.tables.files.json_layout import JsonLayout
+
+
+@dataclass(frozen=True)
+class JsonWriteOptions:
+	"""
+	Settings of a JSON file written by ``Table.to_json``.
+
+	JSON files are always written in UTF-8.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	layout
+		The layout of the rows, one list of objects by default.
+	decimals
+		The number of decimals written for every decimal column, 0 or more. Each value is rounded and keeps its
+		zeros, such as ``1.50``, so the file no longer holds the exact values. When omitted, a decimal is written
+		with every digit of its value.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidCountError
+		When ``decimals`` is negative.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "sales.jsonl"
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])})
+	>>> prices.to_json(path, ndp.JsonWriteOptions(layout=ndp.JsonLayout.LINES, decimals=2))
+	>>> print(path.read_text())
+	{"price":1.50}
+	{"price":8.00}
+	<BLANKLINE>
+	"""
+
+	layout: JsonLayout = JsonLayout.RECORDS
+	decimals: int | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting, and that ``decimals`` is not negative.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidCountError
+			When ``decimals`` is negative.
+		"""
+		require_field_types(self)
+
+		require_decimal_count(self.decimals)

numdaplot/tables/files/missing_texts.py

@@ -0,0 +1,63 @@
+"""
+Texts read as missing values in CSV and Excel files.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+# The texts pandas reads as missing by default, written here so that the reading never depends on the pandas version.
+DEFAULT_MISSING_TEXTS = (
+	"",
+	"#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",
+	"null",
+)
+DEFAULT_MISSING_SETTING = "keep_default_na"
+MISSING_VALUES_SETTING = "na_values"
+
+
+def find_missing_settings(missing_texts: list[str] | None) -> dict[str, Any]:
+	"""
+	Return the settings of ``pandas.read_csv`` or ``pandas.read_excel`` reading exactly the given texts as missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	missing_texts
+		The texts read as missing, the default texts of ``DEFAULT_MISSING_TEXTS`` when None.
+
+	Returns
+	-------
+	dict[str, Any]
+		The pandas settings, which never add the pandas default texts to the given ones.
+
+	Examples
+	--------
+	>>> from numdaplot.tables.files.missing_texts import find_missing_settings
+	>>> find_missing_settings(["N/A"])
+	{'keep_default_na': False, 'na_values': ['N/A']}
+	"""
+	read_texts = list(DEFAULT_MISSING_TEXTS)
+	if missing_texts is not None:
+		read_texts = list(missing_texts)
+
+	missing_settings = {DEFAULT_MISSING_SETTING: False, MISSING_VALUES_SETTING: read_texts}
+
+	return missing_settings

numdaplot/tables/files/optional_package.py

@@ -0,0 +1,42 @@
+"""
+Packages that only some file formats need.
+
+.. versionadded:: 0.1.0
+"""
+
+from importlib.util import find_spec
+
+from numdaplot.errors.missing_dependency_error import MissingDependencyError
+
+
+def require_package(package_name: str, extra_name: str) -> None:
+	"""
+	Check that an optional package is installed.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	package_name
+		The name of the package to import, such as ``openpyxl``.
+	extra_name
+		The numdaplot extra that installs it, such as ``excel``.
+
+	Raises
+	------
+	MissingDependencyError
+		When the package is not installed, with the command that installs it.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.optional_package import require_package
+	>>> try:
+	... 	require_package("package_that_is_not_installed", "excel")
+	... except ndp.MissingDependencyError as error:
+	... 	print(error)
+	This file format needs the package_that_is_not_installed package, install it with: pip install numdaplot[excel]
+	"""
+	package_spec = find_spec(package_name)
+	if package_spec is None:
+		raise MissingDependencyError(package_name, extra_name)

numdaplot/tables/files/pandas_backend.py

@@ -0,0 +1,11 @@
+"""
+How pandas stores the columns it reads from a file.
+
+.. versionadded:: 0.1.0
+"""
+
+NULLABLE_DTYPE_BACKEND = "numpy_nullable"
+"""The pandas setting reading integers, booleans and texts in dtypes that accept missing values.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/files/parquet_file.py

@@ -0,0 +1,91 @@
+"""
+Reading and writing Parquet files.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+from typing import Any, cast
+
+import pandas
+
+from numdaplot.tables.files.optional_package import require_package
+from numdaplot.tables.files.pandas_backend import NULLABLE_DTYPE_BACKEND
+
+PARQUET_PACKAGE = "pyarrow"
+PARQUET_EXTRA = "parquet"
+
+
+def read_parquet_file(path: Path) -> pandas.DataFrame:
+	"""
+	Return the columns of a Parquet file.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing Parquet file.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns as pandas reads them.
+
+	Raises
+	------
+	MissingDependencyError
+		When ``pyarrow`` is not installed.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import pandas
+	>>> from numdaplot.tables.files.parquet_file import read_parquet_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.parquet"
+	>>> pandas.DataFrame({"price": [1.5]}).to_parquet(path, index=False)
+	>>> read_parquet_file(path)
+	   price
+	0    1.5
+	"""
+	require_package(PARQUET_PACKAGE, PARQUET_EXTRA)
+	# Some versions of the pandas stubs leave the parameter types of read_parquet unknown.
+	parquet_pandas = cast(Any, pandas)
+	raw_frame = parquet_pandas.read_parquet(path, dtype_backend=NULLABLE_DTYPE_BACKEND)
+	frame = cast(pandas.DataFrame, raw_frame)
+
+	return frame
+
+
+def write_parquet_file(frame: pandas.DataFrame, path: Path) -> None:
+	"""
+	Write the columns of a Table in a Parquet file, which keeps the type of each column.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	path
+		The path of the file, replaced when it exists.
+
+	Raises
+	------
+	MissingDependencyError
+		When ``pyarrow`` is not installed.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import pandas
+	>>> from numdaplot.tables.files.parquet_file import write_parquet_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.parquet"
+	>>> write_parquet_file(pandas.DataFrame({"price": [1.5]}), path)
+	>>> path.exists()
+	True
+	"""
+	require_package(PARQUET_PACKAGE, PARQUET_EXTRA)
+	frame.to_parquet(path, index=False)

numdaplot/tables/files/parquet_read_options.py

@@ -0,0 +1,56 @@
+r"""
+Settings of the Parquet 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
+
+
+@dataclass(frozen=True)
+class ParquetReadOptions:
+	r"""
+	Settings of a Parquet file (``.parquet``) read by ``Table.from_parquet``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	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.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "sales.parquet"
+	>>> ndp.Table.from_arrays({" price": ndp.Array.from_list([1.5])}).to_parquet(path)
+	>>> options = ndp.ParquetReadOptions(column_names=ndp.ColumnNames.KEPT)
+	>>> ndp.Table.from_parquet(path, options).column_names
+	[' price']
+	"""
+
+	column_names: ColumnNames = ColumnNames.CLEANED
+
+	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)