docs: Documentation update for release 3.0.0 (#652)

Author: lukaszsocha2

HISTORY.rst

@@ -3,6 +3,27 @@
 Release History
 ---------------
 
+3.0.0 (2022-01-17)
+++++++++++++++++++++
+
+**Breaking Changes**
+
+- Drop support for python 2.7 (`#645 <https://github.com/box/box-python-sdk/pull/645>`_)
+- Add missing parameter stream_position to get_admin_events method (`#648 <https://github.com/box/box-python-sdk/pull/648>`_)
+- Drop support for python 3.5 (`#654 <https://github.com/box/box-python-sdk/pull/654>`_)
+- Remove deprecated code using insensitive language (`#651 <https://github.com/box/box-python-sdk/pull/651>`_)
+- Enforcing usage of keyword-only arguments in some functions (`#656 <https://github.com/box/box-python-sdk/pull/656>`_)
+
+**New Features and Enhancements:**
+
+- Remove six library and __future__ imports (`#646 <https://github.com/box/box-python-sdk/pull/646>`_)
+- Add type hints to method parameters (`#650 <https://github.com/box/box-python-sdk/pull/650>`_)
+
+**Bug Fixes:**
+
+- Add missing api_call decorators on multiput calls (`#653 <https://github.com/box/box-python-sdk/pull/653>`_)
+- Added `py.typed` file for mypy to recognise type hints (`#657 <https://github.com/box/box-python-sdk/pull/657>`_)
+
 2.14.0 (2021-12-08)
 ++++++++++++++++++++
 

docs/usage/authentication.md

@@ -83,7 +83,7 @@ auth = OAuth2(
 )
 client = Client(auth)
 me = client.user().get()
-print('My user ID is {0}'.format(me.id))
+print(f'My user ID is {me.id}')
 ```
 
 [dev_console]: https://app.box.com/developers/console
@@ -118,7 +118,7 @@ from boxsdk import JWTAuth, Client
 auth = JWTAuth.from_settings_file('/path/to/settings.json')
 client = Client(auth)
 service_account = client.user().get()
-print('Service Account user ID is {0}'.format(service_account.id))
+print(f'Service Account user ID is {service_account.id}')
 ```
 
 Otherwise, you'll need to provide the necessary configuration fields directly
@@ -262,7 +262,7 @@ oauth = OAuth2(
 client = Client(oauth)
 
 user = client.user().get()
-print('User ID is {0}'.format(user.id))
+print(f'User ID is {user.id}')
 ```
 
 ### Box View Authentication with App Tokens
@@ -330,7 +330,7 @@ This method returns a [`TokenResponse`][token_response] object with the downscop
 ```python
 target_file = client.file(file_id='FILE_ID_HERE')
 token_info = client.downscope_token(['item_preview'], target_file)
-print('Got downscoped access token: {0}'.format(token_info.access_token))
+print(f'Got downscoped access token: {token_info.access_token}')
 ```
 
 [downscope_token]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.downscope_token

docs/usage/classifications.md

@@ -66,15 +66,15 @@ Add another classification
 
 To add another classification, call the
 [`template.start_update()`][start_update] API to start making changes to the 
-template, and then call the [`template.update_info(updates)`][update_info]
+template, and then call the [`template.update_info(updates=new_updates)`][update_info]
 with the changes to apply to the template.
 
 <!-- sample put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema add -->
 ```python
 template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo')
-updates = template.start_update()
-updates.add_enum_option('Box__Security__Classification__Key', 'Sensitive')
-updated_template = template.update_info(updates)
+new_updates = template.start_update()
+new_updates.add_enum_option('Box__Security__Classification__Key', 'Sensitive')
+updated_template = template.update_info(updates=new_updates)
 ```
 
 [start_update]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.metadata_template.MetadataTemplate.start_update
@@ -85,31 +85,31 @@ Update a classification
 
 To update a classification, call the
 [`template.start_update()`][start_update] API to start making changes to the 
-template, and then call the [`template.update_info(updates)`][update_info]
+template, and then call the [`template.update_info(updates=new_updates)`][update_info]
 with the classification to change on the template.
 
 <!-- sample put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema update -->
 ```python
 template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo')
-updates = template.start_update()
-updates.edit_enum_option('Box__Security__Classification__Key', 'Sensitive', 'Very Sensitive')
-updated_template = template.update_info(updates)
+new_updates = template.start_update()
+new_updates.edit_enum_option('Box__Security__Classification__Key', 'Sensitive', 'Very Sensitive')
+updated_template = template.update_info(updates=new_updates)
 ```
 
 Delete a classification
 -----------------------
 
 To delete a classification, call the
 [`template.start_update()`][start_update] API to start making changes to the 
-template, and then call the [`template.update_info(updates)`][update_info]
+template, and then call the [`template.update_info(updates=new_updates)`][update_info]
 with the classification to remove from the template.
 
 <!-- sample put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema delete -->
 ```python
 template = client.metadata_template('enterprise', 'securityClassification-6VMVochwUWo')
-updates = template.start_update()
-updates.remove_enum_option('Box__Security__Classification__Key', 'Sensitive')
-updated_template = template.update_info(updates)
+new_updates = template.start_update()
+new_updates.remove_enum_option('Box__Security__Classification__Key', 'Sensitive')
+updated_template = template.update_info(updates=new_updates)
 ```
 
 Delete all classifications

docs/usage/collaboration.md

@@ -37,7 +37,7 @@ collaboration = client.folder(folder_id='22222').collaborate(user, Collaboration
 collaborator = collaboration.accessible_by
 item = collaboration.item
 has_accepted = 'has' if collaboration.status == 'accepted' else 'has not'
-print('{0} {1} accepted the collaboration to folder "{2}"'.format(collaborator.name, has_accepted, item.name))
+print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"')
 ```
 
 Alternatively, you can also invite a user with their email address.
@@ -61,7 +61,7 @@ collaboration = client.folder(folder_id='22222').collaborate(group, Collaboratio
 collaborator = collaboration.accessible_by
 item = collaboration.item
 has_accepted = 'has' if collaboration.status == 'accepted' else 'has not'
-print('{0} {1} accepted the collaboration to folder "{2}"'.format(collaborator.name, has_accepted, item.name))
+print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"')
 ```
 
 > __Note:__ The `can_view_path` parameter is currently only available for collaborations on folders.
@@ -74,15 +74,15 @@ print('{0} {1} accepted the collaboration to folder "{2}"'.format(collaborator.n
 Edit a Collaboration
 --------------------
 
-A collaboration can be edited by calling [`collaboration.update_info(role, status=None)`][update_info].  This method
+A collaboration can be edited by calling [`collaboration.update_info(*, role=None, status=None, **kwargs)`][update_info].  This method
 returns an updated [`Collaboration`][collaboration_class] object, leaving the original unmodified.
 
 <!-- sample put_collaborations_id -->
 ```python
 from boxsdk.object.collaboration import CollaborationRole, CollaborationStatus
 
 collaboration = client.collaboration(collab_id='12345')
-updated_collaboration = collaboration.update_info(CollaborationRole.EDITOR)
+updated_collaboration = collaboration.update_info(role=CollaborationRole.EDITOR)
 ```
 
 [update_info]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration.Collaboration.update_info
@@ -128,15 +128,15 @@ To retrieve all collaborations on a specified [`Folder`][folder_class] or [`File
 collaborations = client.folder(folder_id='22222').get_collaborations()
 for collab in collaborations:
     target = collab.accessible_by
-    print('{0} {1} is collaborated on the folder'.format(target.type.capitalize(), target.name))
+    print(f'{target.type.capitalize()} {target.name} is collaborated on the folder')
 ```
 
 <!-- sample get_files_id_collaborations -->
 ```python
 collaborations = client.file(file_id='11111').get_collaborations()
 for collab in collaborations
     target = collab.accessible_by
-    print('{0} {1} is collaborated on the file'.format(target.type.capitalize(), target.name))
+    print(f'{target.type.capitalize()} {target.name} is collaborated on the file')
 ```
 
 [folder_class]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.folder.Folder
@@ -155,7 +155,7 @@ can use to iterate over all pending [`Collaboration`][collaboration_class] objec
 ```python
 pending_collaborations = client.get_pending_collaborations()
 for pending_collaboration in pending_collaborations:
-    print('Collaboration {0} is pending'.format(pending_collaboration.id))
+    print(f'Collaboration {pending_collaboration.id} is pending')
 ```
 
 [get_pending_collaborations]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.client.html#boxsdk.client.client.Client.get_pending_collaborations

docs/usage/collaboration_allowlist.md

@@ -35,7 +35,7 @@ objects in the collection.
 allowlist_entries = client.collaboration_allowlist().get_entries()
 for entry in allowlist_entries:
     direction = entry.direction if entry.direction != 'both' else 'bidirectional'
-    print('Domain {0} is allowlisted for {1} collaboration'.format(entry.domain, direction))
+    print(f'Domain {entry.domain} is allowlisted for {direction} collaboration')
 ```
 
 [get_entries]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist.CollaborationAllowlist.get_entries
@@ -44,7 +44,7 @@ for entry in allowlist_entries:
 Get Information for Collaboration Allowlist Entry
 -------------------------------------------------
 
-To get information about a collaboration allowlist entry, use [`collaboration_allowlist_entry.get(fields=None)`][get].
+To get information about a collaboration allowlist entry, use [`collaboration_allowlist_entry.get(*, fields=None, headers=None, **kwargs)`][get].
 This method returns a [`CollaborationAllowlistEntry`][entry_class] object with fields populated by data form the API.
 
 <!-- sample get_collaboration_allowlist_entries_id -->
@@ -100,7 +100,7 @@ a `BoxObjectCollection` that allows you to iterate over each
 ```python
 exemptions = client.collaboration_allowlist().get_exemptions()
 for exemption in exemptions:
-    print('{0} (ID: {1}) is exempt from the collaboration allowlist'.format(exemption.user.name, exemption.user.id))
+    print(f'{exemption.user.name} (ID: {exemption.user.id}) is exempt from the collaboration allowlist')
 ```
 
 [get_exemptions]: https://box-python-sdk.readthedocs.io/en/latest/boxsdk.object.html#boxsdk.object.collaboration_allowlist.CollaborationAllowlist.get_exemptions
@@ -109,8 +109,8 @@ for exemption in exemptions:
 Get Exempt User Information
 ---------------------------
 
-To get information about an exempted user, call [`collaboration_allowlist_exempt_target.get(fields=None)`][get].  This
-method will return a [`CollaborationAllowlistExemptTarget][exemption_class] with fields populated by data from the API.
+To get information about an exempted user, call [`collaboration_allowlist_exempt_target.get(*, fields=None, headers=None, **kwargs)`][get].
+This method will return a [`CollaborationAllowlistExemptTarget][exemption_class] with fields populated by data from the API.
 
 <!-- sample get_collaboration_allowlist_exempt_targets_id -->
 ```python