image-workflow 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.
@@ -0,0 +1,192 @@
1
+ Metadata-Version: 2.4
2
+ Name: image-workflow
3
+ Version: 0.1.0
4
+ Summary: Import, organize, and de-duplicate photo collections.
5
+ Author: image-workflow contributors
6
+ License-Expression: MIT
7
+ Requires-Python: >=3.10
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: Pillow>=10.0
10
+ Provides-Extra: test
11
+ Requires-Dist: pytest>=8.0; extra == "test"
12
+
13
+ # image-workflow
14
+
15
+ Tools for importing camera photos into a date-based archive and cleaning up
16
+ duplicate copies.
17
+
18
+ The repository started as a small collection of shell/Python scripts. It is now
19
+ a Python package with a single CLI and a test suite that builds fake JPEGs with
20
+ EXIF metadata to verify the import rules.
21
+
22
+ ## Install
23
+
24
+ ```sh
25
+ pip install -e .
26
+ ```
27
+
28
+ For development and tests:
29
+
30
+ ```sh
31
+ pip install -e '.[test]'
32
+ pytest
33
+ ```
34
+
35
+ Or, with `uv`:
36
+
37
+ ```sh
38
+ uv run --extra test pytest
39
+ ```
40
+
41
+ The package depends on [Pillow](https://python-pillow.org/) for reading image
42
+ metadata. The optional `fix-times` command also needs `exiftool` on `PATH` to
43
+ rewrite EXIF dates without re-encoding JPEGs.
44
+
45
+ ## Import photos
46
+
47
+ The import command is a Python port of the original `import.sh` exiftool
48
+ command. It requires `Make`, `Model`, and `DateTimeOriginal` in each photo and
49
+ moves it into a `YYYY/MM` archive tree:
50
+
51
+ ```sh
52
+ image-workflow import ../photos_incoming --destination .
53
+ ```
54
+
55
+ The resulting name is:
56
+
57
+ ```text
58
+ YYYYMMDD_HHMMSS[.SubSecTimeOriginal]_Make_Model.<FileTypeExtension>
59
+ ```
60
+
61
+ For example:
62
+
63
+ ```text
64
+ photos_incoming/IMG_0001.JPG
65
+ -> 2024/07/20240715_123456.123_Canon_EOS-5D.jpg
66
+ ```
67
+
68
+ Rules preserved from exiftool:
69
+
70
+ | Detail | Behaviour |
71
+ | --- | --- |
72
+ | Required metadata | Files without `Make`, `Model`, or `DateTimeOriginal` are skipped. |
73
+ | Date tree | Files go to `<destination>/<year>/<month>/`. |
74
+ | Timestamp | `DateTimeOriginal` is formatted as `YYYYMMDD_HHMMSS`. |
75
+ | Subseconds | `SubSecTimeOriginal` is appended as `.123` when present. |
76
+ | Make/model | Spaces become `-`; runs of `-` collapse to one `-`. |
77
+ | Extension | Exiftool's `FileTypeExtension`: JPEG becomes `.jpg`, TIFF `.tif`, etc. |
78
+ | Collisions | Existing names get `_1`, `_2`, ... before the extension. |
79
+ | Already imported | A file already at its computed destination is left unchanged. |
80
+ | File data | Bytes and modification time are preserved (it is a move/rename). |
81
+
82
+ By default only files directly in `SOURCE` are imported, matching `exiftool`
83
+ without `-r`. Use `--recursive` (or `-r`) to include subdirectories. Use
84
+ `--dry-run` (`-n`) to see what would happen without creating directories or
85
+ moving files.
86
+
87
+ The destination defaults to the current directory, which matches running the
88
+ original script from the archive root with `SOURCE=../photos_incoming`.
89
+
90
+ ### Python API
91
+
92
+ ```python
93
+ from image_workflow import import_images
94
+
95
+ results = import_images("../photos_incoming", destination=".", recursive=True)
96
+ for result in results:
97
+ print(result.status, result.source, "->", result.destination)
98
+ ```
99
+
100
+ Each result has one of the statuses `moved`, `would_move`, `unchanged`,
101
+ `skipped`, or `failed`.
102
+
103
+ ## Remove duplicates
104
+
105
+ The duplicate finder is dry-run by default:
106
+
107
+ ```sh
108
+ image-workflow duplicates ~/Pictures
109
+ image-workflow duplicates ~/Pictures --apply
110
+ image-workflow duplicates ~/Pictures --apply --trash
111
+ ```
112
+
113
+ - `--apply` actually deletes/moves files.
114
+ - `--trash` moves duplicates into a mirrored `.dtrash` tree instead of deleting.
115
+ - `--fuzzy` also matches re-exports that differ in resolution or JPEG quality.
116
+ - `--threshold BITS` controls the dHash Hamming distance (default 6/64).
117
+ - `--verbose` logs near matches that were considered but not flagged.
118
+
119
+ Fuzzy matching uses a perceptual dHash gate followed by a pixel-difference
120
+ check, and differing extended-XMP digests veto a match.
121
+
122
+ ## Fix timestamps and re-import
123
+
124
+ The `fix-times` command is a port of `fix_times.sh`:
125
+
126
+ ```sh
127
+ image-workflow fix-times 2025/09_fix --destination .
128
+ ```
129
+
130
+ It adds one hour to all EXIF dates (configurable with `--hours`) and then
131
+ re-imports the JPEGs using the import naming rules, without
132
+ `SubSecTimeOriginal` (matching the original script). Date shifting requires
133
+ `exiftool`.
134
+
135
+ ## Publishing to PyPI
136
+
137
+ Build and publish with uv:
138
+
139
+ ```sh
140
+ uv build --no-sources
141
+ uv publish
142
+ ```
143
+
144
+ `uv publish` reads the PyPI token from `UV_PUBLISH_TOKEN` or accepts `--token`.
145
+ Tagged releases are published automatically by the GitLab pipeline:
146
+
147
+ ```sh
148
+ git tag -a v0.1.0 -m v0.1.0
149
+ git push origin v0.1.0
150
+ ```
151
+
152
+ The `publish` job runs only for tags matching `vX.Y.Z` (including common
153
+ pre-release suffixes), checks the built wheel and source distribution, and then
154
+ runs:
155
+
156
+ ```sh
157
+ uv publish --check-url https://pypi.org/simple/
158
+ ```
159
+
160
+ Before releasing:
161
+
162
+ 1. Add a masked, protected CI/CD variable named `UV_PUBLISH_TOKEN` containing a
163
+ PyPI API token for the `image-workflow` project.
164
+ 2. Optionally protect the `pypi` environment so releases require approval.
165
+ 3. Update the version in `pyproject.toml` (for example with
166
+ `uv version 0.1.0`) and push the matching tag.
167
+
168
+ Trusted publishing for self-managed GitLab is available as a PyPI beta but
169
+ requires onboarding by PyPI staff, so this pipeline uses `UV_PUBLISH_TOKEN`. If
170
+ the instance is onboarded later, or the project moves to gitlab.com/GitHub,
171
+ trusted publishing can replace the token.
172
+
173
+ ## Layout
174
+
175
+ ```text
176
+ .gitlab-ci.yml # test and PyPI release pipeline
177
+ src/image_workflow/
178
+ importer.py # Python import port and naming rules
179
+ duplicates.py # duplicate finder
180
+ fix_times.py # timestamp shifting + re-import
181
+ cli.py # `image-workflow` entry point
182
+ tests/
183
+ conftest.py # fixtures that create fake images with EXIF data
184
+ test_importer.py
185
+ test_duplicates.py
186
+ test_cli.py
187
+ smoke_test.py # checks the built wheel/sdist
188
+ legacy/
189
+ import.sh # original scripts, kept for reference
190
+ fix_times.sh
191
+ duplicates.py
192
+ ```
@@ -0,0 +1,180 @@
1
+ # image-workflow
2
+
3
+ Tools for importing camera photos into a date-based archive and cleaning up
4
+ duplicate copies.
5
+
6
+ The repository started as a small collection of shell/Python scripts. It is now
7
+ a Python package with a single CLI and a test suite that builds fake JPEGs with
8
+ EXIF metadata to verify the import rules.
9
+
10
+ ## Install
11
+
12
+ ```sh
13
+ pip install -e .
14
+ ```
15
+
16
+ For development and tests:
17
+
18
+ ```sh
19
+ pip install -e '.[test]'
20
+ pytest
21
+ ```
22
+
23
+ Or, with `uv`:
24
+
25
+ ```sh
26
+ uv run --extra test pytest
27
+ ```
28
+
29
+ The package depends on [Pillow](https://python-pillow.org/) for reading image
30
+ metadata. The optional `fix-times` command also needs `exiftool` on `PATH` to
31
+ rewrite EXIF dates without re-encoding JPEGs.
32
+
33
+ ## Import photos
34
+
35
+ The import command is a Python port of the original `import.sh` exiftool
36
+ command. It requires `Make`, `Model`, and `DateTimeOriginal` in each photo and
37
+ moves it into a `YYYY/MM` archive tree:
38
+
39
+ ```sh
40
+ image-workflow import ../photos_incoming --destination .
41
+ ```
42
+
43
+ The resulting name is:
44
+
45
+ ```text
46
+ YYYYMMDD_HHMMSS[.SubSecTimeOriginal]_Make_Model.<FileTypeExtension>
47
+ ```
48
+
49
+ For example:
50
+
51
+ ```text
52
+ photos_incoming/IMG_0001.JPG
53
+ -> 2024/07/20240715_123456.123_Canon_EOS-5D.jpg
54
+ ```
55
+
56
+ Rules preserved from exiftool:
57
+
58
+ | Detail | Behaviour |
59
+ | --- | --- |
60
+ | Required metadata | Files without `Make`, `Model`, or `DateTimeOriginal` are skipped. |
61
+ | Date tree | Files go to `<destination>/<year>/<month>/`. |
62
+ | Timestamp | `DateTimeOriginal` is formatted as `YYYYMMDD_HHMMSS`. |
63
+ | Subseconds | `SubSecTimeOriginal` is appended as `.123` when present. |
64
+ | Make/model | Spaces become `-`; runs of `-` collapse to one `-`. |
65
+ | Extension | Exiftool's `FileTypeExtension`: JPEG becomes `.jpg`, TIFF `.tif`, etc. |
66
+ | Collisions | Existing names get `_1`, `_2`, ... before the extension. |
67
+ | Already imported | A file already at its computed destination is left unchanged. |
68
+ | File data | Bytes and modification time are preserved (it is a move/rename). |
69
+
70
+ By default only files directly in `SOURCE` are imported, matching `exiftool`
71
+ without `-r`. Use `--recursive` (or `-r`) to include subdirectories. Use
72
+ `--dry-run` (`-n`) to see what would happen without creating directories or
73
+ moving files.
74
+
75
+ The destination defaults to the current directory, which matches running the
76
+ original script from the archive root with `SOURCE=../photos_incoming`.
77
+
78
+ ### Python API
79
+
80
+ ```python
81
+ from image_workflow import import_images
82
+
83
+ results = import_images("../photos_incoming", destination=".", recursive=True)
84
+ for result in results:
85
+ print(result.status, result.source, "->", result.destination)
86
+ ```
87
+
88
+ Each result has one of the statuses `moved`, `would_move`, `unchanged`,
89
+ `skipped`, or `failed`.
90
+
91
+ ## Remove duplicates
92
+
93
+ The duplicate finder is dry-run by default:
94
+
95
+ ```sh
96
+ image-workflow duplicates ~/Pictures
97
+ image-workflow duplicates ~/Pictures --apply
98
+ image-workflow duplicates ~/Pictures --apply --trash
99
+ ```
100
+
101
+ - `--apply` actually deletes/moves files.
102
+ - `--trash` moves duplicates into a mirrored `.dtrash` tree instead of deleting.
103
+ - `--fuzzy` also matches re-exports that differ in resolution or JPEG quality.
104
+ - `--threshold BITS` controls the dHash Hamming distance (default 6/64).
105
+ - `--verbose` logs near matches that were considered but not flagged.
106
+
107
+ Fuzzy matching uses a perceptual dHash gate followed by a pixel-difference
108
+ check, and differing extended-XMP digests veto a match.
109
+
110
+ ## Fix timestamps and re-import
111
+
112
+ The `fix-times` command is a port of `fix_times.sh`:
113
+
114
+ ```sh
115
+ image-workflow fix-times 2025/09_fix --destination .
116
+ ```
117
+
118
+ It adds one hour to all EXIF dates (configurable with `--hours`) and then
119
+ re-imports the JPEGs using the import naming rules, without
120
+ `SubSecTimeOriginal` (matching the original script). Date shifting requires
121
+ `exiftool`.
122
+
123
+ ## Publishing to PyPI
124
+
125
+ Build and publish with uv:
126
+
127
+ ```sh
128
+ uv build --no-sources
129
+ uv publish
130
+ ```
131
+
132
+ `uv publish` reads the PyPI token from `UV_PUBLISH_TOKEN` or accepts `--token`.
133
+ Tagged releases are published automatically by the GitLab pipeline:
134
+
135
+ ```sh
136
+ git tag -a v0.1.0 -m v0.1.0
137
+ git push origin v0.1.0
138
+ ```
139
+
140
+ The `publish` job runs only for tags matching `vX.Y.Z` (including common
141
+ pre-release suffixes), checks the built wheel and source distribution, and then
142
+ runs:
143
+
144
+ ```sh
145
+ uv publish --check-url https://pypi.org/simple/
146
+ ```
147
+
148
+ Before releasing:
149
+
150
+ 1. Add a masked, protected CI/CD variable named `UV_PUBLISH_TOKEN` containing a
151
+ PyPI API token for the `image-workflow` project.
152
+ 2. Optionally protect the `pypi` environment so releases require approval.
153
+ 3. Update the version in `pyproject.toml` (for example with
154
+ `uv version 0.1.0`) and push the matching tag.
155
+
156
+ Trusted publishing for self-managed GitLab is available as a PyPI beta but
157
+ requires onboarding by PyPI staff, so this pipeline uses `UV_PUBLISH_TOKEN`. If
158
+ the instance is onboarded later, or the project moves to gitlab.com/GitHub,
159
+ trusted publishing can replace the token.
160
+
161
+ ## Layout
162
+
163
+ ```text
164
+ .gitlab-ci.yml # test and PyPI release pipeline
165
+ src/image_workflow/
166
+ importer.py # Python import port and naming rules
167
+ duplicates.py # duplicate finder
168
+ fix_times.py # timestamp shifting + re-import
169
+ cli.py # `image-workflow` entry point
170
+ tests/
171
+ conftest.py # fixtures that create fake images with EXIF data
172
+ test_importer.py
173
+ test_duplicates.py
174
+ test_cli.py
175
+ smoke_test.py # checks the built wheel/sdist
176
+ legacy/
177
+ import.sh # original scripts, kept for reference
178
+ fix_times.sh
179
+ duplicates.py
180
+ ```
@@ -0,0 +1,27 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "image-workflow"
7
+ version = "0.1.0"
8
+ description = "Import, organize, and de-duplicate photo collections."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ authors = [{ name = "image-workflow contributors" }]
13
+ dependencies = ["Pillow>=10.0"]
14
+
15
+ [project.optional-dependencies]
16
+ test = ["pytest>=8.0"]
17
+
18
+ [project.scripts]
19
+ image-workflow = "image_workflow.cli:main"
20
+
21
+ [tool.setuptools.packages.find]
22
+ where = ["src"]
23
+
24
+ [tool.pytest.ini_options]
25
+ testpaths = ["tests"]
26
+ addopts = "-q"
27
+ pythonpath = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,27 @@
1
+ """Image workflow: import, organize, and de-duplicate photo collections."""
2
+
3
+ from .importer import (
4
+ ExifMetadata,
5
+ ImportResult,
6
+ MetadataError,
7
+ NotAnImageError,
8
+ build_filename,
9
+ build_relative_path,
10
+ import_images,
11
+ read_metadata,
12
+ sanitize_component,
13
+ )
14
+
15
+ __all__ = [
16
+ "ExifMetadata",
17
+ "ImportResult",
18
+ "MetadataError",
19
+ "NotAnImageError",
20
+ "build_filename",
21
+ "build_relative_path",
22
+ "import_images",
23
+ "read_metadata",
24
+ "sanitize_component",
25
+ ]
26
+
27
+ __version__ = "0.1.0"
@@ -0,0 +1,4 @@
1
+ from .cli import main
2
+
3
+ if __name__ == "__main__":
4
+ raise SystemExit(main())
@@ -0,0 +1,202 @@
1
+ """Command-line interface for the image-workflow package."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sys
7
+
8
+ from . import duplicates, fix_times
9
+ from .importer import ImportResult, import_images
10
+
11
+
12
+ def _print_import_results(results: list[ImportResult], *, quiet: bool = False) -> None:
13
+ for result in results:
14
+ if result.status == "moved":
15
+ print(f"moved: {result.source} -> {result.destination}")
16
+ elif result.status == "would_move":
17
+ print(f"[dry run] would move: {result.source} -> {result.destination}")
18
+ elif result.status == "unchanged":
19
+ print(f"unchanged: {result.source}")
20
+ elif result.status == "failed":
21
+ print(f"error: {result.source}: {result.reason}", file=sys.stderr)
22
+ elif result.status == "skipped" and not quiet:
23
+ print(f"skipped: {result.source} ({result.reason})")
24
+
25
+
26
+ def _cmd_import(args: argparse.Namespace) -> int:
27
+ try:
28
+ results = import_images(
29
+ args.source,
30
+ args.destination,
31
+ recursive=args.recursive,
32
+ dry_run=args.dry_run,
33
+ include_subseconds=not args.no_subseconds,
34
+ )
35
+ except FileNotFoundError as exc:
36
+ print(f"error: {exc}", file=sys.stderr)
37
+ return 1
38
+
39
+ _print_import_results(results, quiet=args.quiet)
40
+
41
+ moved = sum(r.status in ("moved", "would_move") for r in results)
42
+ skipped = sum(r.status in ("skipped", "failed") for r in results)
43
+ if not args.quiet:
44
+ print(
45
+ f"{moved} file(s) {'would be ' if args.dry_run else ''}moved, {skipped} skipped"
46
+ )
47
+ return 1 if any(r.status == "failed" for r in results) else 0
48
+
49
+
50
+ def build_parser() -> argparse.ArgumentParser:
51
+ parser = argparse.ArgumentParser(
52
+ prog="image-workflow",
53
+ description="Import, organize, and de-duplicate photo collections.",
54
+ )
55
+ subparsers = parser.add_subparsers(dest="command", required=True)
56
+
57
+ importer = subparsers.add_parser(
58
+ "import",
59
+ help="rename camera photos into a YYYY/MM archive tree",
60
+ description="Rename photos into YYYY/MM/YYYYMMDD_HHMMSS[.subsec]_Make_Model.ext.",
61
+ )
62
+ importer.add_argument("source", help="directory (or one file) to import")
63
+ importer.add_argument(
64
+ "--destination",
65
+ "-d",
66
+ default=".",
67
+ help="archive root for the YYYY/MM tree (default: current directory)",
68
+ )
69
+ importer.add_argument(
70
+ "--recursive",
71
+ "-r",
72
+ action="store_true",
73
+ help="also import files in subdirectories of SOURCE",
74
+ )
75
+ importer.add_argument(
76
+ "--dry-run",
77
+ "-n",
78
+ action="store_true",
79
+ help="show what would happen without moving files",
80
+ )
81
+ importer.add_argument(
82
+ "--no-subseconds",
83
+ action="store_true",
84
+ help="omit SubSecTimeOriginal from filenames",
85
+ )
86
+ importer.add_argument(
87
+ "--quiet",
88
+ "-q",
89
+ action="store_true",
90
+ help="do not report skipped files or the summary",
91
+ )
92
+ importer.set_defaults(func=_cmd_import)
93
+
94
+ duplicate_parser = subparsers.add_parser(
95
+ "duplicates",
96
+ help="find/remove duplicate copies such as beach_1.jpg",
97
+ )
98
+ duplicate_parser.add_argument(
99
+ "root", nargs="?", default=".", help="directory to scan"
100
+ )
101
+ duplicate_parser.add_argument(
102
+ "--apply",
103
+ action="store_true",
104
+ help="actually delete/move files (default is dry run)",
105
+ )
106
+ duplicate_parser.add_argument(
107
+ "--trash",
108
+ action="store_true",
109
+ help="move duplicates into .dtrash instead of deleting",
110
+ )
111
+ duplicate_parser.add_argument(
112
+ "--fuzzy",
113
+ action="store_true",
114
+ help="match images that differ in resolution or JPEG quality",
115
+ )
116
+ duplicate_parser.add_argument(
117
+ "--threshold",
118
+ type=int,
119
+ default=6,
120
+ metavar="BITS",
121
+ help="Hamming distance for --fuzzy matches (default: 6 of 64 bits)",
122
+ )
123
+ duplicate_parser.add_argument(
124
+ "--verbose",
125
+ action="store_true",
126
+ help="log fuzzy pairs that were considered but not flagged",
127
+ )
128
+
129
+ def _cmd_duplicates(args: argparse.Namespace) -> int:
130
+ forwarded = [args.root]
131
+ for flag in ("apply", "trash", "fuzzy", "verbose"):
132
+ if getattr(args, flag):
133
+ forwarded.append("--" + flag)
134
+ if args.threshold != 6:
135
+ forwarded.extend(["--threshold", str(args.threshold)])
136
+ return duplicates.main(forwarded)
137
+
138
+ duplicate_parser.set_defaults(func=_cmd_duplicates)
139
+
140
+ fix_parser = subparsers.add_parser(
141
+ "fix-times",
142
+ help="shift EXIF dates and re-import JPEGs",
143
+ )
144
+ fix_parser.add_argument("root", help="directory containing JPEGs to fix")
145
+ fix_parser.add_argument(
146
+ "--destination",
147
+ "-d",
148
+ default=".",
149
+ help="archive root for renamed files (default: current directory)",
150
+ )
151
+ fix_parser.add_argument(
152
+ "--hours",
153
+ type=float,
154
+ default=1.0,
155
+ help="hours to add to all EXIF dates (default: 1)",
156
+ )
157
+ fix_parser.add_argument(
158
+ "--no-recursive",
159
+ action="store_true",
160
+ help="only process JPEGs directly inside ROOT",
161
+ )
162
+ fix_parser.add_argument(
163
+ "--dry-run",
164
+ "-n",
165
+ action="store_true",
166
+ help="report what would happen without shifting or moving files",
167
+ )
168
+ fix_parser.add_argument(
169
+ "--exiftool",
170
+ default="exiftool",
171
+ help="exiftool executable name/path (default: exiftool)",
172
+ )
173
+
174
+ def _cmd_fix_times(args: argparse.Namespace) -> int:
175
+ forwarded = [
176
+ args.root,
177
+ "--destination",
178
+ args.destination,
179
+ "--hours",
180
+ str(args.hours),
181
+ "--exiftool",
182
+ args.exiftool,
183
+ ]
184
+ if args.no_recursive:
185
+ forwarded.append("--no-recursive")
186
+ if args.dry_run:
187
+ forwarded.append("--dry-run")
188
+ return fix_times.main(forwarded)
189
+
190
+ fix_parser.set_defaults(func=_cmd_fix_times)
191
+
192
+ return parser
193
+
194
+
195
+ def main(argv=None) -> int:
196
+ parser = build_parser()
197
+ args = parser.parse_args(argv)
198
+ return args.func(args)
199
+
200
+
201
+ if __name__ == "__main__":
202
+ raise SystemExit(main())