feat: Add support for editable shared links for files

boxsdk/object/base_item.py

@@ -87,12 +87,15 @@ def create_shared_link(self, **kwargs: Any) -> Any:
         if kwargs.get('unshared_at') is not SDK_VALUE_NOT_SET:
             shared_link['unshared_at'] = normalize_date_to_rfc3339_format(kwargs.get('unshared_at'))
 
-        if kwargs.get('allow_download') is not None or kwargs.get('allow_preview') is not None:
-            shared_link['permissions'] = {}
-            if kwargs.get('allow_download') is not None:
-                shared_link['permissions']['can_download'] = kwargs.get('allow_download')
-            if kwargs.get('allow_preview') is not None:
-                shared_link['permissions']['can_preview'] = kwargs.get('allow_preview')
+        permissions = {}
+        if kwargs.get('allow_download') is not None:
+            permissions['can_download'] = kwargs.get('allow_download')
+        if kwargs.get('allow_preview') is not None:
+            permissions['can_preview'] = kwargs.get('allow_preview')
+        if kwargs.get('allow_edit') is not None:
+            permissions['can_edit'] = kwargs.get('allow_edit')
+        if permissions:
+            shared_link['permissions'] = permissions
 
         if kwargs.get('password') is not None:
             shared_link['password'] = kwargs.get('password')

boxsdk/object/file.py

@@ -1,7 +1,7 @@
 import json
 import os
 from datetime import datetime
-from typing import TYPE_CHECKING, Optional, Tuple, Union, IO, Iterable, List
+from typing import TYPE_CHECKING, Optional, Tuple, Union, IO, Iterable, List, Any
 
 from boxsdk.util.datetime_formatter import normalize_date_to_rfc3339_format
 from .item import Item
@@ -367,6 +367,127 @@ def unlock(self) -> 'File':
         data = {'lock': None}
         return self.update_info(data=data)
 
+    @api_call
+    def create_shared_link(
+            self,
+            *,
+            access: Optional[str] = None,
+            etag: Optional[str] = None,
+            unshared_at: Union[datetime, str, None] = SDK_VALUE_NOT_SET,
+            allow_download: Optional[bool] = None,
+            allow_preview: Optional[bool] = None,
+            allow_edit: Optional[bool] = None,
+            password: Optional[str] = None,
+            vanity_name: Optional[str] = None,
+            **kwargs: Any
+    ) -> 'File':
+        """
+        Baseclass override.
+
+        :param access:
+            Determines who can access the shared link. May be open, company, or collaborators. If no access is
+            specified, the default access will be used.
+        :param etag:
+            If specified, instruct the Box API to create the link only if the current version's etag matches.
+        :param unshared_at:
+            The date on which this link should be disabled. May only be set if the current user is not a free user
+            and has permission to set expiration dates. Takes a datetime string supported by the dateutil library
+            or a datetime.datetime object. If no timezone info provided, local timezone will be applied.
+            The time portion can be omitted, which defaults to midnight (00:00:00) on that date.
+        :param allow_download:
+            Whether the file being shared can be downloaded when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param allow_preview:
+            Whether the file being shared can be previewed when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param allow_edit:
+            Whether the file being shared can be edited when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param password:
+            The password required to view this link. If no password is specified then no password will be set.
+            Please notice that this is a premium feature, which might not be available to your app.
+        :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.
+        :param kwargs:
+            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.
+        :raises: :class:`BoxAPIException` if the specified etag doesn't match the latest version of the file.
+        """
+        # pylint:disable=arguments-differ
+        return super().create_shared_link(
+            access=access,
+            etag=etag,
+            unshared_at=unshared_at,
+            allow_download=allow_download,
+            allow_preview=allow_preview,
+            allow_edit=allow_edit,
+            password=password,
+            vanity_name=vanity_name
+        )
+
+    @api_call
+    def get_shared_link(
+            self,
+            *,
+            access: Optional[str] = None,
+            etag: Optional[str] = None,
+            unshared_at: Union[datetime, str, None] = SDK_VALUE_NOT_SET,
+            allow_download: Optional[bool] = None,
+            allow_preview: Optional[bool] = None,
+            allow_edit: Optional[bool] = None,
+            password: Optional[str] = None,
+            vanity_name: Optional[str] = None,
+            **kwargs: Any
+    ) -> 'str':
+        """
+        Baseclass override.
+
+        :param access:
+            Determines who can access the shared link. May be open, company, or collaborators. If no access is
+            specified, the default access will be used.
+        :param etag:
+            If specified, instruct the Box API to create the link only if the current version's etag matches.
+        :param unshared_at:
+            The date on which this link should be disabled. May only be set if the current user is not a free user
+            and has permission to set expiration dates. Takes a datetime string supported by the dateutil library
+            or a datetime.datetime object. If no timezone info provided, local timezone will be applied.
+            The time portion can be omitted, which defaults to midnight (00:00:00) on that date.
+        :param allow_download:
+            Whether the file being shared can be downloaded when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param allow_preview:
+            Whether the file being shared can be previewed when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param allow_edit:
+            Whether the file being shared can be edited when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param password:
+            The password required to view this link. If no password is specified then no password will be set.
+            Please notice that this is a premium feature, which might not be available to your app.
+        :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.
+        :param kwargs:
+            Used to fulfill the contract of overriden method
+        :returns:
+            The URL of the shared link.
+        :raises: :class:`BoxAPIException` if the specified etag doesn't match the latest version of the file.
+        """
+        # pylint:disable=arguments-differ
+        return super().get_shared_link(
+            access=access,
+            etag=etag,
+            unshared_at=unshared_at,
+            allow_download=allow_download,
+            allow_preview=allow_preview,
+            allow_edit=allow_edit,
+            password=password,
+            vanity_name=vanity_name
+        )
+
     @api_call
     def get_shared_link_download_url(
             self,

boxsdk/object/folder.py

@@ -10,6 +10,7 @@
 from boxsdk.pagination.marker_based_object_collection import MarkerBasedObjectCollection
 from boxsdk.util.api_call_decorator import api_call
 from boxsdk.util.datetime_formatter import normalize_date_to_rfc3339_format
+from boxsdk.util.default_arg_value import SDK_VALUE_NOT_SET
 from boxsdk.util.text_enum import TextEnum
 
 if TYPE_CHECKING:
@@ -426,6 +427,117 @@ def update_sync_state(self, sync_state: FolderSyncState) -> 'Folder':
         }
         return self.update_info(data=data)
 
