dazdiff 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- dazdiff-0.1.0/.gitignore +7 -0
- dazdiff-0.1.0/CHANGELOG.md +82 -0
- dazdiff-0.1.0/LICENSE +21 -0
- dazdiff-0.1.0/PKG-INFO +167 -0
- dazdiff-0.1.0/README.md +137 -0
- dazdiff-0.1.0/examples/benchmark.csv +5 -0
- dazdiff-0.1.0/examples/stored.csv +5 -0
- dazdiff-0.1.0/pyproject.toml +67 -0
- dazdiff-0.1.0/src/dazdiff/__init__.py +34 -0
- dazdiff-0.1.0/src/dazdiff/__main__.py +5 -0
- dazdiff-0.1.0/src/dazdiff/cli.py +248 -0
- dazdiff-0.1.0/src/dazdiff/core.py +1357 -0
- dazdiff-0.1.0/src/dazdiff/py.typed +0 -0
- dazdiff-0.1.0/src/dazdiff/report.py +483 -0
- dazdiff-0.1.0/tests/conftest.py +27 -0
- dazdiff-0.1.0/tests/snapshots/py_groups.txt +27 -0
- dazdiff-0.1.0/tests/snapshots/py_readme_ascii.txt +52 -0
- dazdiff-0.1.0/tests/snapshots/py_readme_unicode.txt +52 -0
- dazdiff-0.1.0/tests/snapshots/py_rows.txt +28 -0
- dazdiff-0.1.0/tests/snapshots/py_tolerance_row_number.txt +29 -0
- dazdiff-0.1.0/tests/snapshots/r_bench_tested.txt +52 -0
- dazdiff-0.1.0/tests/snapshots/r_filtered_only_y.txt +26 -0
- dazdiff-0.1.0/tests/snapshots/r_match.txt +7 -0
- dazdiff-0.1.0/tests/snapshots/r_match_dropped.txt +12 -0
- dazdiff-0.1.0/tests/snapshots/r_match_excluded.txt +12 -0
- dazdiff-0.1.0/tests/snapshots/r_mismatch.txt +48 -0
- dazdiff-0.1.0/tests/snapshots/r_mismatch_unicode.txt +48 -0
- dazdiff-0.1.0/tests/snapshots/r_one_measure_of_several.txt +29 -0
- dazdiff-0.1.0/tests/snapshots/r_paired_truncated.txt +31 -0
- dazdiff-0.1.0/tests/test_assert.py +80 -0
- dazdiff-0.1.0/tests/test_cli.py +185 -0
- dazdiff-0.1.0/tests/test_critical_review.py +280 -0
- dazdiff-0.1.0/tests/test_diff_table.py +392 -0
- dazdiff-0.1.0/tests/test_duplicates_row_keys.py +194 -0
- dazdiff-0.1.0/tests/test_explain.py +146 -0
- dazdiff-0.1.0/tests/test_parity.py +358 -0
- dazdiff-0.1.0/tests/test_readme.py +19 -0
- dazdiff-0.1.0/tests/test_report.py +252 -0
- dazdiff-0.1.0/tests/test_review_fixes.py +119 -0
- dazdiff-0.1.0/tests/test_review_fixes_2.py +82 -0
- dazdiff-0.1.0/tests/test_review_gaps.py +225 -0
dazdiff-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 (2026-11-19)
|
|
4
|
+
|
|
5
|
+
First release.
|
|
6
|
+
|
|
7
|
+
- A documentation site, <https://pedrobtz.github.io/py-dazdiff/>, with a
|
|
8
|
+
Get started guide, the command line and the API reference.
|
|
9
|
+
- `diff_table()` compares two DataFrames value by value, in benchmark or
|
|
10
|
+
equal mode; `diff_summary()` and `is_equal()` condense the result.
|
|
11
|
+
- The `dazdiff` command compares two CSV files and exits 0 when they match,
|
|
12
|
+
1 when they differ and 2 on error.
|
|
13
|
+
- Column names are normalized by collapsing runs of other characters into
|
|
14
|
+
one `_` and trimming `_` from the ends; empty or clashing names are an
|
|
15
|
+
error, and messages name columns as you wrote them.
|
|
16
|
+
- With `by`, other non-measure columns are ignored with a note in benchmark
|
|
17
|
+
mode and are an error in equal mode.
|
|
18
|
+
- Comparing tables that share no key is an error.
|
|
19
|
+
- Equal infinities are `same`; tolerances apply to finite pairs only;
|
|
20
|
+
`rel_diff` no longer overflows.
|
|
21
|
+
- Side effects (dropped columns, truncation, no measures) are `DiffNote`
|
|
22
|
+
warnings; `DiffWarning` is kept for answers that may be wrong.
|
|
23
|
+
- `y` can be cast to bool, string and date-time columns of the benchmark.
|
|
24
|
+
- Arguments after `x` and `y` are keyword-only; the result's `attrs` hold
|
|
25
|
+
`shape` and `mode`.
|
|
26
|
+
- Requires pandas 2.2.2 or later.
|
|
27
|
+
- `duplicates="pair"` is now `duplicates="disambiguate"`, as in daffiz.
|
|
28
|
+
- `duplicates="aggregate"` compares the multiset of values per key and
|
|
29
|
+
measure (`attrs["shape"] == "groups"`).
|
|
30
|
+
- `row_key="position"` and `"sorted"` add a `row_number` key, so tables
|
|
31
|
+
whose columns are all measures can be compared; the CLI has `--row-key`.
|
|
32
|
+
- `exclude=` (`--exclude`) leaves columns out of both tables; a name in
|
|
33
|
+
neither table is a warning, one that `by` or `measures` names an error.
|
|
34
|
+
- `cast=False` (`--no-cast`) compares without casting; the compared columns'
|
|
35
|
+
types must agree.
|
|
36
|
+
- Only the compared columns of `y` are cast, so an ignored column can no
|
|
37
|
+
longer refuse the comparison or be truncated.
|
|
38
|
+
- A number cast to the benchmark's text is written with the decimals the
|
|
39
|
+
benchmark uses, so `2` meets `"2.0"`; a value that matches only as a
|
|
40
|
+
number warns.
|
|
41
|
+
- A date-time cast to text is written `%Y-%m-%d %H:%M:%S`, with its fraction
|
|
42
|
+
of a second when it has one; a column with no values casts to any type.
|
|
43
|
+
- When no key aligns, the error names the key columns that share no value,
|
|
44
|
+
with examples, and suggests `exclude` for those holding one value each.
|
|
45
|
+
- `attrs` also hold `tolerance`, `name_map`, `dropped`, `excluded` and
|
|
46
|
+
`ignored`.
|
|
47
|
+
- `is_equal()` is now `is_matching()`, which can judge a result again at
|
|
48
|
+
other `tolerance` and `rel_tol` thresholds.
|
|
49
|
+
- `diff_explain()` (`--explain [COLUMN]`, `--joined`) says which key values
|
|
50
|
+
split the result into same and not same: per key column and per measure,
|
|
51
|
+
or per value of one column.
|
|
52
|
+
- `diff_report()` (`--report`) draws a bounded text report: the columns
|
|
53
|
+
compared, a picture of how the rows align, and per changed measure its
|
|
54
|
+
match rate and largest differences, in Unicode or ASCII (`--ascii`, and
|
|
55
|
+
automatically when the terminal cannot show Unicode).
|
|
56
|
+
- `attrs["paired"]` says whether repeated keys were paired.
|
|
57
|
+
- `assert_table_equal(actual, expected)` asserts that a table matches a
|
|
58
|
+
reference within a relative `1.5e-8`, failing with `diff_summary()` and
|
|
59
|
+
the first records that differ.
|
|
60
|
+
- A cast to an integer column is exact above 2**53 and refuses values
|
|
61
|
+
outside the column's range, instead of wrapping them around.
|
|
62
|
+
- Integer measures are compared exactly, so values above 2**53 that differ
|
|
63
|
+
are `changed`.
|
|
64
|
+
- A number cast to a date-time column is refused instead of being read as
|
|
65
|
+
nanoseconds since 1970.
|
|
66
|
+
- The CLI no longer turns an integer key column into a measure when the
|
|
67
|
+
other file reads it as float only because of an empty value.
|
|
68
|
+
- Every CLI error exits with status 2 and a one-line message, including
|
|
69
|
+
errors writing `--output` and undecodable files.
|
|
70
|
+
- The report's "(...and N more)" counts keys not shown, not rows.
|
|
71
|
+
- Extra columns of `y` whose names normalize to nothing or clash are listed
|
|
72
|
+
as dropped, in `attrs["dropped"]` and the note.
|
|
73
|
+
- `duplicates="aggregate"` compares integer measures exactly above 2**53.
|
|
74
|
+
- `diff_explain()` and `diff_report()` refuse results joined with
|
|
75
|
+
`pd.concat`, whose row ids repeat, instead of miscounting them.
|
|
76
|
+
- An `object` column of `y` holding numbers is cast to the benchmark's text.
|
|
77
|
+
- `by` and `measures` naming the same column is an error.
|
|
78
|
+
- Every public function raises `DiffError` for invalid arguments, and
|
|
79
|
+
`tolerance`/`rel_tol` must be finite numbers (not bools).
|
|
80
|
+
- `assert_table_equal()` passes `diff_table()`'s warnings on when it fails.
|
|
81
|
+
- The CLI reads an integer column with empty cells as integers, and a
|
|
82
|
+
column written with leading zeros (`007`) as text.
|
dazdiff-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 pedrobtz
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
dazdiff-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: dazdiff
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Compare two tables value by value, from Python or the command line.
|
|
5
|
+
Project-URL: Homepage, https://github.com/pedrobtz/py-dazdiff
|
|
6
|
+
Project-URL: Documentation, https://pedrobtz.github.io/py-dazdiff/
|
|
7
|
+
Project-URL: Issues, https://github.com/pedrobtz/py-dazdiff/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/pedrobtz/py-dazdiff/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: pedrobtz <pedrobtz@gmail.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: compare,csv,dataframe,diff,pandas,testing
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering
|
|
25
|
+
Classifier: Topic :: Software Development :: Testing
|
|
26
|
+
Classifier: Typing :: Typed
|
|
27
|
+
Requires-Python: >=3.10
|
|
28
|
+
Requires-Dist: pandas>=2.2.2
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# dazdiff
|
|
32
|
+
|
|
33
|
+
[](https://github.com/pedrobtz/py-dazdiff/actions/workflows/ci.yml)
|
|
34
|
+
[](https://pypi.org/project/dazdiff/)
|
|
35
|
+
[](https://pypi.org/project/dazdiff/)
|
|
36
|
+
|
|
37
|
+
`dazdiff` compares two tables value by value, from Python or from the command
|
|
38
|
+
line. It is a small Python take on the R package
|
|
39
|
+
[pedrobtz/dazdiff](https://github.com/pedrobtz/dazdiff). Documentation:
|
|
40
|
+
<https://pedrobtz.github.io/py-dazdiff/>.
|
|
41
|
+
|
|
42
|
+
Its main function, `diff_table()`, answers one of two questions:
|
|
43
|
+
|
|
44
|
+
- **Does this table match the benchmark?** (`mode="benchmark"`, the default.)
|
|
45
|
+
The benchmark's column types are the truth: the tested table is cast to them
|
|
46
|
+
and its extra columns are dropped.
|
|
47
|
+
- **Are these two tables equal?** (`mode="equal"`.) Both tables must have the
|
|
48
|
+
same columns with the same types; nothing is cast.
|
|
49
|
+
|
|
50
|
+
The result has one row per key and measure, with `row_id_x`, `row_id_y`,
|
|
51
|
+
`value_x`, `value_y`, `diff`, `abs_diff`, `rel_diff` and a `status` of `same`,
|
|
52
|
+
`changed`, `only_x` or `only_y`.
|
|
53
|
+
|
|
54
|
+
## Installation
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
pip install dazdiff # the library and the CLI
|
|
58
|
+
uv tool install dazdiff # the CLI on its own
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
It needs Python 3.10 or later and pandas 2.2.2 or later. The development
|
|
62
|
+
version installs from GitHub:
|
|
63
|
+
`pip install git+https://github.com/pedrobtz/py-dazdiff`.
|
|
64
|
+
|
|
65
|
+
## Command line
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
$ dazdiff examples/benchmark.csv examples/stored.csv --by id,region --only-diffs
|
|
69
|
+
dazdiff: Dropped column(s) of `y` that the benchmark `x` does not have: loaded_at.
|
|
70
|
+
ID REGION metric row_id_x row_id_y value_x value_y diff abs_diff rel_diff status
|
|
71
|
+
1 north UNITS 1 1 10.0 10.4 0.4 0.4 0.038462 changed
|
|
72
|
+
2 south AMOUNT 2 2 200.0 200.5 0.5 0.5 0.002494 changed
|
|
73
|
+
4 west AMOUNT 4 <NA> 400.0 NaN NaN NaN NaN only_x
|
|
74
|
+
...
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
| Option | Meaning |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| `-b, --by COLS` | comma-separated key columns (default: every non-measure column) |
|
|
80
|
+
| `--exclude COLS` | comma-separated columns to leave out of both files |
|
|
81
|
+
| `-m, --measures` | `numeric` (default), `numeric+integer`, or comma-separated names |
|
|
82
|
+
| `--mode` | `benchmark` (default) or `equal` |
|
|
83
|
+
| `-t, --tolerance` | absolute tolerance |
|
|
84
|
+
| `-r, --rel-tol` | relative tolerance (relative to the larger magnitude) |
|
|
85
|
+
| `--no-cast` | do not cast the second file to the first's types; they must agree |
|
|
86
|
+
| `--no-truncate` | refuse casts that would truncate values to integers |
|
|
87
|
+
| `--duplicates` | `disambiguate` repeated keys in arrival order (default), `aggregate` them as multisets, or `error` |
|
|
88
|
+
| `--row-key` | `position` or `sorted`: add a `row_number` key when every column is a measure |
|
|
89
|
+
| `--sep` | CSV separator |
|
|
90
|
+
| `-o, --output FILE` | write the full comparison to a CSV file |
|
|
91
|
+
| `-s, --summary` | print the per-measure summary instead |
|
|
92
|
+
| `-R, --report` | print a text report; `--x-name`, `--y-name` label the files, `--ascii` avoids box-drawing characters |
|
|
93
|
+
| `-e, --explain [COLUMN]` | print which key values split same from not same; with a column, per value of it |
|
|
94
|
+
| `--joined` | with `--explain`, count only rows found in both files |
|
|
95
|
+
| `-d, --only-diffs` | print only rows that are not `same` |
|
|
96
|
+
| `-q, --quiet` | print nothing |
|
|
97
|
+
|
|
98
|
+
The exit status is `0` when the tables match, `1` when they differ and `2` on
|
|
99
|
+
error, so `dazdiff` works in scripts and CI. Column names are normalized (upper
|
|
100
|
+
case, other characters turned into `_`), so `id` and `ID` pair up. Because CSV
|
|
101
|
+
files carry no types, a column read as integer in one file and as decimals in
|
|
102
|
+
the other is compared as float; one that is float only because of an empty
|
|
103
|
+
value stays an integer.
|
|
104
|
+
|
|
105
|
+
`python -m dazdiff` works too.
|
|
106
|
+
|
|
107
|
+
## Python
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
import pandas as pd
|
|
111
|
+
from dazdiff import diff_report, diff_summary, diff_table, is_matching
|
|
112
|
+
|
|
113
|
+
benchmark = pd.read_csv("examples/benchmark.csv")
|
|
114
|
+
stored = pd.read_csv("examples/stored.csv")
|
|
115
|
+
|
|
116
|
+
d = diff_table(benchmark, stored, by=["id", "region"], measures="numeric+integer")
|
|
117
|
+
d[d["status"] != "same"]
|
|
118
|
+
diff_summary(d)
|
|
119
|
+
assert not is_matching(d) # rows 4 and 5 are each in one table only
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`is_matching(d, tolerance=1)` judges the values again at another threshold,
|
|
123
|
+
without running the comparison again.
|
|
124
|
+
|
|
125
|
+
`diff_explain(d)` says which key columns separate the rows that match from
|
|
126
|
+
those that do not, and `diff_explain(d, "region")` counts each status per
|
|
127
|
+
region, most differences first.
|
|
128
|
+
|
|
129
|
+
`exclude=` leaves technical columns (load stamps, run ids) out of both tables.
|
|
130
|
+
When a number of the tested table is cast to the benchmark's text, it is
|
|
131
|
+
written with the decimals the benchmark uses, so `2` meets `"2.0"`.
|
|
132
|
+
|
|
133
|
+
With no measure columns, rows are compared as wholes, and a repeated row counts
|
|
134
|
+
once per copy. Values truncated when casting to the benchmark's integer
|
|
135
|
+
columns are recorded in `d.attrs["truncated"]`.
|
|
136
|
+
|
|
137
|
+
### Report
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
print(diff_report(d, "benchmark", "stored"))
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
draws the columns compared, how the rows of the two tables align, and per
|
|
144
|
+
changed measure its match rate and largest differences.
|
|
145
|
+
`diff_report(d).format(unicode=False)` draws it in ASCII.
|
|
146
|
+
|
|
147
|
+
### In tests
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
from dazdiff import assert_table_equal
|
|
151
|
+
|
|
152
|
+
expected = pd.DataFrame({"id": [1, 2], "amount": [100.0, 200.0]})
|
|
153
|
+
actual = pd.DataFrame({"id": [1, 2], "amount": [100.0, 200.0 + 1e-12]})
|
|
154
|
+
assert_table_equal(actual, expected) # within a relative 1.5e-8
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`assert_table_equal()` tests `actual` against `expected` as the benchmark and
|
|
158
|
+
raises `AssertionError` with `diff_summary()` and the first records that
|
|
159
|
+
differ, so it works under pytest, unittest or a plain script. A repeated key
|
|
160
|
+
is an error unless `duplicates=` says how to treat it.
|
|
161
|
+
|
|
162
|
+
## Development
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
uv sync
|
|
166
|
+
uv run pytest
|
|
167
|
+
```
|
dazdiff-0.1.0/README.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# dazdiff
|
|
2
|
+
|
|
3
|
+
[](https://github.com/pedrobtz/py-dazdiff/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/dazdiff/)
|
|
5
|
+
[](https://pypi.org/project/dazdiff/)
|
|
6
|
+
|
|
7
|
+
`dazdiff` compares two tables value by value, from Python or from the command
|
|
8
|
+
line. It is a small Python take on the R package
|
|
9
|
+
[pedrobtz/dazdiff](https://github.com/pedrobtz/dazdiff). Documentation:
|
|
10
|
+
<https://pedrobtz.github.io/py-dazdiff/>.
|
|
11
|
+
|
|
12
|
+
Its main function, `diff_table()`, answers one of two questions:
|
|
13
|
+
|
|
14
|
+
- **Does this table match the benchmark?** (`mode="benchmark"`, the default.)
|
|
15
|
+
The benchmark's column types are the truth: the tested table is cast to them
|
|
16
|
+
and its extra columns are dropped.
|
|
17
|
+
- **Are these two tables equal?** (`mode="equal"`.) Both tables must have the
|
|
18
|
+
same columns with the same types; nothing is cast.
|
|
19
|
+
|
|
20
|
+
The result has one row per key and measure, with `row_id_x`, `row_id_y`,
|
|
21
|
+
`value_x`, `value_y`, `diff`, `abs_diff`, `rel_diff` and a `status` of `same`,
|
|
22
|
+
`changed`, `only_x` or `only_y`.
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
pip install dazdiff # the library and the CLI
|
|
28
|
+
uv tool install dazdiff # the CLI on its own
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
It needs Python 3.10 or later and pandas 2.2.2 or later. The development
|
|
32
|
+
version installs from GitHub:
|
|
33
|
+
`pip install git+https://github.com/pedrobtz/py-dazdiff`.
|
|
34
|
+
|
|
35
|
+
## Command line
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
$ dazdiff examples/benchmark.csv examples/stored.csv --by id,region --only-diffs
|
|
39
|
+
dazdiff: Dropped column(s) of `y` that the benchmark `x` does not have: loaded_at.
|
|
40
|
+
ID REGION metric row_id_x row_id_y value_x value_y diff abs_diff rel_diff status
|
|
41
|
+
1 north UNITS 1 1 10.0 10.4 0.4 0.4 0.038462 changed
|
|
42
|
+
2 south AMOUNT 2 2 200.0 200.5 0.5 0.5 0.002494 changed
|
|
43
|
+
4 west AMOUNT 4 <NA> 400.0 NaN NaN NaN NaN only_x
|
|
44
|
+
...
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
| Option | Meaning |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| `-b, --by COLS` | comma-separated key columns (default: every non-measure column) |
|
|
50
|
+
| `--exclude COLS` | comma-separated columns to leave out of both files |
|
|
51
|
+
| `-m, --measures` | `numeric` (default), `numeric+integer`, or comma-separated names |
|
|
52
|
+
| `--mode` | `benchmark` (default) or `equal` |
|
|
53
|
+
| `-t, --tolerance` | absolute tolerance |
|
|
54
|
+
| `-r, --rel-tol` | relative tolerance (relative to the larger magnitude) |
|
|
55
|
+
| `--no-cast` | do not cast the second file to the first's types; they must agree |
|
|
56
|
+
| `--no-truncate` | refuse casts that would truncate values to integers |
|
|
57
|
+
| `--duplicates` | `disambiguate` repeated keys in arrival order (default), `aggregate` them as multisets, or `error` |
|
|
58
|
+
| `--row-key` | `position` or `sorted`: add a `row_number` key when every column is a measure |
|
|
59
|
+
| `--sep` | CSV separator |
|
|
60
|
+
| `-o, --output FILE` | write the full comparison to a CSV file |
|
|
61
|
+
| `-s, --summary` | print the per-measure summary instead |
|
|
62
|
+
| `-R, --report` | print a text report; `--x-name`, `--y-name` label the files, `--ascii` avoids box-drawing characters |
|
|
63
|
+
| `-e, --explain [COLUMN]` | print which key values split same from not same; with a column, per value of it |
|
|
64
|
+
| `--joined` | with `--explain`, count only rows found in both files |
|
|
65
|
+
| `-d, --only-diffs` | print only rows that are not `same` |
|
|
66
|
+
| `-q, --quiet` | print nothing |
|
|
67
|
+
|
|
68
|
+
The exit status is `0` when the tables match, `1` when they differ and `2` on
|
|
69
|
+
error, so `dazdiff` works in scripts and CI. Column names are normalized (upper
|
|
70
|
+
case, other characters turned into `_`), so `id` and `ID` pair up. Because CSV
|
|
71
|
+
files carry no types, a column read as integer in one file and as decimals in
|
|
72
|
+
the other is compared as float; one that is float only because of an empty
|
|
73
|
+
value stays an integer.
|
|
74
|
+
|
|
75
|
+
`python -m dazdiff` works too.
|
|
76
|
+
|
|
77
|
+
## Python
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
import pandas as pd
|
|
81
|
+
from dazdiff import diff_report, diff_summary, diff_table, is_matching
|
|
82
|
+
|
|
83
|
+
benchmark = pd.read_csv("examples/benchmark.csv")
|
|
84
|
+
stored = pd.read_csv("examples/stored.csv")
|
|
85
|
+
|
|
86
|
+
d = diff_table(benchmark, stored, by=["id", "region"], measures="numeric+integer")
|
|
87
|
+
d[d["status"] != "same"]
|
|
88
|
+
diff_summary(d)
|
|
89
|
+
assert not is_matching(d) # rows 4 and 5 are each in one table only
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`is_matching(d, tolerance=1)` judges the values again at another threshold,
|
|
93
|
+
without running the comparison again.
|
|
94
|
+
|
|
95
|
+
`diff_explain(d)` says which key columns separate the rows that match from
|
|
96
|
+
those that do not, and `diff_explain(d, "region")` counts each status per
|
|
97
|
+
region, most differences first.
|
|
98
|
+
|
|
99
|
+
`exclude=` leaves technical columns (load stamps, run ids) out of both tables.
|
|
100
|
+
When a number of the tested table is cast to the benchmark's text, it is
|
|
101
|
+
written with the decimals the benchmark uses, so `2` meets `"2.0"`.
|
|
102
|
+
|
|
103
|
+
With no measure columns, rows are compared as wholes, and a repeated row counts
|
|
104
|
+
once per copy. Values truncated when casting to the benchmark's integer
|
|
105
|
+
columns are recorded in `d.attrs["truncated"]`.
|
|
106
|
+
|
|
107
|
+
### Report
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
print(diff_report(d, "benchmark", "stored"))
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
draws the columns compared, how the rows of the two tables align, and per
|
|
114
|
+
changed measure its match rate and largest differences.
|
|
115
|
+
`diff_report(d).format(unicode=False)` draws it in ASCII.
|
|
116
|
+
|
|
117
|
+
### In tests
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
from dazdiff import assert_table_equal
|
|
121
|
+
|
|
122
|
+
expected = pd.DataFrame({"id": [1, 2], "amount": [100.0, 200.0]})
|
|
123
|
+
actual = pd.DataFrame({"id": [1, 2], "amount": [100.0, 200.0 + 1e-12]})
|
|
124
|
+
assert_table_equal(actual, expected) # within a relative 1.5e-8
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`assert_table_equal()` tests `actual` against `expected` as the benchmark and
|
|
128
|
+
raises `AssertionError` with `diff_summary()` and the first records that
|
|
129
|
+
differ, so it works under pytest, unittest or a plain script. A repeated key
|
|
130
|
+
is an error unless `duplicates=` says how to treat it.
|
|
131
|
+
|
|
132
|
+
## Development
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
uv sync
|
|
136
|
+
uv run pytest
|
|
137
|
+
```
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "dazdiff"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Compare two tables value by value, from Python or the command line."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
authors = [
|
|
7
|
+
{ name = "pedrobtz", email = "pedrobtz@gmail.com" }
|
|
8
|
+
]
|
|
9
|
+
license = "MIT"
|
|
10
|
+
license-files = ["LICENSE"]
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
dependencies = [
|
|
13
|
+
"pandas>=2.2.2",
|
|
14
|
+
]
|
|
15
|
+
keywords = ["diff", "compare", "dataframe", "csv", "pandas", "testing"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Intended Audience :: Science/Research",
|
|
20
|
+
"Operating System :: OS Independent",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
23
|
+
"Programming Language :: Python :: 3.10",
|
|
24
|
+
"Programming Language :: Python :: 3.11",
|
|
25
|
+
"Programming Language :: Python :: 3.12",
|
|
26
|
+
"Programming Language :: Python :: 3.13",
|
|
27
|
+
"Programming Language :: Python :: 3.14",
|
|
28
|
+
"Topic :: Scientific/Engineering",
|
|
29
|
+
"Topic :: Software Development :: Testing",
|
|
30
|
+
"Typing :: Typed",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://github.com/pedrobtz/py-dazdiff"
|
|
35
|
+
Documentation = "https://pedrobtz.github.io/py-dazdiff/"
|
|
36
|
+
Issues = "https://github.com/pedrobtz/py-dazdiff/issues"
|
|
37
|
+
Changelog = "https://github.com/pedrobtz/py-dazdiff/blob/main/CHANGELOG.md"
|
|
38
|
+
|
|
39
|
+
[project.scripts]
|
|
40
|
+
dazdiff = "dazdiff.cli:main"
|
|
41
|
+
|
|
42
|
+
[build-system]
|
|
43
|
+
requires = ["hatchling>=1.27"]
|
|
44
|
+
build-backend = "hatchling.build"
|
|
45
|
+
|
|
46
|
+
[tool.hatch.build.targets.sdist]
|
|
47
|
+
exclude = [".agents", ".github", "CLAUDE.md", "uv.lock", ".python-version", "great-docs.yml", "user_guide"]
|
|
48
|
+
|
|
49
|
+
[dependency-groups]
|
|
50
|
+
dev = [
|
|
51
|
+
"pytest>=8.0",
|
|
52
|
+
"pytest-cov>=5.0",
|
|
53
|
+
"ruff>=0.6",
|
|
54
|
+
]
|
|
55
|
+
|
|
56
|
+
[tool.ruff]
|
|
57
|
+
line-length = 100
|
|
58
|
+
target-version = "py310"
|
|
59
|
+
|
|
60
|
+
[tool.ruff.lint]
|
|
61
|
+
select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
|
|
62
|
+
ignore = ["E501"] # line length is the formatter's job
|
|
63
|
+
|
|
64
|
+
[tool.pytest.ini_options]
|
|
65
|
+
testpaths = ["tests"]
|
|
66
|
+
addopts = ["-ra"]
|
|
67
|
+
filterwarnings = ["error"]
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"""dazdiff: compare two tables value by value."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
4
|
+
|
|
5
|
+
from .core import (
|
|
6
|
+
DiffError,
|
|
7
|
+
DiffNote,
|
|
8
|
+
DiffWarning,
|
|
9
|
+
assert_table_equal,
|
|
10
|
+
diff_explain,
|
|
11
|
+
diff_summary,
|
|
12
|
+
diff_table,
|
|
13
|
+
is_matching,
|
|
14
|
+
normalize_names,
|
|
15
|
+
)
|
|
16
|
+
from .report import DiffReport, diff_report
|
|
17
|
+
|
|
18
|
+
try: # one source: the version in pyproject.toml, read from the installed metadata
|
|
19
|
+
__version__ = version("dazdiff")
|
|
20
|
+
except PackageNotFoundError: # pragma: no cover - running from a source tree
|
|
21
|
+
__version__ = "0+unknown"
|
|
22
|
+
__all__ = [
|
|
23
|
+
"DiffError",
|
|
24
|
+
"DiffNote",
|
|
25
|
+
"DiffReport",
|
|
26
|
+
"DiffWarning",
|
|
27
|
+
"assert_table_equal",
|
|
28
|
+
"diff_explain",
|
|
29
|
+
"diff_report",
|
|
30
|
+
"diff_summary",
|
|
31
|
+
"diff_table",
|
|
32
|
+
"is_matching",
|
|
33
|
+
"normalize_names",
|
|
34
|
+
]
|