base.py 175 KB
Newer Older
1 2 3 4 5 6 7 8 9
# -*- coding: utf-8 -*-
# Auto-generated by Stone, do not modify.
# flake8: noqa
# pylint: skip-file

from abc import ABCMeta, abstractmethod
import warnings

from . import (
10
    async_,
11 12
    auth,
    common,
13
    contacts,
14 15
    file_properties,
    file_requests,
16 17
    files,
    paper,
18
    seen_state,
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
    sharing,
    team,
    team_common,
    team_log,
    team_policies,
    users,
    users_common,
)


class DropboxBase(object):
    __metaclass__ = ABCMeta

    @abstractmethod
    def request(self, route, namespace, arg, arg_binary=None):
        pass

    # ------------------------------------------
    # Routes in auth namespace

    def auth_token_from_oauth1(self,
                               oauth1_token,
                               oauth1_token_secret):
        """
        Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access
        token.

        :param str oauth1_token: The supplied OAuth 1.0 access token.
        :param str oauth1_token_secret: The token secret associated with the
            supplied access token.
        :rtype: :class:`dropbox.auth.TokenFromOAuth1Result`
50
        :raises: :class:`.exceptions.ApiError`
51

52
        If this raises, ApiError will contain:
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
            :class:`dropbox.auth.TokenFromOAuth1Error`
        """
        arg = auth.TokenFromOAuth1Arg(oauth1_token,
                                      oauth1_token_secret)
        r = self.request(
            auth.token_from_oauth1,
            'auth',
            arg,
            None,
        )
        return r

    def auth_token_revoke(self):
        """
        Disables the access token used to authenticate the call.

        :rtype: None
        """
        arg = None
        r = self.request(
            auth.token_revoke,
            'auth',
            arg,
            None,
        )
        return None

80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121
    # ------------------------------------------
    # Routes in contacts namespace

    def contacts_delete_manual_contacts(self):
        """
        Removes all manually added contacts. You'll still keep contacts who are
        on your team or who you imported. New contacts will be added when you
        share.

        :rtype: None
        """
        arg = None
        r = self.request(
            contacts.delete_manual_contacts,
            'contacts',
            arg,
            None,
        )
        return None

    def contacts_delete_manual_contacts_batch(self,
                                              email_addresses):
        """
        Removes manually added contacts from the given list.

        :param list email_addresses: List of manually added contacts to be
            deleted.
        :rtype: None
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.contacts.DeleteManualContactsError`
        """
        arg = contacts.DeleteManualContactsArg(email_addresses)
        r = self.request(
            contacts.delete_manual_contacts_batch,
            'contacts',
            arg,
            None,
        )
        return None

122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
    # ------------------------------------------
    # Routes in file_properties namespace

    def file_properties_properties_add(self,
                                       path,
                                       property_groups):
        """
        Add property groups to a Dropbox file. See
        :meth:`file_properties_templates_add_for_user` or
        :meth:`file_properties_templates_add_for_team` to create new templates.

        :param str path: A unique identifier for the file or folder.
        :param list property_groups: The property groups which are to be added
            to a Dropbox file.
        :rtype: None
137
        :raises: :class:`.exceptions.ApiError`
138

139
        If this raises, ApiError will contain:
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
            :class:`dropbox.file_properties.AddPropertiesError`
        """
        arg = file_properties.AddPropertiesArg(path,
                                               property_groups)
        r = self.request(
            file_properties.properties_add,
            'file_properties',
            arg,
            None,
        )
        return None

    def file_properties_properties_overwrite(self,
                                             path,
                                             property_groups):
        """
        Overwrite property groups associated with a file. This endpoint should
        be used instead of :meth:`file_properties_properties_update` when
        property groups are being updated via a "snapshot" instead of via a
        "delta". In other words, this endpoint will delete all omitted fields
        from a property group, whereas :meth:`file_properties_properties_update`
        will only delete fields that are explicitly marked for deletion.

        :param str path: A unique identifier for the file or folder.
        :param list property_groups: The property groups "snapshot" updates to
            force apply.
        :rtype: None
167
        :raises: :class:`.exceptions.ApiError`
168

169
        If this raises, ApiError will contain:
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
            :class:`dropbox.file_properties.InvalidPropertyGroupError`
        """
        arg = file_properties.OverwritePropertyGroupArg(path,
                                                        property_groups)
        r = self.request(
            file_properties.properties_overwrite,
            'file_properties',
            arg,
            None,
        )
        return None

    def file_properties_properties_remove(self,
                                          path,
                                          property_template_ids):
        """
186 187
        Permanently removes the specified property group from the file. To
        remove specific property field key value pairs, see
188 189
        :meth:`file_properties_properties_update`. To update a template, see
        :meth:`file_properties_templates_update_for_user` or
190 191 192
        :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`.
193 194 195 196 197 198

        :param str path: A unique identifier for the file or folder.
        :param list property_template_ids: A list of identifiers for a template
            created by :meth:`file_properties_templates_add_for_user` or
            :meth:`file_properties_templates_add_for_team`.
        :rtype: None
199
        :raises: :class:`.exceptions.ApiError`
200

201
        If this raises, ApiError will contain:
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
            :class:`dropbox.file_properties.RemovePropertiesError`
        """
        arg = file_properties.RemovePropertiesArg(path,
                                                  property_template_ids)
        r = self.request(
            file_properties.properties_remove,
            'file_properties',
            arg,
            None,
        )
        return None

    def file_properties_properties_search(self,
                                          queries,
                                          template_filter=file_properties.TemplateFilter.filter_none):
        """
        Search across property templates for particular property field values.

        :param list queries: Queries to search.
        :param template_filter: Filter results to contain only properties
            associated with these template IDs.
        :type template_filter: :class:`dropbox.file_properties.TemplateFilter`
        :rtype: :class:`dropbox.file_properties.PropertiesSearchResult`
225
        :raises: :class:`.exceptions.ApiError`
226

227
        If this raises, ApiError will contain:
228 229 230 231 232 233 234 235 236 237 238 239
            :class:`dropbox.file_properties.PropertiesSearchError`
        """
        arg = file_properties.PropertiesSearchArg(queries,
                                                  template_filter)
        r = self.request(
            file_properties.properties_search,
            'file_properties',
            arg,
            None,
        )
        return r

240 241 242 243 244 245 246 247 248 249 250
    def file_properties_properties_search_continue(self,
                                                   cursor):
        """
        Once a cursor has been retrieved from
        :meth:`file_properties_properties_search`, use this to paginate through
        all search results.

        :param str cursor: The cursor returned by your last call to
            :meth:`file_properties_properties_search` or
            :meth:`file_properties_properties_search_continue`.
        :rtype: :class:`dropbox.file_properties.PropertiesSearchResult`
251
        :raises: :class:`.exceptions.ApiError`
252

253
        If this raises, ApiError will contain:
254 255 256 257 258 259 260 261 262 263 264
            :class:`dropbox.file_properties.PropertiesSearchContinueError`
        """
        arg = file_properties.PropertiesSearchContinueArg(cursor)
        r = self.request(
            file_properties.properties_search_continue,
            'file_properties',
            arg,
            None,
        )
        return r

