feat: Add vanity_name param for creating shared link to a file or folder (box#637)

Closes: SDK-1815

Author: lukaszsocha2

HISTORY.rst

@@ -9,6 +9,7 @@ Next release
 **New Features and Enhancements:**
 
 - 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>`_)
 
 2.13.0 (2021-09-30)
 ++++++++

boxsdk/object/file.py

@@ -430,6 +430,7 @@ def get_shared_link_download_url(
             unshared_at=None,
             allow_preview=None,
             password=None,
+            vanity_name=None
     ):
         """
         Get a shared link download url for the file with the given access permissions.
@@ -461,6 +462,11 @@ def get_shared_link_download_url(
             Please notice that this is a premium feature, which might not be available to your app.
         :type password:
             `unicode` or None
+        :param vanity_name:
+            Defines a custom vanity name to use in the shared link URL, eg. https://app.box.com/v/my-custom-vanity-name.
+            If this parameter is None, the standard shared link URL will be used.
+        :type vanity_name:
+            `unicode` or None
         :returns:
             The URL of the shared link that allows direct download.
         :rtype:
@@ -473,6 +479,7 @@ def get_shared_link_download_url(
             unshared_at=unshared_at,
             allow_preview=allow_preview,
             password=password,
+            vanity_name=vanity_name
         )
         return item.shared_link['download_url']  # pylint:disable=no-member
 

boxsdk/object/item.py

@@ -219,6 +219,7 @@ def create_shared_link(
             allow_download=None,
             allow_preview=None,
             password=None,
+            vanity_name=None
     ):
         """
         Create a shared link for the item with the given access permissions.
@@ -254,6 +255,11 @@ def create_shared_link(
             Please notice that this is a premium feature, which might not be available to your app.
         :type password:
             `unicode` or None
+        :param vanity_name:
+            Defines a custom vanity name to use in the shared link URL, eg. https://app.box.com/v/my-custom-vanity-name.
+            If this parameter is None, the standard shared link URL will be used.
+        :type vanity_name:
+            `unicode` or None
         :return:
             The updated object with s shared link.
             Returns a new object of the same type, without modifying the original object passed as self.
@@ -280,6 +286,9 @@ def create_shared_link(
         if password is not None:
             data['shared_link']['password'] = password
 
+        if vanity_name is not None:
+            data['shared_link']['vanity_name'] = vanity_name
+
         return self.update_info(data, etag=etag)
 
     @api_call
@@ -291,6 +300,7 @@ def get_shared_link(
             allow_download=None,
             allow_preview=None,
             password=None,
+            vanity_name=None
     ):
         """
         Get a shared link for the item with the given access permissions.
@@ -325,6 +335,11 @@ def get_shared_link(
             Please notice that this is a premium feature, which might not be available to your app.
         :type password:
             `unicode` or None
+        :param vanity_name:
+            Defines a custom vanity name to use in the shared link URL, eg. https://app.box.com/v/my-custom-vanity-name.
+            If this parameter is None, the standard shared link URL will be used.
+        :type vanity_name:
+            `unicode` or None
         :returns:
             The URL of the shared link.
         :rtype:
@@ -338,6 +353,7 @@ def get_shared_link(
             allow_download=allow_download,
             allow_preview=allow_preview,
             password=password,
+            vanity_name=vanity_name
         )
         return item.shared_link['url']  # pylint:disable=no-member
 

docs/usage/files.md

@@ -34,9 +34,9 @@ file's contents, upload new versions, and perform other common file operations
 - [Delete a Previous Version of a File](#delete-a-previous-version-of-a-file)
 - [Lock a File](#lock-a-file)
 - [Unlock a File](#unlock-a-file)
-- [Create a Shared Link](#create-a-shared-link)
+- [Create a Shared Link Download URL](#create-a-shared-link-download-url)
 - [Find a File for a Shared Link](#find-a-file-for-a-shared-link)
-- [Create a Shared Link](#create-a-shared-link-1)
+- [Create a Shared Link](#create-a-shared-link)
 - [Update a Shared Link](#update-a-shared-link)
 - [Get a Shared Link](#get-a-shared-link)
 - [Remove a Shared Link](#remove-a-shared-link)
@@ -627,23 +627,24 @@ print('File "{0}" has been unlocked!'.format(updated_file.name))
 
 [unlock]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.unlock
 
-Create a Shared Link
+Create a Shared Link Download URL
 --------------------
 
 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)`][get_shared_link].
