Merge pull request #5 from auanasgheps/dev

Dev: bugfixes and enhancements (0.34)

Author: auanasgheps

.github/workflows/tests.yml

@@ -2,7 +2,13 @@ name: Tests
 
 on:
   push:
+    paths:
+      - '**.py'
+      - '.github/workflows/tests.yml'
   pull_request:
+    paths:
+      - '**.py'
+      - '.github/workflows/tests.yml'
 
 jobs:
   test:

README.md

@@ -3,7 +3,8 @@
 
 ## Overview
 
-WhatsApp Media Archiver organises your WhatsApp media into a structured folder hierarchy using metadata from the WhatsApp database (`msgstore.db`). Instead of an unstructured dump, you get a browsable archive sorted by contact or group, year, and direction (Sent/Received), with original message timestamps preserved.
+WhatsApp Media Archiver organises your WhatsApp media into a structured folder hierarchy using metadata from the WhatsApp database. 
+Instead of an unstructured dump, you get a browsable archive sorted by contact or group, year, and direction (Sent/Received), with original message timestamps preserved.
 
 > ⚠️ **This tool is designed to run on a backup copy of your WhatsApp data — never on live device files.** For safeguard reasons, this script will always make a copy of your data.
 
@@ -21,8 +22,10 @@ WhatsApp Media Archiver organises your WhatsApp media into a structured folder h
 - Duplicate media detection across runs — CSV report of files with identical content at multiple archive paths
 - Missing media CSV report for manual recovery of old or deleted files
 - Dry run mode for safe previewing before a full run
-- iOS support — reads directly from an iPhone backup (`--ios_backup`); no third-party extraction tool required
-- Encrypted backup support (`msgstore.db.crypt15`) via `wa-crypt-tools`
+- Windows, Linux and MacOS are supported to run the script.
+- WhatsApp platform: Android and iOS are both supported. No root or jailbreak are required.
+    - Android: requires a manual copy of your `/Whatsapp/Media/` folder
+    - iOS: reads directly from an iPhone backup, encrypted backups are supported via `wa-crypt-tools`
 - Restore mode — reconstructs the original `WhatsApp/Media/` folder structure from the archive (Android only)
 
 ### Supported Media Types
@@ -122,7 +125,7 @@ The script is **safe to re-run** on an existing archive:
 - Stickers are not archived in this version.
 - **Year folders reflect the local time of the machine running the script**, not UTC. A message sent just after midnight on 1 January will be filed under the new year only if your machine's clock agrees. This is intentional — the archive reflects your local experience of when media was shared.
 - **iOS restore mode is not supported.** Restore mode reconstructs the Android `Media/` folder layout, which has no equivalent on iOS. Running `--mode restore` on an iOS archive exits with a clear error.
-- **iOS number change tracking is best-effort.** Contacts present in the device address book are consolidated automatically. Contacts not saved to the address book (`ZCONTACTABID = NULL`) appear as separate folders.
+- **iOS number change tracking is best-effort.** Contacts present in the device address book are consolidated automatically. Contacts not saved to the address book appear as separate folders.
 
 ---
 

docs/prerequisites.md

@@ -7,15 +7,21 @@ Ensure Python 3.10+ is installed.
 
 This script relies on some packages for Android and iOS.
 
-Install the relevant package before your first run.
+Install the relevant package before your first run. If you miss any of these, the script will notify you.
 
-For Android encrypted backup decryption, the script uses `wa-crypt-tools`. You are going to use it if you don't have a rooted device.
+
+
+**Android encrypted backup decryption** 
+
+The script uses `wa-crypt-tools`. You are going to use it if you don't have a rooted device.
 
 ```bash
 pip install wa-crypt-tools
 ```
 
-For iOS encrypted backup decryption, the script uses `iphone-backup-decrypt`. You are going to use it if you create password protected iOS backups.
+**iOS encrypted backup decryption** 
+
+The script uses `iphone-backup-decrypt`. You are going to use it if you create password protected iOS backups.
 
 ```bash
 pip install iphone-backup-decrypt
@@ -24,6 +30,15 @@ pip install iphone-backup-decrypt
 > 💡 Windows Users: your Python environment may not have pip in the PATH. If `pip install` doesn't work for you, `use py -m pip install`.
 
 
+**Timezone feature for Windows**
+
+If you plan to use the `--timezone` argument, Windows requires one additional package. macOS and Linux ship the IANA timezone database as part of the OS; Windows does not.
+> ```
+> pip install tzdata
+> ```
+> This is only needed when `--timezone` is used. Normal runs without `--timezone` work on Windows without it.
+
+
 ---
 
 ## 2. WhatsApp E2E Encrypted Backup
@@ -53,7 +68,7 @@ When asked, create the end-to-end ecrypted backup.
 ### Your WhatsApp Media Folder
 
 Before you run the script, you need your WhatsApp (Media) folder on disk - actually, the folder called `WhatsApp` that **contains** the `Media` subfolder. 
-You need to copy this folder from your phone: you can use [Syncthing](https://syncthing.net/) to ease the process.
+You need to copy this folder from your phone: you can use [Syncthing](https://syncthing.net/) to smooth the process.
 
 ```
 /path/to/WhatsApp/

docs/running-the-script.md

@@ -19,6 +19,7 @@ usage: wa_media_archiver.py [-h]
                       [--dry-run]
                       [--limit N]
                       [--since DATE]