265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280
    def file_properties_properties_update(self,
                                          path,
                                          update_property_groups):
        """
        Add, update or remove properties associated with the supplied file and
        templates. This endpoint should be used instead of
        :meth:`file_properties_properties_overwrite` when property groups are
        being updated via a "delta" instead of via a "snapshot" . In other
        words, this endpoint will not delete any omitted fields from a property
        group, whereas :meth:`file_properties_properties_overwrite` will delete
        any fields that are omitted from a property group.

        :param str path: A unique identifier for the file or folder.
        :param list update_property_groups: The property groups "delta" updates
            to apply.
        :rtype: None
281
        :raises: :class:`.exceptions.ApiError`
282

283
        If this raises, ApiError will contain:
284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305
            :class:`dropbox.file_properties.UpdatePropertiesError`
        """
        arg = file_properties.UpdatePropertiesArg(path,
                                                  update_property_groups)
        r = self.request(
            file_properties.properties_update,
            'file_properties',
            arg,
            None,
        )
        return None

    def file_properties_templates_add_for_user(self,
                                               name,
                                               description,
                                               fields):
        """
        Add a template associated with a user. See
        :meth:`file_properties_properties_add` to add properties to a file. This
        endpoint can't be called on a team member or admin's behalf.

        :rtype: :class:`dropbox.file_properties.AddTemplateResult`
306
        :raises: :class:`.exceptions.ApiError`
307

308
        If this raises, ApiError will contain:
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
            :class:`dropbox.file_properties.ModifyTemplateError`
        """
        arg = file_properties.AddTemplateArg(name,
                                             description,
                                             fields)
        r = self.request(
            file_properties.templates_add_for_user,
            'file_properties',
            arg,
            None,
        )
        return r

    def file_properties_templates_get_for_user(self,
                                               template_id):
        """
        Get the schema for a specified template. This endpoint can't be called
        on a team member or admin's behalf.

        :param str template_id: An identifier for template added by route  See
            :meth:`file_properties_templates_add_for_user` or
            :meth:`file_properties_templates_add_for_team`.
        :rtype: :class:`dropbox.file_properties.GetTemplateResult`
332
        :raises: :class:`.exceptions.ApiError`
333

334
        If this raises, ApiError will contain:
335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352
            :class:`dropbox.file_properties.TemplateError`
        """
        arg = file_properties.GetTemplateArg(template_id)
        r = self.request(
            file_properties.templates_get_for_user,
            'file_properties',
            arg,
            None,
        )
        return r

    def file_properties_templates_list_for_user(self):
        """
        Get the template identifiers for a team. To get the schema of each
        template use :meth:`file_properties_templates_get_for_user`. This
        endpoint can't be called on a team member or admin's behalf.

        :rtype: :class:`dropbox.file_properties.ListTemplateResult`
353
        :raises: :class:`.exceptions.ApiError`
354

355
        If this raises, ApiError will contain:
356 357 358 359 360 361 362 363 364 365 366
            :class:`dropbox.file_properties.TemplateError`
        """
        arg = None
        r = self.request(
            file_properties.templates_list_for_user,
            'file_properties',
            arg,
            None,
        )
        return r

367 368 369 370 371 372 373 374 375 376 377 378
    def file_properties_templates_remove_for_user(self,
                                                  template_id):
        """
        Permanently removes the specified template created from
        :meth:`file_properties_templates_add_for_user`. All properties
        associated with the template will also be removed. This action cannot be
        undone.

        :param str template_id: An identifier for a template created by
            :meth:`file_properties_templates_add_for_user` or
            :meth:`file_properties_templates_add_for_team`.
        :rtype: None
379
        :raises: :class:`.exceptions.ApiError`
380

381
        If this raises, ApiError will contain:
382 383 384 385 386 387 388 389 390 391 392
            :class:`dropbox.file_properties.TemplateError`
        """
        arg = file_properties.RemoveTemplateArg(template_id)
        r = self.request(
            file_properties.templates_remove_for_user,
            'file_properties',
            arg,
            None,
        )
        return None

393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414
    def file_properties_templates_update_for_user(self,
                                                  template_id,
                                                  name=None,
                                                  description=None,
                                                  add_fields=None):
        """
        Update a template associated with a user. This route can update the
        template name, the template description and add optional properties to
        templates. This endpoint can't be called on a team member or admin's
        behalf.

        :param str template_id: An identifier for template added by  See
            :meth:`file_properties_templates_add_for_user` or
            :meth:`file_properties_templates_add_for_team`.
        :param Nullable name: A display name for the template. template names
            can be up to 256 bytes.
        :param Nullable description: Description for the new template. Template
            descriptions can be up to 1024 bytes.
        :param Nullable add_fields: Property field templates to be added to the
            group template. There can be up to 32 properties in a single
            template.
        :rtype: :class:`dropbox.file_properties.UpdateTemplateResult`
415
        :raises: :class:`.exceptions.ApiError`
416

417
        If this raises, ApiError will contain:
418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434
            :class:`dropbox.file_properties.ModifyTemplateError`
        """
        arg = file_properties.UpdateTemplateArg(template_id,
                                                name,
                                                description,
                                                add_fields)
        r = self.request(
            file_properties.templates_update_for_user,
            'file_properties',
            arg,
            None,
        )
        return r

    # ------------------------------------------
    # Routes in file_requests namespace

435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450
    def file_requests_count(self):
        """
        Returns the total number of file requests owned by this user. Includes
        both open and closed file requests.

        :rtype: :class:`dropbox.file_requests.CountFileRequestsResult`
        """
        arg = None
        r = self.request(
            file_requests.count,
            'file_requests',
            arg,
            None,
        )
        return r

451 452 453 454 455 456 457 458 459 460 461 462 463
    def file_requests_create(self,
                             title,
                             destination,
                             deadline=None,
                             open=True):
        """
        Creates a file request for this user.

        :param str title: The title of the file request. Must not be empty.
        :param str destination: The path of the folder in the Dropbox where
            uploaded files will be sent. For apps with the app folder
            permission, this will be relative to the app folder.
        :param Nullable deadline: The deadline for the file request. Deadlines
464
            can only be set by Professional and Business accounts.
465 466 467 468
        :param bool open: Whether or not the file request should be open. If the
            file request is closed, it will not accept any file submissions, but
            it can be opened later.
        :rtype: :class:`dropbox.file_requests.FileRequest`
469
        :raises: :class:`.exceptions.ApiError`
470

471
        If this raises, ApiError will contain:
472 473 474 475 476 477 478 479 480 481 482 483 484 485
            :class:`dropbox.file_requests.CreateFileRequestError`
        """
        arg = file_requests.CreateFileRequestArgs(title,
                                                  destination,
                                                  deadline,
                                                  open)
        r = self.request(
            file_requests.create,
            'file_requests',
            arg,
            None,
        )
        return r

486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521
    def file_requests_delete(self,
                             ids):
        """
        Delete a batch of closed file requests.

        :param list ids: List IDs of the file requests to delete.
        :rtype: :class:`dropbox.file_requests.DeleteFileRequestsResult`
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.file_requests.DeleteFileRequestError`
        """
        arg = file_requests.DeleteFileRequestArgs(ids)
        r = self.request(
            file_requests.delete,
            'file_requests',
            arg,
            None,
        )
        return r

    def file_requests_delete_all_closed(self):
        """
        Delete all closed file requests owned by this user.

        :rtype: :class:`dropbox.file_requests.DeleteAllClosedFileRequestsResult`
        """
        arg = None
        r = self.request(
            file_requests.delete_all_closed,
            'file_requests',
            arg,
            None,
        )
        return r

522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538
    def file_requests_get(self,
                          id):
        """
        Returns the specified file request.

        :param str id: The ID of the file request to retrieve.
        :rtype: :class:`dropbox.file_requests.FileRequest`
        """
        arg = file_requests.GetFileRequestArgs(id)
        r = self.request(
            file_requests.get,
            'file_requests',
            arg,
            None,
        )
        return r

539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558
    def file_requests_list_v2(self,
                              limit=1000):
        """
        Returns a list of file requests owned by this user. For apps with the
        app folder permission, this will only return file requests with
        destinations in the app folder.

        :param int limit: The maximum number of file requests that should be
            returned per request.
        :rtype: :class:`dropbox.file_requests.ListFileRequestsV2Result`
        """
        arg = file_requests.ListFileRequestsArg(limit)
        r = self.request(
            file_requests.list_v2,
            'file_requests',
            arg,
            None,
        )
        return r

559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575
    def file_requests_list(self):
        """
        Returns a list of file requests owned by this user. For apps with the
        app folder permission, this will only return file requests with
        destinations in the app folder.

        :rtype: :class:`dropbox.file_requests.ListFileRequestsResult`
        """
        arg = None
        r = self.request(
            file_requests.list,
            'file_requests',
            arg,
            None,
        )
        return r