+    @api_call
+    def create_shared_link(
+            self,
+            *,
+            access: Optional[str] = None,
+            etag: Optional[str] = None,
+            unshared_at: Union[datetime, str, None] = SDK_VALUE_NOT_SET,
+            allow_download: Optional[bool] = None,
+            allow_preview: Optional[bool] = None,
+            password: Optional[str] = None,
+            vanity_name: Optional[str] = None,
+            **kwargs: Any
+    ) -> 'Folder':
+        """
+        Baseclass override.
+
+        :param access:
+            Determines who can access the shared link. May be open, company, or collaborators. If no access is
+            specified, the default access will be used.
+        :param etag:
+            If specified, instruct the Box API to create the link only if the current version's etag matches.
+        :param unshared_at:
+            The date on which this link should be disabled. May only be set if the current user is not a free user
+            and has permission to set expiration dates. Takes a datetime string supported by the dateutil library
+            or a datetime.datetime object. If no timezone info provided, local timezone will be applied.
+            The time portion can be omitted, which defaults to midnight (00:00:00) on that date.
+        :param allow_download:
+            Whether the folder being shared can be downloaded when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param allow_preview:
+            Whether the folder being shared can be previewed when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param password:
+            The password required to view this link. If no password is specified then no password will be set.
+            Please notice that this is a premium feature, which might not be available to your app.
+        :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.
+        :param kwargs:
+            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.
+        :raises: :class:`BoxAPIException` if the specified etag doesn't match the latest version of the folder.
+        """
+        # pylint:disable=arguments-differ
+        return super().create_shared_link(
+            access=access,
+            etag=etag,
+            unshared_at=unshared_at,
+            allow_download=allow_download,
+            allow_preview=allow_preview,
+            password=password,
+            vanity_name=vanity_name
+        )
+
+    @api_call
+    def get_shared_link(
+            self,
+            *,
+            access: Optional[str] = None,
+            etag: Optional[str] = None,
+            unshared_at: Union[datetime, str, None] = SDK_VALUE_NOT_SET,
+            allow_download: Optional[bool] = None,
+            allow_preview: Optional[bool] = None,
+            password: Optional[str] = None,
+            vanity_name: Optional[str] = None,
+            **kwargs: Any
+    ) -> 'str':
+        """
+        Baseclass override.
+
+        :param access:
+            Determines who can access the shared link. May be open, company, or collaborators. If no access is
+            specified, the default access will be used.
+        :param etag:
+            If specified, instruct the Box API to create the link only if the current version's etag matches.
+        :param unshared_at:
+            The date on which this link should be disabled. May only be set if the current user is not a free user
+            and has permission to set expiration dates. Takes a datetime string supported by the dateutil library
+            or a datetime.datetime object. If no timezone info provided, local timezone will be applied.
+            The time portion can be omitted, which defaults to midnight (00:00:00) on that date.
+        :param allow_download:
+            Whether the folder being shared can be downloaded when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param allow_preview:
+            Whether the folder being shared can be previewed when accessed via the shared link.
+            If this parameter is None, the default setting will be used.
+        :param password:
+            The password required to view this link. If no password is specified then no password will be set.
+            Please notice that this is a premium feature, which might not be available to your app.
+        :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.
+        :param kwargs:
+            Used to fulfill the contract of overriden method
+        :returns:
+            The URL of the shared link.
+        :raises: :class:`BoxAPIException` if the specified etag doesn't match the latest version of the folder.
+        """
+        # pylint:disable=arguments-differ
+        return super().get_shared_link(
+            access=access,
+            etag=etag,
+            unshared_at=unshared_at,
+            allow_download=allow_download,
+            allow_preview=allow_preview,
+            password=password,
+            vanity_name=vanity_name
+        )
+
     @api_call
     def add_collaborator(
             self,
@@ -437,7 +549,7 @@ def add_collaborator(
         """Add a collaborator to the folder
 
         :param collaborator:
-            collaborator to add. May be a User, Group, or email address (unicode string)
+            collaborator to add. It may be a User, Group, or email address (unicode string)
         :param role:
             The collaboration role
         :param notify: