Re-generate docs

docs/exchangelib/autodiscover/discovery.html

@@ -54,6 +54,13 @@ <h1 class="title">Module <code>exchangelib.autodiscover.discovery</code></h1>
 
 log = logging.getLogger(__name__)
 
+DNS_LOOKUP_ERRORS = (
+    dns.name.EmptyLabel,
+    dns.resolver.NXDOMAIN,
+    dns.resolver.NoAnswer,
+    dns.resolver.NoNameservers,
+)
+
 
 def discover(email, credentials=None, auth_type=None, retry_policy=None):
     ad_response, protocol = Autodiscovery(email=email, credentials=credentials).discover()
@@ -385,8 +392,9 @@ <h1 class="title">Module <code>exchangelib.autodiscover.discovery</code></h1>
     def _is_valid_hostname(self, hostname):
         log.debug(&#34;Checking if %s can be looked up in DNS&#34;, hostname)
         try:
-            self.resolver.resolve(hostname)
-        except (dns.resolver.NoNameservers, dns.resolver.NXDOMAIN, dns.resolver.NoAnswer, dns.name.EmptyLabel):
+            self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;A&#34;, lifetime=self.DNS_RESOLVER_ATTRS.get(&#34;timeout&#34;))
+        except DNS_LOOKUP_ERRORS as e:
+            log.debug(&#34;DNS A lookup failure: %s&#34;, e)
             return False
         return True
 
@@ -406,9 +414,9 @@ <h1 class="title">Module <code>exchangelib.autodiscover.discovery</code></h1>
         log.debug(&#34;Attempting to get SRV records for %s&#34;, hostname)
         records = []
         try:
-            answers = self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;SRV&#34;)
-        except (dns.resolver.NoNameservers, dns.resolver.NoAnswer, dns.resolver.NXDOMAIN) as e:
-            log.debug(&#34;DNS lookup failure: %s&#34;, e)
+            answers = self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;SRV&#34;, lifetime=self.DNS_RESOLVER_ATTRS.get(&#34;timeout&#34;))
+        except DNS_LOOKUP_ERRORS as e:
+            log.debug(&#34;DNS SRV lookup failure: %s&#34;, e)
             return records
         for rdata in answers:
             try:
@@ -959,8 +967,9 @@ <h2 class="section-title" id="header-classes">Classes</h2>
     def _is_valid_hostname(self, hostname):
         log.debug(&#34;Checking if %s can be looked up in DNS&#34;, hostname)
         try:
-            self.resolver.resolve(hostname)
-        except (dns.resolver.NoNameservers, dns.resolver.NXDOMAIN, dns.resolver.NoAnswer, dns.name.EmptyLabel):
+            self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;A&#34;, lifetime=self.DNS_RESOLVER_ATTRS.get(&#34;timeout&#34;))
+        except DNS_LOOKUP_ERRORS as e:
+            log.debug(&#34;DNS A lookup failure: %s&#34;, e)
             return False
         return True
 
@@ -980,9 +989,9 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         log.debug(&#34;Attempting to get SRV records for %s&#34;, hostname)
         records = []
         try:
-            answers = self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;SRV&#34;)
-        except (dns.resolver.NoNameservers, dns.resolver.NoAnswer, dns.resolver.NXDOMAIN) as e:
-            log.debug(&#34;DNS lookup failure: %s&#34;, e)
+            answers = self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;SRV&#34;, lifetime=self.DNS_RESOLVER_ATTRS.get(&#34;timeout&#34;))
+        except DNS_LOOKUP_ERRORS as e:
+            log.debug(&#34;DNS SRV lookup failure: %s&#34;, e)
             return records
         for rdata in answers:
             try:

docs/exchangelib/autodiscover/index.html

@@ -665,8 +665,9 @@ <h3>Inherited members</h3>
     def _is_valid_hostname(self, hostname):
         log.debug(&#34;Checking if %s can be looked up in DNS&#34;, hostname)
         try:
-            self.resolver.resolve(hostname)
-        except (dns.resolver.NoNameservers, dns.resolver.NXDOMAIN, dns.resolver.NoAnswer, dns.name.EmptyLabel):
+            self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;A&#34;, lifetime=self.DNS_RESOLVER_ATTRS.get(&#34;timeout&#34;))
+        except DNS_LOOKUP_ERRORS as e:
+            log.debug(&#34;DNS A lookup failure: %s&#34;, e)
             return False
         return True
 
@@ -686,9 +687,9 @@ <h3>Inherited members</h3>
         log.debug(&#34;Attempting to get SRV records for %s&#34;, hostname)
         records = []
         try:
-            answers = self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;SRV&#34;)
-        except (dns.resolver.NoNameservers, dns.resolver.NoAnswer, dns.resolver.NXDOMAIN) as e:
-            log.debug(&#34;DNS lookup failure: %s&#34;, e)
+            answers = self.resolver.resolve(f&#34;{hostname}.&#34;, &#34;SRV&#34;, lifetime=self.DNS_RESOLVER_ATTRS.get(&#34;timeout&#34;))
+        except DNS_LOOKUP_ERRORS as e:
+            log.debug(&#34;DNS SRV lookup failure: %s&#34;, e)
             return records
         for rdata in answers:
             try:

docs/exchangelib/configuration.html

@@ -89,12 +89,12 @@ <h1 class="title">Module <code>exchangelib.configuration</code></h1>
         if auth_type is None:
             # Set a default auth type for the credentials where this makes sense
             auth_type = DEFAULT_AUTH_TYPE.get(type(credentials))
-        elif credentials is None and auth_type in CREDENTIALS_REQUIRED:
+        if auth_type is not None and auth_type not in AUTH_TYPE_MAP:
+            raise InvalidEnumValue(&#34;auth_type&#34;, auth_type, AUTH_TYPE_MAP)
+        if credentials is None and auth_type in CREDENTIALS_REQUIRED:
             raise ValueError(f&#34;Auth type {auth_type!r} was detected but no credentials were provided&#34;)
         if server and service_endpoint:
             raise AttributeError(&#34;Only one of &#39;server&#39; or &#39;service_endpoint&#39; must be provided&#34;)
-        if auth_type is not None and auth_type not in AUTH_TYPE_MAP:
-            raise InvalidEnumValue(&#34;auth_type&#34;, auth_type, AUTH_TYPE_MAP)
         if not retry_policy:
             retry_policy = FailFast()
         if not isinstance(version, (Version, type(None))):
@@ -212,12 +212,12 @@ <h2 class="section-title" id="header-classes">Classes</h2>
         if auth_type is None:
             # Set a default auth type for the credentials where this makes sense
             auth_type = DEFAULT_AUTH_TYPE.get(type(credentials))
-        elif credentials is None and auth_type in CREDENTIALS_REQUIRED:
+        if auth_type is not None and auth_type not in AUTH_TYPE_MAP:
+            raise InvalidEnumValue(&#34;auth_type&#34;, auth_type, AUTH_TYPE_MAP)
+        if credentials is None and auth_type in CREDENTIALS_REQUIRED:
             raise ValueError(f&#34;Auth type {auth_type!r} was detected but no credentials were provided&#34;)
         if server and service_endpoint:
             raise AttributeError(&#34;Only one of &#39;server&#39; or &#39;service_endpoint&#39; must be provided&#34;)
-        if auth_type is not None and auth_type not in AUTH_TYPE_MAP:
-            raise InvalidEnumValue(&#34;auth_type&#34;, auth_type, AUTH_TYPE_MAP)
         if not retry_policy:
             retry_policy = FailFast()
         if not isinstance(version, (Version, type(None))):

docs/exchangelib/credentials.html

@@ -141,21 +141,21 @@ <h1 class="title">Module <code>exchangelib.credentials</code></h1>
     the associated auth code grant type for multi-tenant applications.
     &#34;&#34;&#34;
 
-    def __init__(self, client_id, client_secret, tenant_id=None, identity=None):
+    def __init__(self, client_id, client_secret, tenant_id=None, identity=None, access_token=None):
         &#34;&#34;&#34;
 
         :param client_id: ID of an authorized OAuth application, required for automatic token fetching and refreshing
         :param client_secret: Secret associated with the OAuth application
         :param tenant_id: Microsoft tenant ID of the account to access
         :param identity: An Identity object representing the account that these credentials are connected to.
+        :param access_token: Previously-obtained access token, as a dict or an oauthlib.oauth2.OAuth2Token
         &#34;&#34;&#34;
         super().__init__()
         self.client_id = client_id
         self.client_secret = client_secret
         self.tenant_id = tenant_id
         self.identity = identity
-        # When set, access_token is a dict (or an oauthlib.oauth2.OAuth2Token, which is also a dict)
-        self.access_token = None
+        self.access_token = access_token
 
     def refresh(self, session):
         # Creating a new session gets a new access token, so there&#39;s no work here to refresh the credentials. This
@@ -207,8 +207,8 @@ <h1 class="title">Module <code>exchangelib.credentials</code></h1>
     several ways:
     * Given an authorization code, client ID, and client secret, fetch a token ourselves and refresh it as needed if
       supplied with a refresh token.
-    * Given an existing access token, refresh token, client ID, and client secret, use the access token until it
-      expires and then refresh it as needed.
+    * Given an existing access token, client ID, and client secret, use the access token until it expires and then
+      refresh it as needed.
     * Given only an existing access token, use it until it expires. This can be used to let the calling application
       refresh tokens itself by subclassing and implementing refresh().
 
@@ -217,7 +217,7 @@ <h1 class="title">Module <code>exchangelib.credentials</code></h1>
     tenant.
     &#34;&#34;&#34;
 
-    def __init__(self, authorization_code=None, access_token=None, **kwargs):
+    def __init__(self, authorization_code=None, access_token=None, client_id=None, client_secret=None, **kwargs):
         &#34;&#34;&#34;
 
         :param client_id: ID of an authorized OAuth application, required for automatic token fetching and refreshing
@@ -229,7 +229,7 @@ <h1 class="title">Module <code>exchangelib.credentials</code></h1>
         :param access_token: Previously-obtained access token. If a token exists and the application will handle
           refreshing by itself (or opts not to handle it), this parameter alone is sufficient.
         &#34;&#34;&#34;
-        super().__init__(**kwargs)
+        super().__init__(client_id=client_id, client_secret=client_secret, **kwargs)
         self.authorization_code = authorization_code
         if access_token is not None and not isinstance(access_token, dict):
             raise InvalidTypeError(&#34;access_token&#34;, access_token, OAuth2Token)
@@ -442,15 +442,15 @@ <h3>Inherited members</h3>
 </dd>
 <dt id="exchangelib.credentials.OAuth2AuthorizationCodeCredentials"><code class="flex name class">
 <span>class <span class="ident">OAuth2AuthorizationCodeCredentials</span></span>
-<span>(</span><span>authorization_code=None, access_token=None, **kwargs)</span>
+<span>(</span><span>authorization_code=None, access_token=None, client_id=None, client_secret=None, **kwargs)</span>
 </code></dt>
 <dd>
 <div class="desc"><p>Login info for OAuth 2.0 authentication using the authorization code grant type. This can be used in one of
 several ways:
 * Given an authorization code, client ID, and client secret, fetch a token ourselves and refresh it as needed if
 supplied with a refresh token.
-* Given an existing access token, refresh token, client ID, and client secret, use the access token until it
-expires and then refresh it as needed.
+* Given an existing access token, client ID, and client secret, use the access token until it expires and then
+refresh it as needed.
 * Given only an existing access token, use it until it expires. This can be used to let the calling application
 refresh tokens itself by subclassing and implementing refresh().</p>
 <p>Unlike the base (client credentials) grant, authorization code credentials don't require a Microsoft tenant ID
@@ -473,8 +473,8 @@ <h3>Inherited members</h3>
     several ways:
     * Given an authorization code, client ID, and client secret, fetch a token ourselves and refresh it as needed if
       supplied with a refresh token.
-    * Given an existing access token, refresh token, client ID, and client secret, use the access token until it
-      expires and then refresh it as needed.
+    * Given an existing access token, client ID, and client secret, use the access token until it expires and then
+      refresh it as needed.
     * Given only an existing access token, use it until it expires. This can be used to let the calling application
       refresh tokens itself by subclassing and implementing refresh().
 
@@ -483,7 +483,7 @@ <h3>Inherited members</h3>
     tenant.
     &#34;&#34;&#34;
 
-    def __init__(self, authorization_code=None, access_token=None, **kwargs):
+    def __init__(self, authorization_code=None, access_token=None, client_id=None, client_secret=None, **kwargs):
         &#34;&#34;&#34;
 
         :param client_id: ID of an authorized OAuth application, required for automatic token fetching and refreshing
@@ -495,7 +495,7 @@ <h3>Inherited members</h3>
         :param access_token: Previously-obtained access token. If a token exists and the application will handle
           refreshing by itself (or opts not to handle it), this parameter alone is sufficient.
         &#34;&#34;&#34;
-        super().__init__(**kwargs)
+        super().__init__(client_id=client_id, client_secret=client_secret, **kwargs)
         self.authorization_code = authorization_code
         if access_token is not None and not isinstance(access_token, dict):
             raise InvalidTypeError(&#34;access_token&#34;, access_token, OAuth2Token)
@@ -533,7 +533,7 @@ <h3>Inherited members</h3>
 </dd>
 <dt id="exchangelib.credentials.OAuth2Credentials"><code class="flex name class">
 <span>class <span class="ident">OAuth2Credentials</span></span>
-<span>(</span><span>client_id, client_secret, tenant_id=None, identity=None)</span>
+<span>(</span><span>client_id, client_secret, tenant_id=None, identity=None, access_token=None)</span>
 </code></dt>
 <dd>
 <div class="desc"><p>Login info for OAuth 2.0 client credentials authentication, as well as a base for other OAuth 2.0 grant types.</p>
@@ -544,7 +544,8 @@ <h3>Inherited members</h3>
 <p>:param client_id: ID of an authorized OAuth application, required for automatic token fetching and refreshing
 :param client_secret: Secret associated with the OAuth application
 :param tenant_id: Microsoft tenant ID of the account to access
-:param identity: An Identity object representing the account that these credentials are connected to.</p></div>
+:param identity: An Identity object representing the account that these credentials are connected to.
+:param access_token: Previously-obtained access token, as a dict or an oauthlib.oauth2.OAuth2Token</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
@@ -558,21 +559,21 @@ <h3>Inherited members</h3>
     the associated auth code grant type for multi-tenant applications.
     &#34;&#34;&#34;
 
-    def __init__(self, client_id, client_secret, tenant_id=None, identity=None):
+    def __init__(self, client_id, client_secret, tenant_id=None, identity=None, access_token=None):
         &#34;&#34;&#34;
 
         :param client_id: ID of an authorized OAuth application, required for automatic token fetching and refreshing
         :param client_secret: Secret associated with the OAuth application
         :param tenant_id: Microsoft tenant ID of the account to access
         :param identity: An Identity object representing the account that these credentials are connected to.
+        :param access_token: Previously-obtained access token, as a dict or an oauthlib.oauth2.OAuth2Token
         &#34;&#34;&#34;
         super().__init__()
         self.client_id = client_id
         self.client_secret = client_secret
         self.tenant_id = tenant_id
         self.identity = identity
-        # When set, access_token is a dict (or an oauthlib.oauth2.OAuth2Token, which is also a dict)
-        self.access_token = None
+        self.access_token = access_token
 
     def refresh(self, session):
         # Creating a new session gets a new access token, so there&#39;s no work here to refresh the credentials. This