Support iCloud Drive "Trash" operations (enter "Trash", "Restore" files, and "Delete forever" files from Trash.) - picklepete/pyicloud#467

[ebob9]

Breaking change

There is one minor change in this PR that may break existing uses of the drive module.

Previous versions of the pyicloud drive module return root.name as "".

As part of this change, I added support to return a name for special folders (root, trash) This may break existing uses if they expect the old root.name == "" value, as it now is root.name == "root".

The test module has already been updated for this change.

Proposed change

This PR implements functions to support handling of Trash operations on iCloud Drive. Specifically:

• Accessing files in the hidden "Trash" directory.
• "Recover" files in "Trash" back to their original location.
• "Delete Forever" files in the "Trash" (instead of waiting for them to expire.)

As part of the above changes, some enhancements were added:

• drive.refresh_root() and drive.refresh_trash(): These re-load the cached _root and new _trash objects from iCloud. This is helpful if the root or trash directories change (due to new files being deleted/restored/etc.)
• Added names for root and trash when interacting with these special objects.
• Test cases for the Trash handling above
• Updated README.rst with examples.
• Created a custom_request developer function to allow devs/users to try crafting custom iCloud Drive requests without needing to rewrite the drive module. This makes it easy for advanced users/devs to quickly try out new operations.

There were also two bugs I found helpful to fix as part of the work creating this PR: #465 and #466. I submitted these as separate pull requests, as each are helpful but really independent of each other.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New service (thank you!)
• New feature (which adds functionality to an existing service)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests
• Documentation or code sample

Example of code:

Examples from README.rst:

    >>> delete_output = api.drive['Holiday Photos']['2013']['Sicily']['DSC08116.JPG'].delete()
    >>> api.drive.trash.dir()
    ['DSC08116.JPG']

    >>> delete_output = api.drive['Holiday Photos']['2013']['Sicily']['DSC08117.JPG'].delete()
    >>> api.drive.refresh_trash()
    >>> api.drive.trash.dir()
    ['DSC08116.JPG', 'DSC08117.JPG']

    >>> api.drive['Holiday Photos']['2013']['Sicily'].dir()
    []

    >>> recover_output = api.drive.trash['DSC08116.JPG'].recover()
    >>> api.drive['Holiday Photos']['2013']['Sicily'].dir()
    ['DSC08116.JPG']

    >>> api.drive.trash.dir()
    ['DSC08117.JPG']

    >>> purge_output = api.drive.trash['DSC08117.JPG'].delete_forever()
    >>> api.drive.refresh_trash()
    >>> api.drive.trash.dir()
    []

Additional information

• This PR fixes or closes issue: fixes Support iCloud Drive "Trash" operations (enter "Trash", "Restore" files, and "Delete forever" files from Trash.) #467

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
  (Note - tests/test_account.py:73: fails for me on pull of master. After this PR, all other tests & new tests pass, but tests/test_account.py:73: still fails for me.)
• There is no commented out code in this PR.
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated to README