tripsort 0.0.1__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.
tripsort-0.0.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Shubh Dave
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,111 @@
1
+ Metadata-Version: 2.4
2
+ Name: tripsort
3
+ Version: 0.0.1
4
+ Summary: Offline Python library + CLI that merges trip photo zips, removes duplicates, and sorts photos by person, shot type, and category.
5
+ Keywords: photos,deduplication,face-clustering,clip,offline,cli
6
+ Author: Shubh Dave
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 2 - Pre-Alpha
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Multimedia :: Graphics
20
+ Classifier: Typing :: Typed
21
+ Requires-Dist: typer>=0.29.1
22
+ Requires-Python: >=3.11
23
+ Project-URL: Homepage, https://github.com/logn1602/tripsort
24
+ Project-URL: Repository, https://github.com/logn1602/tripsort
25
+ Project-URL: Issues, https://github.com/logn1602/tripsort/issues
26
+ Description-Content-Type: text/markdown
27
+
28
+ # tripsort
29
+
30
+ Offline Python library + CLI that merges trip photo zips, removes duplicates, and sorts photos by person, shot type, and category.
31
+
32
+ > **Status: pre-alpha.** 0.0.1 is a placeholder release: the package installs and
33
+ > `tripsort --version` works, but nothing else does yet. The first useful pre-release
34
+ > will be 0.1.0a1 (ingest, index, and dedupe).
35
+
36
+ ## What it will do
37
+
38
+ After a group trip, everyone has a zip of photos from their own phone. tripsort takes all of them and:
39
+
40
+ - merges them into one pool and removes exact duplicates and recompressed copies (such as WhatsApp copies), keeping the best original;
41
+ - groups faces by person across every zip, so each friend gets a folder with every photo they appear in;
42
+ - splits shots into solo, group, and selfie, ignoring strangers in the background;
43
+ - sorts photos into categories such as scenery, animals, food, and documents, defined as editable text prompts;
44
+ - culls bursts down to the best shot and flags blurry, dark, or eyes-closed photos without deleting anything;
45
+ - exports plain folders plus a `manifest.json`, and never modifies the input zips.
46
+
47
+ Everything runs locally on an ordinary laptop CPU: no account, no cloud uploads, no telemetry.
48
+
49
+ ## Planned usage
50
+
51
+ Not implemented yet; this is the target interface:
52
+
53
+ ```text
54
+ uvx tripsort run mine.zip sam.zip alex.zip -o sorted/ --refs refs/
55
+
56
+ sorted/
57
+ ├── all/ every kept file, once
58
+ ├── people/ one folder per person
59
+ ├── shots/ solo/, group/, selfie/
60
+ ├── categories/ scenery/, animals/, food/, documents/
61
+ ├── rejects/ blurry, dark, eyes closed: review before deleting
62
+ └── manifest.json
63
+ ```
64
+
65
+ ```python
66
+ from tripsort import Project
67
+
68
+ proj = Project.open("sorted/")
69
+ proj.ingest(["mine.zip", "sam.zip", "alex.zip"])
70
+ proj.analyze()
71
+ result = proj.export()
72
+ ```
73
+
74
+ ## Install
75
+
76
+ Requires Python 3.11 or newer.
77
+
78
+ ```console
79
+ uvx tripsort --version
80
+ ```
81
+
82
+ or `pip install tripsort`.
83
+
84
+ ## Development
85
+
86
+ The project uses [uv](https://docs.astral.sh/uv/) for everything. Settled design decisions are
87
+ logged in [docs/decisions.md](docs/decisions.md).
88
+
89
+ ```console
90
+ uv sync # create .venv with the dev tools
91
+ uv run pytest --cov # tests with coverage
92
+ uv run ruff check . # lint
93
+ uv run ruff format --check . # formatting
94
+ uv run mypy # strict type check of src/
95
+ uv run pre-commit install # optional: run the checks on every commit
96
+ ```
97
+
98
+ CI runs the tests, linters, and type checks on Windows, macOS, and Linux with Python 3.11 to 3.13.
99
+
100
+ ### Releasing
101
+
102
+ 1. Set the new version in `pyproject.toml` (`uv version <new-version>`), merge to `main`.
103
+ 2. Tag the merge commit on `main` with `v<version>` and push the tag.
104
+ 3. `.github/workflows/release.yml` builds the package, publishes it to TestPyPI, installs it from
105
+ there on every OS (only tripsort from TestPyPI, its dependencies from PyPI), then publishes to
106
+ PyPI. Both uploads use Trusted Publishing, so the repo stores no tokens.
107
+ 4. To repeat the TestPyPI install check locally: `uv run tools/verify_testpypi.py`.
108
+
109
+ ## License
110
+
111
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,84 @@
1
+ # tripsort
2
+
3
+ Offline Python library + CLI that merges trip photo zips, removes duplicates, and sorts photos by person, shot type, and category.
4
+
5
+ > **Status: pre-alpha.** 0.0.1 is a placeholder release: the package installs and
6
+ > `tripsort --version` works, but nothing else does yet. The first useful pre-release
7
+ > will be 0.1.0a1 (ingest, index, and dedupe).
8
+
9
+ ## What it will do
10
+
11
+ After a group trip, everyone has a zip of photos from their own phone. tripsort takes all of them and:
12
+
13
+ - merges them into one pool and removes exact duplicates and recompressed copies (such as WhatsApp copies), keeping the best original;
14
+ - groups faces by person across every zip, so each friend gets a folder with every photo they appear in;
15
+ - splits shots into solo, group, and selfie, ignoring strangers in the background;
16
+ - sorts photos into categories such as scenery, animals, food, and documents, defined as editable text prompts;
17
+ - culls bursts down to the best shot and flags blurry, dark, or eyes-closed photos without deleting anything;
18
+ - exports plain folders plus a `manifest.json`, and never modifies the input zips.
19
+
20
+ Everything runs locally on an ordinary laptop CPU: no account, no cloud uploads, no telemetry.
21
+
22
+ ## Planned usage
23
+
24
+ Not implemented yet; this is the target interface:
25
+
26
+ ```text
27
+ uvx tripsort run mine.zip sam.zip alex.zip -o sorted/ --refs refs/
28
+
29
+ sorted/
30
+ ├── all/ every kept file, once
31
+ ├── people/ one folder per person
32
+ ├── shots/ solo/, group/, selfie/
33
+ ├── categories/ scenery/, animals/, food/, documents/
34
+ ├── rejects/ blurry, dark, eyes closed: review before deleting
35
+ └── manifest.json
36
+ ```
37
+
38
+ ```python
39
+ from tripsort import Project
40
+
41
+ proj = Project.open("sorted/")
42
+ proj.ingest(["mine.zip", "sam.zip", "alex.zip"])
43
+ proj.analyze()
44
+ result = proj.export()
45
+ ```
46
+
47
+ ## Install
48
+
49
+ Requires Python 3.11 or newer.
50
+
51
+ ```console
52
+ uvx tripsort --version
53
+ ```
54
+
55
+ or `pip install tripsort`.
56
+
57
+ ## Development
58
+
59
+ The project uses [uv](https://docs.astral.sh/uv/) for everything. Settled design decisions are
60
+ logged in [docs/decisions.md](docs/decisions.md).
61
+
62
+ ```console
63
+ uv sync # create .venv with the dev tools
64
+ uv run pytest --cov # tests with coverage
65
+ uv run ruff check . # lint
66
+ uv run ruff format --check . # formatting
67
+ uv run mypy # strict type check of src/
68
+ uv run pre-commit install # optional: run the checks on every commit
69
+ ```
70
+
71
+ CI runs the tests, linters, and type checks on Windows, macOS, and Linux with Python 3.11 to 3.13.
72
+
73
+ ### Releasing
74
+
75
+ 1. Set the new version in `pyproject.toml` (`uv version <new-version>`), merge to `main`.
76
+ 2. Tag the merge commit on `main` with `v<version>` and push the tag.
77
+ 3. `.github/workflows/release.yml` builds the package, publishes it to TestPyPI, installs it from
78
+ there on every OS (only tripsort from TestPyPI, its dependencies from PyPI), then publishes to
79
+ PyPI. Both uploads use Trusted Publishing, so the repo stores no tokens.
80
+ 4. To repeat the TestPyPI install check locally: `uv run tools/verify_testpypi.py`.
81
+
82
+ ## License
83
+
84
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,96 @@
1
+ [project]
2
+ name = "tripsort"
3
+ version = "0.0.1"
4
+ description = "Offline Python library + CLI that merges trip photo zips, removes duplicates, and sorts photos by person, shot type, and category."
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ keywords = [
10
+ "photos",
11
+ "deduplication",
12
+ "face-clustering",
13
+ "clip",
14
+ "offline",
15
+ "cli",
16
+ ]
17
+ classifiers = [
18
+ "Development Status :: 2 - Pre-Alpha",
19
+ "Environment :: Console",
20
+ "Intended Audience :: Developers",
21
+ "Intended Audience :: End Users/Desktop",
22
+ "Operating System :: OS Independent",
23
+ "Programming Language :: Python :: 3",
24
+ "Programming Language :: Python :: 3 :: Only",
25
+ "Programming Language :: Python :: 3.11",
26
+ "Programming Language :: Python :: 3.12",
27
+ "Programming Language :: Python :: 3.13",
28
+ "Topic :: Multimedia :: Graphics",
29
+ "Typing :: Typed",
30
+ ]
31
+ dependencies = ["typer>=0.29.1"]
32
+
33
+ [[project.authors]]
34
+ name = "Shubh Dave"
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/logn1602/tripsort"
38
+ Repository = "https://github.com/logn1602/tripsort"
39
+ Issues = "https://github.com/logn1602/tripsort/issues"
40
+
41
+ [project.scripts]
42
+ tripsort = "tripsort.cli:app"
43
+
44
+ [build-system]
45
+ requires = ["uv_build>=0.11.2,<0.12.0"]
46
+ build-backend = "uv_build"
47
+
48
+ [dependency-groups]
49
+ dev = [
50
+ "mypy>=2.4.1",
51
+ "pre-commit>=4.7.0",
52
+ "pytest>=9.2.0",
53
+ "pytest-cov>=7.1.0",
54
+ "ruff>=0.17.5",
55
+ ]
56
+
57
+ [tool.ruff]
58
+ line-length = 100
59
+ target-version = "py311"
60
+
61
+ [tool.ruff.lint]
62
+ select = [
63
+ "E",
64
+ "W",
65
+ "F",
66
+ "I",
67
+ "B",
68
+ "UP",
69
+ "SIM",
70
+ "C4",
71
+ "PT",
72
+ "PTH",
73
+ "RUF",
74
+ ]
75
+
76
+ [tool.mypy]
77
+ strict = true
78
+ files = ["src"]
79
+
80
+ [tool.pytest.ini_options]
81
+ testpaths = ["tests"]
82
+ addopts = [
83
+ "-ra",
84
+ "--strict-markers",
85
+ "--strict-config",
86
+ ]
87
+ markers = ["models: needs downloaded model weights (skipped unless the models are cached)"]
88
+
89
+ [tool.coverage.run]
90
+ source = ["tripsort"]
91
+ branch = true
92
+ patch = ["subprocess"]
93
+
94
+ [tool.coverage.report]
95
+ show_missing = true
96
+ skip_covered = false
@@ -0,0 +1,87 @@
1
+ [project]
2
+ name = "tripsort"
3
+ version = "0.0.1"
4
+ description = "Offline Python library + CLI that merges trip photo zips, removes duplicates, and sorts photos by person, shot type, and category."
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [{ name = "Shubh Dave" }]
10
+ keywords = ["photos", "deduplication", "face-clustering", "clip", "offline", "cli"]
11
+ classifiers = [
12
+ "Development Status :: 2 - Pre-Alpha",
13
+ "Environment :: Console",
14
+ "Intended Audience :: Developers",
15
+ "Intended Audience :: End Users/Desktop",
16
+ "Operating System :: OS Independent",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3 :: Only",
19
+ "Programming Language :: Python :: 3.11",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ "Topic :: Multimedia :: Graphics",
23
+ "Typing :: Typed",
24
+ ]
25
+ dependencies = [
26
+ "typer>=0.29.1",
27
+ ]
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/logn1602/tripsort"
31
+ Repository = "https://github.com/logn1602/tripsort"
32
+ Issues = "https://github.com/logn1602/tripsort/issues"
33
+
34
+ [project.scripts]
35
+ tripsort = "tripsort.cli:app"
36
+
37
+ [build-system]
38
+ requires = ["uv_build>=0.11.2,<0.12.0"]
39
+ build-backend = "uv_build"
40
+
41
+ [dependency-groups]
42
+ dev = [
43
+ "mypy>=2.4.1",
44
+ "pre-commit>=4.7.0",
45
+ "pytest>=9.2.0",
46
+ "pytest-cov>=7.1.0",
47
+ "ruff>=0.17.5",
48
+ ]
49
+
50
+ [tool.ruff]
51
+ line-length = 100
52
+ target-version = "py311"
53
+
54
+ [tool.ruff.lint]
55
+ select = [
56
+ "E", # pycodestyle errors
57
+ "W", # pycodestyle warnings
58
+ "F", # pyflakes
59
+ "I", # isort
60
+ "B", # flake8-bugbear
61
+ "UP", # pyupgrade
62
+ "SIM", # flake8-simplify
63
+ "C4", # flake8-comprehensions
64
+ "PT", # flake8-pytest-style
65
+ "PTH", # prefer pathlib
66
+ "RUF", # ruff-specific rules
67
+ ]
68
+
69
+ [tool.mypy]
70
+ strict = true
71
+ files = ["src"]
72
+
73
+ [tool.pytest.ini_options]
74
+ testpaths = ["tests"]
75
+ addopts = ["-ra", "--strict-markers", "--strict-config"]
76
+ markers = [
77
+ "models: needs downloaded model weights (skipped unless the models are cached)",
78
+ ]
79
+
80
+ [tool.coverage.run]
81
+ source = ["tripsort"]
82
+ branch = true
83
+ patch = ["subprocess"] # also measure `python -m tripsort` runs started by tests
84
+
85
+ [tool.coverage.report]
86
+ show_missing = true
87
+ skip_covered = false
@@ -0,0 +1,7 @@
1
+ """tripsort: turn a group trip's photo zips into deduplicated, sorted folders, fully offline."""
2
+
3
+ from importlib.metadata import version
4
+
5
+ __version__ = version("tripsort")
6
+
7
+ __all__ = ["__version__"]
@@ -0,0 +1,5 @@
1
+ """Allow `python -m tripsort`."""
2
+
3
+ from tripsort.cli import app
4
+
5
+ app(prog_name="tripsort")
@@ -0,0 +1,58 @@
1
+ """Command-line interface: a thin Typer layer over the tripsort API."""
2
+
3
+ from pathlib import Path
4
+ from typing import Annotated
5
+
6
+ import typer
7
+
8
+ from tripsort import __version__
9
+
10
+ app = typer.Typer(
11
+ name="tripsort",
12
+ help="Turn a group trip's photo zips into deduplicated, sorted folders, fully offline.",
13
+ no_args_is_help=True,
14
+ add_completion=False,
15
+ )
16
+
17
+
18
+ def _version_callback(value: bool) -> None:
19
+ if value:
20
+ typer.echo(f"tripsort {__version__}")
21
+ raise typer.Exit()
22
+
23
+
24
+ @app.callback()
25
+ def main(
26
+ version: Annotated[
27
+ bool,
28
+ typer.Option(
29
+ "--version",
30
+ callback=_version_callback,
31
+ is_eager=True,
32
+ help="Show the version and exit.",
33
+ ),
34
+ ] = False,
35
+ ) -> None:
36
+ """Turn a group trip's photo zips into deduplicated, sorted folders, fully offline."""
37
+
38
+
39
+ @app.command()
40
+ def run(
41
+ zips: Annotated[
42
+ list[Path],
43
+ typer.Argument(
44
+ metavar="ZIP", help="Zip files of photos and videos, usually one per person."
45
+ ),
46
+ ],
47
+ out: Annotated[
48
+ Path,
49
+ typer.Option("--out", "-o", help="Output folder for the sorted files and the index."),
50
+ ],
51
+ refs: Annotated[
52
+ Path | None,
53
+ typer.Option(help="Folder with one clear photo per person, used to name people."),
54
+ ] = None,
55
+ ) -> None:
56
+ """Ingest, analyze, and export in one step."""
57
+ typer.echo("tripsort run is not implemented yet; it arrives in a later release.", err=True)
58
+ raise typer.Exit(code=1)
File without changes