Added type hinting to Account class

Alejandro Casanovas · Alejandro Casanovas · commit 99f63f8fa608 · 2024-02-01T14:13:30.000+01:00
diff --git a/O365/account.py b/O365/account.py
@@ -1,28 +1,27 @@
+from typing import Type, Tuple, Optional, Callable
 from .connection import Connection, Protocol, MSGraphProtocol, MSOffice365Protocol
 from .utils import ME_RESOURCE, consent
 
 
 class Account:
+    connection_constructor: Type = Connection
 
-    connection_constructor = Connection
+    def __init__(self, credentials: Tuple[str, str], *,
+                 protocol: Optional[Protocol] = None,
+                 main_resource: Optional[str] = None, **kwargs):
+        """ Creates an object which is used to access resources related to the specified credentials.
 
-    def __init__(self, credentials, *, protocol=None, main_resource=None, **kwargs):
-        """ Creates an object which is used to access resources related to the
-        specified credentials
-
-        :param tuple credentials: a tuple containing the client_id
-         and client_secret
-        :param Protocol protocol: the protocol to be used in this account
-        :param str main_resource: the resource to be used by this account
-         ('me' or 'users', etc.)
+        :param credentials: a tuple containing the client_id and client_secret
+        :param protocol: the protocol to be used in this account
+        :param main_resource: the resource to be used by this account ('me' or 'users', etc.)
         :param kwargs: any extra args to be passed to the Connection instance
         :raises ValueError: if an invalid protocol is passed
         """
 
         protocol = protocol or MSGraphProtocol  # Defaults to Graph protocol
-        self.protocol = protocol(default_resource=main_resource,
-                                 **kwargs) if isinstance(protocol,
-                                                         type) else protocol
+        if isinstance(protocol, type):
+            protocol = protocol(default_resource=main_resource, **kwargs)
+        self.protocol: Protocol = protocol
 
         if not isinstance(self.protocol, Protocol):
             raise ValueError("'protocol' must be a subclass of Protocol")
@@ -48,7 +47,8 @@ def __init__(self, credentials, *, protocol=None, main_resource=None, **kwargs):
                 main_resource = ''
 
         elif auth_flow_type == 'password':
-            kwargs['scopes'] = self.protocol.get_scopes_for(scopes) if scopes else [self.protocol.prefix_scope('.default')]
+            kwargs['scopes'] = self.protocol.get_scopes_for(scopes) if scopes else [
+                self.protocol.prefix_scope('.default')]
 
             # set main_resource to blank when it's the 'ME' resource
             if self.protocol.default_resource == ME_RESOURCE:
@@ -60,7 +60,7 @@ def __init__(self, credentials, *, protocol=None, main_resource=None, **kwargs):
                              '"public"')
 
         self.con = self.connection_constructor(credentials, **kwargs)
-        self.main_resource = main_resource or self.protocol.default_resource
+        self.main_resource: str = main_resource or self.protocol.default_resource
 
     def __repr__(self):
         if self.con.auth:
@@ -69,34 +69,35 @@ def __repr__(self):
             return 'Unidentified Account'
 
     @property
-    def is_authenticated(self):
+    def is_authenticated(self) -> bool:
         """
-        Checks whether the library has the authentication and that is not expired
-        :return: True if authenticated, False otherwise
+        Checks whether the library has the authentication and that is not expired.
+        Return True if authenticated, False otherwise.
         """
         token = self.con.token_backend.token
         if not token:
             token = self.con.token_backend.get_token()
 
         return token is not None and not token.is_expired
 
-    def authenticate(self, *, scopes=None, handle_consent=consent.consent_input_token, **kwargs):
+    def authenticate(self, *, scopes: Optional[list] = None,
+                     handle_consent: Callable = consent.consent_input_token, **kwargs) -> bool:
         """ Performs the oauth authentication flow using the console resulting in a stored token.
-        It uses the credentials passed on instantiation
+        It uses the credentials passed on instantiation.
+        Returns True if succeded otherwise False.
 
-        :param list[str] or None scopes: list of protocol user scopes to be converted
+        :param scopes: list of protocol user scopes to be converted
          by the protocol or scope helpers
         :param handle_consent: a function to handle the consent process by default just input for the token url
         :param kwargs: other configurations to be passed to the
          Connection.get_authorization_url and Connection.request_token methods
-        :return: Success / Failure
-        :rtype: bool
         """
 
         if self.con.auth_flow_type in ('authorization', 'public'):
             if scopes is not None:
                 if self.con.scopes is not None:
-                    raise RuntimeError('The scopes must be set either at the Account instantiation or on the account.authenticate method.')
+                    raise RuntimeError('The scopes must be set either at the Account '
+                                       'instantiation or on the account.authenticate method.')
                 self.con.scopes = self.protocol.get_scopes_for(scopes)
             else:
                 if self.con.scopes is None:
@@ -140,7 +141,7 @@ def connection(self):
         """
         return self.con
 
