datasemver 0.2.0__tar.gz

datasemver-0.2.0/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+DataSemver versions itself with the vocabulary it applies to datasets: **Major** for
+changes that break what consumers already depend on, **Minor** for new capability that
+leaves existing contracts intact, **Patch** for fixes that keep the same meaning.
+
+This project follows [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-02
+
+### Minor
+- CSV delimiter detection: `,`, `;`, tab and `|` are recognised from the first lines of
+  the file, so a semicolon-separated export no longer loads as a single column. A
+  candidate only wins if it appears in the header and splits every sampled line into the
+  same number of fields, and `.tsv` still forces the tab.
+- `DATASEMVER_CSV_DELIMITER` forces a single delimiter and skips the detection, the tab
+  included and written as `\t`. It overrides the tab of a `.tsv` too, an empty value means
+  unset, and anything longer than one character is an error rather than a silent fallback.
+
+### Patch
+- The dashboard lays out its history controls consistently on narrow screens, and the
+  comparison header shows dataset file names instead of full paths, with the paths kept in
+  the title attribute.
+- `pytest --collect-only` no longer reports 0% coverage and a failing total for a run that
+  never happened.
+- Workflows moved to the action majors that run on Node 24: `checkout@v7`,
+  `setup-python@v7`, `github-script@v9`, `upload-artifact@v7`, `download-artifact@v8` and
+  `codecov-action@v7`.
+- The dashboard tests are collected by the `pytest` console script, not only by
+  `python -m pytest`: the repository root reaches `sys.path` through `pythonpath` instead
+  of relying on the current directory, which is what broke the test workflow on every
+  Python version.
+- Every project link pointed at `datamserver`, the repository's name before it was
+  renamed. The README badges, the clone snippets and the four URLs in the package metadata
+  now name `datasemver`, so the PyPI page no longer leans on a GitHub redirect.
+
+## [0.1.0] - 2026-09-02
+
+### Minor
+- Web dashboard: a FastAPI backend that imports the library and a static frontend with no
+  build step. Upload two datasets or pick two versions from a directory, and read the
+  bump, the classified changes, the column comparison and the changelog in the browser.
+  `POST /api/diff`, `GET /api/history`, `GET /api/history/{dataset}/diff` and
+  `GET /api/meta`.
+- Packaging for PyPI: SPDX license, classifiers, project URLs, a `py.typed` marker so the
+  annotations reach type checkers, a `MANIFEST.in` that keeps the sdist to the library,
+  and `dev` and `web` extras.
+- Release workflow: builds the sdist and the wheel, checks the metadata, refuses a tag
+  that disagrees with the version in `pyproject.toml`, installs the wheel in a clean
+  environment and publishes to PyPI on a GitHub release.
+- Test workflow across Python 3.10 to 3.13, with coverage measured on every run and a
+  floor of 85%. The suite grew from 68 to 151 tests at 99% coverage.
+
+### Patch
+- `Severity` comparisons against strings fell back to the alphabetical order of `str`,
+  which made `bump >= "minor"` false for a major bump. They now compare by impact, and a
+  string that is not a severity raises `TypeError` instead of comparing alphabetically.
+- Documentation for both installation paths, the release flow and the coverage workflow.
+
+## [0.0.1] - 2026-09-02
+
+First working version.
+
+### Minor
+- Compare two versions of a dataset and get the semantic version bump they deserve, with
+  the changelog entry that describes them.
+- Schema changes: columns added, removed and renamed, type changes split into compatible
+  widenings and breaking changes, and nullability shifts.
+- Content changes: row counts, cardinality, mean and standard deviation of numeric
+  columns, mode and category sets of categorical ones.
+- Rename detection from the similarity of both the column name and its values, so
+  `user_name` becoming `username` is reported as a rename rather than a removal plus an
+  addition.
+- Configurable rule engine: severities are lists of rules in YAML, threshold rules such as
+  `row_count_decrease_greater_than` pair with a plain counterpart in a lower severity, and
+  an unknown rule or severity is an error rather than a silent no-op.
+- CSV, JSON (array and lines, nested objects flattened with `.`) and Parquet, whose
+  declared schema is trusted as it stands rather than re-inferred.
+- CLI built on typer and rich: `datasemver diff` with `--rules`, `--current-version`,
+  `--output` and `--json`, plus `datasemver rules` to inspect a rule set.
+- GitHub Action that analyses the datasets a pull request touches and posts the suggested
+  bump as a comment, rewriting the same comment on every push.
+
+[Unreleased]: https://github.com/IzanVil/datasemver/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/IzanVil/datasemver/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/IzanVil/datasemver/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/IzanVil/datasemver/releases/tag/v0.0.1

datasemver-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+izanvilchez6@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

datasemver-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,159 @@
+# Contributing to DataSemver
+
+Thanks for taking the time to help. This document covers how to get the project running
+locally, what a good patch looks like, and how changes get reviewed. Everyone taking part
+is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+```bash
+git clone https://github.com/IzanVil/datasemver.git
+cd datasemver
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+The editable install puts the `datasemver` command on your PATH, so a change in the source
+tree is picked up on the next run. Verify the setup:
+
+```bash
+datasemver diff tests/fixtures/old.csv tests/fixtures/new.csv
+pytest
+```
+
+Python 3.10 or newer is required. Development dependencies are declared in the `dev` extra
+of `pyproject.toml`; `requirements.txt` is kept for the plain `pip install -r` workflow.
+
+## Running the tests
+
+```bash
+pytest                      # whole suite
+pytest tests/test_rules.py  # a single module
+pytest -k rename -v         # a single behaviour
+pytest -q --tb=short        # quieter output while iterating
+```
+
+Coverage runs by default: `pytest` measures `datasemver` and `web`, prints the missing
+lines and writes `coverage.xml`. The run fails below 85%; it currently sits above 99%.
+
+```bash
+pytest --cov-report=html    # browsable report in htmlcov/
+pytest --no-cov             # skip the measurement while iterating
+pytest -m "not web"         # skip the dashboard tests
+```
+
+The dashboard tests import `web`, which is not an installed package; `pythonpath = ["."]`
+in `pyproject.toml` puts the repository root on the path so both `pytest` and
+`python -m pytest` find it.
+
+The suite is fast and hermetic: no network, no fixtures written outside `tmp_path`, and no
+environment read without `monkeypatch.setenv`, which is how the tests for the
+`DATASEMVER_CSV_DELIMITER` override keep the rest of the run untouched. Keep it that way.
+Dataset fixtures live in `tests/fixtures/` and are shared through the fixtures declared in
+`tests/conftest.py`; prefer building small dataframes inline when a test needs a specific
+shape, and only add a file fixture when the format itself is under test. The Parquet
+fixtures hold the same rows as `old.csv` and `new.csv`, which is what lets the suite assert
+that both formats produce identical reports; regenerate them with
+`pandas.DataFrame.to_parquet` if the CSV pair ever changes.
+
+## Code style
+
+- **PEP 8**, 100 character lines, four space indentation.
+- **Type hints on every function signature**, including tests where they clarify intent.
+  Modules use `from __future__ import annotations`.
+- **Docstrings on public functions, classes and modules**, one sentence in the imperative
+  mood. No inline commentary restating what the code says; if a block needs explaining,
+  the explanation belongs in the docstring or in a better name.
+- **Models are pydantic**. Anything that crosses a module boundary or reaches the JSON
+  output is declared in `datasemver/core/models.py`.
+- **No new runtime dependencies** without discussing it in an issue first. The current set
+  is `pandas`, `pyarrow`, `pydantic`, `pyyaml`, `typer` and `rich`.
+- Private helpers are prefixed with `_` and stay at the bottom of the module.
+
+If you use formatters or linters, `ruff format` and `ruff check` with a 100 character line
+length match the existing code. They are not enforced in CI yet.
+
+## Adding a new detection
+
+Most contributions fall into this shape. The path through the code is:
+
+1. Add the case to `ChangeType` in `datasemver/core/models.py`.
+2. Emit the `Change` from `datasemver/core/differ.py`, including the metrics a threshold
+   rule would need. Add a threshold to `DiffConfig` rather than hardcoding a number.
+3. Map it to a severity in `datasemver/rules/default_rules.yaml`, and register the metric
+   in `THRESHOLD_RULES` in `datasemver/rules/engine.py` if it takes a limit.
+4. Document it in `docs/rules.md`.
+5. Cover it in `tests/test_differ.py` and, if it changes the resulting bump, in
+   `tests/test_analyzer.py`.
+
+Detections should be quiet by default: a rule that fires on every dataset is noise, and
+noise is what makes the bump untrustworthy.
+
+## Releasing
+
+Releases are built and published by
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml). The flow is:
+
+1. Bump the version in `pyproject.toml` and `datasemver/__init__.py`; both must match, and
+   move the `Unreleased` section of `CHANGELOG.md` under the new version.
+2. Commit, then tag: `git tag -a v0.1.0 -m "DataSemver 0.1.0"` and push the tag.
+3. Publish a GitHub release pointing at that tag. The workflow builds the sdist and the
+   wheel, checks the metadata with `twine`, refuses to continue when the tag and the
+   version in `pyproject.toml` disagree, installs the wheel in a clean environment to
+   confirm the `datasemver` command works, and uploads to PyPI.
+
+Running it by hand from the Actions tab publishes to TestPyPI by default, and to PyPI when
+the `pypi` target is chosen.
+
+The workflow expects two repository secrets, `PYPI_API_TOKEN` and `TEST_PYPI_API_TOKEN`,
+and two environments named `pypi` and `testpypi` to attach them to. Scope each token to
+the `datasemver` project once it exists on the index.
+
+Building locally, which is worth doing before tagging:
+
+```bash
+pip install build twine
+python -m build
+python -m twine check dist/*
+
+python -m venv /tmp/verify
+/tmp/verify/bin/pip install dist/datasemver-*.whl
+/tmp/verify/bin/datasemver --help
+```
+
+`MANIFEST.in` decides what lands in the sdist: the package, its bundled rules, the docs,
+the example rule profiles and the test suite. The dashboard under `web/`, the sample
+`datasets/` and the CI helper in `scripts/` are deliberately left out, since they are part
+of the repository rather than of the library.
+
+## Reporting issues
+
+Open an issue with the [bug report](.github/ISSUE_TEMPLATE/bug_report.md) or
+[feature request](.github/ISSUE_TEMPLATE/feature_request.md) template. For a bug, the most
+useful report contains:
+
+- The exact command, including the flags.
+- The bump you got and the bump you expected.
+- A minimal pair of datasets that reproduces it, or the `--json` output with anything
+  sensitive removed.
+- Versions: `datasemver --help` works, `python --version`, `pip show pandas pydantic`.
+
+Never attach real production data. A handful of synthetic rows that shows the same shape is
+both safer and easier to debug.
+
+## Pull requests
+
+1. Fork the repository and branch from `main`, e.g. `feat/detect-primary-key-change`.
+2. Keep the change focused. Unrelated refactors belong in their own pull request.
+3. Add tests next to the module you touched, and update the documentation the change
+   affects (`README.md`, `docs/rules.md`).
+4. Run `pytest` before pushing. A red suite will not be reviewed.
+5. Write commit messages in the imperative mood: `add rename detection for numeric
+   columns`, not `added` or `adds`.
+6. Fill in the [pull request template](.github/PULL_REQUEST_TEMPLATE.md), and say
+   explicitly whether the change alters the bump produced for an existing dataset pair.
+
+Review is usually a couple of rounds of comments. Anything that changes the classification
+of existing data is a breaking change for users and will be scrutinised accordingly, so
+motivate it in the description.

datasemver-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Izan Vilchez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datasemver-0.2.0/MANIFEST.in

@@ -0,0 +1,23 @@
+include LICENSE
+include README.md
+include CONTRIBUTING.md
+include CHANGELOG.md
+include CODE_OF_CONDUCT.md
+include requirements.txt
+include requirements-web.txt
+include datasemver/py.typed
+include datasemver/rules/*.yaml
+
+recursive-include docs *.md
+recursive-include examples *.yaml
+recursive-include tests *.py *.csv *.json *.parquet
+
+prune .github
+prune web
+prune datasets
+prune scripts
+exclude demo.cast
+exclude tests/test_web.py
+
+global-exclude *.py[cod]
+global-exclude __pycache__