Updated spec

Author: starforever

dropbox/base.py

@@ -14,6 +14,7 @@
     file_requests,
     files,
     paper,
+    seen_state,
     sharing,
     team,
     team_common,
@@ -143,8 +144,9 @@ def file_properties_properties_remove(self,
         remove specific property field key value pairs, see
         :meth:`file_properties_properties_update`. To update a template, see
         :meth:`file_properties_templates_update_for_user` or
-        :meth:`file_properties_templates_update_for_team`. Templates can't be
-        removed once created.
+        :meth:`file_properties_templates_update_for_team`. To remove a template,
+        see :meth:`file_properties_templates_remove_for_user` or
+        :meth:`file_properties_templates_remove_for_team`.
 
         :param str path: A unique identifier for the file or folder.
         :param list property_template_ids: A list of identifiers for a template
@@ -926,6 +928,61 @@ def files_create_folder(self,
         )
         return r
 
+    def files_create_folder_batch(self,
+                                  paths,
+                                  autorename=False,
+                                  force_async=False):
+        """
+        Create multiple folders at once. This route is asynchronous for large
+        batches, which returns a job ID immediately and runs the create folder
+        batch asynchronously. Otherwise, creates the folders and returns the
+        result synchronously for smaller inputs. You can force asynchronous
+        behaviour by using the ``CreateFolderBatchArg.force_async`` flag.  Use
+        :meth:`files_create_folder_batch_check` to check the job status.
+
+        :param list paths: List of paths to be created in the user's Dropbox.
+            Duplicate path arguments in the batch are considered only once.
+        :param bool autorename: If there's a conflict, have the Dropbox server
+            try to autorename the folder to avoid the conflict.
+        :param bool force_async: Whether to force the create to happen
+            asynchronously.
+        :rtype: :class:`dropbox.files.CreateFolderBatchLaunch`
+        """
+        arg = files.CreateFolderBatchArg(paths,
+                                         autorename,
+                                         force_async)
+        r = self.request(
+            files.create_folder_batch,
+            'files',
+            arg,
+            None,
+        )
+        return r
+
+    def files_create_folder_batch_check(self,
+                                        async_job_id):
+        """
+        Returns the status of an asynchronous job for
+        :meth:`files_create_folder_batch`. If success, it returns list of result
+        for each entry.
+
+        :param str async_job_id: Id of the asynchronous job. This is the value
+            of a response returned from the method that launched the job.
+        :rtype: :class:`dropbox.files.CreateFolderBatchJobStatus`
+        :raises: :class:`.exceptions.ApiError`
+
+        If this raises, ApiError will contain:
+            :class:`dropbox.files.PollError`
+        """
+        arg = async.PollArg(async_job_id)
+        r = self.request(
+            files.create_folder_batch_check,
+            'files',
+            arg,
+            None,
+        )
+        return r
+
     def files_create_folder_v2(self,
                                path,
                                autorename=False):
@@ -952,7 +1009,8 @@ def files_create_folder_v2(self,
         return r
 
     def files_delete(self,
-                     path):
+                     path,
+                     parent_rev=None):
         """
         Delete the file or folder at a given path. If the path is a folder, all
         its contents will be deleted too. A successful response indicates that
@@ -962,6 +1020,9 @@ def files_delete(self,
         and not a :class:`dropbox.files.DeletedMetadata` object.
 
         :param str path: Path in the user's Dropbox to delete.
+        :param Nullable parent_rev: Perform delete if given "rev" matches the
+            existing file's latest "rev". This field does not support deleting a
+            folder.
         :rtype: :class:`dropbox.files.Metadata`
         :raises: :class:`.exceptions.ApiError`
 
@@ -972,7 +1033,8 @@ def files_delete(self,
             'delete is deprecated. Use delete_v2.',
             DeprecationWarning,
         )
-        arg = files.DeleteArg(path)
+        arg = files.DeleteArg(path,
+                              parent_rev)
         r = self.request(
             files.delete,
             'files',
@@ -1025,7 +1087,8 @@ def files_delete_batch_check(self,
         return r
 
     def files_delete_v2(self,
-                        path):
+                        path,
+                        parent_rev=None):
         """
         Delete the file or folder at a given path. If the path is a folder, all
         its contents will be deleted too. A successful response indicates that
@@ -1035,13 +1098,17 @@ def files_delete_v2(self,
         and not a :class:`dropbox.files.DeletedMetadata` object.
 
         :param str path: Path in the user's Dropbox to delete.
+        :param Nullable parent_rev: Perform delete if given "rev" matches the
+            existing file's latest "rev". This field does not support deleting a
+            folder.
         :rtype: :class:`dropbox.files.DeleteResult`
         :raises: :class:`.exceptions.ApiError`
 
         If this raises, ApiError will contain:
             :class:`dropbox.files.DeleteError`
         """
-        arg = files.DeleteArg(path)
+        arg = files.DeleteArg(path,
+                              parent_rev)
         r = self.request(
             files.delete_v2,
             'files',
@@ -1299,7 +1366,8 @@ def files_get_temporary_link(self,
     def files_get_thumbnail(self,
                             path,
                             format=files.ThumbnailFormat.jpeg,
-                            size=files.ThumbnailSize.w64h64):
+                            size=files.ThumbnailSize.w64h64,
+                            mode=files.ThumbnailMode.strict):
         """
         Get a thumbnail for an image. This method currently supports files with
         the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp.
@@ -1313,6 +1381,9 @@ def files_get_thumbnail(self,
         :type format: :class:`dropbox.files.ThumbnailFormat`
         :param size: The size for the thumbnail image.
         :type size: :class:`dropbox.files.ThumbnailSize`
+        :param mode: How to resize and crop the image to achieve the desired
+            size.
+        :type mode: :class:`dropbox.files.ThumbnailMode`
         :rtype: (:class:`dropbox.files.FileMetadata`,
                  :class:`requests.models.Response`)
         :raises: :class:`.exceptions.ApiError`
@@ -1328,7 +1399,8 @@ def files_get_thumbnail(self,
         """
         arg = files.ThumbnailArg(path,
                                  format,
-                                 size)
+                                 size,
+                                 mode)
         r = self.request(
             files.get_thumbnail,
             'files',
@@ -1341,7 +1413,8 @@ def files_get_thumbnail_to_file(self,
                                     download_path,
                                     path,
                                     format=files.ThumbnailFormat.jpeg,
-                                    size=files.ThumbnailSize.w64h64):
+                                    size=files.ThumbnailSize.w64h64,
+                                    mode=files.ThumbnailMode.strict):
         """
         Get a thumbnail for an image. This method currently supports files with
         the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp.
@@ -1356,6 +1429,9 @@ def files_get_thumbnail_to_file(self,
         :type format: :class:`dropbox.files.ThumbnailFormat`
         :param size: The size for the thumbnail image.
         :type size: :class:`dropbox.files.ThumbnailSize`
+        :param mode: How to resize and crop the image to achieve the desired
+            size.
+        :type mode: :class:`dropbox.files.ThumbnailMode`
         :rtype: :class:`dropbox.files.FileMetadata`
         :raises: :class:`.exceptions.ApiError`
 
@@ -1364,7 +1440,8 @@ def files_get_thumbnail_to_file(self,
         """
         arg = files.ThumbnailArg(path,
                                  format,
-                                 size)
+                                 size,
+                                 mode)
         r = self.request(
             files.get_thumbnail,
             'files',
@@ -1790,20 +1867,25 @@ def files_move_v2(self,
         return r
 
     def files_permanently_delete(self,
-                                 path):
+                                 path,
+                                 parent_rev=None):
         """
         Permanently delete the file or folder at a given path (see
         https://www.dropbox.com/en/help/40). Note: This endpoint is only
         available for Dropbox Business apps.
 
         :param str path: Path in the user's Dropbox to delete.
+        :param Nullable parent_rev: Perform delete if given "rev" matches the
+            existing file's latest "rev". This field does not support deleting a
+            folder.
         :rtype: None
         :raises: :class:`.exceptions.ApiError`
 
         If this raises, ApiError will contain:
             :class:`dropbox.files.DeleteError`
         """
-        arg = files.DeleteArg(path)
+        arg = files.DeleteArg(path,
+                              parent_rev)
         r = self.request(
             files.permanently_delete,
             'files',
@@ -2481,7 +2563,7 @@ def paper_docs_get_folder_info(self,
         Retrieves folder information for the given Paper doc. This includes:   -
         folder sharing policy; permissions for subfolders are set by the
         top-level folder.   - full 'filepath', i.e. the list of folders (both
-        folderId and folderName) from the root folder to the folder directly
+        folderId and folderName) from     the root folder to the folder directly
         containing the Paper doc.  Note: If the Paper doc is not in any folder
         (aka unfiled) the response will be empty.
 
@@ -3815,6 +3897,36 @@ def sharing_revoke_shared_link(self,
         )
         return None
 
+    def sharing_set_access_inheritance(self,
+                                       shared_folder_id,
+                                       access_inheritance=sharing.AccessInheritance.inherit):
+        """
+        Change the inheritance policy of an existing Shared Folder. Only
+        permitted for shared folders in a shared team root. If a
+        ``ShareFolderLaunch.async_job_id`` is returned, you'll need to call
+        :meth:`sharing_check_share_job_status` until the action completes to get
+        the metadata for the folder.
+
+        :param access_inheritance: The access inheritance settings for the
+            folder.
+        :type access_inheritance: :class:`dropbox.sharing.AccessInheritance`
+        :param str shared_folder_id: The ID for the shared folder.
+        :rtype: :class:`dropbox.sharing.ShareFolderLaunch`
+        :raises: :class:`.exceptions.ApiError`
+
+        If this raises, ApiError will contain:
+            :class:`dropbox.sharing.SetAccessInheritanceError`
+        """
+        arg = sharing.SetAccessInheritanceArg(shared_folder_id,
+                                              access_inheritance)
+        r = self.request(
+            sharing.set_access_inheritance,
+            'sharing',
+            arg,
+            None,
+        )
+        return r
+
     def sharing_share_folder(self,
                              path,
                              acl_update_policy=None,
@@ -4076,7 +4188,9 @@ def team_log_get_events(self,
                             time=None,
                             category=None):
         """
-        Retrieves team events. Permission : Team Auditing.
+        Retrieves team events. Events have a lifespan of two years. Events older
+        than two years will not be returned. Many attributes note 'may be
+        missing due to historical data gap'. Permission : Team Auditing.
 
         :param long limit: Number of results to return per call.
         :param Nullable account_id: Filter the events by account ID. Return ony

dropbox/base_team.py

@@ -14,6 +14,7 @@
     file_requests,
     files,
     paper,
+    seen_state,
     sharing,
     team,
     team_common,
@@ -1501,19 +1502,23 @@ def team_team_folder_archive_check(self,
         return r
 
     def team_team_folder_create(self,
-                                name):
+                                name,
+                                sync_setting=None):
         """
         Creates a new, active, team folder with no members. Permission : Team
         member file access.
 
         :param str name: Name for the new team folder.
+        :param Nullable sync_setting: The sync setting to apply to this team
+            folder. Only permitted if the team has team selective sync enabled.
         :rtype: :class:`dropbox.team.TeamFolderMetadata`
         :raises: :class:`.exceptions.ApiError`
 
         If this raises, ApiError will contain:
             :class:`dropbox.team.TeamFolderCreateError`
         """
-        arg = team.TeamFolderCreateArg(name)
+        arg = team.TeamFolderCreateArg(name,
+                                       sync_setting)
         r = self.request(
             team.team_folder_create,
             'team',
@@ -1627,6 +1632,36 @@ def team_team_folder_rename(self,
         )
         return r
 
+    def team_team_folder_update_sync_settings(self,
+                                              team_folder_id,
+                                              sync_setting=None,
+                                              content_sync_settings=None):
+        """
+        Updates the sync settings on a team folder or its contents.  Use of this
+        endpoint requires that the team has team selective sync enabled.
+
+        :param Nullable sync_setting: Sync setting to apply to the team folder
+            itself. Only meaningful if the team folder is not a shared team
+            root.
+        :param Nullable content_sync_settings: Sync settings to apply to
+            contents of this team folder.
+        :rtype: :class:`dropbox.team.TeamFolderMetadata`
+        :raises: :class:`.exceptions.ApiError`
+
+        If this raises, ApiError will contain:
+            :class:`dropbox.team.TeamFolderUpdateSyncSettingsError`
+        """
+        arg = team.TeamFolderUpdateSyncSettingsArg(team_folder_id,
+                                                   sync_setting,
+                                                   content_sync_settings)
+        r = self.request(
+            team.team_folder_update_sync_settings,
+            'team',
+            arg,
+            None,
+        )
+        return r
+
     def team_token_get_authenticated_admin(self):
         """
         Returns the member profile of the admin who generated the team access

dropbox/file_properties.py

@@ -18,7 +18,7 @@
 
 Templates are owned either by a user/app pair or team/app pair. Templates and their associated properties can't be accessed by any app other than the app that created them, and even then, only when the app is linked with the owner of the template (either a user or team).
 
-User-owned templates are accessed via the user-auth template/*_for_user endpoints, while team-owned templates are accessed via the team-auth template/*_for_team endpoints. Properties associated with either type of template can be accessed via the user-auth properties/* endpoints.
+User-owned templates are accessed via the user-auth file_properties/templates/*_for_user endpoints, while team-owned templates are accessed via the team-auth file_properties/templates/*_for_team endpoints. Properties associated with either type of template can be accessed via the user-auth properties/* endpoints.
 
 Finally, properties can be accessed from a number of endpoints that return metadata, including `files/get_metadata`, and `files/list_folder`. Properties can also be added during upload, using `files/upload`.
 """