documentation

box · Dec 7, 2021 · e582281 · e582281
1 parent d3b0378
commit e582281
Show file tree

Hide file tree

Showing 9 changed files with 204 additions and 50 deletions.
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -11,6 +11,7 @@ Next release
 - Add `admin_logs_streaming` support for events stream (`#623 <https://github.com/box/box-python-sdk/pull/623>`_)
 - Add `vanity_name` param for creating shared link to a file or folder (`#637 <https://github.com/box/box-python-sdk/pull/637>`_)
 - Add getting files and file versions under retention for a retention policy assignment (`#633 <https://github.com/box/box-python-sdk/pull/633>`_)
+- Support base item operations for WebLink class (`#639 <https://github.com/box/box-python-sdk/pull/639>`_)
 
 **Bug Fixes:**
 - Limit cryptography to version <3.5.0 (`#636 <https://github.com/box/box-python-sdk/pull/636>`_)

diff --git a/boxsdk/object/base_item.py b/boxsdk/object/base_item.py
@@ -77,7 +77,7 @@ def create_shared_link(self, **kwargs):
         Create a shared link for the item with the given access permissions.
 
         :param kwargs:
-            Keyword arguments passed from overriden method used to build request properties.
+            Keyword arguments passed from overriding method used to build request properties.
         :return:
             The updated object with shared link.
             Returns a new object of the same type, without modifying the original object passed as self.
@@ -117,7 +117,7 @@ def get_shared_link(self, **kwargs):
         This url leads to a Box.com shared link page, where the item can be previewed, downloaded, etc.
 
         :param kwargs:
-            Keyword arguments passed from overriden method used to create a new shared link.
+            Keyword arguments passed from overriding method used to create a new shared link.
         :returns:
             The URL of the shared link.
         :rtype:
@@ -132,7 +132,7 @@ def remove_shared_link(self, **kwargs):
         Delete the shared link for the item.
 
         :param kwargs:
-            Keyword arguments passed from overriden method used to build request properties.
+            Keyword arguments passed from overriding method used to build request properties.
         :returns:
             Whether or not the update was successful.
         :rtype:

