Add more documentation around contructor parameters for client, async_client and legacy_client as well as their base classes. In particular focusing on documenting the proxy and ssl parameters (relates to #1214).

Author: Filip Maj

slack_sdk/web/async_base_client.py

@@ -44,14 +44,35 @@ def __init__(
         retry_handlers: Optional[List[RetryHandler]] = None,
     ):
         self.token = None if token is None else token.strip()
+        """A string specifying an `xoxp-*` or `xoxb-*` token."""
         self.base_url = base_url
+        """A string representing the Slack API base URL.
+        Default is `'https://www.slack.com/api/'`."""
         self.timeout = timeout
+        """The maximum number of seconds the client will wait
+        to connect and receive a response from Slack.
+        Default is 30 seconds."""
         self.ssl = ssl
+        """An [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html#ssl.SSLContext)
+        instance, helpful for specifying your own custom
+        certificate chain."""
         self.proxy = proxy
+        """String representing a fully-qualified URL to a proxy through which
+        to route all requests to the Slack API. Even if this parameter
+        is not specified, if any of the following environment variables are
+        present, they will be loaded into this parameter: `HTTPS_PROXY`,
+        `https_proxy`, `HTTP_PROXY` or `http_proxy`."""
         self.session = session
+        """An [`aiohttp.ClientSession`](https://docs.aiohttp.org/en/stable/client_reference.html#client-session)
+        to attach to all outgoing requests."""
         # https://github.com/slackapi/python-slack-sdk/issues/738
         self.trust_env_in_session = trust_env_in_session
+        """Boolean setting whether aiohttp outgoing requests
+        are allowed to read environment variables. Commonly used in conjunction
+        with proxy support via the `HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY` and
+        `http_proxy` environment variables."""
         self.headers = headers or {}
+        """`dict` representing additional request headers to attach to all requests."""
         self.headers["User-Agent"] = get_user_agent(
             user_agent_prefix, user_agent_suffix
         )

slack_sdk/web/async_client.py

@@ -39,15 +39,28 @@ class AsyncWebClient(AsyncBaseClient):
     as well as parsing any responses received into a `SlackResponse`.
 
     Attributes:
-        token (str): A string specifying an xoxp or xoxb token.
+        token (str): A string specifying an `xoxp-*` or `xoxb-*` token.
         base_url (str): A string representing the Slack API base URL.
-            Default is 'https://www.slack.com/api/'
+            Default is `'https://www.slack.com/api/'`
         timeout (int): The maximum number of seconds the client will wait
             to connect and receive a response from Slack.
             Default is 30 seconds.
+        ssl (SSLContext): An [`ssl.SSLContext`][1] instance, helpful for specifying
+            your own custom certificate chain.
+        proxy (str): String representing a fully-qualified URL to a proxy through
+            which to route all requests to the Slack API. Even if this parameter
+            is not specified, if any of the following environment variables are
+            present, they will be loaded into this parameter: `HTTPS_PROXY`,
+            `https_proxy`, `HTTP_PROXY` or `http_proxy`.
+        session (ClientSession): [`aiohttp.ClientSession`][2] to attach to all outgoing requests.
+        trust_env_in_session (bool): Boolean setting whether aiohttp outgoing requests
+            are allowed to read environment variables. Commonly used in conjunction
+            with proxy support via the `HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY` and
+            `http_proxy` environment variables.
+        headers (dict): Additional request headers to attach to all requests.
 
     Methods:
-        api_call: Constructs a request and executes the API call to Slack.
+        `api_call`: Constructs a request and executes the API call to Slack.
 
     Example of recommended usage:
     ```python
@@ -80,6 +93,9 @@ class AsyncWebClient(AsyncBaseClient):
         Any attributes or methods prefixed with _underscores are
         intended to be "private" internal use only. They may be changed or
         removed at anytime.
+
+    [1]: https://docs.python.org/3/library/ssl.html#ssl.SSLContext
+    [2]: https://docs.aiohttp.org/en/stable/client_reference.html#client-session
     """
 
     async def admin_analytics_getFile(

slack_sdk/web/base_client.py

@@ -57,11 +57,26 @@ def __init__(
         retry_handlers: Optional[List[RetryHandler]] = None,
     ):
         self.token = None if token is None else token.strip()
+        """A string specifying an `xoxp-*` or `xoxb-*` token."""
         self.base_url = base_url
+        """A string representing the Slack API base URL.
+        Default is `'https://www.slack.com/api/'`."""
         self.timeout = timeout
+        """The maximum number of seconds the client will wait
+        to connect and receive a response from Slack.
+        Default is 30 seconds."""
         self.ssl = ssl
+        """An [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html#ssl.SSLContext)
+        instance, helpful for specifying your own custom
+        certificate chain."""
         self.proxy = proxy
+        """String representing a fully-qualified URL to a proxy through which
+        to route all requests to the Slack API. Even if this parameter
+        is not specified, if any of the following environment variables are
+        present, they will be loaded into this parameter: `HTTPS_PROXY`,
+        `https_proxy`, `HTTP_PROXY` or `http_proxy`."""
         self.headers = headers or {}
+        """`dict` representing additional request headers to attach to all requests."""
         self.headers["User-Agent"] = get_user_agent(
             user_agent_prefix, user_agent_suffix
         )

slack_sdk/web/client.py

@@ -30,15 +30,23 @@ class WebClient(BaseClient):
     as well as parsing any responses received into a `SlackResponse`.
 
     Attributes:
-        token (str): A string specifying an xoxp or xoxb token.
+        token (str): A string specifying an `xoxp-*` or `xoxb-*` token.
         base_url (str): A string representing the Slack API base URL.
-            Default is 'https://www.slack.com/api/'
+            Default is `'https://www.slack.com/api/'`
         timeout (int): The maximum number of seconds the client will wait
             to connect and receive a response from Slack.
             Default is 30 seconds.
+        ssl (SSLContext): An [`ssl.SSLContext`][1] instance, helpful for specifying
+            your own custom certificate chain.
+        proxy (str): String representing a fully-qualified URL to a proxy through
+            which to route all requests to the Slack API. Even if this parameter
+            is not specified, if any of the following environment variables are
+            present, they will be loaded into this parameter: `HTTPS_PROXY`,
+            `https_proxy`, `HTTP_PROXY` or `http_proxy`.
+        headers (dict): Additional request headers to attach to all requests.
 
     Methods:
-        api_call: Constructs a request and executes the API call to Slack.
+        `api_call`: Constructs a request and executes the API call to Slack.
 
     Example of recommended usage:
     ```python
@@ -71,6 +79,8 @@ class WebClient(BaseClient):
         Any attributes or methods prefixed with _underscores are
         intended to be "private" internal use only. They may be changed or
         removed at anytime.
+
+    [1]: https://docs.python.org/3/library/ssl.html#ssl.SSLContext
     """
 
     def admin_analytics_getFile(

slack_sdk/web/legacy_base_client.py

@@ -59,14 +59,29 @@ def __init__(
         logger: Optional[logging.Logger] = None,
     ):
         self.token = None if token is None else token.strip()
+        """A string specifying an `xoxp-*` or `xoxb-*` token."""
         self.base_url = base_url
+        """A string representing the Slack API base URL.
+        Default is `'https://www.slack.com/api/'`."""
         self.timeout = timeout
+        """The maximum number of seconds the client will wait
+        to connect and receive a response from Slack.
+        Default is 30 seconds."""
         self.ssl = ssl
+        """An [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html#ssl.SSLContext)
+        instance, helpful for specifying your own custom
+        certificate chain."""
         self.proxy = proxy
+        """String representing a fully-qualified URL to a proxy through which
+        to route all requests to the Slack API. Even if this parameter
+        is not specified, if any of the following environment variables are
+        present, they will be loaded into this parameter: `HTTPS_PROXY`,
+        `https_proxy`, `HTTP_PROXY` or `http_proxy`."""
         self.run_async = run_async
         self.use_sync_aiohttp = use_sync_aiohttp
         self.session = session
         self.headers = headers or {}
+        """`dict` representing additional request headers to attach to all requests."""
         self.headers["User-Agent"] = get_user_agent(
             user_agent_prefix, user_agent_suffix
         )

slack_sdk/web/legacy_client.py

@@ -41,15 +41,24 @@ class LegacyWebClient(LegacyBaseClient):
     as well as parsing any responses received into a `SlackResponse`.
 
     Attributes:
-        token (str): A string specifying an xoxp or xoxb token.
+        token (str): A string specifying an `xoxp-*` or `xoxb-*` token.
         base_url (str): A string representing the Slack API base URL.
-            Default is 'https://www.slack.com/api/'
+            Default is `'https://www.slack.com/api/'`
         timeout (int): The maximum number of seconds the client will wait
             to connect and receive a response from Slack.
             Default is 30 seconds.
+        ssl (SSLContext): An [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html#ssl.SSLContext)
+            instance, helpful for specifying your own custom certificate
+            chain.
+        proxy (str): String representing a fully-qualified URL to a proxy through
+            which to route all requests to the Slack API. Even if this parameter
+            is not specified, if any of the following environment variables are
+            present, they will be loaded into this parameter: `HTTPS_PROXY`,
+            `https_proxy`, `HTTP_PROXY` or `http_proxy`.
+        headers (dict): Additional request headers to attach to all requests.
 
     Methods:
-        api_call: Constructs a request and executes the API call to Slack.
+        `api_call`: Constructs a request and executes the API call to Slack.
 
     Example of recommended usage:
     ```python