576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600
    def file_requests_list_continue(self,
                                    cursor):
        """
        Once a cursor has been retrieved from :meth:`file_requests_list_v2`, use
        this to paginate through all file requests. The cursor must come from a
        previous call to :meth:`file_requests_list_v2` or
        :meth:`file_requests_list_continue`.

        :param str cursor: The cursor returned by the previous API call
            specified in the endpoint description.
        :rtype: :class:`dropbox.file_requests.ListFileRequestsV2Result`
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.file_requests.ListFileRequestsContinueError`
        """
        arg = file_requests.ListFileRequestsContinueArg(cursor)
        r = self.request(
            file_requests.list_continue,
            'file_requests',
            arg,
            None,
        )
        return r

601 602 603 604 605 606 607 608 609 610 611 612 613 614 615
    def file_requests_update(self,
                             id,
                             title=None,
                             destination=None,
                             deadline=file_requests.UpdateFileRequestDeadline.no_update,
                             open=None):
        """
        Update a file request.

        :param str id: The ID of the file request to update.
        :param Nullable title: The new title of the file request. Must not be
            empty.
        :param Nullable destination: The new path of the folder in the Dropbox
            where uploaded files will be sent. For apps with the app folder
            permission, this will be relative to the app folder.
616 617
        :param deadline: The new deadline for the file request. Deadlines can
            only be set by Professional and Business accounts.
618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635
        :type deadline: :class:`dropbox.file_requests.UpdateFileRequestDeadline`
        :param Nullable open: Whether to set this file request as open or
            closed.
        :rtype: :class:`dropbox.file_requests.FileRequest`
        """
        arg = file_requests.UpdateFileRequestArgs(id,
                                                  title,
                                                  destination,
                                                  deadline,
                                                  open)
        r = self.request(
            file_requests.update,
            'file_requests',
            arg,
            None,
        )
        return r

636 637 638 639 640 641 642 643
    # ------------------------------------------
    # Routes in files namespace

    def files_alpha_get_metadata(self,
                                 path,
                                 include_media_info=False,
                                 include_deleted=False,
                                 include_has_explicit_shared_members=False,
644
                                 include_property_groups=None,
645 646 647 648 649 650 651 652 653 654
                                 include_property_templates=None):
        """
        Returns the metadata for a file or folder. This is an alpha endpoint
        compatible with the properties API. Note: Metadata for the root folder
        is unsupported.

        :param Nullable include_property_templates: If set to a valid list of
            template IDs, ``FileMetadata.property_groups`` is set for files with
            custom properties.
        :rtype: :class:`dropbox.files.Metadata`
655
        :raises: :class:`.exceptions.ApiError`
656

657
        If this raises, ApiError will contain:
658 659
            :class:`dropbox.files.AlphaGetMetadataError`
        """
660 661 662 663
        warnings.warn(
            'alpha/get_metadata is deprecated. Use get_metadata.',
            DeprecationWarning,
        )
664 665 666 667
        arg = files.AlphaGetMetadataArg(path,
                                        include_media_info,
                                        include_deleted,
                                        include_has_explicit_shared_members,
668
                                        include_property_groups,
669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684
                                        include_property_templates)
        r = self.request(
            files.alpha_get_metadata,
            'files',
            arg,
            None,
        )
        return r

    def files_alpha_upload(self,
                           f,
                           path,
                           mode=files.WriteMode.add,
                           autorename=False,
                           client_modified=None,
                           mute=False,
685 686
                           property_groups=None,
                           strict_conflict=False):
687 688 689 690 691 692 693 694 695 696
        """
        Create a new file with the contents provided in the request. Note that
        this endpoint is part of the properties API alpha and is slightly
        different from :meth:`files_upload`. Do not use this to upload a file
        larger than 150 MB. Instead, create an upload session with
        :meth:`files_upload_session_start`.

        :param bytes f: Contents to upload.
        :rtype: :class:`dropbox.files.FileMetadata`
        """
697 698 699 700
        warnings.warn(
            'alpha/upload is deprecated. Use alpha/upload.',
            DeprecationWarning,
        )
701 702 703 704 705
        arg = files.CommitInfoWithProperties(path,
                                             mode,
                                             autorename,
                                             client_modified,
                                             mute,
706 707
                                             property_groups,
                                             strict_conflict)
708 709 710 711 712 713 714 715
        r = self.request(
            files.alpha_upload,
            'files',
            arg,
            f,
        )
        return r

716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754
    def files_copy_v2(self,
                      from_path,
                      to_path,
                      allow_shared_folder=False,
                      autorename=False,
                      allow_ownership_transfer=False):
        """
        Copy a file or folder to a different location in the user's Dropbox. If
        the source path is a folder all its contents will be copied.

        :param bool allow_shared_folder: If true, :meth:`files_copy` will copy
            contents in shared folder, otherwise
            ``RelocationError.cant_copy_shared_folder`` will be returned if
            ``from_path`` contains shared folder. This field is always true for
            :meth:`files_move`.
        :param bool autorename: If there's a conflict, have the Dropbox server
            try to autorename the file to avoid the conflict.
        :param bool allow_ownership_transfer: Allow moves by owner even if it
            would result in an ownership transfer for the content being moved.
            This does not apply to copies.
        :rtype: :class:`dropbox.files.RelocationResult`
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.files.RelocationError`
        """
        arg = files.RelocationArg(from_path,
                                  to_path,
                                  allow_shared_folder,
                                  autorename,
                                  allow_ownership_transfer)
        r = self.request(
            files.copy_v2,
            'files',
            arg,
            None,
        )
        return r

755 756 757 758
    def files_copy(self,
                   from_path,
                   to_path,
                   allow_shared_folder=False,
759 760
                   autorename=False,
                   allow_ownership_transfer=False):
761 762 763 764 765 766 767 768 769 770 771
        """
        Copy a file or folder to a different location in the user's Dropbox. If
        the source path is a folder all its contents will be copied.

        :param bool allow_shared_folder: If true, :meth:`files_copy` will copy
            contents in shared folder, otherwise
            ``RelocationError.cant_copy_shared_folder`` will be returned if
            ``from_path`` contains shared folder. This field is always true for
            :meth:`files_move`.
        :param bool autorename: If there's a conflict, have the Dropbox server
            try to autorename the file to avoid the conflict.
772 773 774
        :param bool allow_ownership_transfer: Allow moves by owner even if it
            would result in an ownership transfer for the content being moved.
            This does not apply to copies.
775
        :rtype: :class:`dropbox.files.Metadata`
776
        :raises: :class:`.exceptions.ApiError`
777

778
        If this raises, ApiError will contain:
779 780
            :class:`dropbox.files.RelocationError`
        """
781
        warnings.warn(
782
            'copy is deprecated. Use copy.',
783 784
            DeprecationWarning,
        )
785 786 787
        arg = files.RelocationArg(from_path,
                                  to_path,
                                  allow_shared_folder,
788 789
                                  autorename,
                                  allow_ownership_transfer)
790 791 792 793 794 795 796 797
        r = self.request(
            files.copy,
            'files',
            arg,
            None,
        )
        return r

798 799 800 801 802 803
    def files_copy_batch_v2(self,
                            entries,
                            autorename=False):
        """
        Copy multiple files or folders to different locations at once in the
        user's Dropbox. This route will replace :meth:`files_copy_batch`. The
804
        main difference is this route will return status for each entry, while
805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825
        :meth:`files_copy_batch` raises failure if any entry fails. This route
        will either finish synchronously, or return a job ID and do the async
        copy job in background. Please use :meth:`files_copy_batch_check_v2` to
        check the job status.

        :param list entries: List of entries to be moved or copied. Each entry
            is :class:`dropbox.files.RelocationPath`.
        :param bool autorename: If there's a conflict with any file, have the
            Dropbox server try to autorename that file to avoid the conflict.
        :rtype: :class:`dropbox.files.RelocationBatchV2Launch`
        """
        arg = files.RelocationBatchArgBase(entries,
                                           autorename)
        r = self.request(
            files.copy_batch_v2,
            'files',
            arg,
            None,
        )
        return r