+                      [--timezone TZ]
 ```
 
 | Argument | Required | Description |
@@ -37,6 +38,7 @@ usage: wa_media_archiver.py [-h]
 | `--dry-run` | No | Simulate the run without copying any files |
 | `--limit N` | No | Cap rows returned per chat type (N/2 from groups, N/2 from 1-to-1). Total rows ≤ N. Useful for test runs |
 | `--since DATE` | No | Only include messages on or after this date (`YYYY-MM-DD`). Combines freely with `--limit` |
+| `--timezone TZ` | No | [IANA timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) for year folder assignment and report timestamps (e.g. `Europe/Rome`, `America/New_York`, `UTC`). Ensures files land in the correct `<YYYY>/` subfolder regardless of where or when the script is run. Also applied to `--since` date interpretation. Defaults to machine local time. **Windows users: requires `pip install tzdata`** |
 
 ---
 
@@ -173,7 +175,7 @@ python3 wa_media_archiver.py \
 
 Restore mode reconstructs the flat `WhatsApp/Media/` folder structure directly inside the archive folder, without needing the original device or database. This is useful when re-importing media into tools that expect the original WhatsApp layout.
 
-> ⚠️ **Android archives only.** iOS media is stored at `Message/Media/...` paths that have no equivalent reconstruction target outside the iPhone backup format. Running restore mode on an iOS archive exits with a clear error.
+> ⚠️ **Android archives only.** iOS media is stored at `Message/Media/...` paths that have no equivalent reconstruction target outside the iPhone backup format. Running restore mode on an iOS archive is disallowed.
 
 The reconstructed tree is written to `<output>/Media/`, alongside the existing `Contacts/` and `Groups/` folders. No files are overwritten — identical files already in place are skipped silently.
 

tests/test_wa_media_archiver.py

@@ -148,6 +148,36 @@ def test_known_timestamp(self):
         year = wa.get_year(ts_ms)
         assert year == "2024"
 
+    def test_utc_timezone(self):
+        pytest.importorskip('zoneinfo', reason="zoneinfo unavailable")
+        from zoneinfo import ZoneInfo
+        try:
+            tz = ZoneInfo('UTC')
+        except Exception:
+            pytest.skip("tzdata not installed")
+        # 2024-12-31 23:30:00 UTC → still 2024 in UTC
+        ts_ms = 1735688200000  # 2024-12-31 23:36:40 UTC
+        assert wa.get_year(ts_ms, tz=tz) == "2024"
+
+    def test_timezone_crosses_year_boundary(self):
+        from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+        try:
+            rome = ZoneInfo('Europe/Rome')
+            utc  = ZoneInfo('UTC')
+        except ZoneInfoNotFoundError:
+            pytest.skip("tzdata not installed (required on Windows)")
+        # 2024-12-31 23:30:00 UTC = 2025-01-01 00:30:00 in UTC+1 (Europe/Rome in winter)
+        ts_ms = 1735687800000  # 2024-12-31 23:30:00 UTC exactly
+        assert wa.get_year(ts_ms, tz=rome) == "2025"
+        assert wa.get_year(ts_ms, tz=utc)  == "2024"
+
+    def test_no_tz_returns_string(self):
+        # Without tz, returns a 4-digit year string (value depends on local time, just check format)
+        ts_ms = 1705276800000
+        year = wa.get_year(ts_ms)
+        assert len(year) == 4
+        assert year.isdigit()
+
 
 class TestAppendSenderToFilename:
     def test_normal_case(self):
@@ -1869,3 +1899,56 @@ def test_failure_raises(self, logger, tmp_path):
                    side_effect=subprocess.CalledProcessError(1, 'adb', stderr=b"fail")):
             with pytest.raises(subprocess.CalledProcessError):
                 adb.pull_contacts(str(tmp_path), logger=logger)
+
+
+# ---------------------------------------------------------------------------
+# TestCheckDependencies
+# ---------------------------------------------------------------------------
+
+class TestCheckDependencies:
+    def _args(self, **kwargs):
+        """Return a minimal namespace; only set the fields under test."""
+        defaults = dict(mode=None, e2e_key=None, ios_password=None)
+        defaults.update(kwargs)
+        import argparse
+        return argparse.Namespace(**defaults)
+
+    def test_no_issues_passes_silently(self, logger):
+        args = self._args()
+        wa.check_dependencies(args, logger)  # must not raise
+
+    def test_adb_missing_raises(self, logger):
+        args = self._args(mode='adb')
+        with patch("wa_media_archiver.shutil.which", return_value=None):
+            with pytest.raises(SystemExit):
+                wa.check_dependencies(args, logger)
+
+    def test_adb_present_passes(self, logger):
+        args = self._args(mode='adb')
+        with patch("wa_media_archiver.shutil.which", return_value="/usr/bin/adb"):
+            wa.check_dependencies(args, logger)  # must not raise
+
+    def test_wa_crypt_tools_missing_raises(self, logger):
+        args = self._args(e2e_key='key.bin')
+        with patch("importlib.util.find_spec", return_value=None):
+            with pytest.raises(SystemExit):
+                wa.check_dependencies(args, logger)
+
+    def test_iphone_backup_decrypt_missing_raises(self, logger):
+        args = self._args(ios_password='secret')
+        with patch("importlib.util.find_spec", return_value=None):
+            with pytest.raises(SystemExit):
+                wa.check_dependencies(args, logger)
+
+    def test_multiple_missing_reported_together(self, logger, caplog):
+        args = self._args(mode='adb', e2e_key='key.bin')
+        # Capture what logger.error receives by inspecting the call
+        errors = []
+        logger.error = lambda msg, *a, **kw: errors.append(msg)
+        with patch("wa_media_archiver.shutil.which", return_value=None), \
+             patch("importlib.util.find_spec", return_value=None), \
+             pytest.raises(SystemExit):
+            wa.check_dependencies(args, logger)
+        assert len(errors) == 1, "Expected a single combined error message"
+        assert "adb" in errors[0]
+        assert "wa-crypt-tools" in errors[0]