numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/duplicates/keep.py

@@ -0,0 +1,81 @@
+"""
+Which row of a group of duplicated rows is kept.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class Keep(Enum):
+	"""
+	Which row of a group of duplicated rows is kept, used by ``Deduplication``.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.drop_duplicates(ndp.Deduplication(columns=["city"], keep=ndp.Keep.LAST))
+	    city   price
+	    TEXT FLOAT64
+	0   Lyon    80.0
+	1  Paris   150.0
+	>>> sales.drop_duplicates(ndp.Deduplication(columns=["city"], keep=ndp.Keep.NONE))
+	   city   price
+	   TEXT FLOAT64
+	0  Lyon    80.0
+	"""
+
+	FIRST = auto()
+	"""
+	The first row of each group is kept. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.drop_duplicates(ndp.Deduplication(columns=["city"], keep=ndp.Keep.FIRST))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris   120.0
+	1   Lyon    80.0
+	"""
+
+	LAST = auto()
+	"""
+	The last row of each group is kept.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.drop_duplicates(ndp.Deduplication(columns=["city"], keep=ndp.Keep.LAST))
+	    city   price
+	    TEXT FLOAT64
+	0   Lyon    80.0
+	1  Paris   150.0
+	"""
+
+	NONE = auto()
+	"""
+	No row of a duplicated group is kept, only rows that appear once remain.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> cities = ndp.Array.from_list(["Paris", "Lyon", "Paris"])
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 150.0])
+	>>> sales = ndp.Table.from_arrays({"city": cities, "price": prices})
+	>>> sales.drop_duplicates(ndp.Deduplication(columns=["city"], keep=ndp.Keep.NONE))
+	   city   price
+	   TEXT FLOAT64
+	0  Lyon    80.0
+	"""

numdaplot/tables/files/__init__.py

@@ -0,0 +1,5 @@
+"""
+Reading and writing Tables in files: CSV, JSON, Excel, Parquet, Stata, SAS and XPT.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/files/column_names.py