826 827
    def files_copy_batch(self,
                         entries,
828
                         autorename=False,
829
                         allow_shared_folder=False,
830
                         allow_ownership_transfer=False):
831 832 833
        """
        Copy multiple files or folders to different locations at once in the
        user's Dropbox. If ``RelocationBatchArg.allow_shared_folder`` is false,
834 835 836 837 838
        this route is atomic. If one entry fails, the whole transaction will
        abort. If ``RelocationBatchArg.allow_shared_folder`` is true, atomicity
        is not guaranteed, but it allows you to copy the contents of shared
        folders to new locations. This route will return job ID immediately and
        do the async copy job in background. Please use
839 840 841 842 843
        :meth:`files_copy_batch_check` to check the job status.

        :param bool allow_shared_folder: If true, :meth:`files_copy_batch` will
            copy contents in shared folder, otherwise
            ``RelocationError.cant_copy_shared_folder`` will be returned if
844
            ``RelocationPath.from_path`` contains shared folder. This field is
845
            always true for :meth:`files_move_batch`.
846 847 848
        :param bool allow_ownership_transfer: Allow moves by owner even if it
            would result in an ownership transfer for the content being moved.
            This does not apply to copies.
849 850
        :rtype: :class:`dropbox.files.RelocationBatchLaunch`
        """
851 852 853 854
        warnings.warn(
            'copy_batch is deprecated. Use copy_batch.',
            DeprecationWarning,
        )
855
        arg = files.RelocationBatchArg(entries,
856
                                       autorename,
857
                                       allow_shared_folder,
858
                                       allow_ownership_transfer)
859 860 861 862 863 864 865 866
        r = self.request(
            files.copy_batch,
            'files',
            arg,
            None,
        )
        return r

867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889
    def files_copy_batch_check_v2(self,
                                  async_job_id):
        """
        Returns the status of an asynchronous job for
        :meth:`files_copy_batch_v2`. It returns list of results 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.RelocationBatchV2JobStatus`
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.files.PollError`
        """
        arg = async_.PollArg(async_job_id)
        r = self.request(
            files.copy_batch_check_v2,
            'files',
            arg,
            None,
        )
        return r

890 891 892 893 894 895 896 897 898
    def files_copy_batch_check(self,
                               async_job_id):
        """
        Returns the status of an asynchronous job for :meth:`files_copy_batch`.
        If success, it returns list of results 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.RelocationBatchJobStatus`
899
        :raises: :class:`.exceptions.ApiError`
900

901
        If this raises, ApiError will contain:
902 903
            :class:`dropbox.files.PollError`
        """
904 905 906 907
        warnings.warn(
            'copy_batch/check is deprecated. Use copy_batch/check.',
            DeprecationWarning,
        )
908
        arg = async_.PollArg(async_job_id)
909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926
        r = self.request(
            files.copy_batch_check,
            'files',
            arg,
            None,
        )
        return r

    def files_copy_reference_get(self,
                                 path):
        """
        Get a copy reference to a file or folder. This reference string can be
        used to save that file or folder to another user's Dropbox by passing it
        to :meth:`files_copy_reference_save`.

        :param str path: The path to the file or folder you want to get a copy
            reference to.
        :rtype: :class:`dropbox.files.GetCopyReferenceResult`
927
        :raises: :class:`.exceptions.ApiError`
928

929
        If this raises, ApiError will contain:
930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951
            :class:`dropbox.files.GetCopyReferenceError`
        """
        arg = files.GetCopyReferenceArg(path)
        r = self.request(
            files.copy_reference_get,
            'files',
            arg,
            None,
        )
        return r

    def files_copy_reference_save(self,
                                  copy_reference,
                                  path):
        """
        Save a copy reference returned by :meth:`files_copy_reference_get` to
        the user's Dropbox.

        :param str copy_reference: A copy reference returned by
            :meth:`files_copy_reference_get`.
        :param str path: Path in the user's Dropbox that is the destination.
        :rtype: :class:`dropbox.files.SaveCopyReferenceResult`
952
        :raises: :class:`.exceptions.ApiError`
953

954
        If this raises, ApiError will contain:
955 956 957 958 959 960 961 962 963 964 965 966
            :class:`dropbox.files.SaveCopyReferenceError`
        """
        arg = files.SaveCopyReferenceArg(copy_reference,
                                         path)
        r = self.request(
            files.copy_reference_save,
            'files',
            arg,
            None,
        )
        return r

967 968 969
    def files_create_folder_v2(self,
                               path,
                               autorename=False):
970
        """
971
        Create a folder at a given path.
972

973
        :param str path: Path in the user's Dropbox to create.
974
        :param bool autorename: If there's a conflict, have the Dropbox server
975 976
            try to autorename the folder to avoid the conflict.
        :rtype: :class:`dropbox.files.CreateFolderResult`
977
        :raises: :class:`.exceptions.ApiError`
978

979
        If this raises, ApiError will contain:
980
            :class:`dropbox.files.CreateFolderError`
981
        """
982 983
        arg = files.CreateFolderArg(path,
                                    autorename)
984
        r = self.request(
985
            files.create_folder_v2,
986 987 988 989 990 991
            'files',
            arg,
            None,
        )
        return r

992 993 994 995 996 997 998 999 1000 1001
    def files_create_folder(self,
                            path,
                            autorename=False):
        """
        Create a folder at a given path.

        :param str path: Path in the user's Dropbox to create.
        :param bool autorename: If there's a conflict, have the Dropbox server
            try to autorename the folder to avoid the conflict.
        :rtype: :class:`dropbox.files.FolderMetadata`
1002
        :raises: :class:`.exceptions.ApiError`
1003

1004
        If this raises, ApiError will contain:
1005 1006
            :class:`dropbox.files.CreateFolderError`
        """
1007
        warnings.warn(
1008
            'create_folder is deprecated. Use create_folder.',
1009 1010
            DeprecationWarning,
        )
1011 1012 1013 1014 1015 1016 1017 1018 1019 1020
        arg = files.CreateFolderArg(path,
                                    autorename)
        r = self.request(
            files.create_folder,
            'files',
            arg,
            None,
        )
        return r

1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075
    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

1076 1077 1078
    def files_delete_v2(self,
                        path,
                        parent_rev=None):
1079
        """
1080 1081 1082 1083 1084 1085
        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
        the file or folder was deleted. The returned metadata will be the
        corresponding :class:`dropbox.files.FileMetadata` or
        :class:`dropbox.files.FolderMetadata` for the item at time of deletion,
        and not a :class:`dropbox.files.DeletedMetadata` object.
1086

1087 1088 1089 1090 1091
        :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`
1092
        :raises: :class:`.exceptions.ApiError`
1093

1094
        If this raises, ApiError will contain:
1095
            :class:`dropbox.files.DeleteError`
1096
        """
1097 1098
        arg = files.DeleteArg(path,
                              parent_rev)
1099
        r = self.request(
1100
            files.delete_v2,
1101 1102 1103 1104 1105 1106
            'files',
            arg,
            None,
        )
        return r

1107
    def files_delete(self,
1108 1109
                     path,
                     parent_rev=None):
1110 1111 1112 1113 1114 1115 1116 1117 1118
        """
        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
        the file or folder was deleted. The returned metadata will be the
        corresponding :class:`dropbox.files.FileMetadata` or
        :class:`dropbox.files.FolderMetadata` for the item at time of deletion,
        and not a :class:`dropbox.files.DeletedMetadata` object.

        :param str path: Path in the user's Dropbox to delete.
1119 1120 1121
        :param Nullable parent_rev: Perform delete if given "rev" matches the
            existing file's latest "rev". This field does not support deleting a
            folder.
1122
        :rtype: :class:`dropbox.files.Metadata`
1123
        :raises: :class:`.exceptions.ApiError`
1124

1125
        If this raises, ApiError will contain:
1126 1127
            :class:`dropbox.files.DeleteError`
        """
