file-split-kit 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,5 @@
1
+ """Split, verify, and restore files with SHA-256 manifests."""
2
+
3
+ from ._core import IntegrityError, merge, split, verify
4
+
5
+ __all__ = ["IntegrityError", "merge", "split", "verify"]
@@ -0,0 +1,4 @@
1
+ from ._cli import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())
file_split_kit/_cli.py ADDED
@@ -0,0 +1,66 @@
1
+ import argparse
2
+ import sys
3
+ from collections.abc import Sequence
4
+
5
+ from ._core import DEFAULT_CHUNK_SIZE, merge, split, verify
6
+
7
+
8
+ def main(argv: Sequence[str] | None = None) -> int:
9
+ parser = argparse.ArgumentParser(
10
+ prog="file-split-kit", description="Split, verify, and restore files."
11
+ )
12
+ commands = parser.add_subparsers(dest="command", required=True)
13
+
14
+ split_parser = commands.add_parser(
15
+ "split", help="Split a file and create its manifest."
16
+ )
17
+ split_parser.add_argument("source", help="File to split.")
18
+ split_parser.add_argument("-o", "--output-dir", help="Defaults to SOURCE.parts.")
19
+ split_parser.add_argument(
20
+ "--chunk-size",
21
+ metavar="BYTES",
22
+ type=int,
23
+ default=DEFAULT_CHUNK_SIZE,
24
+ help="Maximum bytes per chunk (default: 20 MiB).",
25
+ )
26
+ split_parser.add_argument(
27
+ "--overwrite", action="store_true", help="Replace an existing parts directory."
28
+ )
29
+
30
+ merge_parser = commands.add_parser("merge", help="Verify and restore a file.")
31
+ merge_parser.add_argument("parts_dir", help="Directory containing manifest.json.")
32
+ merge_parser.add_argument(
33
+ "-o",
34
+ "--output",
35
+ help="Defaults to the original name next to the parts directory.",
36
+ )
37
+ merge_parser.add_argument(
38
+ "--overwrite", action="store_true", help="Replace an existing output file."
39
+ )
40
+
41
+ verify_parser = commands.add_parser(
42
+ "verify", help="Check the parts and complete file hashes."
43
+ )
44
+ verify_parser.add_argument("parts_dir", help="Directory containing manifest.json.")
45
+
46
+ args = parser.parse_args(argv)
47
+ try:
48
+ if args.command == "split":
49
+ print(
50
+ split(
51
+ args.source,
52
+ args.output_dir,
53
+ chunk_size=args.chunk_size,
54
+ overwrite=args.overwrite,
55
+ )
56
+ )
57
+ elif args.command == "merge":
58
+ print(merge(args.parts_dir, args.output, overwrite=args.overwrite))
59
+ else:
60
+ verify(args.parts_dir)
61
+ print(f"Verified {args.parts_dir}")
62
+ except (OSError, ValueError) as exc:
63
+ print(f"{parser.prog}: {exc}", file=sys.stderr)
64
+ return 1
65
+
66
+ return 0
@@ -0,0 +1,224 @@
1
+ import os
2
+ import re
3
+ import shutil
4
+ import stat
5
+ from collections.abc import Callable
6
+ from hashlib import sha256
7
+ from pathlib import Path
8
+ from tempfile import TemporaryDirectory, mkdtemp
9
+ from typing import BinaryIO
10
+
11
+ from pydantic import ValidationError
12
+
13
+ from ._manifest import (
14
+ MANIFEST_NAME,
15
+ PART_NAME_PATTERN,
16
+ Manifest,
17
+ Part,
18
+ validate_basename,
19
+ )
20
+
21
+ DEFAULT_CHUNK_SIZE = 20 * 1024**2
22
+ BUFFER_SIZE = 1024**2
23
+ PathLike = str | os.PathLike[str]
24
+
25
+
26
+ class IntegrityError(ValueError):
27
+ """The manifest or its declared file contents failed validation."""
28
+
29
+
30
+ def split(
31
+ source: PathLike,
32
+ output_dir: PathLike | None = None,
33
+ *,
34
+ chunk_size: int = DEFAULT_CHUNK_SIZE,
35
+ overwrite: bool = False,
36
+ ) -> Path:
37
+ """Split a file and return the directory containing its parts and manifest."""
38
+ if (
39
+ isinstance(chunk_size, bool)
40
+ or not isinstance(chunk_size, int)
41
+ or chunk_size < 1
42
+ ):
43
+ raise ValueError("chunk_size must be a positive integer in bytes")
44
+
45
+ source = Path(source)
46
+ if not stat.S_ISREG(source.stat().st_mode):
47
+ raise ValueError(f"expected a regular source file: {source}")
48
+ validate_basename(source.name)
49
+
50
+ destination = (
51
+ Path(output_dir)
52
+ if output_dir is not None
53
+ else source.with_name(f"{source.name}.parts")
54
+ )
55
+ if not destination.name or destination.name == "..":
56
+ raise ValueError(f"expected a named output directory: {destination}")
57
+ if not overwrite and os.path.lexists(destination):
58
+ raise FileExistsError(f"output directory already exists: {destination}")
59
+ if source.resolve().is_relative_to(destination.resolve()):
60
+ raise ValueError("the output directory cannot contain the source file")
61
+
62
+ destination.parent.mkdir(parents=True, exist_ok=True)
63
+ with TemporaryDirectory(
64
+ dir=destination.parent, prefix=".file-split-kit-", ignore_cleanup_errors=True
65
+ ) as work:
66
+ staging = Path(work) / "parts"
67
+ staging.mkdir()
68
+ _write_parts(source, staging, chunk_size)
69
+ _publish_parts(staging, destination, overwrite)
70
+
71
+ return destination
72
+
73
+
74
+ def merge(
75
+ parts_dir: PathLike,
76
+ output: PathLike | None = None,
77
+ *,
78
+ overwrite: bool = False,
79
+ ) -> Path:
80
+ """Verify and restore a file, then return the restored file's path."""
81
+ directory = Path(parts_dir)
82
+ manifest = _read_manifest(directory)
83
+ destination = (
84
+ Path(output)
85
+ if output is not None
86
+ else directory.parent / manifest.original_name
87
+ )
88
+ if destination.parent.resolve() == directory.resolve() and (
89
+ destination.name == MANIFEST_NAME
90
+ or any(part.name == destination.name for part in manifest.parts)
91
+ ):
92
+ raise ValueError(
93
+ f"output would replace a file required for merging: {destination}"
94
+ )
95
+ if not overwrite and os.path.lexists(destination):
96
+ raise FileExistsError(f"output file already exists: {destination}")
97
+
98
+ destination.parent.mkdir(parents=True, exist_ok=True)
99
+ with TemporaryDirectory(
100
+ dir=destination.parent, prefix=".file-split-kit-", ignore_cleanup_errors=True
101
+ ) as work:
102
+ path = Path(work) / "output"
103
+ with path.open("wb") as writer:
104
+ _verify_parts(directory, manifest, writer)
105
+ path.replace(destination)
106
+
107
+ return destination
108
+
109
+
110
+ def verify(parts_dir: PathLike) -> None:
111
+ """Verify every declared part and the reconstructed file without writing it."""
112
+ directory = Path(parts_dir)
113
+ _verify_parts(directory, _read_manifest(directory), None)
114
+
115
+
116
+ def _transfer(
117
+ reader: BinaryIO,
118
+ writer: BinaryIO | None,
119
+ limit: int,
120
+ update_total: Callable[[bytes], None],
121
+ ) -> tuple[int, str]:
122
+ digest = sha256()
123
+ size = 0
124
+ while size < limit:
125
+ block = reader.read(min(BUFFER_SIZE, limit - size))
126
+ if not block:
127
+ break
128
+ if writer is not None:
129
+ writer.write(block)
130
+ size += len(block)
131
+ digest.update(block)
132
+ update_total(block)
133
+
134
+ return size, digest.hexdigest()
135
+
136
+
137
+ def _write_parts(source: Path, directory: Path, chunk_size: int) -> None:
138
+ digest = sha256()
139
+ original_size = 0
140
+ parts: list[Part] = []
141
+ with source.open("rb") as reader:
142
+ while reader.peek(1):
143
+ name = f"part-{len(parts) + 1:06d}.chunk"
144
+ with (directory / name).open("wb") as writer:
145
+ size, part_sha256 = _transfer(reader, writer, chunk_size, digest.update)
146
+ original_size += size
147
+ parts.append(Part(name=name, size=size, sha256=part_sha256))
148
+
149
+ manifest = Manifest(
150
+ original_name=source.name,
151
+ original_size=original_size,
152
+ original_sha256=digest.hexdigest(),
153
+ parts=parts,
154
+ )
155
+ (directory / MANIFEST_NAME).write_bytes(
156
+ (manifest.model_dump_json(indent=2) + "\n").encode("utf-8")
157
+ )
158
+
159
+
160
+ def _open_package_file(path: Path) -> BinaryIO:
161
+ try:
162
+ if not stat.S_ISREG(path.lstat().st_mode):
163
+ raise IntegrityError(f"expected a regular file: {path}")
164
+ return path.open("rb")
165
+ except OSError as exc:
166
+ raise IntegrityError(f"cannot open {path}: {exc.strerror}") from exc
167
+
168
+
169
+ def _read_manifest(directory: Path) -> Manifest:
170
+ path = directory / MANIFEST_NAME
171
+ with _open_package_file(path) as reader:
172
+ data = reader.read()
173
+ try:
174
+ return Manifest.model_validate_json(data)
175
+ except ValidationError as exc:
176
+ raise IntegrityError(f"invalid manifest {path}\n{exc}") from exc
177
+
178
+
179
+ def _verify_parts(directory: Path, manifest: Manifest, writer: BinaryIO | None) -> None:
180
+ digest = sha256()
181
+ for part in manifest.parts:
182
+ with _open_package_file(directory / part.name) as reader:
183
+ size, part_sha256 = _transfer(reader, writer, part.size, digest.update)
184
+ if size != part.size or reader.read(1):
185
+ raise IntegrityError(f"size mismatch for {part.name}")
186
+ if part_sha256 != part.sha256:
187
+ raise IntegrityError(f"SHA-256 mismatch for {part.name}")
188
+
189
+ if digest.hexdigest() != manifest.original_sha256:
190
+ raise IntegrityError("SHA-256 mismatch for the complete file")
191
+
192
+
193
+ def _publish_parts(staging: Path, destination: Path, overwrite: bool) -> None:
194
+ if not os.path.lexists(destination):
195
+ staging.rename(destination)
196
+ return
197
+ if not overwrite or not stat.S_ISDIR(destination.lstat().st_mode):
198
+ raise FileExistsError(f"output path already exists: {destination}")
199
+
200
+ has_manifest = False
201
+ for entry in destination.iterdir():
202
+ if not stat.S_ISREG(entry.lstat().st_mode) or (
203
+ entry.name != MANIFEST_NAME
204
+ and re.fullmatch(PART_NAME_PATTERN, entry.name) is None
205
+ ):
206
+ raise FileExistsError(f"unexpected file in output directory: {entry}")
207
+ if entry.name == MANIFEST_NAME:
208
+ has_manifest = True
209
+ if not has_manifest:
210
+ raise FileExistsError(
211
+ f"output directory is missing {MANIFEST_NAME}: {destination}"
212
+ )
213
+
214
+ backup = Path(mkdtemp(dir=destination.parent, prefix=".file-split-kit-backup-"))
215
+ previous = backup / "parts"
216
+ try:
217
+ destination.rename(previous)
218
+ staging.rename(destination)
219
+ except BaseException:
220
+ if previous.exists():
221
+ previous.rename(destination)
222
+ shutil.rmtree(backup, ignore_errors=True)
223
+ raise
224
+ shutil.rmtree(backup, ignore_errors=True)
@@ -0,0 +1,59 @@
1
+ from typing import Annotated
2
+
3
+ from pydantic import (
4
+ AfterValidator,
5
+ BaseModel,
6
+ ConfigDict,
7
+ NonNegativeInt,
8
+ PositiveInt,
9
+ StringConstraints,
10
+ model_validator,
11
+ )
12
+
13
+ MANIFEST_NAME = "manifest.json"
14
+ PART_NAME_PATTERN = r"^part-[0-9]{6,}\.chunk$"
15
+
16
+
17
+ def validate_basename(value: str) -> str:
18
+ if not value or value in {".", ".."} or any(char in value for char in "/\\:\0"):
19
+ raise ValueError("must be a plain filename")
20
+ return value
21
+
22
+
23
+ Basename = Annotated[str, AfterValidator(validate_basename)]
24
+ PartName = Annotated[str, StringConstraints(pattern=PART_NAME_PATTERN)]
25
+ SHA256 = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{64}$")]
26
+
27
+
28
+ class Part(BaseModel):
29
+ model_config = ConfigDict(strict=True, extra="forbid")
30
+
31
+ name: PartName
32
+ size: PositiveInt
33
+ sha256: SHA256
34
+
35
+
36
+ class Manifest(BaseModel):
37
+ model_config = ConfigDict(strict=True, extra="forbid")
38
+
39
+ original_name: Basename
40
+ original_size: NonNegativeInt
41
+ original_sha256: SHA256
42
+ parts: list[Part]
43
+
44
+ @model_validator(mode="after")
45
+ def validate_parts(self) -> "Manifest":
46
+ names: set[str] = set()
47
+ total_size = 0
48
+ for part in self.parts:
49
+ if part.name in names:
50
+ raise ValueError(f"duplicate part name: {part.name}")
51
+ names.add(part.name)
52
+ total_size += part.size
53
+
54
+ if total_size != self.original_size:
55
+ raise ValueError(
56
+ f"parts sizes total {total_size}, expected {self.original_size}"
57
+ )
58
+
59
+ return self
@@ -0,0 +1,52 @@
1
+ Metadata-Version: 2.5
2
+ Name: file-split-kit
3
+ Version: 0.1.0
4
+ Summary: Split, verify, and restore large files using JSON manifests and SHA-256.
5
+ Project-URL: Repository, https://github.com/fishyy119/file-split-kit
6
+ Project-URL: Documentation, https://github.com/fishyy119/file-split-kit#readme
7
+ Project-URL: Issues, https://github.com/fishyy119/file-split-kit/issues
8
+ Author-email: fishyy119 <fishyy109@foxmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: file chunking,file integrity,file merging,file splitting,large files,sha256
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Topic :: Utilities
17
+ Requires-Python: >=3.10
18
+ Requires-Dist: pydantic<3,>=2
19
+ Description-Content-Type: text/markdown
20
+
21
+ # file-split-kit
22
+
23
+ ![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)
24
+
25
+ 将大文件按固定大小拆分,并根据 JSON 清单逐字节还原。校验涵盖每个分块和完整文件的大小及 SHA-256。
26
+
27
+ ## 命令行
28
+
29
+ ```sh
30
+ file-split-kit split archive.bin
31
+ file-split-kit verify archive.bin.parts
32
+ file-split-kit merge archive.bin.parts --output archive.restored.bin
33
+ ```
34
+
35
+ `split` 默认每块最多 20 MiB,在原文件旁生成 `<原文件名>.parts/`,内含 `manifest.json` 和分块。用 `--chunk-size BYTES` 调整上限,或用 `--output-dir PATH` 指定分块目录。
36
+
37
+ `verify` 只做校验。`merge` 默认在分块目录同级以原文件名还原,也可用 `--output PATH` 指定目标。`split` 和 `merge` 会自动创建缺失的父目录,覆盖已有结果需显式指定 `--overwrite`。
38
+
39
+ > [!NOTE]
40
+ > 如果将分块提交到 Git 仓库,需要在 `.gitattributes` 中加入 `*.chunk -text -merge`,关闭换行转换和逐行合并,保留分块的原始字节。
41
+
42
+ ## Python API
43
+
44
+ ```python
45
+ from file_split_kit import merge, split, verify
46
+
47
+ parts_dir = split("archive.bin")
48
+ verify(parts_dir)
49
+ restored = merge(parts_dir, "archive.restored.bin")
50
+ ```
51
+
52
+ `split` 和 `merge` 返回输出路径。清单或分块校验失败时抛出 `file_split_kit.IntegrityError`。
@@ -0,0 +1,10 @@
1
+ file_split_kit/__init__.py,sha256=ubqGg44I_u9J_S6nyfNT9G5zcEcnzled67WntdhOTbg,178
2
+ file_split_kit/__main__.py,sha256=Uopa9kP0x57Hia6OojVeeTX1C4MHsuXr-cYNLOoBFdE,80
3
+ file_split_kit/_cli.py,sha256=UHt0u80hK8qIjNRE1gblF385vGMeEdAvmmqmyKfOrck,2255
4
+ file_split_kit/_core.py,sha256=5ChUFIBwM5J0s2NoYP4j3NWNZJOSSx4s8MbU4vtoH_Q,7423
5
+ file_split_kit/_manifest.py,sha256=noHcazoPzqgmdbW3f9kXumKjEvGbqmIRmvwe9ouuwds,1550
6
+ file_split_kit-0.1.0.dist-info/METADATA,sha256=ANJpBtYU6F65LV6UTHSEkpWUBltqhMMbxUTecCwSsQ8,2156
7
+ file_split_kit-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
8
+ file_split_kit-0.1.0.dist-info/entry_points.txt,sha256=kKo2B201rn1ieZdRsp3ycuQWHv5yba1QcGM0XjIQyY8,60
9
+ file_split_kit-0.1.0.dist-info/licenses/LICENSE,sha256=i2NrWe5xAunNhjMEnYkoDHHdterUnyiepNh1shXKS2Y,1066
10
+ file_split_kit-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ file-split-kit = file_split_kit._cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 fishyy119
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.