diff --git a/boxsdk/object/item.py b/boxsdk/object/item.py
@@ -206,14 +206,15 @@ def create_shared_link(
         :type vanity_name:
             `unicode` or None
         :param kwargs:
-            Used to fulfill the contract of overrided method
+            Used to fulfill the contract of overriden method
         :return:
             The updated object with shared link.
             Returns a new object of the same type, without modifying the original object passed as self.
         :rtype:
             :class:`Item`
         :raises: :class:`BoxAPIException` if the specified etag doesn't match the latest version of the item.
         """
+        # pylint:disable=arguments-differ
         return super(Item, self).create_shared_link(
             access=access,
             etag=etag,
@@ -274,13 +275,14 @@ def get_shared_link(
         :type vanity_name:
             `unicode` or None
         :param kwargs:
-            Used to fulfill the contract of overrided method
+            Used to fulfill the contract of overriden method
         :returns:
             The URL of the shared link.
         :rtype:
             `unicode`
         :raises: :class:`BoxAPIException` if the specified etag doesn't match the latest version of the item.
         """
+        # pylint:disable=arguments-differ
         return super(Item, self).get_shared_link(
             access=access,
             etag=etag,
@@ -301,13 +303,14 @@ def remove_shared_link(self, etag=None, **kwargs):
         :type etag:
             `unicode` or None
         :param kwargs:
-            Used to fulfill the contract of overrided method
+            Used to fulfill the contract of overriden method
         :returns:
             Whether or not the update was successful.
         :rtype:
             `bool`
         :raises: :class:`BoxAPIException` if the specified etag doesn't match the latest version of the item.
         """
+        # pylint:disable=arguments-differ
         return super(Item, self).remove_shared_link(etag=etag)
 
     @api_call

diff --git a/boxsdk/object/web_link.py b/boxsdk/object/web_link.py
@@ -46,13 +46,14 @@ def create_shared_link(
         :type vanity_name:
             `unicode` or None
         :param kwargs:
-            Used to fulfill the contract of overrided method
+            Used to fulfill the contract of overriden method
         :return:
             The updated object with s shared link.
             Returns a new object of the same type, without modifying the original object passed as self.
         :rtype:
             :class:`WebLink`
         """
+        # pylint:disable=arguments-differ
         return super(WebLink, self).create_shared_link(
             access=access,
             unshared_at=unshared_at,
@@ -93,14 +94,15 @@ def get_shared_link(
         :type vanity_name:
             `unicode` or None
         :param kwargs:
-            Used to fulfill the contract of overrided method
+            Used to fulfill the contract of overriden method
         :param kwargs:
             Passed to the superclass
         :returns:
             The URL of the shared link.
         :rtype:
             `unicode`
         """
+        # pylint:disable=arguments-differ
         return super(WebLink, self).get_shared_link(
             access=access,
             unshared_at=unshared_at,
@@ -114,7 +116,7 @@ def remove_shared_link(self, **kwargs):
         Baseclass override.
 
         :param kwargs:
-            Used to fulfill the contract of overrided method
+            Used to fulfill the contract of overriden method
         :returns:
             Whether or not the update was successful.
         :rtype:

diff --git a/docs/usage/collections.md b/docs/usage/collections.md
@@ -1,16 +1,15 @@
 Collections
 ===========
 
-Collections allow users to mark specific files and folders to make it easier to find them.
+Collections allow users to mark specific files, folders and web links to make it easier to find them.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-
 - [Get a User's Collections](#get-a-users-collections)
 - [Get the Items in a Collection](#get-the-items-in-a-collection)
-- [Add Item to Collection](#add-item-to-collection)
-- [Remove Item from Collection](#remove-item-from-collection)
+- [Add an Item to a Collection](#add-an-item-to-a-collection)
+- [Remove an Item from a Collection](#remove-an-item-from-a-collection)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -36,8 +35,8 @@ Get the Items in a Collection
 
 To retrieve a list of items contained in a collection, call
 [`collection.get_items(limit=None, offset=0, fields=None)`][get_items].  This method returns a
-`BoxObjectCollection` that you can use to iterate over all the [`Item`][item_class] objects in
-the collection.
+`BoxObjectCollection` that you can use to iterate over all the [`BaseItem`][base_item_class] objects in
+the collection. [`BaseItem`][base_item_class] is a super class for files, folders and web links.
 
 <!-- sample get_collections_id_items -->
 ```python
@@ -47,13 +46,13 @@ for item in items:
 ```
 
 [get_items]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collection.Collection.get_items
-[item_class]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item
+[base_item_class]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem
 
-Add Item to Collection
+Add an Item to a Collection
 ----------------------
 
-To add an [`Item`][item_class] to a collection, call [`item.add_to_collection(collection)`][add_to_collection] with the
-[`Collection`][collection_class] you want to add the item to.  This method returns the updated [`Item`][item_class]
+To add an [`BaseItem`][base_item_class] to a collection, call [`item.add_to_collection(collection)`][add_to_collection] with the
+[`Collection`][collection_class] you want to add the item to.  This method returns the updated [`BaseItem`][base_item_class]
 object.
 
 <!-- sample put_files_id add_to_collection -->
@@ -63,14 +62,14 @@ updated_file = client.file(file_id='11111').add_to_collection(collection)
 print('File "{0}" added to collection!'.format(updated_file.name))
 ```
 
-[add_to_collection]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.add_to_collection
+[add_to_collection]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.add_to_collection
 
-Remove Item from Collection
+Remove an Item from a Collection
 ---------------------------
 
-To remove an [`Item`][item_class] from a collection, call
+To remove an [`BaseItem`][base_item_class]  from a collection, call
 [`item.remove_from_collection(collection)`][remove_from_collection] with the [`Collection`][collection_class] you want
-to remove the item from.  This method returns the updated [`Item`][item_class] object.
+to remove the item from.  This method returns the updated [`BaseItem`][base_item_class]  object.
 
 <!-- sample put_files_id remove_from_collection -->
 ```python
@@ -79,4 +78,4 @@ updated_file = client.file(file_id='11111').remove_from_collection(collection)
 print('File "{0}" removed from collection!'.format(updated_file.name))
 ```
 
-[remove_from_collection]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_from_collection
+[remove_from_collection]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.remove_from_collection
diff --git a/docs/usage/files.md b/docs/usage/files.md
@@ -8,7 +8,6 @@ file's contents, upload new versions, and perform other common file operations
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-
 - [Get a File's Information](#get-a-files-information)
 - [Update a File's Information](#update-a-files-information)
 - [Download a File](#download-a-file)
@@ -27,6 +26,7 @@ file's contents, upload new versions, and perform other common file operations
     - [List Upload Parts](#list-upload-parts)
 - [Move a File](#move-a-file)
 - [Copy a File](#copy-a-file)
+- [Rename a File](#rename-a-file)
 - [Delete a File](#delete-a-file)
 - [Get Previous Versions of a File](#get-previous-versions-of-a-file)
 - [Upload a New Version of a File](#upload-a-new-version-of-a-file)
@@ -42,6 +42,7 @@ file's contents, upload new versions, and perform other common file operations
 - [Remove a Shared Link](#remove-a-shared-link)
 - [Get an Embed Link](#get-an-embed-link)
 - [Get File Representations](#get-file-representations)
+- [Get Thumbnail (Deprecated)](#get-thumbnail-deprecated)
 - [Get Thumbnail](#get-thumbnail)
 - [Set Metadata](#set-metadata)
 - [Get Metadata](#get-metadata)
@@ -458,7 +459,7 @@ moved_file = file_to_move.move(destination_folder)
 print('File "{0}" has been moved into folder "{1}"'.format(moved_file.name, moved_file.parent.name))
 ```
 
-[move]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.move
+[move]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.move
 
 Copy a File
 -----------
@@ -479,7 +480,22 @@ file_copy = file_to_copy.copy(destination_folder)
 print('File "{0}" has been copied into folder "{1}"'.format(file_copy.name, file_copy.parent.name))
 ```
 
-[copy]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.copy
+[copy]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.copy
+
+Rename a File
+-----------
+
+A file can be renamed by calling [`file.rebane(name)`][rename]. This method returns the updated
+[`File`][file_class] object with a new name. Remeber to provide also extention of the file along with the new name. 
+
+```python
+file = client.file(file_id='11111')
+
+renamed_file = file.rename("new-name.pdf")
+print('File was renamed to "{0}"'.format(renamed_file.name))
+```
+
+[rename]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.base_item.BaseItem.rename
 
 Delete a File
 -------------
@@ -639,7 +655,7 @@ This method returns a `unicode` string containing the shared link URL.
 ```python
 file_id = '11111'
 
-url = client.file(file_id).get_shared_link_download_url(access='open', vanity_name="my-unique-vanity-name")
+url = client.file(file_id).get_shared_link_download_url(access='collaborators', vanity_name="my-unique-vanity-name")
 print('The file shared link download URL is: {0}'.format(url))
 ```
 
@@ -663,7 +679,7 @@ Create a Shared Link
 
 A shared link for a file can be generated by calling
 [`file.get_shared_link(access=None, etag=None, unshared_at=None, allow_download=None, allow_preview=None,
-password=None, vanity_name=None)`][get_shared_link].
+password=None, vanity_name=None, **kwargs)`][get_shared_link].
 This method returns a `unicode` string containing the shared link URL.
 
 <!-- sample put_files_id add_shared_link -->
@@ -681,7 +697,7 @@ Update a Shared Link
 
 A shared link for a file can be updated by calling
 [`file.get_shared_link(access=None, etag=None, unshared_at=None, allow_download=None, allow_preview=None,
-password=None, vanity_name=None)`][update_shared_link]
+password=None, vanity_name=None, **kwargs)`][update_shared_link]
 with an updated list of properties.
 
 This method returns a `unicode` string containing the shared link URL.
@@ -709,24 +725,22 @@ This method returns a `unicode` string containing the shared link URL.
 ```python
 file_id = '11111'
 shared_link = client.file(file_id).get().shared_link
-url = shared_link['download_url']
+url = shared_link['url']
 ```
 
-[remove_shared_link]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_shared_link
-
 Remove a Shared Link
 --------------------
 
-A shared link for a file can be removed calling
-[`file.remove_shared_link(etag=None)`][remove_shared_link].
+A shared link for a file can be removed by calling [`file.remove_shared_link(etag=None, **kwargs)`][remove_shared_link].
 
 <!-- sample put_files_id remove_shared_link -->
 ```python
 file_id = '11111'
 client.file(file_id).remove_shared_link()
 ```
 
-[remove_shared_link]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_shared_link
+[remove_shared_link]:
+https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.remove_shared_link
 
 
 Get an Embed Link