1128
        warnings.warn(
1129
            'delete is deprecated. Use delete.',
1130 1131
            DeprecationWarning,
        )
1132 1133
        arg = files.DeleteArg(path,
                              parent_rev)
1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170
        r = self.request(
            files.delete,
            'files',
            arg,
            None,
        )
        return r

    def files_delete_batch(self,
                           entries):
        """
        Delete multiple files/folders at once. This route is asynchronous, which
        returns a job ID immediately and runs the delete batch asynchronously.
        Use :meth:`files_delete_batch_check` to check the job status.

        :type entries: list
        :rtype: :class:`dropbox.files.DeleteBatchLaunch`
        """
        arg = files.DeleteBatchArg(entries)
        r = self.request(
            files.delete_batch,
            'files',
            arg,
            None,
        )
        return r

    def files_delete_batch_check(self,
                                 async_job_id):
        """
        Returns the status of an asynchronous job for
        :meth:`files_delete_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.DeleteBatchJobStatus`
1171
        :raises: :class:`.exceptions.ApiError`
1172

1173
        If this raises, ApiError will contain:
1174 1175
            :class:`dropbox.files.PollError`
        """
1176
        arg = async_.PollArg(async_job_id)
1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191
        r = self.request(
            files.delete_batch_check,
            'files',
            arg,
            None,
        )
        return r

    def files_download(self,
                       path,
                       rev=None):
        """
        Download a file from a user's Dropbox.

        :param str path: The path of the file to download.
1192
        :param Nullable rev: Please specify revision in ``path`` instead.
1193 1194
        :rtype: (:class:`dropbox.files.FileMetadata`,
                 :class:`requests.models.Response`)
1195
        :raises: :class:`.exceptions.ApiError`
1196

1197
        If this raises, ApiError will contain:
1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224
            :class:`dropbox.files.DownloadError`

        If you do not consume the entire response body, then you must call close
        on the response object, otherwise you will max out your available
        connections. We recommend using the `contextlib.closing
        <https://docs.python.org/2/library/contextlib.html#contextlib.closing>`_
        context manager to ensure this.
        """
        arg = files.DownloadArg(path,
                                rev)
        r = self.request(
            files.download,
            'files',
            arg,
            None,
        )
        return r

    def files_download_to_file(self,
                               download_path,
                               path,
                               rev=None):
        """
        Download a file from a user's Dropbox.

        :param str download_path: Path on local machine to save file.
        :param str path: The path of the file to download.
1225
        :param Nullable rev: Please specify revision in ``path`` instead.
1226 1227
        :rtype: :class:`dropbox.files.FileMetadata`
        :raises: :class:`.exceptions.ApiError`
1228

1229
        If this raises, ApiError will contain:
1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242
            :class:`dropbox.files.DownloadError`
        """
        arg = files.DownloadArg(path,
                                rev)
        r = self.request(
            files.download,
            'files',
            arg,
            None,
        )
        self._save_body_to_file(download_path, r[1])
        return r[0]

1243 1244 1245 1246
    def files_download_zip(self,
                           path):
        """
        Download a folder from the user's Dropbox, as a zip file. The folder
1247 1248 1249
        must be less than 20 GB in size and have fewer than 10,000 total files.
        The input cannot be a single file. Any single file must be less than 4GB
        in size.
1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278

        :param str path: The path of the folder to download.
        :rtype: (:class:`dropbox.files.DownloadZipResult`,
                 :class:`requests.models.Response`)
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.files.DownloadZipError`

        If you do not consume the entire response body, then you must call close
        on the response object, otherwise you will max out your available
        connections. We recommend using the `contextlib.closing
        <https://docs.python.org/2/library/contextlib.html#contextlib.closing>`_
        context manager to ensure this.
        """
        arg = files.DownloadZipArg(path)
        r = self.request(
            files.download_zip,
            'files',
            arg,
            None,
        )
        return r

    def files_download_zip_to_file(self,
                                   download_path,
                                   path):
        """
        Download a folder from the user's Dropbox, as a zip file. The folder
1279 1280 1281
        must be less than 20 GB in size and have fewer than 10,000 total files.
        The input cannot be a single file. Any single file must be less than 4GB
        in size.
1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300

        :param str download_path: Path on local machine to save file.
        :param str path: The path of the folder to download.
        :rtype: :class:`dropbox.files.DownloadZipResult`
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.files.DownloadZipError`
        """
        arg = files.DownloadZipArg(path)
        r = self.request(
            files.download_zip,
            'files',
            arg,
            None,
        )
        self._save_body_to_file(download_path, r[1])
        return r[0]

1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356
    def files_export(self,
                     path):
        """
        Export a file from a user's Dropbox. This route only supports exporting
        files that cannot be downloaded directly  and whose
        ``ExportResult.file_metadata`` has ``ExportInfo.export_as`` populated.

        :param str path: The path of the file to be exported.
        :rtype: (:class:`dropbox.files.ExportResult`,
                 :class:`requests.models.Response`)
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.files.ExportError`

        If you do not consume the entire response body, then you must call close
        on the response object, otherwise you will max out your available
        connections. We recommend using the `contextlib.closing
        <https://docs.python.org/2/library/contextlib.html#contextlib.closing>`_
        context manager to ensure this.
        """
        arg = files.ExportArg(path)
        r = self.request(
            files.export,
            'files',
            arg,
            None,
        )
        return r

    def files_export_to_file(self,
                             download_path,
                             path):
        """
        Export a file from a user's Dropbox. This route only supports exporting
        files that cannot be downloaded directly  and whose
        ``ExportResult.file_metadata`` has ``ExportInfo.export_as`` populated.

        :param str download_path: Path on local machine to save file.
        :param str path: The path of the file to be exported.
        :rtype: :class:`dropbox.files.ExportResult`
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.files.ExportError`
        """
        arg = files.ExportArg(path)
        r = self.request(
            files.export,
            'files',
            arg,
            None,
        )
        self._save_body_to_file(download_path, r[1])
        return r[0]

1357 1358 1359 1360
    def files_get_metadata(self,
                           path,
                           include_media_info=False,
                           include_deleted=False,
1361 1362
                           include_has_explicit_shared_members=False,
                           include_property_groups=None):
1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376
        """
        Returns the metadata for a file or folder. Note: Metadata for the root
        folder is unsupported.

        :param str path: The path of a file or folder on Dropbox.
        :param bool include_media_info: If true, ``FileMetadata.media_info`` is
            set for photo and video.
        :param bool include_deleted: If true,
            :class:`dropbox.files.DeletedMetadata` will be returned for deleted
            file or folder, otherwise ``LookupError.not_found`` will be
            returned.
        :param bool include_has_explicit_shared_members: If true, the results
            will include a flag for each file indicating whether or not  that
            file has any explicit members.
1377 1378 1379 1380
        :param Nullable include_property_groups: If set to a valid list of
            template IDs, ``FileMetadata.property_groups`` is set if there
            exists property data associated with the file and each of the listed
            templates.
1381
        :rtype: :class:`dropbox.files.Metadata`
1382
        :raises: :class:`.exceptions.ApiError`
1383

1384
        If this raises, ApiError will contain:
1385 1386 1387 1388 1389
            :class:`dropbox.files.GetMetadataError`
        """
        arg = files.GetMetadataArg(path,
                                   include_media_info,
                                   include_deleted,
1390 1391
                                   include_has_explicit_shared_members,
                                   include_property_groups)
1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405
        r = self.request(
            files.get_metadata,
            'files',
            arg,
            None,
        )
        return r

    def files_get_preview(self,
                          path,
                          rev=None):
        """
        Get a preview for a file. Currently, PDF previews are generated for
        files with the following extensions: .ai, .doc, .docm, .docx, .eps,
1406 1407 1408 1409
        .gdoc, .gslides, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx,
        .rtf. HTML previews are generated for files with the following
        extensions: .csv, .ods, .xls, .xlsm, .gsheet, .xlsx. Other formats will
        return an unsupported extension error.
1410 1411

        :param str path: The path of the file to preview.
1412
        :param Nullable rev: Please specify revision in ``path`` instead.
1413 1414
        :rtype: (:class:`dropbox.files.FileMetadata`,
                 :class:`requests.models.Response`)
1415
        :raises: :class:`.exceptions.ApiError`
1416

1417
        If this raises, ApiError will contain:
1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442
            :class:`dropbox.files.PreviewError`

        If you do not consume the entire response body, then you must call close
        on the response object, otherwise you will max out your available
        connections. We recommend using the `contextlib.closing
        <https://docs.python.org/2/library/contextlib.html#contextlib.closing>`_
        context manager to ensure this.
        """
        arg = files.PreviewArg(path,
                               rev)
        r = self.request(
            files.get_preview,
            'files',
            arg,
            None,
        )
        return r

    def files_get_preview_to_file(self,
                                  download_path,
                                  path,
                                  rev=None):
        """
        Get a preview for a file. Currently, PDF previews are generated for
        files with the following extensions: .ai, .doc, .docm, .docx, .eps,
1443 1444 1445 1446
        .gdoc, .gslides, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx,
        .rtf. HTML previews are generated for files with the following
        extensions: .csv, .ods, .xls, .xlsm, .gsheet, .xlsx. Other formats will
        return an unsupported extension error.
1447 1448 1449

        :param str download_path: Path on local machine to save file.
        :param str path: The path of the file to preview.
1450
        :param Nullable rev: Please specify revision in ``path`` instead.
1451 1452
        :rtype: :class:`dropbox.files.FileMetadata`
        :raises: :class:`.exceptions.ApiError`
1453

1454
        If this raises, ApiError will contain:
1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471
            :class:`dropbox.files.PreviewError`
        """
        arg = files.PreviewArg(path,
                               rev)
        r = self.request(
            files.get_preview,
            'files',
            arg,
            None,
        )
        self._save_body_to_file(download_path, r[1])
        return r[0]

    def files_get_temporary_link(self,
                                 path):
        """
        Get a temporary link to stream content of a file. This link will expire
1472 1473
        in four hours and afterwards you will get 410 Gone. This URL should not
        be used to display content directly in the browser. The Content-Type of
1474
        the link is determined automatically by the file's mime type.
1475 1476 1477

        :param str path: The path to the file you want a temporary link to.
        :rtype: :class:`dropbox.files.GetTemporaryLinkResult`
1478
        :raises: :class:`.exceptions.ApiError`
1479

1480
        If this raises, ApiError will contain:
1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491
            :class:`dropbox.files.GetTemporaryLinkError`
        """
        arg = files.GetTemporaryLinkArg(path)
        r = self.request(
            files.get_temporary_link,
            'files',
            arg,
            None,
        )
        return r

1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545
    def files_get_temporary_upload_link(self,
                                        commit_info,
                                        duration=14400.0):
        """
        Get a one-time use temporary upload link to upload a file to a Dropbox
        location.  This endpoint acts as a delayed :meth:`files_upload`. The
        returned temporary upload link may be used to make a POST request with
        the data to be uploaded. The upload will then be perfomed with the
        :class:`dropbox.files.CommitInfo` previously provided to
        :meth:`files_get_temporary_upload_link` but evaluated only upon
        consumption. Hence, errors stemming from invalid
        :class:`dropbox.files.CommitInfo` with respect to the state of the
        user's Dropbox will only be communicated at consumption time.
        Additionally, these errors are surfaced as generic HTTP 409 Conflict
        responses, potentially hiding issue details. The maximum temporary
        upload link duration is 4 hours. Upon consumption or expiration, a new
        link will have to be generated. Multiple links may exist for a specific
        upload path at any given time.  The POST request on the temporary upload
        link must have its Content-Type set to "application/octet-stream".
        Example temporary upload link consumption request:  curl -X POST
        https://dl.dropboxusercontent.com/apitul/1/bNi2uIYF51cVBND --header
        "Content-Type: application/octet-stream" --data-binary @local_file.txt
        A successful temporary upload link consumption request returns the
        content hash of the uploaded data in JSON format.  Example succesful
        temporary upload link consumption response: {"content-hash":
        "599d71033d700ac892a0e48fa61b125d2f5994"}  An unsuccessful temporary
        upload link consumption request returns any of the following status
        codes:  HTTP 400 Bad Request: Content-Type is not one of
        application/octet-stream and text/plain or request is invalid. HTTP 409
        Conflict: The temporary upload link does not exist or is currently
        unavailable, the upload failed, or another error happened. HTTP 410
        Gone: The temporary upload link is expired or consumed.  Example
        unsuccessful temporary upload link consumption response: Temporary
        upload link has been recently consumed.

        :param commit_info: Contains the path and other optional modifiers for
            the future upload commit. Equivalent to the parameters provided to
            :meth:`files_upload`.
        :type commit_info: :class:`dropbox.files.CommitInfo`
        :param float duration: How long before this link expires, in seconds.
            Attempting to start an upload with this link longer than this period
            of time after link creation will result in an error.
        :rtype: :class:`dropbox.files.GetTemporaryUploadLinkResult`
        """
        arg = files.GetTemporaryUploadLinkArg(commit_info,
                                              duration)
        r = self.request(
            files.get_temporary_upload_link,
            'files',
            arg,
            None,
        )
        return r

1546 1547 1548
    def files_get_thumbnail(self,
                            path,
                            format=files.ThumbnailFormat.jpeg,
1549 1550
                            size=files.ThumbnailSize.w64h64,
                            mode=files.ThumbnailMode.strict):
1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563
        """
        Get a thumbnail for an image. This method currently supports files with
        the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp.
        Photos that are larger than 20MB in size won't be converted to a
        thumbnail.

        :param str path: The path to the image file you want to thumbnail.
        :param format: The format for the thumbnail image, jpeg (default) or
            png. For  images that are photos, jpeg should be preferred, while
            png is  better for screenshots and digital arts.
        :type format: :class:`dropbox.files.ThumbnailFormat`
        :param size: The size for the thumbnail image.
        :type size: :class:`dropbox.files.ThumbnailSize`
1564 1565 1566
        :param mode: How to resize and crop the image to achieve the desired
            size.
        :type mode: :class:`dropbox.files.ThumbnailMode`
1567 1568
        :rtype: (:class:`dropbox.files.FileMetadata`,
                 :class:`requests.models.Response`)
1569
        :raises: :class:`.exceptions.ApiError`
1570

1571
        If this raises, ApiError will contain:
1572 1573 1574 1575 1576 1577 1578 1579 1580 1581
            :class:`dropbox.files.ThumbnailError`

        If you do not consume the entire response body, then you must call close
        on the response object, otherwise you will max out your available
        connections. We recommend using the `contextlib.closing
        <https://docs.python.org/2/library/contextlib.html#contextlib.closing>`_
        context manager to ensure this.
        """
        arg = files.ThumbnailArg(path,
                                 format,
1582 1583
                                 size,
                                 mode)
1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595
        r = self.request(
            files.get_thumbnail,
            'files',
            arg,
            None,
        )
        return r

    def files_get_thumbnail_to_file(self,
                                    download_path,
                                    path,
                                    format=files.ThumbnailFormat.jpeg,
1596 1597
                                    size=files.ThumbnailSize.w64h64,
                                    mode=files.ThumbnailMode.strict):
1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611
        """
        Get a thumbnail for an image. This method currently supports files with
        the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp.
        Photos that are larger than 20MB in size won't be converted to a
        thumbnail.

        :param str download_path: Path on local machine to save file.
        :param str path: The path to the image file you want to thumbnail.
        :param format: The format for the thumbnail image, jpeg (default) or
            png. For  images that are photos, jpeg should be preferred, while
            png is  better for screenshots and digital arts.
        :type format: :class:`dropbox.files.ThumbnailFormat`
        :param size: The size for the thumbnail image.
        :type size: :class:`dropbox.files.ThumbnailSize`
1612 1613 1614
        :param mode: How to resize and crop the image to achieve the desired
            size.
        :type mode: :class:`dropbox.files.ThumbnailMode`
1615 1616
        :rtype: :class:`dropbox.files.FileMetadata`
        :raises: :class:`.exceptions.ApiError`
1617

1618
        If this raises, ApiError will contain:
1619 1620 1621 1622
            :class:`dropbox.files.ThumbnailError`
        """
        arg = files.ThumbnailArg(path,
                                 format,
1623 1624
                                 size,
                                 mode)