@@ -0,0 +1,60 @@
+r"""
+Whether a Table cleans the column names it reads.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class ColumnNames(Enum):
+	r"""
+	Whether the column names read from a file or a pandas DataFrame are cleaned.
+
+	Cleaning removes what ``str.strip`` removes at the start and the end of each name: spaces, tabs, line breaks and
+	non-breaking spaces. The inside of a name is never changed.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "vehicles.csv"
+	>>> _ = path.write_text('"id_vehicule\n";speed\n1;50\n')
+	>>> ndp.Table.from_csv(path, ndp.CsvReadOptions(separator=";")).column_names
+	['id_vehicule', 'speed']
+	"""
+
+	CLEANED = auto()
+	r"""
+	The spaces, tabs and line breaks at the start and the end of each name are removed. Default value.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "vehicles.csv"
+	>>> _ = path.write_text('" id_vehicule\n";speed\n1;50\n')
+	>>> options = ndp.CsvReadOptions(separator=";", column_names=ndp.ColumnNames.CLEANED)
+	>>> ndp.Table.from_csv(path, options).column_names
+	['id_vehicule', 'speed']
+	"""
+
+	KEPT = auto()
+	r"""
+	Each name is kept as written.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "vehicles.csv"
+	>>> _ = path.write_text('" id_vehicule\n";speed\n1;50\n')
+	>>> options = ndp.CsvReadOptions(separator=";", column_names=ndp.ColumnNames.KEPT)
+	>>> ndp.Table.from_csv(path, options).column_names
+	[' id_vehicule\n', 'speed']
+	"""

numdaplot/tables/files/csv_file.py

@@ -0,0 +1,265 @@
+"""
+Reading and writing CSV files.
+
+.. versionadded:: 0.1.0
+"""
+
+import csv
+import warnings
+from pathlib import Path
+from typing import Any, cast
+
+import pandas
+from pandas.api.types import infer_dtype
+
+from numdaplot.tables.columns.column_names import require_column_names
+from numdaplot.tables.files.csv_read_options import CsvReadOptions
+from numdaplot.tables.files.csv_write_options import CsvWriteOptions
+from numdaplot.tables.files.missing_texts import find_missing_settings
+from numdaplot.tables.files.pandas_backend import NULLABLE_DTYPE_BACKEND
+from numdaplot.tables.frames.frame_normalization import PYTHON_OBJECT_DTYPE
+from numdaplot.tables.frames.pandas_decimals import find_exact_csv_settings
+
+CSV_NEWLINE = ""
+DECIMAL_FORMAT = "%.{decimals}f"
+IGNORE_ACTION = "ignore"
+# The kinds pandas infers for a column whose blocks were read as numbers or booleans in one place and texts in another.
+MIXED_BLOCK_KINDS = frozenset({"mixed", "mixed-integer"})
+TEXT_COLUMNS_SETTING = "usecols"
+TEXT_DTYPE_SETTING = "dtype"
+
+
+def read_csv_file(path: Path, options: CsvReadOptions) -> pandas.DataFrame:
+	r"""
+	Return the columns of a CSV file whose first row holds the column names, with the exact value of each decimal.
+
+	pandas reads a long file in blocks, each block guessing its own types. A column whose blocks get different types,
+	such as numbers then texts, is read again as texts, so every value keeps the text of the file, such as ``01``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing CSV file.
+	options
+		The separator and the encoding of the file.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns as pandas reads them, empty for an empty file.
+
+	Raises
+	------
+	InvalidColumnNameError
+		When a column name is empty.
+	DuplicateColumnError
+		When a column name appears twice.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.csv_file import read_csv_file
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "sales.csv"
+	>>> _ = path.write_text("city;price\nParis;1.5\n")
+	>>> read_csv_file(path, ndp.CsvReadOptions(separator=";"))
+	    city  price
+	0  Paris    1.5
+	"""
+	header = read_csv_header(path, options)
+	if header is None:
+		empty_frame = pandas.DataFrame()
+		return empty_frame
+
+	require_column_names(header)
+	block_frame = read_pandas_csv(path, options, {})
+	mixed_names = find_mixed_columns(block_frame)
+	if mixed_names == []:
+		return block_frame
+
+	text_settings = {TEXT_COLUMNS_SETTING: mixed_names, TEXT_DTYPE_SETTING: str}
+	text_frame = read_pandas_csv(path, options, text_settings)
+	text_columns = {name: text_frame[name] for name in mixed_names}
+	frame = block_frame.assign(**text_columns)
+
+	return frame
+
+
+def read_pandas_csv(path: Path, options: CsvReadOptions, column_settings: dict[str, Any]) -> pandas.DataFrame:
+	r"""
+	Return the columns of a CSV file as ``pandas.read_csv`` reads them in blocks, with the exact value of each decimal.
+
+	The ``DtypeWarning`` pandas emits when the blocks of a column get different types is not shown, as
+	``read_csv_file`` reads such a column again as texts.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing CSV file whose first row holds the column names.
+	options
+		The separator, the encoding and the texts read as missing.
+	column_settings
+		Other settings of ``pandas.read_csv``, such as the columns to read and their dtype.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns as pandas reads them.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.csv_file import read_pandas_csv
+	>>> path = Path(tempfile.mkdtemp()) / "codes.csv"
+	>>> _ = path.write_text("code;price\n01;1.5\n")
+	>>> read_pandas_csv(path, ndp.CsvReadOptions(separator=";"), {"usecols": ["code"], "dtype": str})
+	  code
+	0   01
+	"""
+	# Some versions of the pandas stubs leave the parameter types of read_csv unknown.
+	csv_pandas = cast(Any, pandas)
+	exact_settings = find_exact_csv_settings()
+	missing_settings = find_missing_settings(options.missing_texts)
+	with warnings.catch_warnings():
+		warnings.simplefilter(IGNORE_ACTION, pandas.errors.DtypeWarning)
+		raw_frame = csv_pandas.read_csv(
+			path,
+			sep=options.separator,
+			encoding=options.encoding.value,
+			dtype_backend=NULLABLE_DTYPE_BACKEND,
+			**exact_settings,
+			**missing_settings,
+			**column_settings,
+		)
+
+	frame = cast(pandas.DataFrame, raw_frame)
+
+	return frame
+
+
+def find_mixed_columns(frame: pandas.DataFrame) -> list[str]:
+	"""
+	Return the names of the columns whose blocks pandas read with different types, such as numbers then texts.
+
+	A block holding only ``01`` is read as the number 1, so the text of such a column is no longer the one of the file.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a CSV file as ``pandas.read_csv`` reads them in blocks.
+
+	Returns
+	-------
+	list[str]
+		The names of the mixed columns, in the order of the file.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.tables.files.csv_file import find_mixed_columns
+	>>> codes = pandas.Series([1, "2A"], dtype=object)
+	>>> prices = pandas.Series([1.5, 2.0])
+	>>> find_mixed_columns(pandas.DataFrame({"code": codes, "price": prices}))
+	['code']
+	"""
+	mixed_names = list[str]()
+	for column_name, column in frame.items():
+		if column.dtype != PYTHON_OBJECT_DTYPE:
+			continue
+
+		inferred_kind = infer_dtype(column, skipna=True)
+		if inferred_kind in MIXED_BLOCK_KINDS:
+			mixed_names.append(str(column_name))
+
+	return mixed_names
+
+
+def read_csv_header(path: Path, options: CsvReadOptions) -> list[str] | None:
+	r"""
+	Return the column names written on the first row of a CSV file, before pandas renames repeated ones.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing CSV file.
+	options
+		The separator and the encoding of the file.
+
+	Returns
+	-------
+	list[str] or None
+		The names of the first row, ``None`` for an empty file.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.csv_file import read_csv_header
+	>>> folder = Path(tempfile.mkdtemp())
+	>>> path = folder / "sales.csv"
+	>>> _ = path.write_text("price,price\n1,2\n")
+	>>> read_csv_header(path, ndp.CsvReadOptions())
+	['price', 'price']
+	"""
+	with path.open(encoding=options.encoding.value, newline=CSV_NEWLINE) as file:
+		rows = csv.reader(file, delimiter=options.separator)
+		header = next(rows, None)
+
+	return header
+
+
+def write_csv_file(frame: pandas.DataFrame, path: Path, options: CsvWriteOptions) -> None:
+	"""
+	Write the columns of a Table in a CSV file, column names on the first row and without row numbers.
+
+	Missing values are written as empty values.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	path
+		The path of the file, replaced when it exists.
+	options
+		The separator and the encoding of the file.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.csv_file import write_csv_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.csv"
+	>>> write_csv_file(pandas.DataFrame({"price": [1.5]}), path, ndp.CsvWriteOptions())
+	>>> print(path.read_text())
+	price
+	1.5
+	<BLANKLINE>
+	"""
+	decimal_format = None
+	if options.decimals is not None:
+		decimal_format = DECIMAL_FORMAT.format(decimals=options.decimals)
+
+	frame.to_csv(
+		path,
+		sep=options.separator,
+		encoding=options.encoding.value,
+		index=False,
+		float_format=decimal_format,
+	)

numdaplot/tables/files/csv_read_options.py

@@ -0,0 +1,89 @@
+"""
+Settings of the CSV 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.csv_separator import DEFAULT_SEPARATOR, require_separator
+from numdaplot.tables.files.encoding import Encoding
+
+
+@dataclass(frozen=True)
+class CsvReadOptions:
+	r"""
+	Settings of a CSV file read by ``Table.from_csv``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	separator
+		The character between two values of a row, ``","`` by default.
+	encoding
+		The text encoding of the file, UTF-8 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.
+	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, so a column of numbers with an empty value is read as texts.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidSeparatorError
+		When the separator is not exactly one character.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "sales.csv"
+	>>> _ = path.write_text("city;price\nParis;1.5\nLyon;8.0\n")
+	>>> ndp.Table.from_csv(path, ndp.CsvReadOptions(separator=";"))
+	    city   price
+	    TEXT FLOAT64
+	0  Paris     1.5
+	1   Lyon     8.0
+	>>> _ = path.write_text("city;code\nParis;N/A\nLyon;\n")
+	>>> ndp.Table.from_csv(path, ndp.CsvReadOptions(separator=";", missing_texts=[""]))
+	    city code
+	    TEXT TEXT
+	0  Paris  N/A
+	1   Lyon <NA>
+	"""
+
+	separator: str = DEFAULT_SEPARATOR
+	encoding: Encoding = Encoding.UTF_8
+	column_names: ColumnNames = ColumnNames.CLEANED
+	missing_texts: list[str] | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting, and that the separator is exactly one character.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidSeparatorError
+			When the separator is not exactly one character.
+		"""
+		require_field_types(self)
+
+		require_separator(self.separator)
+
+		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/csv_separator.py

@@ -0,0 +1,41 @@
+"""
+Check of the separator of a CSV file.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.invalid_separator_error import InvalidSeparatorError
+
+DEFAULT_SEPARATOR = ","
+SEPARATOR_LENGTH = 1
+
+
+def require_separator(separator: str) -> None:
+	"""
+	Check that the separator of a CSV file is exactly one character.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	separator
+		The character between two values of a row.
+
+	Raises
+	------
+	InvalidSeparatorError
+		When the separator is empty or longer than one character.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.csv_separator import require_separator
+	>>> try:
+	... 	require_separator(";;")
+	... except ndp.InvalidSeparatorError as error:
+	... 	print(error)
+	Expected a separator of exactly one character, got ';;'.
+	"""
+	separator_length = len(separator)
+	if separator_length != SEPARATOR_LENGTH:
+		raise InvalidSeparatorError(separator)

