numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/table_reading.py

@@ -0,0 +1,451 @@
+"""
+Creation of a Table from a file.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+from typing import Self
+
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.files.csv_file import read_csv_file
+from numdaplot.tables.files.csv_read_options import CsvReadOptions
+from numdaplot.tables.files.excel_file import read_excel_file
+from numdaplot.tables.files.excel_read_options import ExcelReadOptions
+from numdaplot.tables.files.file_access import READ_OPERATION, FileAccessErrors
+from numdaplot.tables.files.file_paths import FilePath, require_existing_file
+from numdaplot.tables.files.json_file import read_json_file
+from numdaplot.tables.files.json_read_options import JsonReadOptions
+from numdaplot.tables.files.parquet_file import read_parquet_file
+from numdaplot.tables.files.parquet_read_options import ParquetReadOptions
+from numdaplot.tables.files.sas_file import read_sas_file, read_xpt_file
+from numdaplot.tables.files.sas_read_options import SasReadOptions
+from numdaplot.tables.files.stata_file import read_stata_file
+from numdaplot.tables.files.stata_read_options import StataReadOptions
+from numdaplot.tables.files.xpt_read_options import XptReadOptions
+from numdaplot.tables.table_data import TableData
+
+
+class TableReading(TableData):
+	"""
+	Creation of a Table from a CSV, JSON, Excel, Parquet, Stata, SAS or XPT file.
+
+	Integers become ``INT64``, decimals ``FLOAT64`` and true or false values ``BOOL``. Any other column of a CSV
+	or JSON file becomes ``TEXT``, dates included: convert them afterwards. Empty cells and the usual markers
+	such as ``NA`` or ``null`` are read as missing values; ``missing_texts`` of ``CsvReadOptions`` and
+	``ExcelReadOptions`` chooses other ones.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@classmethod
+	@checked_arguments
+	def from_csv(cls, path: FilePath, options: CsvReadOptions | None = None) -> Self:
+		r"""
+		Return a Table read from a CSV file whose first row holds the column names.
+
+		Each column takes the type of all its values, even in a long file: a column mixing numbers and texts is read
+		as texts written as in the file, such as ``01``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, a ``FilePath`` such as ``"sales.csv"`` or ``Path("data/sales.csv")``.
+		options
+			The separator and the encoding, ``","`` and UTF-8 when omitted.
+
+		Returns
+		-------
+		Self
+			A new Table, empty for an empty file.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileNotFoundError
+			When there is no file at the path.
+		FileAccessError
+			When the file system refuses the file, for a missing permission for example.
+		InvalidColumnNameError, DuplicateColumnError
+			When a column name is empty, even once cleaned, or appears twice, or two names become the same once
+			cleaned.
+
+		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;\n")
+		>>> ndp.Table.from_csv(path, ndp.CsvReadOptions(separator=";"))
+		    city   price
+		    TEXT FLOAT64
+		0  Paris     1.5
+		1   Lyon     NaN
+		"""
+		if options is None:
+			options = CsvReadOptions()
+
+		file_path = Path(path)
+		require_existing_file(file_path)
+		with FileAccessErrors(READ_OPERATION, file_path):
+			frame = read_csv_file(file_path, options)
+
+		table = cls._from_read_frame(frame, options.column_names)
+
+		return table
+
+	@classmethod
+	@checked_arguments
+	def from_json(cls, path: FilePath, options: JsonReadOptions | None = None) -> Self:
+		r"""
+		Return a Table read from a JSON file in UTF-8 holding one object per row.
+
+		Each column takes the type of its JSON values: a text that looks like a number or a date stays a text.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, a ``FilePath`` such as ``"sales.json"`` or ``Path("data/sales.json")``.
+		options
+			The layout of the rows, one list of objects when omitted.
+
+		Returns
+		-------
+		Self
+			A new Table, with one column per name found in the objects.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileNotFoundError
+			When there is no file at the path.
+		FileAccessError
+			When the file system refuses the file, for a missing permission for example.
+		InvalidColumnNameError, DuplicateColumnError
+			When a column name is empty, even once cleaned, or two names become the same once cleaned.
+
+		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": null}\n')
+		>>> ndp.Table.from_json(path, ndp.JsonReadOptions(layout=ndp.JsonLayout.LINES))
+		    city count
+		    TEXT INT64
+		0  Paris     2
+		1   Lyon  <NA>
+		"""
+		file_path = Path(path)
+		require_existing_file(file_path)
+		if options is None:
+			options = JsonReadOptions()
+
+		with FileAccessErrors(READ_OPERATION, file_path):
+			frame = read_json_file(file_path, options)
+
+		table = cls._from_read_frame(frame, options.column_names)
+
+		return table
+
+	@classmethod
+	@checked_arguments
+	def from_excel(cls, path: FilePath, options: ExcelReadOptions | None = None) -> Self:
+		"""
+		Return a Table read from a sheet of an Excel file whose first row holds the column names.
+
+		Needs the ``excel`` extra: ``pip install numdaplot[excel]``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, a ``FilePath`` such as ``"sales.xlsx"`` or ``Path("data/sales.xlsx")``.
+		options
+			The sheet to read, the first one when omitted.
+
+		Returns
+		-------
+		Self
+			A new Table. Dates of the sheet become ``DATETIME`` columns. A column of time cells only, such as
+			``hh:mm``, becomes ``TIME``, and a column of duration cells only, such as ``[h]:mm``, ``DURATION``: a
+			column mixing them with texts stays ``TEXT``.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileNotFoundError
+			When there is no file at the path.
+		FileAccessError
+			When the file system refuses the file, for a missing permission for example.
+		MissingDependencyError
+			When the ``excel`` extra is not installed.
+		InvalidColumnNameError, DuplicateColumnError
+			When a cell of the first row is empty, even once cleaned, is not a text, or repeats another one, or two
+			names become the same once cleaned.
+		TimeOverflowError
+			When a column holds a datetime outside 1677 to 2262, or a duration beyond about 292 years.
+
+		Examples
+		--------
+		>>> import tempfile
+		>>> from pathlib import Path
+		>>> import numdaplot as ndp
+		>>> path = Path(tempfile.mkdtemp()) / "sales.xlsx"
+		>>> ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])}).to_excel(path)
+		>>> ndp.Table.from_excel(path).column_types
+		{'price': <Type.FLOAT64: 10>}
+		"""
+		file_path = Path(path)
+		require_existing_file(file_path)
+		if options is None:
+			options = ExcelReadOptions()
+
+		with FileAccessErrors(READ_OPERATION, file_path):
+			frame = read_excel_file(file_path, options)
+
+		table = cls._from_read_frame(frame, options.column_names)
+
+		return table
+
+	@classmethod
+	@checked_arguments
+	def from_parquet(cls, path: FilePath, options: ParquetReadOptions | None = None) -> Self:
+		"""
+		Return a Table read from a Parquet file.
+
+		Needs the ``parquet`` extra: ``pip install numdaplot[parquet]``.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, a ``FilePath`` such as ``"sales.parquet"`` or ``Path("data/sales.parquet")``.
+		options
+			Whether the column names are cleaned, cleaned when omitted.
+
+		Returns
+		-------
+		Self
+			A new Table, with the types stored in the file.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileNotFoundError
+			When there is no file at the path.
+		FileAccessError
+			When the file system refuses the file, for a missing permission for example.
+		MissingDependencyError
+			When the ``parquet`` extra is not installed.
+		TimeOverflowError
+			When a column holds a datetime outside 1677 to 2262, or a duration beyond about 292 years.
+		DuplicateColumnError
+			When two column names become the same once cleaned.
+
+		Examples
+		--------
+		>>> import tempfile
+		>>> from pathlib import Path
+		>>> import numdaplot as ndp
+		>>> path = Path(tempfile.mkdtemp()) / "sales.parquet"
+		>>> ndp.Table.from_arrays({"count": ndp.Array.from_list([3])}).to_parquet(path)
+		>>> ndp.Table.from_parquet(path).column_types
+		{'count': <Type.INT64: 4>}
+		"""
+		if options is None:
+			options = ParquetReadOptions()
+
+		file_path = Path(path)
+		require_existing_file(file_path)
+		with FileAccessErrors(READ_OPERATION, file_path):
+			frame = read_parquet_file(file_path)
+
+		table = cls._from_read_frame(frame, options.column_names)
+
+		return table
+
+	@classmethod
+	@checked_arguments
+	def from_stata(cls, path: FilePath, options: StataReadOptions | None = None) -> Self:
+		"""
+		Return a Table read from a Stata file (``.dta``).
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, a ``FilePath`` such as ``"sales.dta"`` or ``Path("data/sales.dta")``.
+		options
+			Whether the column names are cleaned, cleaned when omitted.
+
+		Returns
+		-------
+		Self
+			A new Table, with the types stored in the file.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileNotFoundError
+			When there is no file at the path.
+		FileAccessError
+			When the file system refuses the file, for a missing permission for example.
+		TimeOverflowError
+			When a column holds a datetime outside 1677 to 2262, or a duration beyond about 292 years.
+		DuplicateColumnError
+			When two column names become the same once cleaned.
+
+		Examples
+		--------
+		>>> import tempfile
+		>>> from pathlib import Path
+		>>> import numdaplot as ndp
+		>>> path = Path(tempfile.mkdtemp()) / "sales.dta"
+		>>> ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])}).to_stata(path)
+		>>> ndp.Table.from_stata(path).column_types
+		{'price': <Type.FLOAT64: 10>}
+		"""
+		if options is None:
+			options = StataReadOptions()
+
+		file_path = Path(path)
+		require_existing_file(file_path)
+		with FileAccessErrors(READ_OPERATION, file_path):
+			frame = read_stata_file(file_path)
+
+		table = cls._from_read_frame(frame, options.column_names)
+
+		return table
+
+	@classmethod
+	@checked_arguments
+	def from_sas(cls, path: FilePath, options: SasReadOptions | None = None) -> Self:
+		"""
+		Return a Table read from a SAS data file (``.sas7bdat``). numdaplot does not write this format.
+
+		The example reads
+		[airline.sas7bdat](https://github.com/Ryieru/numdaplot/blob/main/tests/data/airline.sas7bdat),
+		a SAS data file of 32 rows.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, a ``FilePath`` such as ``"sales.sas7bdat"`` or ``Path("data/sales.sas7bdat")``.
+		options
+			The encoding of the texts, UTF-8 when omitted.
+
+		Returns
+		-------
+		Self
+			A new Table. SAS stores every number as a decimal, so numbers become ``FLOAT64``.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileNotFoundError
+			When there is no file at the path.
+		FileAccessError
+			When the file system refuses the file, for a missing permission for example.
+		TimeOverflowError
+			When a column holds a datetime outside 1677 to 2262, or a duration beyond about 292 years.
+		DuplicateColumnError
+			When two column names become the same once cleaned.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> airline = ndp.Table.from_sas("airline.sas7bdat")
+		>>> airline.preview(ndp.Preview(count=3))
+		     YEAR       Y       W       R       L       K
+		  FLOAT64 FLOAT64 FLOAT64 FLOAT64 FLOAT64 FLOAT64
+		0  1948.0   1.214   0.243  0.1454   1.415   0.612
+		1  1949.0   1.354   0.260  0.2181   1.384   0.559
+		2  1950.0   1.569   0.278  0.3157   1.388   0.573
+		"""
+		file_path = Path(path)
+		require_existing_file(file_path)
+		if options is None:
+			options = SasReadOptions()
+
+		with FileAccessErrors(READ_OPERATION, file_path):
+			frame = read_sas_file(file_path, options)
+
+		table = cls._from_read_frame(frame, options.column_names)
+
+		return table
+
+	@classmethod
+	@checked_arguments
+	def from_xpt(cls, path: FilePath, options: XptReadOptions | None = None) -> Self:
+		"""
+		Return a Table read from a SAS transport file (``.xpt``). numdaplot does not write this format.
+
+		The example reads
+		[paxraw_d_short.xpt](https://github.com/Ryieru/numdaplot/blob/main/tests/data/paxraw_d_short.xpt),
+		a SAS transport file of 100 rows.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, a ``FilePath`` such as ``"sales.xpt"`` or ``Path("data/sales.xpt")``.
+		options
+			The encoding of the texts, UTF-8 when omitted.
+
+		Returns
+		-------
+		Self
+			A new Table. SAS stores every number as a decimal, so numbers become ``FLOAT64``.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileNotFoundError
+			When there is no file at the path.
+		FileAccessError
+			When the file system refuses the file, for a missing permission for example.
+		TimeOverflowError
+			When a column holds a datetime outside 1677 to 2262, or a duration beyond about 292 years.
+		DuplicateColumnError
+			When two column names become the same once cleaned.
+
+		Examples
+		--------
+		>>> import numdaplot as ndp
+		>>> activity = ndp.Table.from_xpt("paxraw_d_short.xpt")
+		>>> activity.row_count
+		100
+		>>> activity.column_names
+		['SEQN', 'PAXSTAT', 'PAXCAL', 'PAXDAY', 'PAXN', 'PAXHOUR', 'PAXMINUT', 'PAXINTEN', 'PAXSTEP']
+		"""
+		file_path = Path(path)
+		require_existing_file(file_path)
+		if options is None:
+			options = XptReadOptions()
+
+		with FileAccessErrors(READ_OPERATION, file_path):
+			frame = read_xpt_file(file_path, options)
+
+		table = cls._from_read_frame(frame, options.column_names)
+
+		return table