-    def new_message(self, resource=None):
+    def new_message(self, resource: Optional[str] = None):
         """ Creates a new message to be sent or stored
 
         :param str resource: Custom resource to be used in this message
@@ -151,24 +152,24 @@ def new_message(self, resource=None):
         from .message import Message
         return Message(parent=self, main_resource=resource, is_draft=True)
 
-    def mailbox(self, resource=None):
+    def mailbox(self, resource: Optional[str] = None):
         """ Get an instance to the mailbox for the specified account resource
 
-        :param str resource: Custom resource to be used in this mailbox
+        :param resource: Custom resource to be used in this mailbox
          (Defaults to parent main_resource)
         :return: a representation of account mailbox
         :rtype: O365.mailbox.MailBox
         """
         from .mailbox import MailBox
         return MailBox(parent=self, main_resource=resource, name='MailBox')
 
-    def address_book(self, *, resource=None, address_book='personal'):
+    def address_book(self, *, resource: Optional[str] = None, address_book: str = 'personal'):
         """ Get an instance to the specified address book for the
         specified account resource
 
-        :param str resource: Custom resource to be used in this address book
+        :param resource: Custom resource to be used in this address book
          (Defaults to parent main_resource)
-        :param str address_book: Choose from 'Personal' or 'Directory'
+        :param address_book: Choose from 'Personal' or 'Directory'
         :return: a representation of the specified address book
         :rtype: AddressBook or GlobalAddressList
         :raises RuntimeError: if invalid address_book is specified
@@ -188,29 +189,29 @@ def address_book(self, *, resource=None, address_book='personal'):
                 'address_book must be either "Personal" '
                 '(resource address book) or "Directory" (Active Directory)')
 
-    def directory(self, resource=None):
+    def directory(self, resource: Optional[str] = None):
         """ Returns the active directory instance"""
         from .directory import Directory, USERS_RESOURCE
 
         return Directory(parent=self, main_resource=resource or USERS_RESOURCE)
 
-    def schedule(self, *, resource=None):
+    def schedule(self, *, resource: Optional[str] = None):
         """ Get an instance to work with calendar events for the
         specified account resource
 
-        :param str resource: Custom resource to be used in this schedule object
+        :param resource: Custom resource to be used in this schedule object
          (Defaults to parent main_resource)
         :return: a representation of calendar events
         :rtype: Schedule
         """
         from .calendar import Schedule
         return Schedule(parent=self, main_resource=resource)
 
-    def storage(self, *, resource=None):
+    def storage(self, *, resource: Optional[str] = None):
         """ Get an instance to handle file storage (OneDrive / Sharepoint)
         for the specified account resource
 
-        :param str resource: Custom resource to be used in this drive object
+        :param resource: Custom resource to be used in this drive object
          (Defaults to parent main_resource)
         :return: a representation of OneDrive File Storage
         :rtype: Storage
@@ -223,11 +224,11 @@ def storage(self, *, resource=None):
         from .drive import Storage
         return Storage(parent=self, main_resource=resource)
 
-    def sharepoint(self, *, resource=''):
+    def sharepoint(self, *, resource: str = ''):
         """ Get an instance to read information from Sharepoint sites for the
         specified account resource
 
-        :param str resource: Custom resource to be used in this sharepoint
+        :param resource: Custom resource to be used in this sharepoint
          object (Defaults to parent main_resource)
         :return: a representation of Sharepoint Sites
         :rtype: Sharepoint
@@ -242,7 +243,7 @@ def sharepoint(self, *, resource=''):
         from .sharepoint import Sharepoint
         return Sharepoint(parent=self, main_resource=resource)
 
-    def planner(self, *, resource=''):
+    def planner(self, *, resource: str = ''):
         """ Get an instance to read information from Microsoft planner """
 
         if not isinstance(self.protocol, MSGraphProtocol):
@@ -253,7 +254,7 @@ def planner(self, *, resource=''):
         from .planner import Planner
         return Planner(parent=self, main_resource=resource)
 
-    def tasks(self, *, resource=''):
+    def tasks(self, *, resource: str = ''):
         """ Get an instance to read information from Microsoft ToDo """
 
         if isinstance(self.protocol, MSOffice365Protocol):
@@ -262,8 +263,8 @@ def tasks(self, *, resource=''):
             from .tasks_graph import ToDo as ToDo
 
         return ToDo(parent=self, main_resource=resource)
-    
-    def teams(self, *, resource=''):
+
+    def teams(self, *, resource: str = ''):
         """ Get an instance to read information from Microsoft Teams """
 
         if not isinstance(self.protocol, MSGraphProtocol):
@@ -273,13 +274,13 @@ def teams(self, *, resource=''):
         from .teams import Teams
         return Teams(parent=self, main_resource=resource)
 
-    def outlook_categories(self, *, resource=''):
+    def outlook_categories(self, *, resource: str = ''):
         """ Returns a Categories object to handle the available Outlook Categories """
         from .category import Categories
 
         return Categories(parent=self, main_resource=resource)
 
-    def groups(self, *, resource=''):
+    def groups(self, *, resource: str = ''):
         """ Get an instance to read information from Microsoft Groups """
 
         if not isinstance(self.protocol, MSGraphProtocol):
