Add comments on base_path potential deprecation (#1097)

New `NOTE: ...` comments call out `base_path` settings as something
considered problematic, as they've hampered us in the past.

Removing them is a significant breaking change, and as class
attributes, they would require a more elaborate deprecation strategy
if we wanted to have them actually issue deprecation warnings.

Limiting ourselves to a comment for now helps authors know not to use
`base_path` for new classes without having to solve how we can
actually deprecate and remove the setting.

src/globus_sdk/client.py

@@ -47,7 +47,11 @@ class BaseClient:
 
     # service name is used to lookup a service URL from config
     service_name: str = "_base"
+
     # path under the client base URL
+    # NOTE: using this attribute is now considered bad practice for client definitions,
+    # as it prevents calls to new routes at the root of an API's base_url
+    # Consider removing in a future release
     base_path: str = "/"
 
     #: the class for errors raised by this client on HTTP 4xx and 5xx errors

src/globus_sdk/services/groups/client.py

@@ -22,6 +22,8 @@ class GroupsClient(client.BaseClient):
     .. automethodlist:: globus_sdk.GroupsClient
     """
 
+    # NOTE: setting base_path is no longer considered good practice
+    #       see the BaseClient source for details
     base_path = "/v2/"
     error_class = GroupsAPIError
     service_name = "groups"

src/globus_sdk/services/transfer/client.py

@@ -107,6 +107,8 @@ class TransferClient(client.BaseClient):
     """
 
     service_name = "transfer"
+    # NOTE: setting base_path is no longer considered good practice
+    #       see the BaseClient source for details
     base_path = "/v0.10/"
     transport_class: type[TransferRequestsTransport] = TransferRequestsTransport
     error_class = TransferAPIError