torram-ng 2.0.0__tar.gz

torram_ng-2.0.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

torram_ng-2.0.0/NOTICE

@@ -0,0 +1,12 @@
+torram-ng
+Copyright 2026 Brian K
+
+This product includes software originally developed as "torram"
+(formerly "torrent-upstart") by Volodymyr Buell:
+
+    https://github.com/vbuell/torram
+
+The original project was published without a license file. The Apache
+License 2.0 in this repository covers contributions made to this fork.
+See https://github.com/kanya-approve/torram-ng/issues for the tracking
+issue on resolving the upstream licensing status.

torram_ng-2.0.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: torram-ng
+Version: 2.0.0
+Summary: Recover torrent data by reconstructing files from fully and partially downloaded sources
+Keywords: torrent,bittorrent,recovery,data-recovery,salvage
+Author: Brian K
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: File Sharing
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: System :: Recovery Tools
+Requires-Dist: bencode-py>=4.0
+Maintainer: Brian K
+Requires-Python: >=3.8
+Project-URL: Homepage, https://github.com/kanya-approve/torram-ng
+Project-URL: Repository, https://github.com/kanya-approve/torram-ng
+Project-URL: Issues, https://github.com/kanya-approve/torram-ng/issues
+Description-Content-Type: text/markdown
+
+# torram-ng
+
+Recover torrent data by reconstructing files from fully and partially downloaded sources.
+
+Given a `.torrent` file and one or more directories containing incomplete copies of its
+contents, torram-ng identifies which pieces are intact by checking them against the piece
+hashes in the torrent, and rebuilds the most complete output it can from what it finds.
+
+If you have two dead torrents of the same release — one 75% done, the other 85% — the pieces
+you are missing from one may be present in the other. Combined, they can add up to a complete
+file.
+
+> **Status: early.** This is a modernization of the unmaintained
+> [`vbuell/torram`](https://github.com/vbuell/torram). This release makes the project
+> installable, tested and continuously integrated; **the recovery engine itself is still the
+> original 0.9.0 code and has known correctness defects.** Read
+> [Known limitations](#known-limitations) before trusting it with anything you care about.
+
+## Install
+
+```sh
+uv tool install git+https://github.com/kanya-approve/torram-ng
+```
+
+Or run it once without installing:
+
+```sh
+uvx --from git+https://github.com/kanya-approve/torram-ng torram-ng --help
+```
+
+Both `torram-ng` and `torram` are installed as commands. Python 3.8 or newer.
+
+## Usage
+
+```
+torram-ng [-h] [--symlink] [--minsize MINSIZE] [-v] [-o OUTPUT_DIR] [-a]
+          [-c] [-s] [--fileext FILE_EXT] [--version]
+          torrentFile root
+```
+
+| Argument | Meaning |
+|---|---|
+| `torrentFile` | the `.torrent` to analyze |
+| `root` | directory to search recursively for candidate files |
+| `-o`, `--output_dir` | where to write recovered files (**required in practice**, see limitations) |
+| `--minsize` | smallest file size to consider, in bytes. Defaults to 1 MiB, which silently excludes smaller files — pass `--minsize 0` |
+| `-s`, `--autoskip` | skip prompting when there is only one option; `-ss` automates further |
+| `-v`, `--verbose` | repeat for more detail (`-vv`, `-vvv`) |
+| `-c`, `--use_color` | ANSI colour output |
+| `--fileext` | suffix to append to output files, e.g. `.!qB` for incomplete qBittorrent files |
+
+Example — scan two drives and rebuild into `./recovered`:
+
+```sh
+torram-ng show.torrent /mnt/disk1 -o ./recovered --minsize 0 -ss
+```
+
+After recovery, run a **force recheck** in your torrent client so it notices the files changed.
+
+## How it works
+
+A torrent describes its contents as one continuous byte stream, split into fixed-size pieces.
+Each piece has a **SHA-1** hash stored in the `.torrent`. torram-ng walks the search directory,
+picks out files whose size matches a file in the torrent, and hashes their pieces to find which
+ones are intact. Where several sources each hold different good pieces, it can combine them.
+
+## Known limitations
+
+These are inherited from the original implementation and are tracked as
+[issues](https://github.com/kanya-approve/torram-ng/issues). The most significant:
+
+- **Pieces spanning file boundaries never verify.** In a multi-file torrent, a piece that
+  straddles two files is read from only the first one, so it always fails. Even a perfect,
+  complete source reports missing pieces. ([#3](https://github.com/kanya-approve/torram-ng/issues/3))
+- **Files with no attributable piece default to being skipped.** A file that fits entirely
+  inside a piece beginning in an earlier file gets no piece assigned to it, so it is reported
+  `[0 of 0] (Bad)` and the suggested action is Skip. Interactively you can override this by
+  choosing a candidate number; under `-s`/`-ss` it is dropped without prompting. On a real
+  torrent this is not rare — 7 of the 12 files in Big Buck Bunny are affected.
+  ([#3](https://github.com/kanya-approve/torram-ng/issues/3),
+  [#11](https://github.com/kanya-approve/torram-ng/issues/11))
+- **The merge path writes pieces at incorrect offsets** and never verifies the result, so
+  combining sources can produce a corrupt file that reports success.
+  ([#1](https://github.com/kanya-approve/torram-ng/issues/1))
+- **Scanning several drives can lose candidates**, because hardlink de-duplication keys on the
+  inode number without the device. ([#6](https://github.com/kanya-approve/torram-ng/issues/6))
+- **`--minsize` defaults to 1 MiB**, so small-file torrents recover nothing unless you pass
+  `--minsize 0`. ([#14](https://github.com/kanya-approve/torram-ng/issues/14))
+- **`--symlink` does nothing** — it is parsed but never implemented.
+  ([#17](https://github.com/kanya-approve/torram-ng/issues/17))
+- **`-a` / `--autodetect_output_dir` cannot work**; it needs PyQt4, which has no Python 3 build.
+  ([#18](https://github.com/kanya-approve/torram-ng/issues/18))
+- **Performance does not scale.** The verification loop is roughly
+  `candidates × pieces × files`, so large or many-file torrents are impractically slow.
+  ([#21](https://github.com/kanya-approve/torram-ng/issues/21))
+- Only BitTorrent v1 is supported. v2 and hybrid torrents are untested.
+
+A [rewrite of the core](https://github.com/kanya-approve/torram-ng/issues/28) around a global
+piece model is planned; it addresses most of the above structurally rather than one at a time.
+
+The tool only ever reads from the directories you point it at, and writes solely to the output
+directory. It does not modify your sources.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run pytest
+uv run ruff check
+uv run ruff format --check
+```
+
+Tests generate their own torrents and content deterministically, so nothing large is committed.
+Two real torrents are included as parse-only fixtures — see [`tests/data/README.md`](tests/data/README.md).
+
+Known bugs are covered by `xfail(strict=True)` tests referencing their issue number. They keep
+CI green while documenting each defect as executable behaviour; when one is fixed its test
+starts failing, which is the signal to remove the marker.
+
+## Credits
+
+Originally written by Volodymyr Buell as
+[torram](https://github.com/vbuell/torram) (formerly torrent-upstart). See [NOTICE](NOTICE).
+
+## License
+
+[Apache-2.0](LICENSE). Note that the upstream project was published without a license; see
+[#29](https://github.com/kanya-approve/torram-ng/issues/29).

torram_ng-2.0.0/README.md

@@ -0,0 +1,128 @@
+# torram-ng
+
+Recover torrent data by reconstructing files from fully and partially downloaded sources.
+
+Given a `.torrent` file and one or more directories containing incomplete copies of its
+contents, torram-ng identifies which pieces are intact by checking them against the piece
+hashes in the torrent, and rebuilds the most complete output it can from what it finds.
+
+If you have two dead torrents of the same release — one 75% done, the other 85% — the pieces
+you are missing from one may be present in the other. Combined, they can add up to a complete
+file.
+
+> **Status: early.** This is a modernization of the unmaintained
+> [`vbuell/torram`](https://github.com/vbuell/torram). This release makes the project
+> installable, tested and continuously integrated; **the recovery engine itself is still the
+> original 0.9.0 code and has known correctness defects.** Read
+> [Known limitations](#known-limitations) before trusting it with anything you care about.
+
+## Install
+
+```sh
+uv tool install git+https://github.com/kanya-approve/torram-ng
+```
+
+Or run it once without installing:
+
+```sh
+uvx --from git+https://github.com/kanya-approve/torram-ng torram-ng --help
+```
+
+Both `torram-ng` and `torram` are installed as commands. Python 3.8 or newer.
+
+## Usage
+
+```
+torram-ng [-h] [--symlink] [--minsize MINSIZE] [-v] [-o OUTPUT_DIR] [-a]
+          [-c] [-s] [--fileext FILE_EXT] [--version]
+          torrentFile root
+```
+
+| Argument | Meaning |
+|---|---|
+| `torrentFile` | the `.torrent` to analyze |
+| `root` | directory to search recursively for candidate files |
+| `-o`, `--output_dir` | where to write recovered files (**required in practice**, see limitations) |
+| `--minsize` | smallest file size to consider, in bytes. Defaults to 1 MiB, which silently excludes smaller files — pass `--minsize 0` |
+| `-s`, `--autoskip` | skip prompting when there is only one option; `-ss` automates further |
+| `-v`, `--verbose` | repeat for more detail (`-vv`, `-vvv`) |
+| `-c`, `--use_color` | ANSI colour output |
+| `--fileext` | suffix to append to output files, e.g. `.!qB` for incomplete qBittorrent files |
+
+Example — scan two drives and rebuild into `./recovered`:
+
+```sh
+torram-ng show.torrent /mnt/disk1 -o ./recovered --minsize 0 -ss
+```
+
+After recovery, run a **force recheck** in your torrent client so it notices the files changed.
+
+## How it works
+
+A torrent describes its contents as one continuous byte stream, split into fixed-size pieces.
+Each piece has a **SHA-1** hash stored in the `.torrent`. torram-ng walks the search directory,
+picks out files whose size matches a file in the torrent, and hashes their pieces to find which
+ones are intact. Where several sources each hold different good pieces, it can combine them.
+
+## Known limitations
+
+These are inherited from the original implementation and are tracked as
+[issues](https://github.com/kanya-approve/torram-ng/issues). The most significant:
+
+- **Pieces spanning file boundaries never verify.** In a multi-file torrent, a piece that
+  straddles two files is read from only the first one, so it always fails. Even a perfect,
+  complete source reports missing pieces. ([#3](https://github.com/kanya-approve/torram-ng/issues/3))
+- **Files with no attributable piece default to being skipped.** A file that fits entirely
+  inside a piece beginning in an earlier file gets no piece assigned to it, so it is reported
+  `[0 of 0] (Bad)` and the suggested action is Skip. Interactively you can override this by
+  choosing a candidate number; under `-s`/`-ss` it is dropped without prompting. On a real
+  torrent this is not rare — 7 of the 12 files in Big Buck Bunny are affected.
+  ([#3](https://github.com/kanya-approve/torram-ng/issues/3),
+  [#11](https://github.com/kanya-approve/torram-ng/issues/11))
+- **The merge path writes pieces at incorrect offsets** and never verifies the result, so
+  combining sources can produce a corrupt file that reports success.
+  ([#1](https://github.com/kanya-approve/torram-ng/issues/1))
+- **Scanning several drives can lose candidates**, because hardlink de-duplication keys on the
+  inode number without the device. ([#6](https://github.com/kanya-approve/torram-ng/issues/6))
+- **`--minsize` defaults to 1 MiB**, so small-file torrents recover nothing unless you pass
+  `--minsize 0`. ([#14](https://github.com/kanya-approve/torram-ng/issues/14))
+- **`--symlink` does nothing** — it is parsed but never implemented.
+  ([#17](https://github.com/kanya-approve/torram-ng/issues/17))
+- **`-a` / `--autodetect_output_dir` cannot work**; it needs PyQt4, which has no Python 3 build.
+  ([#18](https://github.com/kanya-approve/torram-ng/issues/18))
+- **Performance does not scale.** The verification loop is roughly
+  `candidates × pieces × files`, so large or many-file torrents are impractically slow.
+  ([#21](https://github.com/kanya-approve/torram-ng/issues/21))
+- Only BitTorrent v1 is supported. v2 and hybrid torrents are untested.
+
+A [rewrite of the core](https://github.com/kanya-approve/torram-ng/issues/28) around a global
+piece model is planned; it addresses most of the above structurally rather than one at a time.
+
+The tool only ever reads from the directories you point it at, and writes solely to the output
+directory. It does not modify your sources.
+
+## Development
+
+```sh
+uv sync --all-groups
+uv run pytest
+uv run ruff check
+uv run ruff format --check
+```
+
+Tests generate their own torrents and content deterministically, so nothing large is committed.
+Two real torrents are included as parse-only fixtures — see [`tests/data/README.md`](tests/data/README.md).
+
+Known bugs are covered by `xfail(strict=True)` tests referencing their issue number. They keep
+CI green while documenting each defect as executable behaviour; when one is fixed its test
+starts failing, which is the signal to remove the marker.
+
+## Credits
+
+Originally written by Volodymyr Buell as
+[torram](https://github.com/vbuell/torram) (formerly torrent-upstart). See [NOTICE](NOTICE).
+
+## License
+
+[Apache-2.0](LICENSE). Note that the upstream project was published without a license; see
+[#29](https://github.com/kanya-approve/torram-ng/issues/29).

torram_ng-2.0.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "torram-ng"
+version = "2.0.0"
+description = "Recover torrent data by reconstructing files from fully and partially downloaded sources"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "Apache-2.0"
+license-files = [
+    "LICENSE",
+    "NOTICE",
+]
+keywords = [
+    "torrent",
+    "bittorrent",
+    "recovery",
+    "data-recovery",
+    "salvage",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Communications :: File Sharing",
+    "Topic :: System :: Archiving",
+    "Topic :: System :: Recovery Tools",
+]
+dependencies = ["bencode.py>=4.0"]
+
+[[project.authors]]
+name = "Brian K"
+
+[[project.maintainers]]
+name = "Brian K"
+
+[project.urls]
+Homepage = "https://github.com/kanya-approve/torram-ng"
+Repository = "https://github.com/kanya-approve/torram-ng"
+Issues = "https://github.com/kanya-approve/torram-ng/issues"
+
+[project.scripts]
+torram-ng = "torram_ng.cli:main"
+torram = "torram_ng.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[tool.uv.build-backend]
+module-name = "torram_ng"
+module-root = "src"
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config -m 'not network'"
+xfail_strict = true
+markers = ["network: fetches real torrent content over HTTPS; deselected by default, run with -m network"]
+
+[tool.ruff]
+target-version = "py38"
+line-length = 120
+src = [
+    "src",
+    "tests",
+]
+extend-exclude = ["src/torram_ng/cli.py"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "UP",
+    "B",
+    "C4",
+    "PIE",
+    "RUF",
+]

torram_ng-2.0.0/pyproject.toml.orig

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "torram-ng"
+version = "2.0.0"
+description = "Recover torrent data by reconstructing files from fully and partially downloaded sources"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Brian K" }]
+maintainers = [{ name = "Brian K" }]
+keywords = ["torrent", "bittorrent", "recovery", "data-recovery", "salvage"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Communications :: File Sharing",
+    "Topic :: System :: Archiving",
+    "Topic :: System :: Recovery Tools",
+]
+dependencies = ["bencode.py>=4.0"]
+
+[project.urls]
+Homepage = "https://github.com/kanya-approve/torram-ng"
+Repository = "https://github.com/kanya-approve/torram-ng"
+Issues = "https://github.com/kanya-approve/torram-ng/issues"
+
+[project.scripts]
+torram-ng = "torram_ng.cli:main"
+torram = "torram_ng.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[tool.uv.build-backend]
+module-name = "torram_ng"
+module-root = "src"
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config -m 'not network'"
+xfail_strict = true
+markers = [
+    "network: fetches real torrent content over HTTPS; deselected by default, run with -m network",
+]
+
+[tool.ruff]
+target-version = "py38"
+line-length = 120
+src = ["src", "tests"]
+# cli.py is the original torram 0.9.0 script, vendored near-verbatim so the diff
+# against upstream stays reviewable. Its defects are tracked as issues and will be
+# resolved by the rewrite, not by lint churn. Excluded from both lint and format.
+extend-exclude = ["src/torram_ng/cli.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "PIE", "RUF"]

torram_ng-2.0.0/src/torram_ng/__init__.py

@@ -0,0 +1,10 @@
+"""torram-ng: recover torrent data from fully and partially downloaded files."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("torram-ng")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0+unknown"
+
+__all__ = ["__version__"]

torram_ng-2.0.0/src/torram_ng/cli.py

@@ -0,0 +1,410 @@
+import functools
+import hashlib
+import io
+import os
+import re
+import shutil
+import stat
+import sys
+import tempfile
+import bencode
+
+from torram_ng import __version__ as VERSION
+
+
+DELUGE_DIR = '~/.config/deluge/state'
+QBITTORRENT_RESUME_CONF = '~/.config/qBittorrent/qBittorrent-resume.conf'
+FILES_DIR = '~'
+MINIMUM_FILESIZE_TO_SEARCH = 1024 * 1024
+
+
+class AnsiFormatter(object):
+    aaa = {'RED': "\033[31m",
+           'BOLD': "\033[1m",
+           'YELLOW': "\033[33m",
+           'INVERT': "\033[40m\033[37m",
+           'GREEN': "\033[32m",
+           'BLUE': "\033[34m",
+           'BLACK2': "\033[90m",
+           'BLACK1': "\033[37m",
+           'BLACK0': "\033[97m",
+           }
+
+    def format(self, txt, *code):
+        return ''.join([self.aaa[c] for c in code]) + txt + "\033[0m"
+
+
+class BaseFormatter(object):
+    def format(self, txt, *code):
+        return txt
+
+
+fmt = BaseFormatter()
+args = None
+
+
+class FileInfo():
+    def __init__(self):
+        self.start_offset = None
+        self.isOriginal = False
+        self.isHardlink = False
+
+
+def suggest_method(file_infos):
+    fullest_file_idx = None
+    fullest_file_rate = 0
+    downladed_file_rate = 0
+    mixed_pieces = []
+
+    # calculate per file
+    for idx, file_info in enumerate(file_infos):
+        if len(file_info.chunks) == 0:
+            return 'S'
+        num_of_success = file_info.num_of_good_chunks
+        rate = float(num_of_success) / len(file_info.chunks)
+        if file_info.isOriginal:
+            downladed_file_rate = rate
+        if rate > fullest_file_rate:
+            fullest_file_rate = rate
+            fullest_file_idx = idx
+
+    # calculate mixed
+    if len(file_infos) > 1:
+        for aa in zip(*[fi.chunks for fi in file_infos]):
+    #        print aa, type(aa), any(aa)
+            mixed_pieces.append(any(aa))
+        num_of_success = functools.reduce(lambda x, y: x + int(y), mixed_pieces, 0)
+
+        if float(num_of_success) / len(mixed_pieces) > fullest_file_rate:
+            pattern = 'Got [{0} of {1} good pieces from {2} files.'
+            print(fmt.format(pattern.format(num_of_success, len(mixed_pieces), len(file_infos)), 'RED', 'BOLD'))
+            return 'M'
+
+    if downladed_file_rate >= fullest_file_rate:
+        return 'S'
+    return str(fullest_file_idx)
+
+
+def get_similatity_rate_and_color(success_blocks, all_blocks):
+    if all_blocks == 0:
+        return 'BLACK2', 'Bad'
+
+    rate = float(success_blocks) / all_blocks
+    if rate > 0.9:
+        return 'GREEN', 'Excellent'
+    if rate > 0.5:
+        return 'YELLOW', 'Good'
+    if rate > 0.01:
+        return 'YELLOW', 'Poor'
+    else:
+        return 'BLACK2', 'Bad'
+
+
+def get_file_sizes(info):
+    global args
+    if 'files' in info:     # yield pieces from a multi-file torrent
+        return [fi['length'] for fi in info['files'] if fi['length'] > int(args.minsize)]
+    else:       # yield pieces from a single file torrent
+        return [info['length']]
+
+
+def get_possible_files(rootdir, sizes):
+    """Find duplicate files in directory tree."""
+    filesizes = {}
+    # Build up dict with key as filesize and value is list of filenames.
+    for path, dirs, files in os.walk(rootdir):
+        for filename in files:
+            filepath = os.path.join(path, filename)
+            filesize = os.lstat(filepath).st_size
+            if args.verbose >= 2:
+              print("File registered: %s (%d bytes)" % (filepath, filesize))
+            if filesize in sizes:
+                filesizes.setdefault(filesize, []).append(filepath)
+    return filesizes
+
+
+def remove_hard_links(files):
+    inode_to_filename = {}
+    for filename in files:
+        stat_info = os.stat(filename)
+        inode_to_filename[stat_info[stat.ST_INO]] = filename
+    return inode_to_filename.values()
+
+
+def load_qbittorrent_conf(hash):
+    """Load qBittorrent settings."""
+    from PyQt4 import QtCore
+
+    settings = QtCore.QSettings(os.path.expanduser(QBITTORRENT_RESUME_CONF), QtCore.QSettings.IniFormat)
+
+    root = settings.value('torrents').toPyObject()
+    record = root[QtCore.QString(hash)]
+    path = record[QtCore.QString('save_path')]
+
+    if isinstance(path, QtCore.QString):
+        path = str(path)
+
+    return path
+
+
+def check_file_chunk(hash, offset, length, filename):
+    with open(filename, "rb") as sfile:
+        sfile.seek(offset)
+        piece = sfile.read(length)
+
+        piece_hash = hashlib.sha1(piece).digest()
+        return piece_hash == hash
+
+
+def get_chunk(filesizes, global_offset):
+    """
+    Returns file offset using global continuous file
+
+    >>> get_chunk([], 0)
+    (0, 0)
+    >>> get_chunk([100], 0)
+    (0, 0)
+    >>> get_chunk([100], 100)
+    (0, 0)
+    >>> get_chunk([50,50,30], 100)
+    (2, 0)
+    """
+    file_offset = 0
+    file_idx = 0
+
+    # Find file idx
+    for filesize in filesizes:
+        if file_offset + filesize > global_offset:
+            break
+
+        file_offset += filesize
+        file_idx += 1
+
+    return (file_idx, global_offset - file_offset)
+
+
+def construct_file(file_infos, piece_length, dest_filename):
+    # TODO: Get biggest file
+    max_num_of_good_chunks = max(fi.num_of_good_chunks for fi in file_infos)
+    biggest_file = next(fi for fi in file_infos if fi.num_of_good_chunks == max_num_of_good_chunks)
+
+    f = tempfile.NamedTemporaryFile(mode='w+b', delete=False)
+    file_name = f.name
+    print("Temporary file:", file_name)
+    f.close()
+    print("Copy file: ", biggest_file.path)
+    shutil.copy(biggest_file.path, f.name)
+
+    if len(file_infos) > 1:
+        with open(file_name, 'r+b') as f:
+            for chunk_idx, chunks_merged in enumerate(zip(*[fi.chunks for fi in file_infos])):
+                for i, p in enumerate(chunks_merged):
+                    if p:
+                        # copy chunk from and to (file_offset, piece_length)
+                        file_info = file_infos[i]
+                        src = open(file_info.path, 'rb')
+                        src.seek(file_info.start_offset + chunk_idx * piece_length)
+                        f.seek(file_info.start_offset + chunk_idx * piece_length)
+                        f.write(src.read(piece_length))
+                        src.close()
+                        break
+
+    print("Move temporary file to ", dest_filename)
+    shutil.move(file_name, dest_filename)
+
+
+def ensure_dir_exists(f):
+    d = os.path.dirname(f)
+    if not os.path.exists(d):
+        os.makedirs(d)
+
+
+def guess_file(file_info, file_idx, files, pieces, piece_length, files_sizes_array, basedir):
+    global args
+    global fmt
+    global save_path
+
+    if 'path' in file_info:
+        file_name = os.path.join(*file_info['path'])
+    else:
+        file_name = file_info['name']
+
+    file_length = file_info['length']
+    destination_path = os.path.join(save_path, basedir, file_name)
+
+    if file_length in files:
+        print("Processing file: " + fmt.format(str(file_name), 'BLUE', 'BOLD'))
+        file_infos = []
+
+        add_incomplete_file_with_different_size(destination_path, files[file_length])
+
+        if args.autoskip and len(files[file_length]) < 2 and \
+                max(file.startswith(destination_path) for file in files[file_length]):
+            print("Only one file found. Thus, skipping...")
+            return
+
+        uniq_filenames = remove_hard_links(files[file_length])
+
+        for file_number, file in enumerate(files[file_length]):
+            file_info = FileInfo()
+            file_info.path = file
+
+            if file.startswith(destination_path):
+                number_to_show = ' * '
+                file_info.isOriginal = True
+            else:
+                number_to_show = ' ' + str(file_number) + ' '
+            if file in uniq_filenames:
+                pieces.seek(0)
+                sys.stdout.write(fmt.format(number_to_show, 'BLACK0', 'BOLD') + str(file))
+
+                num_of_checks = 0
+                num_of_successes = 0
+                offset = 0
+                pieces_list = []
+                while True:
+                    hash = pieces.read(20)
+                    if not hash:
+                        break
+                    idx, file_offset = get_chunk(files_sizes_array, offset * piece_length)
+                    if not file_info.start_offset:
+                        file_info.start_offset = file_offset
+
+                    if idx == file_idx:
+                        num_of_checks += 1
+                        hash_result = check_file_chunk(hash, file_offset, piece_length, file)
+                        pieces_list.append(hash_result)
+                        if hash_result:
+                            num_of_successes += 1
+
+                    offset += 1
+
+                file_info.chunks = pieces_list
+                file_info.num_of_good_chunks = num_of_successes
+                file_infos.append(file_info)
+
+                color_code, result_message = get_similatity_rate_and_color(num_of_successes, num_of_checks)
+                pattern = ' [{0} of {1}] ({2})'
+                print(fmt.format(pattern.format(num_of_successes, num_of_checks, result_message), color_code))
+            else:
+                sys.stdout.write(fmt.format(number_to_show, 'BLACK0', 'BOLD') + str(file) + " hardlink -> skipped\n")
+
+        suggestion = suggest_method(file_infos)
+        while True:
+            user_input = ''
+            if args.autoskip < 2 and not (suggestion == 'S' and args.autoskip > 0):
+                user_input = input(fmt.format('Choose file number or [S]kip/co[M]bine/[A]uto [<N>/S/M/A] ({0}) '.format(suggestion), 'INVERT'))
+
+            if user_input == '':
+                user_input = suggestion
+            if re.match('^[0-9]+$', user_input):
+                src_path = file_infos[int(user_input)].path
+                print('Copying:', destination_path, src_path)
+                ensure_dir_exists(destination_path)
+                shutil.copyfile(src_path, destination_path + args.file_ext)
+                break
+            elif user_input.upper() == 'M':
+                print('Creating mixed file from multiple sources')
+                ensure_dir_exists(destination_path)
+                construct_file(file_infos, piece_length, destination_path + args.file_ext)
+                break
+            elif user_input.upper() == 'S':
+                print('Skipping...')
+                break
+            elif user_input.upper() == 'A':
+                print('Autoselect default option')
+                args.autoskip = 2
+            else:
+                print('Mmmm?')
+
+    else:
+        if args.verbose > 0:
+            print("Skipping file: %s (%d bytes)" % (file_name, file_length))
+
+
+def add_incomplete_file_with_different_size(filepath, list):
+    if os.path.exists(filepath):
+        for filename in os.listdir(os.path.dirname(filepath)):
+            curr_filepath = os.path.join(os.path.dirname(filepath), filename)
+            if curr_filepath.startswith(filepath):
+                if curr_filepath not in list:
+                    list.append(curr_filepath)
+
+
+def run():
+    global args
+    global save_path
+
+    # Open torrent file
+    torrent_file = open(args.torrentfile, "rb")
+    metainfo = bencode.bdecode(torrent_file.read())
+    info = metainfo['info']
+    pieces = io.BytesIO(info['pieces'])
+
+    hash = hashlib.sha1(bencode.bencode(info)).hexdigest()
+    print("Hash:", hash)
+
+    sizes = get_file_sizes(info)
+    print('Sizes', sizes)
+
+    if args.autodetect_output_dir:
+        save_path = load_qbittorrent_conf(hash)
+        print(save_path)
+    else:
+        save_path = args.output_dir
+
+    # Get possible files
+    print('Searching for file pretenders...')
+    files = get_possible_files(os.path.expanduser(args.root), sizes)
+
+    # Check files one by one
+    if 'files' in info:
+        files_sizes_array = [f['length'] for f in info['files']]
+        file_idx = 0
+        for f in info['files']:
+            guess_file(f, file_idx, files, pieces, info['piece length'], files_sizes_array, info['name'])
+            file_idx += 1
+    else:
+        files_sizes_array = [info['length']]
+        guess_file(info, 0, files, pieces, info['piece length'], files_sizes_array, '')
+
+
+def main(argv=None):
+    global args
+    global fmt
+
+    from argparse import ArgumentParser
+
+    parser = ArgumentParser(prog='torram-ng', description='Recreate download directory for .torrent file from fully and partially downloaded file(s).')
+    parser.add_argument('torrentfile', metavar='torrentFile', help='.torrent file to analyze')
+    parser.add_argument('root', metavar='root', help='Directory to recursively search files in')
+    parser.add_argument('--symlink', action='store_true',
+                        help='Use symlinks instead of copying files. '
+                             '(Caution: You may lose your data if files are not actually identical.)')
+    parser.add_argument('--minsize', default=MINIMUM_FILESIZE_TO_SEARCH,
+                        help='Minimum file size in bytes to be recoverable. Default: ' + str(MINIMUM_FILESIZE_TO_SEARCH))
+    parser.add_argument('-v', '--verbose', action='count', default=0,
+                        help='Be verbose (multiple levels: use -vv or -vvv to see more)')
+    parser.add_argument('-o', '--output_dir', dest='output_dir',
+                        help='Output directory where to place recreated files')
+    parser.add_argument('-a', '--autodetect_output_dir', dest='autodetect_output_dir', action='store_true',
+                        help='Autodetect output directory (only qBittorrent currently supported)')
+    parser.add_argument('-c', '--use_color', dest='use_color', action='store_true', help='Output format: [ansi, ascii]')
+    parser.add_argument('-s', '--autoskip', dest='autoskip', action='count', default=0,
+                        help='Dont ask questions if there is only one viable choice. Use -ss to behave even more automated')
+    parser.add_argument('--fileext', dest='file_ext', default='',
+                        help='Extension to be added to output files (ex, .!qB for incomplete qBittorrent files)')
+    parser.add_argument('--version', action='version', version=VERSION)
+    args = parser.parse_args(argv)
+
+    if args.use_color:
+        fmt = AnsiFormatter()
+    else:
+        fmt = BaseFormatter()
+
+    run()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())