numdaplot/tables/files/csv_write_options.py

@@ -0,0 +1,79 @@
+"""
+Settings of the CSV 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.csv_separator import DEFAULT_SEPARATOR, require_separator
+from numdaplot.tables.files.decimal_count import require_decimal_count
+from numdaplot.tables.files.encoding import Encoding
+
+
+@dataclass(frozen=True)
+class CsvWriteOptions:
+	"""
+	Settings of a CSV file written by ``Table.to_csv``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	separator
+		The character between two values of a row, ``","`` by default.
+	encoding
+		The text encoding of the file, UTF-8 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.
+	InvalidSeparatorError
+		When the separator is not exactly one character.
+	InvalidCountError
+		When ``decimals`` is negative.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "sales.csv"
+	>>> prices = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])})
+	>>> prices.to_csv(path, ndp.CsvWriteOptions(separator=";", decimals=2))
+	>>> print(path.read_text())
+	price
+	1.50
+	8.00
+	<BLANKLINE>
+	"""
+
+	separator: str = DEFAULT_SEPARATOR
+	encoding: Encoding = Encoding.UTF_8
+	decimals: int | None = None
+
+	def __post_init__(self) -> None:
+		"""
+		Check every setting: its type, a separator of exactly one character and ``decimals`` not negative.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidSeparatorError
+			When the separator is not exactly one character.
+		InvalidCountError
+			When ``decimals`` is negative.
+		"""
+		require_field_types(self)
+
+		require_separator(self.separator)
+		require_decimal_count(self.decimals)

numdaplot/tables/files/decimal_count.py

@@ -0,0 +1,42 @@
+"""
+Check of the number of decimals written in a file.
+
+.. versionadded:: 0.1.0
+"""
+
+from numdaplot.errors.invalid_count_error import InvalidCountError
+
+MINIMUM_DECIMAL_COUNT = 0
+
+
+def require_decimal_count(decimals: int | None) -> None:
+	"""
+	Check that a number of written decimals, when given, is 0 or more.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	decimals
+		The number of decimals, or None when every digit is written.
+
+	Raises
+	------
+	InvalidCountError
+		When the number is negative.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.files.decimal_count import require_decimal_count
+	>>> try:
+	... 	require_decimal_count(-1)
+	... except ndp.InvalidCountError as error:
+	... 	print(error)
+	Expected a count of at least 0, got -1.
+	"""
+	if decimals is None:
+		return
+
+	if decimals < MINIMUM_DECIMAL_COUNT:
+		raise InvalidCountError(decimals, MINIMUM_DECIMAL_COUNT)