#!/data/data/com.termux/files/usr/bin/python3
#!/usr/bin/env python3  <= fails in Termux:Widget (see also _etc shims)
"""
=======================================================================
Export Phone Content, Part 1: Phone    [new in 1.2]

Run exports occasionally (if ever) to propagate your on-phone content 
changes to both PC and proxy drive, via an on-phone zip and fast 
Mergealls to PC and proxy.  Use this after changing content on your
phone, to propagate the on-phone changes to your PC and proxy.

See _README.html for license, attribution, version, and docs.

-----------------------------------------------------------------------
Details:

Exports are a specialization of the verify scripts:

- Part 1 (run on phone) simply runs the verify scripts' part 1 to 
  zip content on the phone and prompt for the zip copy to proxy.

- Part 2 (run on PC) is a custom script that unzips on the PC, and 
  syncs to the PC and proxy-drive copies with extra Mergealls. 
  It does not run the content comparisons used for verifications.

Then net effect eliminates the manual PC-move and proxy-Mergeall 
requirements for exports formerly performed with the verify scripts.  

Exports run with the x-export-* scripts are still fairly slow: they 
copy phone content in full to PC, and require a manual zipfile copy
because POSIX code cannot access USB directly on Android 11 and later.  
Still, the PC and proxy updates use fast Mergealls, so the on-phone 
zip is the primary speed hit, and naturally varies by content size.

Though designed for backsync change propagation, the export scripts 
may also be used to export phone content in full: simply leave the
the target folder empty on PC, proxy, or both. 

-----------------------------------------------------------------------
Usage:

Run this on your phone first (before running Part 2 on your PC), with:

     python3 x-export-phone-part1-phone.py

Run this from the Termux app's console, or any other app with a 
console terminal.  This file may also be run with no command line 
from a Python IDE app (e.g., Pydroid 3 or QPython), and/or a 
home-screen shortcut or widget (e.g., Termux:Widget).

Run this from any folder.  It uses paths set in config_phone.py,
and finds commmon.py in its own folder automatically.

Step runtimes are shown in the console after step completion.  
Step outputs go to files in LOGS; watch with 'tail -f LOGS/file'.

-----------------------------------------------------------------------
**CAUTION**:

Exporting your phone's content copy to your PC should work well for 
normal files and folders, but might damage nonportable content items
on your PC.  In particular, _symlinks_ may not survive the export to 
PC, because they may be stored on your phone as simple 'stub' files 
which will differ from PC symlinks by type even if unchanged.  

This risk varies per Android storage type; for finer-grained details, 
see _README.html#storagemetadata.  But if your content contains such 
exotic items, _always_ inspect the PC/phone differences here before
syncing phone content to your PC or proxy.  As a guideline, symlinks
are best unused in content that will be copied to and from phones.

Also note:

- If BackupChanges is True in the PC config file, symlinks overwritten
  on the PC by exports are saved in __bkp__, from which they may be 
  manually restored if desired.  This is a last-resort measure.

- Utility script _etc/find-all-symlinks.py may be run manually to
  report any and all symlinks in your content copy on any device.
  Run this first if symlinks may be both present and an issue.

- Symlinks will survive a trip to and from a phone if you use Android
  app-private storage for your content, because they are supported by
  this storage type, and zipped in transit.  See the top-level folder's
  _README.html#termux-app-private-SAF for tips on using this storage.

- Though less harmful, Unix _permissions_ may also be overwritten by 
  exports from on-phone shared or app-specific storage.  This happens 
  only for files changed on the phone alone, and is an unavoidable 
  interoperability hurdle.  See  _README.html#Unix Permissions.

-----------------------------------------------------------------------
Notes:

0) "PC" here means a Windows, macOS, or Linux device, but "phone" 
can be anything: though designed to sync changes to Android 11 and 
later, these scripts can also sync to earlier Androids and PCs.

1) You can run the zip and manual-move steps here manually; this
script is simply a convenience that automates the steps and 
follows the rest of this package's motif, with error/safety checks.

2) This uses the phone config's settings unchanged, but inverts 
their meaning: "TO" (the on-phone copy) is really FROM here (it's 
what is zipped), and "FROM" is assumed to be usable for creating 
the zip (and should be optimal: use app storage instead of shared 
storage for much faster zips).

3) Caveat: exporting makes a full-content zipfile on the phone,
which is then moved to the proxy drive and unzipped on the PC.
Hence, you'll need _twice_ the size of full content on all three
devices.  This is unavoidable without on-phone POSIX USB access. 

4) This uses _uncompressed_ zips for speed; space diff is minimal,
and wouldn't help much with the preceding point.

5) This uses a bit of a hack to reuse the verify-part-1 script: 
it defines global EXPORTING and exec()s the verify script, which 
was augmented to check for the global but doesn't define it for 
its own runs, as follows (a try/except can do similar work):

    MODE = 'Export' if globals().get('EXPORTING') else 'Verify'

This allows for mode-specific message text, but should ideally 
use a function parameter instead (and do more recoding work):

    def zip_phone(mode): 
        ...entire script...
    if name == '__main__':
       zip_phone('Verify')

    from x_verify_phone_part1_phone import zip_phone
    zip_phone('Export')

6) This is named "x-export..." both because it's a lesser/secondary 
tool, and so that it appears at the end of by-name folder listings.
=======================================================================
"""


EXPORTING = True                                      # different role in messages
exec(open('x-verify-phone-part1-phone.py').read())    # Part 1 == verify: zip+copy