1625 1626 1627 1628 1629 1630 1631 1632 1633
        r = self.request(
            files.get_thumbnail,
            'files',
            arg,
            None,
        )
        self._save_body_to_file(download_path, r[1])
        return r[0]

1634 1635 1636 1637 1638 1639 1640 1641 1642 1643
    def files_get_thumbnail_batch(self,
                                  entries):
        """
        Get thumbnails for a list of images. We allow up to 25 thumbnails in a
        single batch. This method currently supports files with the following
        file extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are
        larger than 20MB in size won't be converted to a thumbnail.

        :param list entries: List of files to get thumbnails.
        :rtype: :class:`dropbox.files.GetThumbnailBatchResult`
1644
        :raises: :class:`.exceptions.ApiError`
1645

1646
        If this raises, ApiError will contain:
1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657
            :class:`dropbox.files.GetThumbnailBatchError`
        """
        arg = files.GetThumbnailBatchArg(entries)
        r = self.request(
            files.get_thumbnail_batch,
            'files',
            arg,
            None,
        )
        return r

1658 1659 1660 1661 1662
    def files_list_folder(self,
                          path,
                          recursive=False,
                          include_media_info=False,
                          include_deleted=False,
1663 1664 1665
                          include_has_explicit_shared_members=False,
                          include_mounted_folders=True,
                          limit=None,
1666
                          shared_link=None,
1667 1668
                          include_property_groups=None,
                          include_non_downloadable_files=True):
1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694
        """
        Starts returning the contents of a folder. If the result's
        ``ListFolderResult.has_more`` field is ``True``, call
        :meth:`files_list_folder_continue` with the returned
        ``ListFolderResult.cursor`` to retrieve more entries. If you're using
        ``ListFolderArg.recursive`` set to ``True`` to keep a local cache of the
        contents of a Dropbox account, iterate through each entry in order and
        process them as follows to keep your local state in sync: For each
        :class:`dropbox.files.FileMetadata`, store the new entry at the given
        path in your local state. If the required parent folders don't exist
        yet, create them. If there's already something else at the given path,
        replace it and remove all its children. For each
        :class:`dropbox.files.FolderMetadata`, store the new entry at the given
        path in your local state. If the required parent folders don't exist
        yet, create them. If there's already something else at the given path,
        replace it but leave the children as they are. Check the new entry's
        ``FolderSharingInfo.read_only`` and set all its children's read-only
        statuses to match. For each :class:`dropbox.files.DeletedMetadata`, if
        your local state has something at the given path, remove it and all its
        children. If there's nothing at the given path, ignore this entry. Note:
        :class:`dropbox.auth.RateLimitError` may be returned if multiple
        :meth:`files_list_folder` or :meth:`files_list_folder_continue` calls
        with same parameters are made simultaneously by same API app for same
        user. If your app implements retry logic, please hold off the retry
        until the previous request finishes.

1695
        :param str path: A unique identifier for the file.
1696 1697 1698 1699
        :param bool recursive: If true, the list folder operation will be
            applied recursively to all subfolders and the response will contain
            contents of all subfolders.
        :param bool include_media_info: If true, ``FileMetadata.media_info`` is
1700 1701
            set for photo and video. This parameter will no longer have an
            effect starting December 2, 2019.
1702 1703 1704 1705 1706
        :param bool include_deleted: If true, the results will include entries
            for files and folders that used to exist but were deleted.
        :param bool include_has_explicit_shared_members: If true, the results
            will include a flag for each file indicating whether or not  that
            file has any explicit members.
1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717
        :param bool include_mounted_folders: If true, the results will include
            entries under mounted folders which includes app folder, shared
            folder and team folder.
        :param Nullable limit: The maximum number of results to return per
            request. Note: This is an approximate number and there can be
            slightly more entries returned in some cases.
        :param Nullable shared_link: A shared link to list the contents of. If
            the link is password-protected, the password must be provided. If
            this field is present, ``ListFolderArg.path`` will be relative to
            root of the shared link. Only non-recursive mode is supported for
            shared link.
1718 1719 1720 1721
        :param Nullable include_property_groups: If set to a valid list of
            template IDs, ``FileMetadata.property_groups`` is set if there
            exists property data associated with the file and each of the listed
            templates.
1722 1723
        :param bool include_non_downloadable_files: If true, include files that
            are not downloadable, i.e. Google Docs.
1724
        :rtype: :class:`dropbox.files.ListFolderResult`
1725
        :raises: :class:`.exceptions.ApiError`
1726

1727
        If this raises, ApiError will contain:
1728 1729 1730 1731 1732 1733
            :class:`dropbox.files.ListFolderError`
        """
        arg = files.ListFolderArg(path,
                                  recursive,
                                  include_media_info,
                                  include_deleted,
1734 1735 1736
                                  include_has_explicit_shared_members,
                                  include_mounted_folders,
                                  limit,
1737
                                  shared_link,
1738 1739
                                  include_property_groups,
                                  include_non_downloadable_files)
1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757
        r = self.request(
            files.list_folder,
            'files',
            arg,
            None,
        )
        return r

    def files_list_folder_continue(self,
                                   cursor):
        """
        Once a cursor has been retrieved from :meth:`files_list_folder`, use
        this to paginate through all files and retrieve updates to the folder,
        following the same rules as documented for :meth:`files_list_folder`.

        :param str cursor: The cursor returned by your last call to
            :meth:`files_list_folder` or :meth:`files_list_folder_continue`.
        :rtype: :class:`dropbox.files.ListFolderResult`
1758
        :raises: :class:`.exceptions.ApiError`
1759

1760
        If this raises, ApiError will contain:
1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776
            :class:`dropbox.files.ListFolderContinueError`
        """
        arg = files.ListFolderContinueArg(cursor)
        r = self.request(
            files.list_folder_continue,
            'files',
            arg,
            None,
        )
        return r

    def files_list_folder_get_latest_cursor(self,
                                            path,
                                            recursive=False,
                                            include_media_info=False,
                                            include_deleted=False,
1777 1778 1779
                                            include_has_explicit_shared_members=False,
                                            include_mounted_folders=True,
                                            limit=None,
1780
                                            shared_link=None,
1781 1782
                                            include_property_groups=None,
                                            include_non_downloadable_files=True):
1783 1784 1785 1786 1787 1788 1789
        """
        A way to quickly get a cursor for the folder's state. Unlike
        :meth:`files_list_folder`, :meth:`files_list_folder_get_latest_cursor`
        doesn't return any entries. This endpoint is for app which only needs to
        know about new files and modifications and doesn't need to know about
        files that already exist in Dropbox.

1790
        :param str path: A unique identifier for the file.
1791 1792 1793 1794
        :param bool recursive: If true, the list folder operation will be
            applied recursively to all subfolders and the response will contain
            contents of all subfolders.
        :param bool include_media_info: If true, ``FileMetadata.media_info`` is
1795 1796
            set for photo and video. This parameter will no longer have an
            effect starting December 2, 2019.
1797 1798 1799 1800 1801
        :param bool include_deleted: If true, the results will include entries
            for files and folders that used to exist but were deleted.
        :param bool include_has_explicit_shared_members: If true, the results
            will include a flag for each file indicating whether or not  that
            file has any explicit members.
1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812
        :param bool include_mounted_folders: If true, the results will include
            entries under mounted folders which includes app folder, shared
            folder and team folder.
        :param Nullable limit: The maximum number of results to return per
            request. Note: This is an approximate number and there can be
            slightly more entries returned in some cases.
        :param Nullable shared_link: A shared link to list the contents of. If
            the link is password-protected, the password must be provided. If
            this field is present, ``ListFolderArg.path`` will be relative to
            root of the shared link. Only non-recursive mode is supported for
            shared link.
1813 1814 1815 1816
        :param Nullable include_property_groups: If set to a valid list of
            template IDs, ``FileMetadata.property_groups`` is set if there
            exists property data associated with the file and each of the listed
            templates.
1817 1818
        :param bool include_non_downloadable_files: If true, include files that
            are not downloadable, i.e. Google Docs.
1819
        :rtype: :class:`dropbox.files.ListFolderGetLatestCursorResult`
1820
        :raises: :class:`.exceptions.ApiError`
1821

1822
        If this raises, ApiError will contain:
1823 1824 1825 1826 1827 1828
            :class:`dropbox.files.ListFolderError`
        """
        arg = files.ListFolderArg(path,
                                  recursive,
                                  include_media_info,
                                  include_deleted,
1829 1830 1831
                                  include_has_explicit_shared_members,
                                  include_mounted_folders,
                                  limit,
1832
                                  shared_link,
1833 1834
                                  include_property_groups,
                                  include_non_downloadable_files)
