Welcome to pyranoid_copy’s documentation!

README

Documentation Status

What is pyranoid copy

A lightweight & granular file copy tool built for DITs and photographers.

This tool should become the sucessor to my media-copytool (which is scripted entirely in PowerShell and Windows only). The reason that I created media-copytool is because none of the existing Digital Asset Management (DAM) programs (to my knowledge) offered the options for importing files from media cards that I wanted (see Proposed features). pyranoid_copy will be written in Python to maximise compatibility.

Note that as of now, this tool is not even finished in a rough state - I am still in the progress of writing the main features and testing them.

Proposed features

  • Will work on all (desktop) OSs that are supported by Python ≥ 3.5,

  • Optimised for copying large quantities of mission critical files, e.g. wedding photos,

  • Lightweight,

  • Standalone binaries (i.e. pyranoid_copy.exe) available,

  • Highly granular controls:

    • Use one or multiple source and/or target path(s),

    • Rename files while copying them (magic strings available!),

    • Create subfolders (magic strings available!),

    • Filter files to copy – inclusion & exclusion possible,

  • Option to avoid overwriting existing files by searching iterations of the name that are not yet used,

  • Option to avoid duplicates based on:

    • a history file (user specified JSON file),

    • duplicate files in the input folder(s),

    • duplicate files in the target path,

  • Option to prevent the device from going to sleep (likely by using a built-in version of espresso-python),

  • Proper documentation (or so I hope ;-) )

Details

  • Lightweight PySimpleGUI for the parameters with CLI as option,

  • Standalone planned / as little extra dependencies as feasible (and all on pip) with decent usability (planned at the moment: tqdm required, colorama recommended, crc32c if desired) for “source” installation (i.e. not using the binaries, but the script file itself),

  • (Smart) renaming options for files and subfolders: Strftime magic strings (e.g. %Y-%m-%d for 2019-11-31),

  • Redundancy checks against history file / target-folder / multiple inputs,

  • Checking CRC32 of every file after clearing the disk cache, thus reducing the risk of a bad copy,

  • Include/exclude by regex pattern(s) (e.g. .*\.jpg - see my regex101.com example for what this does).

A high-level overview:

                            +------------+        +-------------------+
+------START-------+        | Check for  |        | Search files,     |
|./pyranoid_copy.py| -----> | parameters | -----> | then filter them* |
+------------------+        | & presets  |        +-------------------+
                            +------------+                   |
                                                             |
                                                             v
+---------------------+       +--------------+       +----------------+
| Create subfolders*, |       | Get source's |       | Deduplication- |
| check for file name | <---- | hash*        | <---- | routines*      |
| collisions*         |       +--------------+       +----------------+
+---------------------+
          |
          |
          v            +--------------+       +---------------+
+--------------+       | Get target's |       | Compare file- |
| Copy file(s) | ----> | hash*        | ----> | attributes*   |
+--------------+       +--------------+       +---------------+

* can be enabled/disabled

Installation

This will probably change once this repo is in a working state. At the moment:

# get the repository:
git clone https://github.com/flolilo/pyranoid_copy.git
cd ./pyranoid_copy

# create virtual environment, activate it:
python -m venv ./.venv
<Powershell:> & ./.venv/Scripts/activate.ps1
<sh:> source ./.venv/bin/activate

# install requirements:
python -m pip install -r ./requirements.txt

# run pyranoid_copy:
python ./pyranoid_copy.py

Contribution

You do not even need to be have a GitHub account to report issues - simply mail to pyranoid_copy@fire.fundersclub.com. (It will not publish your mail address or name!)

Please add as much information as possible - e.g. the used OS, Python version, pyranoid version, where the error occured, what the error is, …

For all versions < 0.99.x, please see TODO.rst - it may be that your issue is already seen as a milestone.

Any help would be appreciated!

Milestones

See TODO.rst.

Licenses

See LICENSE.rst - You can use all of my code under either the GNU GPLv3 or the BSD 3-Clause Clear license. Please note that third party software is used in this project, but as of now, it requires the user to download the software (and agree to the respective license agreement). If this changes in the future, it will be reflected in this document.

As coding should not be about reinventing the wheel, some code is copied verbatim (though most of the time, it does need modifications) from internet sources. See the # CREDIT: comments for links to my sources.