numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/table_writing.py

@@ -0,0 +1,269 @@
+"""
+Writing of a Table in a file.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+
+from numdaplot.settings.argument_types import checked_arguments
+from numdaplot.tables.conflict import Conflict
+from numdaplot.tables.files.csv_file import write_csv_file
+from numdaplot.tables.files.csv_write_options import CsvWriteOptions
+from numdaplot.tables.files.excel_file import write_excel_file
+from numdaplot.tables.files.excel_write_options import ExcelWriteOptions
+from numdaplot.tables.files.file_access import WRITE_OPERATION, FileAccessErrors
+from numdaplot.tables.files.file_paths import FilePath, require_free_path
+from numdaplot.tables.files.json_file import write_json_file
+from numdaplot.tables.files.json_write_options import JsonWriteOptions
+from numdaplot.tables.files.parquet_file import write_parquet_file
+from numdaplot.tables.files.stata_file import write_stata_file
+from numdaplot.tables.frames.time_columns import read_time_objects_frame, write_time_texts_frame
+from numdaplot.tables.table_data import TableData
+
+
+class TableWriting(TableData):
+	"""
+	Writing of a Table in a CSV, JSON, Excel, Parquet or Stata file.
+
+	An existing file is never overwritten unless ``on_conflict`` is ``Conflict.REPLACE``.
+
+	.. versionadded:: 0.1.0
+	"""
+
+	@checked_arguments
+	def to_csv(
+		self, path: FilePath, options: CsvWriteOptions | None = None, on_conflict: Conflict = Conflict.ERROR
+	) -> None:
+		"""
+		Write the Table in a CSV file, column names on the first row, without row numbers.
+
+		Missing values are written as empty values, and times of day as texts such as ``15:35:00``.
+
+		.. 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.
+		on_conflict
+			``ERROR`` by default, refusing to overwrite an existing file, or ``REPLACE`` to overwrite it.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileExistsError
+			When a file exists at the path and ``on_conflict`` is ``ERROR``.
+		FileAccessError
+			When the file system refuses the file: missing folder, missing permission and so on.
+
+		Examples
+		--------
+		>>> import tempfile
+		>>> from pathlib import Path
+		>>> import numdaplot as ndp
+		>>> path = Path(tempfile.mkdtemp()) / "sales.csv"
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5, 8.0])})
+		>>> table.to_csv(path, ndp.CsvWriteOptions(separator=";"))
+		>>> print(path.read_text())
+		price
+		1.5
+		8.0
+		<BLANKLINE>
+		"""
+		file_path = Path(path)
+		require_free_path(file_path, on_conflict)
+		if options is None:
+			options = CsvWriteOptions()
+
+		with FileAccessErrors(WRITE_OPERATION, file_path):
+			write_csv_file(write_time_texts_frame(self._frame), file_path, options)
+
+	@checked_arguments
+	def to_json(
+		self, path: FilePath, options: JsonWriteOptions | None = None, on_conflict: Conflict = Conflict.ERROR
+	) -> None:
+		"""
+		Write the Table in a JSON file in UTF-8, one object per row.
+
+		Missing values are written as ``null``, dates and durations in the ISO 8601 format, times of day as texts such
+		as ``15:35:00``, and decimals with every digit of their value unless ``options`` gives their number.
+
+		.. 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 and the number of decimals, one list of objects with every digit when omitted.
+		on_conflict
+			``ERROR`` by default, refusing to overwrite an existing file, or ``REPLACE`` to overwrite it.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileExistsError
+			When a file exists at the path and ``on_conflict`` is ``ERROR``.
+		FileAccessError
+			When the file system refuses the file: missing folder, missing permission and so on.
+		ValueConversionError
+			At the first infinite value of a decimal column, which JSON cannot write: replace it first.
+
+		Examples
+		--------
+		>>> import tempfile
+		>>> from pathlib import Path
+		>>> import numdaplot as ndp
+		>>> path = Path(tempfile.mkdtemp()) / "sales.json"
+		>>> ndp.Table.from_arrays({"city": ndp.Array.from_list(["Paris"])}).to_json(path)
+		>>> path.read_text()
+		'[{"city":"Paris"}]'
+		"""
+		file_path = Path(path)
+		require_free_path(file_path, on_conflict)
+		if options is None:
+			options = JsonWriteOptions()
+
+		with FileAccessErrors(WRITE_OPERATION, file_path):
+			write_json_file(write_time_texts_frame(self._frame), file_path, options)
+
+	@checked_arguments
+	def to_excel(
+		self, path: FilePath, options: ExcelWriteOptions | None = None, on_conflict: Conflict = Conflict.ERROR
+	) -> None:
+		"""
+		Write the Table in a sheet of an Excel file, column names on the first row.
+
+		Times of day are written as texts such as ``15:35:00``. 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 name of the sheet, ``"Sheet1"`` when omitted.
+		on_conflict
+			``ERROR`` by default, refusing to overwrite an existing file, or ``REPLACE`` to overwrite it.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileExistsError
+			When a file exists at the path and ``on_conflict`` is ``ERROR``.
+		FileAccessError
+			When the file system refuses the file: missing folder, missing permission and so on.
+		MissingDependencyError
+			When the ``excel`` extra is not installed.
+
+		Examples
+		--------
+		>>> import tempfile
+		>>> from pathlib import Path
+		>>> import numdaplot as ndp
+		>>> path = Path(tempfile.mkdtemp()) / "sales.xlsx"
+		>>> table = ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])})
+		>>> table.to_excel(path, ndp.ExcelWriteOptions(sheet="Sales"))
+		>>> ndp.Table.from_excel(path, ndp.ExcelReadOptions(sheet="Sales")).row_count
+		1
+		"""
+		file_path = Path(path)
+		require_free_path(file_path, on_conflict)
+		if options is None:
+			options = ExcelWriteOptions()
+
+		with FileAccessErrors(WRITE_OPERATION, file_path):
+			write_excel_file(write_time_texts_frame(self._frame), file_path, options)
+
+	@checked_arguments
+	def to_parquet(self, path: FilePath, on_conflict: Conflict = Conflict.ERROR) -> None:
+		"""
+		Write the Table in a Parquet file, which keeps the type of each column.
+
+		Times of day are stored as Parquet times, read back as ``TIME``. 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")``.
+		on_conflict
+			``ERROR`` by default, refusing to overwrite an existing file, or ``REPLACE`` to overwrite it.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileExistsError
+			When a file exists at the path and ``on_conflict`` is ``ERROR``.
+		FileAccessError
+			When the file system refuses the file: missing folder, missing permission and so on.
+		MissingDependencyError
+			When the ``parquet`` extra is not installed.
+
+		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)
+		>>> path.exists()
+		True
+		"""
+		file_path = Path(path)
+		require_free_path(file_path, on_conflict)
+		with FileAccessErrors(WRITE_OPERATION, file_path):
+			write_parquet_file(read_time_objects_frame(self._frame), file_path)
+
+	@checked_arguments
+	def to_stata(self, path: FilePath, on_conflict: Conflict = Conflict.ERROR) -> None:
+		"""
+		Write the Table in a Stata file (``.dta``).
+
+		Stata stores integers and booleans holding missing values as decimals, a missing text as an empty text, and
+		times of day as texts such as ``15:35:00``, as it has no type for them. Column names that Stata refuses, such
+		as names with spaces, are changed by pandas with a warning.
+
+		.. versionadded:: 0.1.0
+
+		Parameters
+		----------
+		path
+			The path of the file, a ``FilePath`` such as ``"sales.dta"`` or ``Path("data/sales.dta")``.
+		on_conflict
+			``ERROR`` by default, refusing to overwrite an existing file, or ``REPLACE`` to overwrite it.
+
+		Raises
+		------
+		InvalidTypeError
+			When an argument is not of the type its annotation names.
+		FileExistsError
+			When a file exists at the path and ``on_conflict`` is ``ERROR``.
+		FileAccessError
+			When the file system refuses the file: missing folder, missing permission and so on.
+
+		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)
+		>>> path.exists()
+		True
+		"""
+		file_path = Path(path)
+		require_free_path(file_path, on_conflict)
+		with FileAccessErrors(WRITE_OPERATION, file_path):
+			write_stata_file(write_time_texts_frame(self._frame), file_path)

numdaplot-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: numdaplot
+Version: 0.1.0
+Summary: A simpler, explicit API over numpy, pandas and matplotlib.
+Project-URL: Repository, https://github.com/Ryieru/numdaplot
+Project-URL: Documentation, https://ryieru.github.io/numdaplot/
+Author: Ryieru
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: matplotlib<4,>=3.10.7
+Requires-Dist: numpy<3,>=2.2
+Requires-Dist: pandas<4,>=2.3
+Provides-Extra: excel
+Requires-Dist: openpyxl<4,>=3.1.3; extra == 'excel'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=18.1; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# numdaplot
+
+A simpler, explicit API over numpy, pandas and matplotlib.
+
+Each action has exactly one way to be written, settings are typed objects that check their values
+when they are created, and every operation returns a new object.
+
+```python
+import numdaplot as ndp
+
+prices = ndp.Array.from_list([12.5, 8.0, None, 30.0])
+taxed_prices = prices * 1.2
+high_prices = taxed_prices.select(ndp.Greater(10))
+mean_price = prices.compute(ndp.Mean()).to_value()
+
+sales = ndp.Table.from_csv("sales.csv")
+expensive = ndp.Condition(rule=ndp.Greater(100), columns=["price"])
+expensive_sales = sales.filter(ndp.Filter(conditions=[expensive]))
+average_price = ndp.Calculation(column="price", function=ndp.Mean())
+by_city = expensive_sales.aggregate(ndp.Aggregation(calculations=[average_price], group_by=["city"]))
+
+chart = ndp.BarChart(x="city", y=["price_mean"])
+style = ndp.PlotStyle(title="Average price per city")
+plot = ndp.Plot.bar(by_city, chart, style)
+plot.save("prices.png")
+```
+
+## Status
+
+numdaplot is in alpha: the API can still change between versions, and `ndp.__version__` gives the installed version.
+The shared foundations (types, rules, statistics, positions,
+sort settings, errors), `Array`, `Table`, the tools for missing values and dates (formats, time zones,
+parts, periods and durations), line, bar, scatter, histogram, box, pie, heatmap and missing value plots,
+charts overlaid on a plot, and figures placing plots on a grid are available.
+
+## Requirements
+
+- Python 3.13 or later
+- numpy 2.2+, pandas 2.3+ and matplotlib 3.10.7+
+- Optional extras: `excel` (openpyxl) and `parquet` (pyarrow)
+
+## Installation
+
+```
+pip install numdaplot
+pip install "numdaplot[excel,parquet]"
+```
+
+The `excel` extra reads and writes Excel files, the `parquet` extra reads and writes Parquet files.
+
+## Development
+
+From a clone of the repository, with [uv](https://docs.astral.sh/uv/):
+
+```
+uv sync --all-extras
+```
+
+The extras are needed to run every test, since the Excel and Parquet tests write real files.
+
+## Run the tests
+
+The test entry point runs the unit tests, the functional tests and every docstring example:
+
+```
+uv run python run_tests.py
+```
+
+Arguments are passed to pytest, for example `uv run python run_tests.py -k between`.
+
+## Measure the coverage
+
+The coverage of every line and every branch of `src/numdaplot` and `tools/docs` is measured while the whole suite
+runs, and must reach 99.50%:
+
+```
+uv run coverage run run_tests.py
+uv run coverage report
+```
+
+`uv run coverage html` writes a detailed report in `htmlcov/`.
+
+## Check the code
+
+```
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+```
+
+## Documentation
+
+The documentation is online at https://ryieru.github.io/numdaplot/. It is generated from the docstrings,
+and shown locally with:
+
+```
+uv run mkdocs serve
+```
+
+## Release
+
+A version is published by pushing a tag `v<version>`. The `Release` workflow then runs the checks, builds the
+package, publishes it on TestPyPI, waits for an approval on GitHub, publishes it on PyPI, publishes the
+documentation site and creates the GitHub release with the changes of `CHANGELOG.md`.
+
+1. A minor or major version, such as `0.2.0` or `1.0.0`, is first tried as a release candidate: set
+   `version = "0.2.0rc1"` in `pyproject.toml`, commit, push, then push the tag. A release candidate only goes to
+   TestPyPI. Check its page and its installation, and fix with `0.2.0rc2` and so on until it is right.
+2. Set the final version in `pyproject.toml`, and replace `## [Unreleased]` with `## [0.2.0] - <date>` in
+   `CHANGELOG.md`. Commit, push, then push the tag.
+3. Check the version on TestPyPI, then approve the `pypi` environment in the workflow run on GitHub.
+
+A patch version, such as `0.1.1`, skips step 1. When TestPyPI shows a problem, the approval is refused and the patch
+is tried again as `0.1.1rc1`.
+
+```
+git tag v0.2.0rc1
+git push origin v0.2.0rc1
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ numdaplot==0.2.0rc1
+```
+
+## Code organization
+
+```
+src/numdaplot/
+	__init__.py     every public name, available as ndp.*
+	arrays/         Array and its settings: Shape, Spacing, distributions, math functions...
+	tables/         Table and its settings: file options, Filter, Aggregation, PivotTable, Sorting, Preview...
+	dates/          DateFormat, TimeZone, TimeZoneChange, DatePart, DatePeriod, DurationIn, ToDuration...
+	plots/          Plot and its creation methods, the charts, the PlotStyle and Figure
+	errors/         NumdaplotError, the precise errors, NumdaplotWarning and the precise warnings
+	data_types/     the Type enum and its conversion to numpy and pandas dtypes
+	ratios/         validation of fractions between 0 and 1, and the Measure enum
+	rules/          tests applied to each value: Equal, Greater, Between, IsIn, Contains, IsMissing...
+	statistics/     Sum, Mean, Median, Quantile, StandardDeviation...
+	positions/      Region, Index, Range and Axis
+	ordering/       Order and MissingPosition
+	settings/       check of the settings against their annotations, InvalidTypeError being raised
+tests/
+	unit/           one test file per source file, mirroring src/numdaplot
+	functional/     one test file per notion, using the library as ndp
+docs/               pages and stylesheet of the documentation site
+tools/docs/         griffe extensions and MkDocs hooks building the documentation site and its API pages
+run_tests.py        test entry point
+conftest.py         pytest settings shared by the tests and the docstring examples
+```
+
+## License
+
+BSD-3-Clause, see [LICENSE](https://github.com/Ryieru/numdaplot/blob/main/LICENSE).