1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857
        r = self.request(
            files.list_folder_get_latest_cursor,
            'files',
            arg,
            None,
        )
        return r

    def files_list_folder_longpoll(self,
                                   cursor,
                                   timeout=30):
        """
        A longpoll endpoint to wait for changes on an account. In conjunction
        with :meth:`files_list_folder_continue`, this call gives you a
        low-latency way to monitor an account for file changes. The connection
        will block until there are changes available or a timeout occurs. This
        endpoint is useful mostly for client-side apps. If you're looking for
        server-side notifications, check out our `webhooks documentation
        <https://www.dropbox.com/developers/reference/webhooks>`_.

        :param str cursor: A cursor as returned by :meth:`files_list_folder` or
            :meth:`files_list_folder_continue`. Cursors retrieved by setting
            ``ListFolderArg.include_media_info`` to ``True`` are not supported.
1858
        :param int timeout: A timeout in seconds. The request will block for at
1859 1860 1861 1862 1863
            most this length of time, plus up to 90 seconds of random jitter
            added to avoid the thundering herd problem. Care should be taken
            when using this parameter, as some network infrastructure does not
            support long timeouts.
        :rtype: :class:`dropbox.files.ListFolderLongpollResult`
1864
        :raises: :class:`.exceptions.ApiError`
1865

1866
        If this raises, ApiError will contain:
1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880
            :class:`dropbox.files.ListFolderLongpollError`
        """
        arg = files.ListFolderLongpollArg(cursor,
                                          timeout)
        r = self.request(
            files.list_folder_longpoll,
            'files',
            arg,
            None,
        )
        return r

    def files_list_revisions(self,
                             path,
1881
                             mode=files.ListRevisionsMode.path,
1882 1883
                             limit=10):
        """
1884 1885 1886 1887 1888 1889 1890 1891 1892
        Returns revisions for files based on a file path or a file id. The file
        path or file id is identified from the latest file entry at the given
        file path or id. This end point allows your app to query either by file
        path or file id by setting the mode parameter appropriately. In the
        ``ListRevisionsMode.path`` (default) mode, all revisions at the same
        file path as the latest file entry are returned. If revisions with the
        same file id are desired, then mode must be set to
        ``ListRevisionsMode.id``. The ``ListRevisionsMode.id`` mode is useful to
        retrieve revisions for a given file across moves or renames.
1893 1894

        :param str path: The path to the file you want to see the revisions of.
1895 1896 1897
        :param mode: Determines the behavior of the API in listing the revisions
            for a given file path or id.
        :type mode: :class:`dropbox.files.ListRevisionsMode`
1898
        :param int limit: The maximum number of revision entries returned.
1899
        :rtype: :class:`dropbox.files.ListRevisionsResult`
1900
        :raises: :class:`.exceptions.ApiError`
1901

1902
        If this raises, ApiError will contain:
1903 1904 1905
            :class:`dropbox.files.ListRevisionsError`
        """
        arg = files.ListRevisionsArg(path,
1906
                                     mode,
1907 1908 1909 1910 1911 1912 1913 1914 1915
                                     limit)
        r = self.request(
            files.list_revisions,
            'files',
            arg,
            None,
        )
        return r

1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954
    def files_move_v2(self,
                      from_path,
                      to_path,
                      allow_shared_folder=False,
                      autorename=False,
                      allow_ownership_transfer=False):
        """
        Move a file or folder to a different location in the user's Dropbox. If
        the source path is a folder all its contents will be moved.

        :param bool allow_shared_folder: If true, :meth:`files_copy` will copy
            contents in shared folder, otherwise
            ``RelocationError.cant_copy_shared_folder`` will be returned if
            ``from_path`` contains shared folder. This field is always true for
            :meth:`files_move`.
        :param bool autorename: If there's a conflict, have the Dropbox server
            try to autorename the file to avoid the conflict.
        :param bool allow_ownership_transfer: Allow moves by owner even if it
            would result in an ownership transfer for the content being moved.
            This does not apply to copies.
        :rtype: :class:`dropbox.files.RelocationResult`
        :raises: :class:`.exceptions.ApiError`

        If this raises, ApiError will contain:
            :class:`dropbox.files.RelocationError`
        """
        arg = files.RelocationArg(from_path,
                                  to_path,
                                  allow_shared_folder,
                                  autorename,
                                  allow_ownership_transfer)
        r = self.request(
            files.move_v2,
            'files',
            arg,
            None,
        )
        return r

1955 1956 1957 1958
    def files_move(self,
                   from_path,
                   to_path,
                   allow_shared_folder=False,
1959 1960
                   autorename=False,
                   allow_ownership_transfer=False):
1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971
        """
        Move a file or folder to a different location in the user's Dropbox. If
        the source path is a folder all its contents will be moved.

        :param bool allow_shared_folder: If true, :meth:`files_copy` will copy
            contents in shared folder, otherwise
            ``RelocationError.cant_copy_shared_folder`` will be returned if
            ``from_path`` contains shared folder. This field is always true for
            :meth:`files_move`.
        :param bool autorename: If there's a conflict, have the Dropbox server
            try to autorename the file to avoid the conflict.
1972 1973 1974
        :param bool allow_ownership_transfer: Allow moves by owner even if it
            would result in an ownership transfer for the content being moved.
            This does not apply to copies.
1975
        :rtype: :class:`dropbox.files.Metadata`
1976
        :raises: :class:`.exceptions.ApiError`
1977

1978
        If this raises, ApiError will contain:
1979 1980
            :class:`dropbox.files.RelocationError`
        """
1981
        warnings.warn(
1982
            'move is deprecated. Use move.',
1983 1984
            DeprecationWarning,
        )
1985 1986 1987
        arg = files.RelocationArg(from_path,
                                  to_path,
                                  allow_shared_folder,
1988 1989
                                  autorename,
                                  allow_ownership_transfer)
1990 1991 1992 1993 1994 1995 1996 1997
        r = self.request(
            files.move,
            'files',
            arg,
            None,
        )
        return r

1998 1999 2000 2001 2002 2003
    def files_move_batch_v2(self,
                            entries,
                            autorename=False,
                            allow_ownership_transfer=False):
        """
        Move multiple files or folders to different locations at once in the
2004 2005
        user's Dropbox. This route will replace :meth:`files_move_batch`. The
        main difference is this route will return status for each entry, while
2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026
        :meth:`files_move_batch` raises failure if any entry fails. This route
        will either finish synchronously, or return a job ID and do the async
        move job in background. Please use :meth:`files_move_batch_check_v2` to
        check the job status.

        :param bool allow_ownership_transfer: Allow moves by owner even if it
            would result in an ownership transfer for the content being moved.
            This does not apply to copies.
        :rtype: :class:`dropbox.files.RelocationBatchV2Launch`
        """
        arg = files.MoveBatchArg(entries,
                                 autorename,
                                 allow_ownership_transfer)
        r = self.request(
            files.move_batch_v2,
            'files',
            arg,
            None,
        )
        return r