+[`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_download_url].
 This method returns a `unicode` string containing the shared link URL.
 
 <!-- sample put_files_id add_shared_link -->
 ```python
 file_id = '11111'
 
-url = client.file(file_id).get_shared_link()
-print('The file shared link URL is: {0}'.format(url))
+url = client.file(file_id).get_shared_link_download_url(access='open', vanity_name="my-unique-vanity-name")
+print('The file shared link download URL is: {0}'.format(url))
 ```
 
-[get_shared_link]:
-https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_shared_link
+[get_shared_link_download_url]:
+https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.file.File.get_shared_link_download_url
 
 Find a File for a Shared Link
 -----------------------------
@@ -661,7 +662,8 @@ 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)`][get_shared_link].
+[`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].
 This method returns a `unicode` string containing the shared link URL.
 
 <!-- sample put_files_id add_shared_link -->
@@ -678,8 +680,8 @@ 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)`][update_shared_link]
+[`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]
 with an updated list of properties.
 
 This method returns a `unicode` string containing the shared link URL.

docs/usage/folders.md

@@ -195,16 +195,17 @@ folder = client.get_shared_item('https://app.box.com/s/gjasdasjhasd', password='
 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)`][get_shared_link].
+A shared link for a folder can be generated by calling
+[`folder.get_shared_link(access=None, etag=None, unshared_at=None, allow_download=None, allow_preview=None,
+password=None, vanity_name=None)`][get_shared_link].
 This method returns a `unicode` string containing the shared link URL.
 
 <!-- sample put_folders_id add_shared_link -->
 ```python
-file_id = '11111'
+folder_id = '11111'
 
-url = client.file(file_id).get_shared_link(access='open', allow_download=False)
-print('The file shared link URL is: {0}'.format(url))
+url = client.folder(folder_id).get_shared_link(access='open', allow_download=False)
+print('The folder shared link URL is: {0}'.format(url))
 ```
 
 [get_shared_link]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.item.Item.get_shared_link
@@ -213,8 +214,8 @@ Update a Shared Link
 --------------------
 
 A shared link for a folder can be updated by calling
-[`folder.get_shared_link(access=None, etag=None, unshared_at=None,
-allow_download=None, allow_preview=None, password=None)`][update_shared_link]
+[`folder.get_shared_link(access=None, etag=None, unshared_at=None, allow_download=None, allow_preview=None,
+password=None, vanity_name=None)`][update_shared_link]
 with an updated list of properties.
 
 This method returns a `unicode` string containing the shared link URL.

test/unit/object/conftest.py

@@ -369,6 +369,11 @@ def shared_link_unshared_at(request):
     return request.param
 
 
+@pytest.fixture(params=('my-custom-vanity-name', None))
+def shared_link_vanity_name(request):
+    return request.param
+
+
 @pytest.fixture(params=[
     # Test case for plain message
     (

test/unit/object/test_file.py

@@ -580,6 +580,7 @@ def test_get_shared_link_download_url(
         shared_link_unshared_at,
         shared_link_password,
         shared_link_can_preview,
+        shared_link_vanity_name,
         test_url,
         etag,
         if_match_header,
@@ -606,12 +607,16 @@ def test_get_shared_link_download_url(
         permissions['can_preview'] = shared_link_can_preview
     if shared_link_password is not None:
         expected_data['shared_link']['password'] = shared_link_password
+    if shared_link_vanity_name is not None:
+        expected_data['shared_link']['vanity_name'] = shared_link_vanity_name
+
     url = test_file.get_shared_link_download_url(
         etag=etag,
         access=shared_link_access,
         unshared_at=shared_link_unshared_at,
         password=shared_link_password,
         allow_preview=shared_link_can_preview,
+        vanity_name=shared_link_vanity_name,
     )
     mock_box_session.put.assert_called_once_with(
         expected_url,

test/unit/object/test_item.py

@@ -133,6 +133,7 @@ def test_get_shared_link(
         shared_link_password,
         shared_link_can_download,
         shared_link_can_preview,
+        shared_link_vanity_name,
         test_url,
         etag,
         if_match_header,
@@ -160,13 +161,17 @@ def test_get_shared_link(
             permissions['can_preview'] = shared_link_can_preview
     if shared_link_password is not None:
         expected_data['shared_link']['password'] = shared_link_password
+    if shared_link_vanity_name is not None:
+        expected_data['shared_link']['vanity_name'] = shared_link_vanity_name
+
     url = test_item.get_shared_link(
         etag=etag,
         access=shared_link_access,
         unshared_at=shared_link_unshared_at,
         password=shared_link_password,
         allow_download=shared_link_can_download,
         allow_preview=shared_link_can_preview,
+        vanity_name=shared_link_vanity_name,
     )
     mock_box_session.put.assert_called_once_with(
         expected_url,