numdaplot 0.1.0__tar.gz

numdaplot-0.1.0/.github/workflows/checks.yml

@@ -0,0 +1,47 @@
+name: Checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+jobs:
+  checks:
+    name: Python ${{ matrix.python }} - ${{ matrix.dependencies }} dependencies
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python: "3.13"
+            dependencies: latest
+            resolution: highest
+          - python: "3.13"
+            dependencies: minimum
+            resolution: lowest-direct
+          - python: "3.14"
+            dependencies: latest
+            resolution: highest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.23"
+          python-version: ${{ matrix.python }}
+      - name: Resolve dependencies
+        run: uv lock --resolution ${{ matrix.resolution }} --upgrade
+      - name: Install
+        run: uv sync --frozen --all-extras
+      - name: Lint
+        run: uv run --frozen ruff check .
+      - name: Format
+        run: uv run --frozen ruff format --check .
+      - name: Type check
+        run: uv run --frozen pyright
+      - name: Tests
+        run: uv run --frozen coverage run run_tests.py
+      - name: Coverage
+        run: uv run --frozen coverage report
+      - name: Documentation
+        run: uv run --frozen mkdocs build --strict

numdaplot-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,141 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  checks:
+    uses: ./.github/workflows/checks.yml
+
+  build:
+    name: Build the package
+    needs: checks
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.23"
+          python-version: "3.13"
+      - name: Check that the tag names the version of the project
+        run: |
+          project_version="$(uv version --short)"
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$project_version" != "$tag_version" ]; then
+            echo "The tag $GITHUB_REF_NAME does not name the version $project_version of pyproject.toml."
+            exit 1
+          fi
+      - name: Read the changes of the version in the changelog
+        if: ${{ !contains(github.ref_name, 'rc') }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v heading="## [$version]" '
+            index($0, heading) == 1 { found = 1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' CHANGELOG.md > release_notes.md
+          if [ ! -s release_notes.md ]; then
+            echo "CHANGELOG.md has no section for $version."
+            exit 1
+          fi
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: ${{ !contains(github.ref_name, 'rc') }}
+        with:
+          name: release-notes
+          path: release_notes.md
+      - name: Build
+        run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: package
+          path: dist/
+
+  testpypi:
+    name: Publish on TestPyPI
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/numdaplot
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: package
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    name: Publish on PyPI
+    needs: testpypi
+    if: ${{ !contains(github.ref_name, 'rc') }}
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/numdaplot
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: package
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  site:
+    name: Publish the site
+    needs: pypi
+    runs-on: ubuntu-24.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version: "0.12.23"
+          python-version: "3.13"
+      - name: Install
+        run: uv sync --frozen --all-extras
+      - name: Build
+        run: uv run --frozen mkdocs build --strict
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+
+  github-release:
+    name: Create the GitHub release
+    needs: pypi
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: package
+          path: dist/
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-notes
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >
+          gh release create "$GITHUB_REF_NAME" dist/*
+          --repo "$GITHUB_REPOSITORY" --title "$GITHUB_REF_NAME" --notes-file release_notes.md

numdaplot-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.egg-info/
+build/
+dist/
+site/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

numdaplot-0.1.0/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+All notable changes to numdaplot are listed in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and numdaplot follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-10
+
+### Added
+
+- `numdaplot.__version__` gives the version of the installed package.
+- `dir(numdaplot)` and the completion of notebooks show only the public names and `__version__`.
+- `Array`: values of one type in one or several dimensions, created with `Array.from_list`, `Array.from_numpy`,
+  `Array.filled`, `Array.from_range`, `Array.from_spacing`, `Array.from_date_parts` and `Array.random`; combined with
+  `+`, `-`, `*`, `/`, `//`, `%`, `**` and, for booleans, `&`, `|`, `~`; read with `Array.select`, `Array.check`,
+  `Array.take`, `Array.replace`, `Array.compute`, `Array.apply`, `Array.reshape`, `Array.transpose`, `Array.flatten`,
+  `Array.sort`, `Array.unique`, `Array.to_list`, `Array.to_value`, `Array.to_numpy` and `Array.is_equal`.
+- `Array.from_date_parts(DateParts(year, month, day))` builds a `DATE` Array from three Arrays of whole numbers, such
+  as the day, month and year columns of a file, a date being missing where a part is missing; `ValueConversionError`
+  names a part that is not whole or a year, month and day that form no date.
+- Array settings: `Shape`, `Spacing`, `ArraySorting`, `Replacement`, `Equality` and the `TypeMatch` enum.
+- Dates: arithmetic between dates, datetimes, durations and numbers on `Array`, time functions applied by
+  `Array.apply` (`TimeFunction`, `DatePart`, `DatePeriod`, `DurationIn`, `ToDuration`, with the `DatePartUnit`,
+  `PeriodUnit` and `DurationUnit` enums), date formats and time zones for `Table.convert` (`DateFormat` enum,
+  `CustomDateFormat`, `TimeZone`, `TimeZoneChange` and the `TimeZoneMode` enum), and `Table.column_time_zones`.
+- Plots: `Plot.line`, `Plot.bar`, `Plot.scatter`, `Plot.histogram`, `Plot.box`, `Plot.pie`, `Plot.heatmap`,
+  `Plot.missing_by_column` and `Plot.missing_map` create a `Plot`, shown with `Plot.show`, saved as a PNG, SVG
+  or PDF image with `Plot.save` and turned into a matplotlib figure with `Plot.to_matplotlib`. `Plot.add_line`,
+  `Plot.add_bar` and `Plot.add_scatter` draw other charts over a Plot, on its axis or on a second axis on the
+  right with the `ValueAxis` enum.
+- Plots of missing values: `Plot.missing_by_column` writes the count and the share of the rows above each bar, and
+  `Plot.missing_map` keeps a mark for every missing value of a long Table, with its total in a legend past the axes.
+- `PlotStyle(renaming=Renaming(...))` shows columns under other names in the legend, the labels of boxes, heatmaps
+  and missing value charts and the default title and axis labels, on every chart of a Plot, without renaming the
+  Table; the columns of an Array are named `"0"`, `"1"`...
+- Plot titles and axis labels are written by default: the title is the `y` label by the `x` label, such as
+  `sales by month`, and `PlotStyle` replaces them or removes them with an empty text.
+- Plots with many text labels, such as bars, heatmaps and boxes, only create the labels that fit, so they stay fast
+  on long Tables.
+- `Plot.heatmap` shows the mean of the cells in each band when they do not fit in the image, with a
+  `ReadabilityWarning`, instead of leaving most of them out.
+- Figures: `Figure` places Plots on the cells of a `Layout` with `Figure.place` and `Cell`, takes its title and its
+  size from a `FigureStyle`, and has `show`, `save` and `to_matplotlib` like a Plot.
+- `Plot.show` and `Figure.show` emit a `DisplayWarning` at the line calling them when no window can be opened, such
+  as without `tkinter` or on a server, suggesting to install `tkinter` or to save the image.
+- Plot settings: `Chart`, `LineChart`, `BarChart`, `ScatterChart`, `HistogramChart`, `BoxChart`, `PieChart`,
+  `HeatmapChart`, `MissingChart`, `BinCount`, `BinWidth`, `PlotStyle`, `Size`, `CustomColor`, `ImageOptions`, and the
+  `Color`, `LineType`, `MarkerShape`, `Orientation`, `BarLayout`, `Outliers`, `Percentages`, `ColorScale`,
+  `CellValues`, `LegendPosition`, `GridLines` and `SizeUnit` enums.
+- Plots: the labels of an axis without enough room are left out, one out of as many as needed from the first one,
+  with a `ReadabilityWarning` when they may be texts.
+- Plot errors and warnings: `ConflictingSettingsError`, `DuplicateLabelError`, `EmptyTotalError`,
+  `InvalidBinWidthError`, `InvalidChartDataError`, `InvalidColorCountError`, `InvalidColorError`,
+  `InvalidOpacityError`, `InvalidPointSizeError`, `InvalidResolutionError`, `InvalidRotationError`,
+  `InvalidSizeError`, `MissingValueError`, `RefusedSettingError`,
+  `UnsupportedImageFormatError`, `IncompatibleChartsError`, `OccupiedCellError`, `CellOutOfRangeError`,
+  `ReadabilityWarning` and `DisplayWarning`.
+- Date errors: `InvalidConversionError`, `InvalidDateFormatError`, `InvalidTimeZoneChangeError`,
+  `TimeZoneMismatchError` and `UnknownTimeZoneError`.
+- `Table`: named columns of one type each, read with `Table.from_csv`, `Table.from_json`, `Table.from_excel`,
+  `Table.from_parquet`, `Table.from_stata`, `Table.from_sas`, `Table.from_xpt`, `Table.from_pandas` and
+  `Table.from_arrays`; written with `Table.to_csv`, `Table.to_json`, `Table.to_excel`, `Table.to_parquet` and
+  `Table.to_stata`; changed with `Table.filter`, `Table.take`, `Table.choose_columns`, `Table.rename`,
+  `Table.convert`, `Table.add_column`, `Table.aggregate`, `Table.describe`, `Table.sort`,
+  `Table.drop_duplicates` and `Table.drop_missing`; read with `Table.column`, `Table.check`,
+  `Table.count_missing`, `Table.to_value`, `Table.to_pandas`, `Table.is_equal`, `Table.row_count`,
+  `Table.column_count`, `Table.column_names`, `Table.column_types`, `Table.preview`, `Table.preview_missing`
+  and `print`.
+- A `Table` written at the end of a notebook cell is shown as the HTML table of `Table.preview`, with every column
+  and the type of each column under its name; a long Table shows its first and last rows, as its text does.
+- `Table.from_csv` gives each column the type of all its values, even when pandas reads a long file in blocks: a
+  column mixing numbers and texts keeps every text as written, such as `01`, without the pandas `DtypeWarning`.
+- `Array`, `Table` and `Plot`, and the base classes `Rule`, `Statistic`, `MathFunction`, `TimeFunction`,
+  `Distribution` and `Chart`, refuse their constructor with `RefusedOperationError`, which names what to use instead.
+  Settings, methods and arithmetic operators check their values against their annotations and raise
+  `InvalidTypeError`, which names what they accept.
+- Settings that work as they are may be omitted: `Array.sort`, `Table.preview`, `Table.describe`,
+  `Table.drop_duplicates`, `Table.drop_missing` and `Table.count_missing` use their default settings, and the Plot
+  creation methods and `Plot.add_*`, except `Plot.pie`, their default chart.
+- `Table.convert` converts booleans to numbers, 1 for `True` and 0 for `False`, and numbers to booleans, only 0 and
+  1 by default or every number but 0 as `True` with `BooleanRule.NONZERO_TRUE`.
+- File settings, separate for reading and writing so that each setting only exists where it applies:
+  `CsvReadOptions`, `CsvWriteOptions`, `JsonReadOptions`, `JsonWriteOptions`, `ExcelReadOptions`,
+  `ExcelWriteOptions`, `SasReadOptions`, `XptReadOptions`, `ParquetReadOptions` and `StataReadOptions`.
+- Every file reading and `Table.from_pandas` remove the spaces, tabs and line breaks at the start and the end of each
+  column name, unless `ColumnNames.KEPT` is given; two names that become the same raise `DuplicateColumnError`.
+- `CsvReadOptions` and `ExcelReadOptions` take `missing_texts`, the texts read as missing values, which replace the 19
+  texts pandas reads as missing by default; an Excel column named like one of them, such as `NA`, keeps its name.
+- Table settings: `Filter`, `Condition`,
+  `Aggregation`, `Calculation`, `PivotTable`, `Description`, `ColumnChoice`, `Renaming`, `NameChange`, `Conversion`, `NewColumn`,
+  `Sorting`, `SortKey`, `Deduplication`, `Preview`, `MissingCount`, `MissingDrop`, `MissingRatio`, and the `BooleanRule`, `Encoding`,
+  `JsonLayout`, `Conflict`, `FilterMode`, `ColumnMatch`, `ColumnMode`, `Keep`, `Side`, `ShownColumns`, `MissingMode`,
+  `RatioComparison` and `Measure` enums. `Equality` compares two Tables as well as two Arrays.
+- Table errors: `ColumnNotFoundError`, `DuplicateColumnError`, `DuplicateStatisticError`, `EmptyListError`,
+  `FileAccessError`, `FileExistsError`, `FileNotFoundError`, `InvalidColumnNameError`, `InvalidSeparatorError`,
+  `InvalidSheetNameError`, `MissingDependencyError` and `UnsupportedIndexError`. `FileNotFoundError` and
+  `FileExistsError` are also the Python errors of the same name, and `FileAccessError` is also an `OSError`.
+- Distributions: `Distribution`, `Uniform`, `Normal`, `RandomIntegers`.
+- Number brackets: `Conversion(dtype=Type.CATEGORY, format=Brackets(limits, bounds, labels, first, last, others))`
+  cuts a number column into categories kept in the order of the brackets, named after the values they hold, such as
+  `0 to 9` or `65 or more`, with the `BracketEnd` enum and the `InvalidLimitsError` and `InvalidLabelCountError`
+  errors; `UnmatchedValueError` also names a value in no bracket.
+- Value mapping: `Array.apply(ValueMapping(changes=[ValueChange(old_value, new_value)], others=Unmatched.ERROR))`
+  replaces listed values by new ones, such as codes by labels, with `DuplicateValueError` for an old value given twice
+  and `UnmatchedValueError` for a value without new value; `Unmatched.MISSING` makes those values missing.
+- Math functions: `MathFunction`, `SquareRoot`, `Exponential`, `Logarithm`, `Absolute`, `Round`, `Sine`, `Cosine`.
+- Array errors: `DimensionError`, `EmptyArrayError`, `IncompatibleTypesError`, `InvalidBaseError`,
+  `InvalidCountError`, `InvalidDeviationError`, `InvalidPositionError`, `InvalidSeedError`,
+  `IntegerOverflowError`, `InvalidShapeError`, `IrregularListError`, `MissingTypeError`, `NotSingleValueError`, `OutOfDomainError`,
+  `RefusedOperationError`, `ShapeMismatchError`, `TimeOverflowError`, `UnsupportedMissingError`,
+  `ValueConversionError`.
+- `Type.TIME`: times of day from 00:00 to 23:59:59.999999, created from `datetime.time` values with
+  `Array.from_list`, read back as `datetime.time` by `to_list`, `to_numpy` and `Table.to_pandas`, compared by the
+  rules and sorted; durations of any unit read from numpy or pandas stay `DURATION`.
+- `Table.convert` reads texts as `TIME`, as `HH:MM`, `HH:MM:SS` or `HH:MM:SS.ffffff` by default or with a
+  `CustomDateFormat` of a time only such as `"%H%M"`, takes the local time of day of a `DATETIME`, and writes `TIME` as
+  texts or categories, `15:35:00` by default.
+- Calculations on `TIME`: two times subtracted give a `DURATION`, a duration added or subtracted moves a time within
+  its day with a `TimeOverflowError` past midnight, a `DATE` plus a `TIME` gives a `DATETIME`, `DatePart` reads the
+  hour, the minute and the second, and `Min`, `Max`, `Count`, `CountDistinct` and `MostFrequent` apply to times.
+- `TIME` columns are written as texts such as `15:35:00` in CSV, JSON, Excel and Stata files, read back as `TEXT`,
+  and as Parquet times read back as `TIME`.
+- `Table.from_excel` reads columns of time cells as `TIME` and columns of duration cells as `DURATION`.
+- Plots place `TIME` columns at their hours on the x axis of line, bar and scatter charts, labeled `HH:MM`, and
+  name heatmap rows, pie slices, `color_by` groups and box `group_by` groups with `HH:MM` labels.
+- Plots measure `TIME` values on an axis labeled `HH:MM`: `y` of line and scatter charts, box charts, histograms
+  and Arrays of times of day. A histogram of times has one bin per hour from 00:00 to 24:00 by default, and
+  `BinWidth` takes a duration of at most a day for times of day.
+- `Table.join` joins two Tables on key columns (`Join`, `JoinMode`, `JoinSuffixes`, `KeyTypes`): inner, left,
+  right and outer joins, missing keys never matching, keys of one family by default, an optional check of how many
+  times each key appears (`Relation`), `InvalidSuffixesError` and `JoinRelationError`.
+- `Type` enum of value types and its conversion to numpy and pandas dtypes, and the `Library` enum read on
+  `UnsupportedTypeError`.
+- Rules: `Equal`, `NotEqual`, `Greater`, `GreaterOrEqual`, `Less`, `LessOrEqual`, `Between`, `IsIn`,
+  `Contains`, `IsMissing`, `IsPresent`, with the `Bounds` and `Case` enums.
+- Statistics: `Sum`, `Mean`, `Median`, `Min`, `Max`, `Count` with the `CountedMissing` enum, `CountDistinct`,
+  `StandardDeviation`, `Quantile`, `MostFrequent`, `MostFrequentCount`.
+- Positions: `Region`, `Index`, `Range` and the `Axis` enum.
+- Sort settings: `Order` and `MissingPosition` enums.
+- Errors: `NumdaplotError`, `EmptyRegionError`, `EmptyTextError`, `EmptyValuesError`, `InvalidBoundsError`,
+  `InvalidFractionError`, `InvalidTypeError`, `InvalidStepError`, `UnsupportedTypeError`, and the
+  `BroadcastWarning` and `CalculationWarning` warnings.
+- `NumdaplotWarning`, the base of every numdaplot warning, filters them all at once with the `warnings` module.

numdaplot-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Ryieru
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

numdaplot-0.1.0/PKG-INFO

@@ -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).