dstrack 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.
- dstrack-0.1.0/LICENSE +21 -0
- dstrack-0.1.0/PKG-INFO +123 -0
- dstrack-0.1.0/README.md +98 -0
- dstrack-0.1.0/pyproject.toml +114 -0
- dstrack-0.1.0/src/dstrack/__init__.py +8 -0
- dstrack-0.1.0/src/dstrack/_benchmark/__init__.py +54 -0
- dstrack-0.1.0/src/dstrack/_benchmark/_cli.py +114 -0
- dstrack-0.1.0/src/dstrack/_benchmark/_environment.py +144 -0
- dstrack-0.1.0/src/dstrack/_benchmark/_profiling.py +207 -0
- dstrack-0.1.0/src/dstrack/_benchmark/_report.py +152 -0
- dstrack-0.1.0/src/dstrack/_benchmark/_runner.py +196 -0
- dstrack-0.1.0/src/dstrack/_benchmark/_synthetic.py +158 -0
- dstrack-0.1.0/src/dstrack/_cli.py +105 -0
- dstrack-0.1.0/src/dstrack/_log.py +268 -0
- dstrack-0.1.0/src/dstrack/_log_render.py +282 -0
- dstrack-0.1.0/src/dstrack/_logging.py +60 -0
- dstrack-0.1.0/src/dstrack/_store_template.py +58 -0
- dstrack-0.1.0/src/dstrack/_track.py +144 -0
- dstrack-0.1.0/src/dstrack/cache.py +448 -0
- dstrack-0.1.0/src/dstrack/console.py +47 -0
- dstrack-0.1.0/src/dstrack/errors.py +22 -0
- dstrack-0.1.0/src/dstrack/paths.py +88 -0
- dstrack-0.1.0/src/dstrack/readers/__init__.py +69 -0
- dstrack-0.1.0/src/dstrack/readers/_csv.py +361 -0
- dstrack-0.1.0/src/dstrack/readers/_protocol.py +120 -0
- dstrack-0.1.0/src/dstrack/readers/_registry.py +241 -0
- dstrack-0.1.0/src/dstrack/readers/_resolve.py +140 -0
- dstrack-0.1.0/src/dstrack/schemas/snapshot_v1.json +299 -0
- dstrack-0.1.0/src/dstrack/snapshot/__init__.py +46 -0
- dstrack-0.1.0/src/dstrack/snapshot/_builder.py +114 -0
- dstrack-0.1.0/src/dstrack/snapshot/_metadata.py +154 -0
- dstrack-0.1.0/src/dstrack/snapshot/_stats.py +487 -0
- dstrack-0.1.0/src/dstrack/snapshot/_version.py +13 -0
- dstrack-0.1.0/src/dstrack/store.py +765 -0
- dstrack-0.1.0/src/dstrack/utils.py +6 -0
dstrack-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Leonardo Ayala
|
|
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.
|
dstrack-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dstrack
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Python package for versioning and monitoring dataset changes throughout the machine learning lifecycle.
|
|
5
|
+
Keywords: dataset,versioning,monitoring,machine learning,mlops,data science
|
|
6
|
+
Author: Leonardo Ayala
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Dist: rich>=15.0.0
|
|
21
|
+
Requires-Dist: typer>=0.26.8
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Project-URL: GitHub, https://github.com/leoyala/dstrack
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# dstrack
|
|
27
|
+
|
|
28
|
+
[](https://github.com/leoyala/dstrack/actions/workflows/unittests.yaml)
|
|
29
|
+
[](https://codecov.io/github/leoyala/dstrack)
|
|
30
|
+
|
|
31
|
+
<p align="center">
|
|
32
|
+
<img src="docs/assets/dstrack-logo.png" width="200" alt="dstrack logo">
|
|
33
|
+
</p>
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
A Python package for versioning and monitoring dataset changes throughout the machine learning lifecycle.
|
|
37
|
+
|
|
38
|
+
<p align="center">
|
|
39
|
+
<img src="docs/assets/cli.gif" alt="CLI example">
|
|
40
|
+
</p>
|
|
41
|
+
|
|
42
|
+
## Overview
|
|
43
|
+
|
|
44
|
+
`dstrack` helps data scientists and ML engineers track how datasets evolve over time, catching schema drift, distribution shifts, and unexpected mutations before they silently break pipelines or degrade model performance.
|
|
45
|
+
|
|
46
|
+
## What dstrack is (and isn't)
|
|
47
|
+
|
|
48
|
+
`dstrack` records *semantics* about a dataset - its schema, a content fingerprint, and per-column statistics - not the dataset itself.
|
|
49
|
+
It is not a data version control system: unlike DVC, LakeFS, or Git LFS, it never copies your files into a store or pushes them to a
|
|
50
|
+
remote, and it cannot check an old version of `data.csv` back out for you. Your data stays wherever it already lives, and `dstrack` keeps a small,
|
|
51
|
+
human-readable audit trail beside your code so you can see how that data changed and when. If you need to store and retrieve the bytes, reach for
|
|
52
|
+
DVC and use `dstrack` alongside it.
|
|
53
|
+
|
|
54
|
+
## Installation
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install dstrack
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Requires Python 3.11 or later.
|
|
61
|
+
|
|
62
|
+
## Getting started
|
|
63
|
+
|
|
64
|
+
Initialize a store in your project, then take your first snapshot.
|
|
65
|
+
|
|
66
|
+
**1. Create a local store** - this adds a `.dstrack/` directory at the current location:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
dstrack init
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
ℹ Generating local store structure at /path/to/.dstrack.
|
|
74
|
+
✔ Finished creating local store: /path/to/.dstrack
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**2. Track a dataset** - point `dstrack` at a data file to snapshot it. Given a small
|
|
78
|
+
`data.csv`:
|
|
79
|
+
|
|
80
|
+
```csv
|
|
81
|
+
id,name,value
|
|
82
|
+
1,alpha,10.5
|
|
83
|
+
2,beta,20.0
|
|
84
|
+
3,gamma,15.25
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
dstrack track data.csv
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
```text
|
|
92
|
+
ℹ Reading data.csv and computing snapshot...
|
|
93
|
+
✔ Snapshot <snapshot-uuid> written (new dataset, dataset <dataset-uuid>).
|
|
94
|
+
ℹ Stored at /path/to/.dstrack/datasets/<dataset-uuid>/snapshots/<snapshot-uuid>.json
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**3. Re-track as the data changes** - running `track` again on the same path extends the
|
|
98
|
+
dataset's lineage instead of starting a new one:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
dstrack track data.csv
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
✔ Snapshot <snapshot-uuid> written (continued lineage, dataset <dataset-uuid>).
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Each snapshot captures the file's schema, a content fingerprint, and per-column
|
|
109
|
+
statistics. See the [Getting Started guide](https://leoyala.github.io/dstrack/getting_started/)
|
|
110
|
+
for options such as `--name`, `--reader`, and `--dataset-id`.
|
|
111
|
+
|
|
112
|
+
## Features
|
|
113
|
+
|
|
114
|
+
- **Dataset versioning** - snapshot a dataset and track its lineage across pipeline stages
|
|
115
|
+
- **Rich snapshots** - schema hash, content fingerprint, and per-column statistics (ranges, null rates, and more)
|
|
116
|
+
- **CSV out of the box** - pure standard-library reader, no heavy dependencies
|
|
117
|
+
- **Lightweight CLI** - a small, git-like local store you can commit alongside your code
|
|
118
|
+
|
|
119
|
+
## Roadmap
|
|
120
|
+
|
|
121
|
+
Change detection and drift monitoring are on the way - comparing snapshots, surfacing
|
|
122
|
+
schema and distribution shifts, and failing CI on drift. See the
|
|
123
|
+
[roadmap](docs/roadmap.md) for what's planned.
|
dstrack-0.1.0/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# dstrack
|
|
2
|
+
|
|
3
|
+
[](https://github.com/leoyala/dstrack/actions/workflows/unittests.yaml)
|
|
4
|
+
[](https://codecov.io/github/leoyala/dstrack)
|
|
5
|
+
|
|
6
|
+
<p align="center">
|
|
7
|
+
<img src="docs/assets/dstrack-logo.png" width="200" alt="dstrack logo">
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
A Python package for versioning and monitoring dataset changes throughout the machine learning lifecycle.
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<img src="docs/assets/cli.gif" alt="CLI example">
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
## Overview
|
|
18
|
+
|
|
19
|
+
`dstrack` helps data scientists and ML engineers track how datasets evolve over time, catching schema drift, distribution shifts, and unexpected mutations before they silently break pipelines or degrade model performance.
|
|
20
|
+
|
|
21
|
+
## What dstrack is (and isn't)
|
|
22
|
+
|
|
23
|
+
`dstrack` records *semantics* about a dataset - its schema, a content fingerprint, and per-column statistics - not the dataset itself.
|
|
24
|
+
It is not a data version control system: unlike DVC, LakeFS, or Git LFS, it never copies your files into a store or pushes them to a
|
|
25
|
+
remote, and it cannot check an old version of `data.csv` back out for you. Your data stays wherever it already lives, and `dstrack` keeps a small,
|
|
26
|
+
human-readable audit trail beside your code so you can see how that data changed and when. If you need to store and retrieve the bytes, reach for
|
|
27
|
+
DVC and use `dstrack` alongside it.
|
|
28
|
+
|
|
29
|
+
## Installation
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pip install dstrack
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Requires Python 3.11 or later.
|
|
36
|
+
|
|
37
|
+
## Getting started
|
|
38
|
+
|
|
39
|
+
Initialize a store in your project, then take your first snapshot.
|
|
40
|
+
|
|
41
|
+
**1. Create a local store** - this adds a `.dstrack/` directory at the current location:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
dstrack init
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
ℹ Generating local store structure at /path/to/.dstrack.
|
|
49
|
+
✔ Finished creating local store: /path/to/.dstrack
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**2. Track a dataset** - point `dstrack` at a data file to snapshot it. Given a small
|
|
53
|
+
`data.csv`:
|
|
54
|
+
|
|
55
|
+
```csv
|
|
56
|
+
id,name,value
|
|
57
|
+
1,alpha,10.5
|
|
58
|
+
2,beta,20.0
|
|
59
|
+
3,gamma,15.25
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
dstrack track data.csv
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
ℹ Reading data.csv and computing snapshot...
|
|
68
|
+
✔ Snapshot <snapshot-uuid> written (new dataset, dataset <dataset-uuid>).
|
|
69
|
+
ℹ Stored at /path/to/.dstrack/datasets/<dataset-uuid>/snapshots/<snapshot-uuid>.json
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**3. Re-track as the data changes** - running `track` again on the same path extends the
|
|
73
|
+
dataset's lineage instead of starting a new one:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
dstrack track data.csv
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```text
|
|
80
|
+
✔ Snapshot <snapshot-uuid> written (continued lineage, dataset <dataset-uuid>).
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Each snapshot captures the file's schema, a content fingerprint, and per-column
|
|
84
|
+
statistics. See the [Getting Started guide](https://leoyala.github.io/dstrack/getting_started/)
|
|
85
|
+
for options such as `--name`, `--reader`, and `--dataset-id`.
|
|
86
|
+
|
|
87
|
+
## Features
|
|
88
|
+
|
|
89
|
+
- **Dataset versioning** - snapshot a dataset and track its lineage across pipeline stages
|
|
90
|
+
- **Rich snapshots** - schema hash, content fingerprint, and per-column statistics (ranges, null rates, and more)
|
|
91
|
+
- **CSV out of the box** - pure standard-library reader, no heavy dependencies
|
|
92
|
+
- **Lightweight CLI** - a small, git-like local store you can commit alongside your code
|
|
93
|
+
|
|
94
|
+
## Roadmap
|
|
95
|
+
|
|
96
|
+
Change detection and drift monitoring are on the way - comparing snapshots, surfacing
|
|
97
|
+
schema and distribution shifts, and failing CI on drift. See the
|
|
98
|
+
[roadmap](docs/roadmap.md) for what's planned.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "dstrack"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "A Python package for versioning and monitoring dataset changes throughout the machine learning lifecycle."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [
|
|
9
|
+
{ name = "Leonardo Ayala" }
|
|
10
|
+
]
|
|
11
|
+
keywords = ["dataset", "versioning", "monitoring", "machine learning", "mlops", "data science"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 3 - Alpha",
|
|
14
|
+
"Intended Audience :: Developers",
|
|
15
|
+
"Intended Audience :: Science/Research",
|
|
16
|
+
"License :: OSI Approved :: MIT License",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Programming Language :: Python :: 3.13",
|
|
21
|
+
"Programming Language :: Python :: 3.14",
|
|
22
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
23
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
24
|
+
]
|
|
25
|
+
requires-python = ">=3.11"
|
|
26
|
+
dependencies = [
|
|
27
|
+
"rich>=15.0.0",
|
|
28
|
+
"typer>=0.26.8",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.urls]
|
|
32
|
+
GitHub = "https://github.com/leoyala/dstrack"
|
|
33
|
+
|
|
34
|
+
[project.scripts]
|
|
35
|
+
dstrack = "dstrack._cli:app"
|
|
36
|
+
dstrack-benchmark = "dstrack._benchmark:app"
|
|
37
|
+
|
|
38
|
+
[build-system]
|
|
39
|
+
requires = ["uv_build>=0.11.28,<0.12.0"]
|
|
40
|
+
build-backend = "uv_build"
|
|
41
|
+
|
|
42
|
+
# -----------------------------------------------------------------------------
|
|
43
|
+
# Ruff: linter + formatter
|
|
44
|
+
# -----------------------------------------------------------------------------
|
|
45
|
+
[tool.ruff]
|
|
46
|
+
line-length = 88
|
|
47
|
+
src = ["src", "tests"]
|
|
48
|
+
|
|
49
|
+
[tool.ruff.lint]
|
|
50
|
+
# A pragmatic, high-signal rule set.
|
|
51
|
+
select = [
|
|
52
|
+
"E", # pycodestyle errors
|
|
53
|
+
"W", # pycodestyle warnings
|
|
54
|
+
"F", # pyflakes
|
|
55
|
+
"I", # isort (import sorting)
|
|
56
|
+
"B", # flake8-bugbear (likely bugs)
|
|
57
|
+
"UP", # pyupgrade (modernize syntax)
|
|
58
|
+
"SIM", # flake8-simplify
|
|
59
|
+
"C4", # flake8-comprehensions
|
|
60
|
+
"PERF", # perflint (performance anti-patterns)
|
|
61
|
+
"RUF", # ruff-specific rules
|
|
62
|
+
]
|
|
63
|
+
ignore = [
|
|
64
|
+
"E501", # line length is handled by the formatter
|
|
65
|
+
]
|
|
66
|
+
|
|
67
|
+
[tool.ruff.lint.per-file-ignores]
|
|
68
|
+
# Tests can use assert, magic values, etc.
|
|
69
|
+
"tests/**" = ["B", "S101"]
|
|
70
|
+
|
|
71
|
+
[tool.ruff.lint.pydocstyle]
|
|
72
|
+
convention = "google"
|
|
73
|
+
|
|
74
|
+
[tool.ruff.format]
|
|
75
|
+
docstring-code-format = true
|
|
76
|
+
quote-style = "double"
|
|
77
|
+
|
|
78
|
+
# -----------------------------------------------------------------------------
|
|
79
|
+
# mypy: static type checking
|
|
80
|
+
# -----------------------------------------------------------------------------
|
|
81
|
+
[tool.mypy]
|
|
82
|
+
files = ["src"]
|
|
83
|
+
python_version = "3.11"
|
|
84
|
+
strict = true
|
|
85
|
+
show_error_codes = true
|
|
86
|
+
warn_unreachable = true
|
|
87
|
+
warn_redundant_casts = true
|
|
88
|
+
warn_unused_ignores = true
|
|
89
|
+
enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
|
|
90
|
+
|
|
91
|
+
# Silence missing stubs for third-party libs that don't ship types.
|
|
92
|
+
[[tool.mypy.overrides]]
|
|
93
|
+
module = [
|
|
94
|
+
"numpy.*",
|
|
95
|
+
"pandas.*",
|
|
96
|
+
"sklearn.*",
|
|
97
|
+
]
|
|
98
|
+
ignore_missing_imports = true
|
|
99
|
+
|
|
100
|
+
# -----------------------------------------------------------------------------
|
|
101
|
+
# codespell: spell-checking for code, docstrings, and docs
|
|
102
|
+
# -----------------------------------------------------------------------------
|
|
103
|
+
[tool.codespell]
|
|
104
|
+
ignore-words-list = "nd,hist,ans"
|
|
105
|
+
skip = "*.lock,*.csv,*.parquet,./data,./datasets"
|
|
106
|
+
|
|
107
|
+
[dependency-groups]
|
|
108
|
+
dev = [
|
|
109
|
+
"jsonschema>=4.26.0",
|
|
110
|
+
"mkdocstrings-python>=2.0.5",
|
|
111
|
+
"pytest>=9.1.1",
|
|
112
|
+
"pytest-cov>=7.1.0",
|
|
113
|
+
"zensical>=0.0.50",
|
|
114
|
+
]
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
"""Benchmark for dstrack's snapshot creation pipeline.
|
|
2
|
+
|
|
3
|
+
Generates a synthetic CSV in a temporary directory, then times how long it
|
|
4
|
+
takes to build snapshot metadata and statistics for it, alongside a summary of
|
|
5
|
+
the environment the benchmark ran in and a call tree of dstrack's own methods.
|
|
6
|
+
|
|
7
|
+
Layers
|
|
8
|
+
------
|
|
9
|
+
[dstrack._benchmark._synthetic][]
|
|
10
|
+
Describes and writes the synthetic dataset.
|
|
11
|
+
|
|
12
|
+
[dstrack._benchmark._runner][]
|
|
13
|
+
Runs the snapshot pipeline against it and times each phase.
|
|
14
|
+
|
|
15
|
+
[dstrack._benchmark._profiling][]
|
|
16
|
+
Reduces the ``cProfile`` run to a call tree of dstrack's own methods.
|
|
17
|
+
|
|
18
|
+
[dstrack._benchmark._environment][]
|
|
19
|
+
Describes the machine the benchmark ran on.
|
|
20
|
+
|
|
21
|
+
[dstrack._benchmark._report][], [dstrack._benchmark._cli][]
|
|
22
|
+
Render runs to a console, and wire the whole thing to ``dstrack-benchmark``.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from ._cli import app
|
|
26
|
+
from ._environment import EnvironmentInfo, collect_environment_info
|
|
27
|
+
from ._profiling import CallGraph, CallNode, CallScope
|
|
28
|
+
from ._report import ConsoleReporter
|
|
29
|
+
from ._runner import (
|
|
30
|
+
BenchmarkObserver,
|
|
31
|
+
BenchmarkResult,
|
|
32
|
+
BenchmarkRun,
|
|
33
|
+
BenchmarkRunner,
|
|
34
|
+
SilentObserver,
|
|
35
|
+
)
|
|
36
|
+
from ._synthetic import SyntheticColumn, SyntheticCsvSpec, write_synthetic_csv
|
|
37
|
+
|
|
38
|
+
__all__ = [
|
|
39
|
+
"BenchmarkObserver",
|
|
40
|
+
"BenchmarkResult",
|
|
41
|
+
"BenchmarkRun",
|
|
42
|
+
"BenchmarkRunner",
|
|
43
|
+
"CallGraph",
|
|
44
|
+
"CallNode",
|
|
45
|
+
"CallScope",
|
|
46
|
+
"ConsoleReporter",
|
|
47
|
+
"EnvironmentInfo",
|
|
48
|
+
"SilentObserver",
|
|
49
|
+
"SyntheticColumn",
|
|
50
|
+
"SyntheticCsvSpec",
|
|
51
|
+
"app",
|
|
52
|
+
"collect_environment_info",
|
|
53
|
+
"write_synthetic_csv",
|
|
54
|
+
]
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
"""Command-line entry point for the snapshot benchmark."""
|
|
2
|
+
|
|
3
|
+
import shutil
|
|
4
|
+
import tempfile
|
|
5
|
+
from collections.abc import Iterator
|
|
6
|
+
from contextlib import contextmanager
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Annotated
|
|
9
|
+
|
|
10
|
+
import typer
|
|
11
|
+
|
|
12
|
+
from dstrack._benchmark._report import ConsoleReporter
|
|
13
|
+
from dstrack._benchmark._runner import BenchmarkRunner
|
|
14
|
+
from dstrack._benchmark._synthetic import SyntheticCsvSpec
|
|
15
|
+
|
|
16
|
+
app = typer.Typer(
|
|
17
|
+
no_args_is_help=True,
|
|
18
|
+
pretty_exceptions_show_locals=False,
|
|
19
|
+
help="Benchmark dstrack's snapshot creation pipeline against a synthetic CSV.",
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
_DEFAULTS = SyntheticCsvSpec()
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@app.callback()
|
|
26
|
+
def _main() -> None:
|
|
27
|
+
"""Keep ``run`` a named subcommand so a bare invocation shows help.
|
|
28
|
+
|
|
29
|
+
Typer promotes a lone command to the top level, which quietly discards
|
|
30
|
+
``no_args_is_help``; an explicit callback keeps the command group intact so
|
|
31
|
+
running ``dstrack-benchmark`` with no arguments prints help instead of
|
|
32
|
+
silently kicking off a full-size benchmark.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@contextmanager
|
|
37
|
+
def _workspace(reporter: ConsoleReporter, *, keep_csv: bool) -> Iterator[Path]:
|
|
38
|
+
"""Yield a path for the synthetic CSV, discarding it unless ``keep_csv``."""
|
|
39
|
+
tmp_dir = Path(tempfile.mkdtemp(prefix="dstrack-benchmark-"))
|
|
40
|
+
csv_path = tmp_dir / "synthetic_dataset.csv"
|
|
41
|
+
try:
|
|
42
|
+
yield csv_path
|
|
43
|
+
finally:
|
|
44
|
+
if keep_csv:
|
|
45
|
+
reporter.csv_kept(csv_path)
|
|
46
|
+
else:
|
|
47
|
+
shutil.rmtree(tmp_dir, ignore_errors=True)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
@app.command(help="Generate a synthetic CSV and benchmark snapshot creation on it.")
|
|
51
|
+
def run(
|
|
52
|
+
rows: Annotated[
|
|
53
|
+
int, typer.Option(min=0, help="Number of data rows to generate.")
|
|
54
|
+
] = _DEFAULTS.num_rows,
|
|
55
|
+
numeric_cols: Annotated[
|
|
56
|
+
int, typer.Option(min=0, help="Number of numeric (float) columns.")
|
|
57
|
+
] = _DEFAULTS.num_numeric_cols,
|
|
58
|
+
string_cols: Annotated[
|
|
59
|
+
int, typer.Option(min=0, help="Number of string columns.")
|
|
60
|
+
] = _DEFAULTS.num_string_cols,
|
|
61
|
+
datetime_cols: Annotated[
|
|
62
|
+
int, typer.Option(min=0, help="Number of datetime columns.")
|
|
63
|
+
] = _DEFAULTS.num_datetime_cols,
|
|
64
|
+
bool_cols: Annotated[
|
|
65
|
+
int, typer.Option(min=0, help="Number of boolean columns.")
|
|
66
|
+
] = _DEFAULTS.num_bool_cols,
|
|
67
|
+
null_rate: Annotated[
|
|
68
|
+
float,
|
|
69
|
+
typer.Option(min=0.0, max=1.0, help="Fraction of non-id cells left null."),
|
|
70
|
+
] = _DEFAULTS.null_rate,
|
|
71
|
+
seed: Annotated[
|
|
72
|
+
int, typer.Option(help="Random seed for reproducible synthetic data.")
|
|
73
|
+
] = _DEFAULTS.seed,
|
|
74
|
+
keep_csv: Annotated[
|
|
75
|
+
bool,
|
|
76
|
+
typer.Option(
|
|
77
|
+
help="Keep the generated CSV instead of deleting it after the run."
|
|
78
|
+
),
|
|
79
|
+
] = False,
|
|
80
|
+
profile: Annotated[
|
|
81
|
+
bool,
|
|
82
|
+
typer.Option(
|
|
83
|
+
help="Profile dstrack's own methods while building the snapshot. "
|
|
84
|
+
"Adds cProfile overhead to the reported metadata/stats timings."
|
|
85
|
+
),
|
|
86
|
+
] = True,
|
|
87
|
+
profile_limit: Annotated[
|
|
88
|
+
int,
|
|
89
|
+
typer.Option(
|
|
90
|
+
min=0,
|
|
91
|
+
help="Max number of child methods shown under each node of the "
|
|
92
|
+
"profile call tree, ranked by cumulative time.",
|
|
93
|
+
),
|
|
94
|
+
] = 20,
|
|
95
|
+
) -> None:
|
|
96
|
+
spec = SyntheticCsvSpec(
|
|
97
|
+
num_rows=rows,
|
|
98
|
+
num_numeric_cols=numeric_cols,
|
|
99
|
+
num_string_cols=string_cols,
|
|
100
|
+
num_datetime_cols=datetime_cols,
|
|
101
|
+
num_bool_cols=bool_cols,
|
|
102
|
+
null_rate=null_rate,
|
|
103
|
+
seed=seed,
|
|
104
|
+
)
|
|
105
|
+
reporter = ConsoleReporter()
|
|
106
|
+
runner = BenchmarkRunner(spec, observer=reporter, profile=profile)
|
|
107
|
+
|
|
108
|
+
with _workspace(reporter, keep_csv=keep_csv) as csv_path:
|
|
109
|
+
benchmark_run = runner.run(csv_path)
|
|
110
|
+
reporter.report(benchmark_run, profile_limit=profile_limit)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
if __name__ == "__main__":
|
|
114
|
+
app()
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
"""Describes the machine and runtime a benchmark executed under.
|
|
2
|
+
|
|
3
|
+
Hardware facts have no portable API, so each is read by a per-OS probe. Every
|
|
4
|
+
probe is best-effort: it returns ``None`` (or raises, which
|
|
5
|
+
[_attempt()][dstrack._benchmark._environment._attempt] swallows) when the
|
|
6
|
+
platform will not give up the answer, and the caller falls back to something
|
|
7
|
+
always available.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
import platform
|
|
12
|
+
import subprocess
|
|
13
|
+
from collections.abc import Callable
|
|
14
|
+
from dataclasses import dataclass
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
from typing import TypeVar
|
|
17
|
+
|
|
18
|
+
from dstrack import __version__
|
|
19
|
+
|
|
20
|
+
T = TypeVar("T")
|
|
21
|
+
|
|
22
|
+
_PROBE_TIMEOUT_SECONDS = 5
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass(frozen=True)
|
|
26
|
+
class EnvironmentInfo:
|
|
27
|
+
"""Snapshot of the machine and runtime a benchmark executed under."""
|
|
28
|
+
|
|
29
|
+
os_name: str
|
|
30
|
+
os_release: str
|
|
31
|
+
os_version: str
|
|
32
|
+
machine: str
|
|
33
|
+
cpu_model: str
|
|
34
|
+
cpu_count: int | None
|
|
35
|
+
total_memory_gb: float | None
|
|
36
|
+
python_implementation: str
|
|
37
|
+
python_version: str
|
|
38
|
+
dstrack_version: str
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _attempt(probe: Callable[[], T | None]) -> T | None:
|
|
42
|
+
"""Run a probe, returning ``None`` if the platform refuses to answer."""
|
|
43
|
+
try:
|
|
44
|
+
return probe()
|
|
45
|
+
except (OSError, subprocess.SubprocessError, ValueError):
|
|
46
|
+
return None
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _command_output(*args: str) -> str:
|
|
50
|
+
"""Gets the stdout of a command, raising if it fails or times out."""
|
|
51
|
+
result = subprocess.run(
|
|
52
|
+
args,
|
|
53
|
+
capture_output=True,
|
|
54
|
+
text=True,
|
|
55
|
+
timeout=_PROBE_TIMEOUT_SECONDS,
|
|
56
|
+
check=True,
|
|
57
|
+
)
|
|
58
|
+
return result.stdout.strip()
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _first_matching_line(path: Path, prefix: str) -> str | None:
|
|
62
|
+
"""First line of ``path`` starting with ``prefix`` (case-insensitive)."""
|
|
63
|
+
if not path.is_file():
|
|
64
|
+
return None
|
|
65
|
+
for line in path.read_text().splitlines():
|
|
66
|
+
if line.lower().startswith(prefix.lower()):
|
|
67
|
+
return line
|
|
68
|
+
return None
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _linux_cpu_model() -> str | None:
|
|
72
|
+
line = _first_matching_line(Path("/proc/cpuinfo"), "model name")
|
|
73
|
+
return line.split(":", 1)[1].strip() if line else None
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _darwin_cpu_model() -> str | None:
|
|
77
|
+
return _command_output("sysctl", "-n", "machdep.cpu.brand_string")
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _windows_cpu_model() -> str | None:
|
|
81
|
+
lines = [
|
|
82
|
+
line.strip()
|
|
83
|
+
for line in _command_output("wmic", "cpu", "get", "name").splitlines()
|
|
84
|
+
if line.strip()
|
|
85
|
+
]
|
|
86
|
+
return lines[1] if len(lines) >= 2 else None
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _linux_total_memory() -> int | None:
|
|
90
|
+
line = _first_matching_line(Path("/proc/meminfo"), "MemTotal:")
|
|
91
|
+
return int(line.split()[1]) * 1024 if line else None
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _darwin_total_memory() -> int | None:
|
|
95
|
+
return int(_command_output("sysctl", "-n", "hw.memsize"))
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _sysconf_total_memory() -> int | None:
|
|
99
|
+
"""Page size times page count, on any POSIX platform exposing sysconf."""
|
|
100
|
+
if not hasattr(os, "sysconf") or "SC_PAGE_SIZE" not in os.sysconf_names:
|
|
101
|
+
return None
|
|
102
|
+
return os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
_CPU_MODEL_PROBES: dict[str, Callable[[], str | None]] = {
|
|
106
|
+
"Linux": _linux_cpu_model,
|
|
107
|
+
"Darwin": _darwin_cpu_model,
|
|
108
|
+
"Windows": _windows_cpu_model,
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
_TOTAL_MEMORY_PROBES: dict[str, Callable[[], int | None]] = {
|
|
112
|
+
"Linux": _linux_total_memory,
|
|
113
|
+
"Darwin": _darwin_total_memory,
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _cpu_model() -> str:
|
|
118
|
+
"""Best-effort human-readable CPU model string for the current machine."""
|
|
119
|
+
probe = _CPU_MODEL_PROBES.get(platform.system())
|
|
120
|
+
model = _attempt(probe) if probe is not None else None
|
|
121
|
+
return model or platform.processor() or platform.machine() or "unknown"
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _total_memory_bytes() -> int | None:
|
|
125
|
+
"""Best-effort total physical memory in bytes, or None if it can't be read."""
|
|
126
|
+
probe = _TOTAL_MEMORY_PROBES.get(platform.system(), _sysconf_total_memory)
|
|
127
|
+
return _attempt(probe)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def collect_environment_info() -> EnvironmentInfo:
|
|
131
|
+
"""Collect OS, hardware, and runtime details describing the current machine."""
|
|
132
|
+
total_memory = _total_memory_bytes()
|
|
133
|
+
return EnvironmentInfo(
|
|
134
|
+
os_name=platform.system(),
|
|
135
|
+
os_release=platform.release(),
|
|
136
|
+
os_version=platform.version(),
|
|
137
|
+
machine=platform.machine(),
|
|
138
|
+
cpu_model=_cpu_model(),
|
|
139
|
+
cpu_count=os.cpu_count(),
|
|
140
|
+
total_memory_gb=total_memory / (1024**3) if total_memory is not None else None,
|
|
141
|
+
python_implementation=platform.python_implementation(),
|
|
142
|
+
python_version=platform.python_version(),
|
|
143
|
+
dstrack_version=__version__,
|
|
144
|
+
)
|