dblock 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: dblock
3
+ Version: 0.1.0
4
+ Summary: Lockfiles for bioinformatics reference databases: pin, fetch, verify and cite exact releases.
5
+ Author: Dev Patel
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/dpatel511/dblock
8
+ Keywords: bioinformatics,reproducibility,databases,lockfile,metagenomics
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
11
+ Classifier: Environment :: Console
12
+ Requires-Python: >=3.11
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Dynamic: license-file
16
+
17
+ # dblock
18
+
19
+ **Lockfiles for bioinformatics reference databases.** Pin the exact releases an analysis uses, fetch and verify them, check they match your tool versions, and print provenance you can paste into a methods section.
20
+
21
+ > Status: early development (`0.1.0`). Commands and file formats may still change.
22
+
23
+ Tools like GTDB-Tk, Kraken 2, CheckM2 and Bakta depend on large reference databases. Each tool downloads its database differently, often fetching "latest", and pipelines usually record the tool version but not the database release or checksum. dblock adds the missing piece: a small `dblock.lock` file, committed with your code, that says exactly which database files were used.
24
+
25
+ ## Install
26
+
27
+ Python 3.11 or newer. No other dependencies.
28
+
29
+ ```bash
30
+ python -m pip install git+https://github.com/dpatel511/dblock.git
31
+ dblock --version
32
+ ```
33
+
34
+ ## Quick start
35
+
36
+ ```bash
37
+ dblock recipes # known databases and releases
38
+ dblock recipes gtdbtk # details: dates, sizes, checksums, compatible tool versions
39
+
40
+ dblock add gtdbtk@r226 checkm2 # pin releases (NAME or NAME@RELEASE) in ./dblock.lock
41
+ dblock fetch # download (resumable), check checksums, unpack, record hashes
42
+ dblock verify # fast check: file names and sizes
43
+ dblock verify --full # re-hash every file
44
+ dblock check-compat # are installed tools compatible with these releases?
45
+ dblock provenance # text for a methods section (or --format json)
46
+
47
+ export GTDBTK_DATA_PATH="$(dblock path gtdbtk)/release226"
48
+ ```
49
+
50
+ Databases are stored in `$DBLOCK_STORE` (default `~/.dblock/store`), one folder per name and release, so several releases can live side by side on a shared server.
51
+
52
+ ## What gets checked
53
+
54
+ | Check | When | What it catches |
55
+ |---|---|---|
56
+ | Upstream checksum (MD5/SHA-256) | `fetch`, when the provider publishes one | Corrupt or truncated downloads |
57
+ | Locked archive SHA-256 | `fetch` on another machine | Upstream silently replacing a file under the same name |
58
+ | Expected layout | `fetch` | Wrong or half-unpacked archives (e.g. missing `*.k2d` files) |
59
+ | Tree digest and per-file manifest | `verify` | Files deleted, added or modified after install |
60
+ | Tool-version rules | `check-compat` | Database release used with an incompatible tool version |
61
+
62
+ When a provider publishes no checksum (GTDB, one older Kraken 2 index), dblock records the SHA-256 of the first download and says so (`checksum_origin = "first-download"`). It never claims more than it checked.
63
+
64
+ ## The lockfile
65
+
66
+ ```toml
67
+ lock_version = 1
68
+
69
+ [databases.checkm2]
70
+ release = "3"
71
+ filename = "checkm2_database.tar.gz"
72
+ urls = ["https://zenodo.org/api/records/14897628/files/checkm2_database.tar.gz/content"]
73
+ upstream_checksum = "md5:07c10655620843b517d0df0c160d911f"
74
+ tool = "checkm2"
75
+ archive_sha256 = "…" # recorded at first fetch
76
+ checksum_origin = "upstream-verified"
77
+ tree_digest = "sha256:…" # digest of every unpacked file
78
+ files = 2
79
+ fetched_at = "2026-11-10"
80
+ ```
81
+
82
+ The store location is machine-specific and deliberately not in the lockfile.
83
+
84
+ ## Bundled recipes
85
+
86
+ | Name | Releases | Upstream checksum | Tool-version rules |
87
+ |---|---|---|---|
88
+ | `gtdbtk` | r232, r226, r220 | none published | from GTDB-Tk docs |
89
+ | `kraken2` | standard-8gb, pluspf, viral (2026-10-22, 2024-09-04) | MD5 (except standard-8gb-20240904) | none stated |
90
+ | `checkm2` | 3 (Zenodo) | MD5 | none stated |
91
+ | `bakta` | 6.0, 6.0-light (Zenodo) | MD5 | from `db-versions.json` |
92
+ | `bakta-galaxy-test` | 390 KB test database | MD5 | for trying dblock |
93
+
94
+ dblock always downloads from the official sources and never re-hosts data.
95
+
96
+ ### Add your own recipe
97
+
98
+ A recipe is one TOML file. Put it in a folder and pass `--recipes FOLDER` (or set `$DBLOCK_RECIPES`); it overrides a bundled recipe with the same name.
99
+
100
+ ```toml
101
+ name = "mydb"
102
+ description = "My reference database"
103
+ homepage = "https://example.org"
104
+ tool = "mytool"
105
+ version_command = ["mytool", "--version"]
106
+
107
+ [[releases]] # newest first
108
+ version = "2"
109
+ filename = "mydb-2.tar.gz"
110
+ format = "tar.gz" # tar.gz, tar.xz, tar.bz2, tar, zip, gz or file
111
+ size = 123456
112
+ checksum = "md5:…" # optional
113
+ tool_versions = ">=1.4,<2" # optional
114
+ layout = ["mydb/index.bin"] # optional: must exist after unpacking (globs allowed)
115
+ urls = ["https://example.org/mydb-2.tar.gz", "https://mirror.example.org/mydb-2.tar.gz"]
116
+ ```
117
+
118
+ ## Exit codes
119
+
120
+ `0` success · `1` problems found (failed verification, checksum mismatch, incompatible tool) · `2` usage or runtime error. Progress goes to stderr, results to stdout.
121
+
122
+ ## Development
123
+
124
+ ```bash
125
+ python -m pip install -e .
126
+ python -m unittest discover -s tests -v
127
+ ```
128
+
129
+ Tests run against a local HTTP server and need no internet access.
130
+
131
+ ## Licence
132
+
133
+ MIT
@@ -0,0 +1,19 @@
1
+ dblock/__init__.py,sha256=7OWVYeBu5GsSS2UG1UUwTSd86gVRAQHtaj-cli23JWY,87
2
+ dblock/__main__.py,sha256=YUejISSh6FETsFZzz2Yt1159UWWCoPbzoCFaDncfR_4,58
3
+ dblock/cli.py,sha256=2b1j50GB6v52b4wgah9vXujowY8ebro7yR10UL7LihM,16833
4
+ dblock/compat.py,sha256=vlDSQGzy1fZ2KGJGLDrfh-DJKMtCQJrXCGmqqx6NVQA,2433
5
+ dblock/download.py,sha256=zGRZoBBWhW4Quio4Nd7Kqoh2zBoi52a0VLQhhZ6LfDM,4584
6
+ dblock/lockfile.py,sha256=40vGdnJge2UwNq5-vhPx4EKs-rxw7cuP-skvlyHvtjI,4234
7
+ dblock/recipes.py,sha256=WkTNz1tG7mudgLm9qZ1-pdNDsnrcdLj4x6mhX-uZsgM,4681
8
+ dblock/store.py,sha256=yqW_0QqIFWKa5n6Eyn7Ti-LKPUSOXhIn_gB3IKc3t2M,8116
9
+ dblock/recipes/bakta-galaxy-test.toml,sha256=GG2c8jvnjv7dc6mySxnLlXutLIlioCJAXqAhTKvzzUE,636
10
+ dblock/recipes/bakta.toml,sha256=Ce4BkZcKPxP1UYcV0MBN-BJ5B4kTSJ1CN2QcNyQc7HU,1208
11
+ dblock/recipes/checkm2.toml,sha256=TyO5SBizNkTflLzYKRtTLJ4JT7nZs6k-4hm7y6jNXXE,856
12
+ dblock/recipes/gtdbtk.toml,sha256=uIhttgDN3K_6P8ldBpkrpUJUZJmAftWfaVutQjeF8uA,2060
13
+ dblock/recipes/kraken2.toml,sha256=M2hrHj5R92q_urDfRNQVxcXDrsJpb_C6ReQkHpb38tA,2955
14
+ dblock-0.1.0.dist-info/licenses/LICENSE,sha256=cHDx2QXkxyVfXl5V-YvmLHhvs69PQq-9nDhYDl5rtVI,1066
15
+ dblock-0.1.0.dist-info/METADATA,sha256=T6aRYUDSsZ9RhRvpAyAGFyoYNUbfDyzM69Cnn9U93-8,5390
16
+ dblock-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
17
+ dblock-0.1.0.dist-info/entry_points.txt,sha256=iQ8R70xHtiGeyIzqCZYWgymvJU3_r-5u_D23C8hrB1I,43
18
+ dblock-0.1.0.dist-info/top_level.txt,sha256=Mr0Nf36SSGQwY0EhGBcQ5mWco5ILRzXfOnhLh1eLhsU,7
19
+ dblock-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ dblock = dblock.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dev Patel
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.
@@ -0,0 +1 @@
1
+ dblock