diff --git a/docs/conf.py b/docs/conf.py index fb11842..490eb49 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,6 +41,7 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx.ext.todo", "sphinx.ext.viewcode", + "sphinx.ext.napoleon", ] # Add any paths that contain templates here, relative to this directory. @@ -182,3 +183,13 @@ intersphinx_mapping = {"https://docs.python.org/": None} todo_include_todos = True todo_link_only = True + +# -- Options for napoleon extension ---------------------------------------------- + +# Use Google style docstrings +napoleon_google_docstring = True +napoleon_numpy_docstring = False + +# napoleon_use_admonition_for_examples = False +# napoleon_use_admonition_for_notes = False +# napoleon_use_admonition_for_references = False diff --git a/fbchat/_client.py b/fbchat/_client.py index ec70f87..aeced3b 100644 --- a/fbchat/_client.py +++ b/fbchat/_client.py @@ -74,16 +74,16 @@ class Client(object): ): """Initialize and log in the client. - :param email: Facebook ``email``, ``id`` or ``phone number`` - :param password: Facebook account password - :param user_agent: Custom user agent to use when sending requests. If `None`, user agent will be chosen from a premade list - :param max_tries: Maximum number of times to try logging in - :param session_cookies: Cookies from a previous session (Will default to login if these are invalid) - :param logging_level: Configures the `logging level `_. Defaults to ``logging.INFO`` - :type max_tries: int - :type session_cookies: dict - :type logging_level: int - :raises: FBchatException on failed login + Args: + email: Facebook ``email``, ``id`` or ``phone number`` + password: Facebook account password + user_agent: Custom user agent to use when sending requests. If `None`, user agent will be chosen from a premade list + max_tries (int): Maximum number of times to try logging in + session_cookies (dict): Cookies from a previous session (Will default to login if these are invalid) + logging_level (int): Configures the `logging level `_. Defaults to ``logging.INFO`` + + Raises: + FBchatException: On failed login """ self._sticky, self._pool = (None, None) self._seq = "0" @@ -169,12 +169,14 @@ class Client(object): def graphql_requests(self, *queries): """Execute graphql queries. - :param queries: Zero or more dictionaries - :type queries: dict + Args: + queries (dict): Zero or more dictionaries - :raises: FBchatException if request failed - :return: A tuple containing json graphql queries - :rtype: tuple + Returns: + tuple: A tuple containing json graphql queries + + Raises: + FBchatException: If request failed """ data = { "method": "GET", @@ -186,7 +188,8 @@ class Client(object): def graphql_request(self, query): """Shorthand for ``graphql_requests(query)[0]``. - :raises: FBchatException if request failed + Raises: + FBchatException: If request failed """ return self.graphql_requests(query)[0] @@ -201,26 +204,27 @@ class Client(object): def isLoggedIn(self): """Send a request to Facebook to check the login status. - :return: True if the client is still logged in - :rtype: bool + Returns: + bool: True if the client is still logged in """ return self._state.is_logged_in() def getSession(self): """Retrieve session cookies. - :return: A dictionay containing session cookies - :rtype: dict + Returns: + dict: A dictionay containing session cookies """ return self._state.get_cookies() def setSession(self, session_cookies, user_agent=None): """Load session cookies. - :param session_cookies: A dictionay containing session cookies - :type session_cookies: dict - :return: False if ``session_cookies`` does not contain proper cookies - :rtype: bool + Args: + session_cookies (dict): A dictionay containing session cookies + + Returns: + bool: False if ``session_cookies`` does not contain proper cookies """ try: # Load cookies into current session @@ -241,11 +245,13 @@ class Client(object): If the user is already logged in, this will do a re-login. - :param email: Facebook ``email`` or ``id`` or ``phone number`` - :param password: Facebook account password - :param max_tries: Maximum number of times to try logging in - :type max_tries: int - :raises: FBchatException on failed login + Args: + email: Facebook ``email`` or ``id`` or ``phone number`` + password: Facebook account password + max_tries (int): Maximum number of times to try logging in + + Raises: + FBchatException: On failed login """ self.onLoggingIn(email=email) @@ -280,8 +286,8 @@ class Client(object): def logout(self): """Safely log out the client. - :return: True if the action was successful - :rtype: bool + Returns: + bool: True if the action was successful """ if self._state.logout(): self._state = None @@ -300,9 +306,11 @@ class Client(object): def _getThread(self, given_thread_id=None, given_thread_type=None): """Check if thread ID is given and if default is set, and return correct values. - :raises ValueError: If thread ID is not given and there is no default - :return: Thread ID and thread type - :rtype: tuple + Returns: + tuple: Thread ID and thread type + + Raises: + ValueError: If thread ID is not given and there is no default """ if given_thread_id is None: if self._default_thread_id is not None: @@ -315,9 +323,9 @@ class Client(object): def setDefaultThread(self, thread_id, thread_type): """Set default thread to send messages to. - :param thread_id: User/Group ID to default to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType + Args: + thread_id: User/Group ID to default to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` """ self._default_thread_id = thread_id self._default_thread_type = thread_type @@ -343,13 +351,17 @@ class Client(object): Threads will be sorted from newest to oldest. - :param thread_location: ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER - :param before: Fetch only thread before this epoch (in ms) (default all threads) - :param after: Fetch only thread after this epoch (in ms) (default all threads) - :param limit: The max. amount of threads to fetch (default all threads) - :return: :class:`Thread` objects - :rtype: list - :raises: FBchatException if request failed + Args: + thread_location (ThreadLocation): INBOX, PENDING, ARCHIVED or OTHER + before: Fetch only thread before this epoch (in ms) (default all threads) + after: Fetch only thread after this epoch (in ms) (default all threads) + limit: The max. amount of threads to fetch (default all threads) + + Returns: + list: :class:`Thread` objects + + Raises: + FBchatException: If request failed """ threads = [] @@ -394,10 +406,14 @@ class Client(object): def fetchAllUsersFromThreads(self, threads): """Fetch all users involved in given threads. - :param threads: Thread: List of threads to check for users - :return: :class:`User` objects - :rtype: list - :raises: FBchatException if request failed + Args: + threads: Thread: List of threads to check for users + + Returns: + list: :class:`User` objects + + Raises: + FBchatException: If request failed """ users = [] users_to_fetch = [] # It's more efficient to fetch all users in one request @@ -419,9 +435,11 @@ class Client(object): def fetchAllUsers(self): """Fetch all users the client is currently chatting with. - :return: :class:`User` objects - :rtype: list - :raises: FBchatException if request failed + Returns: + list: :class:`User` objects + + Raises: + FBchatException: If request failed """ data = {"viewer": self._uid} j = self._payload_post("/chat/user_info_all", data) @@ -438,11 +456,15 @@ class Client(object): def searchForUsers(self, name, limit=10): """Find and get users by their name. - :param name: Name of the user - :param limit: The max. amount of users to fetch - :return: :class:`User` objects, ordered by relevance - :rtype: list - :raises: FBchatException if request failed + Args: + name: Name of the user + limit: The max. amount of users to fetch + + Returns: + list: :class:`User` objects, ordered by relevance + + Raises: + FBchatException: If request failed """ params = {"search": name, "limit": limit} j = self.graphql_request(_graphql.from_query(_graphql.SEARCH_USER, params)) @@ -452,10 +474,14 @@ class Client(object): def searchForPages(self, name, limit=10): """Find and get pages by their name. - :param name: Name of the page - :return: :class:`Page` objects, ordered by relevance - :rtype: list - :raises: FBchatException if request failed + Args: + name: Name of the page + + Returns: + list: :class:`Page` objects, ordered by relevance + + Raises: + FBchatException: If request failed """ params = {"search": name, "limit": limit} j = self.graphql_request(_graphql.from_query(_graphql.SEARCH_PAGE, params)) @@ -465,11 +491,15 @@ class Client(object): def searchForGroups(self, name, limit=10): """Find and get group threads by their name. - :param name: Name of the group thread - :param limit: The max. amount of groups to fetch - :return: :class:`Group` objects, ordered by relevance - :rtype: list - :raises: FBchatException if request failed + Args: + name: Name of the group thread + limit: The max. amount of groups to fetch + + Returns: + list: :class:`Group` objects, ordered by relevance + + Raises: + FBchatException: If request failed """ params = {"search": name, "limit": limit} j = self.graphql_request(_graphql.from_query(_graphql.SEARCH_GROUP, params)) @@ -479,11 +509,15 @@ class Client(object): def searchForThreads(self, name, limit=10): """Find and get threads by their name. - :param name: Name of the thread - :param limit: The max. amount of groups to fetch - :return: :class:`User`, :class:`Group` and :class:`Page` objects, ordered by relevance - :rtype: list - :raises: FBchatException if request failed + Args: + name: Name of the thread + limit: The max. amount of groups to fetch + + Returns: + list: :class:`User`, :class:`Group` and :class:`Page` objects, ordered by relevance + + Raises: + FBchatException: If request failed """ params = {"search": name, "limit": limit} j = self.graphql_request(_graphql.from_query(_graphql.SEARCH_THREAD, params)) @@ -510,15 +544,17 @@ class Client(object): def searchForMessageIDs(self, query, offset=0, limit=5, thread_id=None): """Find and get message IDs by query. - :param query: Text to search for - :param offset: Number of messages to skip - :param limit: Max. number of messages to retrieve - :param thread_id: User/Group ID to search in. See :ref:`intro_threads` - :type offset: int - :type limit: int - :return: Found Message IDs - :rtype: typing.Iterable - :raises: FBchatException if request failed + Args: + query: Text to search for + offset (int): Number of messages to skip + limit (int): Max. number of messages to retrieve + thread_id: User/Group ID to search in. See :ref:`intro_threads` + + Returns: + typing.Iterable: Found Message IDs + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -539,18 +575,20 @@ class Client(object): def searchForMessages(self, query, offset=0, limit=5, thread_id=None): """Find and get `Message` objects by query. - .. warning:: + Warning: This method sends request for every found message ID. - :param query: Text to search for - :param offset: Number of messages to skip - :param limit: Max. number of messages to retrieve - :param thread_id: User/Group ID to search in. See :ref:`intro_threads` - :type offset: int - :type limit: int - :return: Found :class:`Message` objects - :rtype: typing.Iterable - :raises: FBchatException if request failed + Args: + query: Text to search for + offset (int): Number of messages to skip + limit (int): Max. number of messages to retrieve + thread_id: User/Group ID to search in. See :ref:`intro_threads` + + Returns: + typing.Iterable: Found :class:`Message` objects + + Raises: + FBchatException: If request failed """ message_ids = self.searchForMessageIDs( query, offset=offset, limit=limit, thread_id=thread_id @@ -561,15 +599,17 @@ class Client(object): def search(self, query, fetch_messages=False, thread_limit=5, message_limit=5): """Search for messages in all threads. - :param query: Text to search for - :param fetch_messages: Whether to fetch :class:`Message` objects or IDs only - :param thread_limit: Max. number of threads to retrieve - :param message_limit: Max. number of messages to retrieve - :type thread_limit: int - :type message_limit: int - :return: Dictionary with thread IDs as keys and iterables to get messages as values - :rtype: typing.Dict[str, typing.Iterable] - :raises: FBchatException if request failed + Args: + query: Text to search for + fetch_messages: Whether to fetch :class:`Message` objects or IDs only + thread_limit (int): Max. number of threads to retrieve + message_limit (int): Max. number of messages to retrieve + + Returns: + typing.Dict[str, typing.Iterable]: Dictionary with thread IDs as keys and iterables to get messages as values + + Raises: + FBchatException: If request failed """ data = {"query": query, "snippetLimit": thread_limit} j = self._payload_post("/ajax/mercury/search_snippets.php?dpr=1", data) @@ -628,13 +668,17 @@ class Client(object): def fetchUserInfo(self, *user_ids): """Fetch users' info from IDs, unordered. - .. warning:: + Warning: Sends two requests, to fetch all available info! - :param user_ids: One or more user ID(s) to query - :return: :class:`User` objects, labeled by their ID - :rtype: dict - :raises: FBchatException if request failed + Args: + user_ids: One or more user ID(s) to query + + Returns: + dict: :class:`User` objects, labeled by their ID + + Raises: + FBchatException: If request failed """ threads = self.fetchThreadInfo(*user_ids) users = {} @@ -649,13 +693,17 @@ class Client(object): def fetchPageInfo(self, *page_ids): """Fetch pages' info from IDs, unordered. - .. warning:: + Warning: Sends two requests, to fetch all available info! - :param page_ids: One or more page ID(s) to query - :return: :class:`Page` objects, labeled by their ID - :rtype: dict - :raises: FBchatException if request failed + Args: + page_ids: One or more page ID(s) to query + + Returns: + dict: :class:`Page` objects, labeled by their ID + + Raises: + FBchatException: If request failed """ threads = self.fetchThreadInfo(*page_ids) pages = {} @@ -670,10 +718,14 @@ class Client(object): def fetchGroupInfo(self, *group_ids): """Fetch groups' info from IDs, unordered. - :param group_ids: One or more group ID(s) to query - :return: :class:`Group` objects, labeled by their ID - :rtype: dict - :raises: FBchatException if request failed + Args: + group_ids: One or more group ID(s) to query + + Returns: + dict: :class:`Group` objects, labeled by their ID + + Raises: + FBchatException: If request failed """ threads = self.fetchThreadInfo(*group_ids) groups = {} @@ -688,13 +740,17 @@ class Client(object): def fetchThreadInfo(self, *thread_ids): """Fetch threads' info from IDs, unordered. - .. warning:: + Warning: Sends two requests if users or pages are present, to fetch all available info! - :param thread_ids: One or more thread ID(s) to query - :return: :class:`Thread` objects, labeled by their ID - :rtype: dict - :raises: FBchatException if request failed + Args: + thread_ids: One or more thread ID(s) to query + + Returns: + dict: :class:`Thread` objects, labeled by their ID + + Raises: + FBchatException: If request failed """ queries = [] for thread_id in thread_ids: @@ -751,14 +807,16 @@ class Client(object): def fetchThreadMessages(self, thread_id=None, limit=20, before=None): """Fetch messages in a thread, ordered by most recent. - :param thread_id: User/Group ID to get messages from. See :ref:`intro_threads` - :param limit: Max. number of messages to retrieve - :param before: A timestamp, indicating from which point to retrieve messages - :type limit: int - :type before: int - :return: :class:`Message` objects - :rtype: list - :raises: FBchatException if request failed + Args: + thread_id: User/Group ID to get messages from. See :ref:`intro_threads` + limit (int): Max. number of messages to retrieve + before (int): A timestamp, indicating from which point to retrieve messages + + Returns: + list: :class:`Message` objects + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -794,15 +852,17 @@ class Client(object): ): """Fetch the client's thread list. - :param offset: Deprecated. Do not use! - :param limit: Max. number of threads to retrieve. Capped at 20 - :param thread_location: ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER - :param before: A timestamp (in milliseconds), indicating from which point to retrieve threads - :type limit: int - :type before: int - :return: :class:`Thread` objects - :rtype: list - :raises: FBchatException if request failed + Args: + offset: Deprecated. Do not use! + limit (int): Max. number of threads to retrieve. Capped at 20 + thread_location (ThreadLocation): INBOX, PENDING, ARCHIVED or OTHER + before (int): A timestamp (in milliseconds), indicating from which point to retrieve threads + + Returns: + list: :class:`Thread` objects + + Raises: + FBchatException: If request failed """ if offset is not None: log.warning( @@ -844,9 +904,11 @@ class Client(object): def fetchUnread(self): """Fetch unread threads. - :return: List of unread thread ids - :rtype: list - :raises: FBchatException if request failed + Returns: + list: List of unread thread ids + + Raises: + FBchatException: If request failed """ form = { "folders[0]": "inbox", @@ -862,9 +924,11 @@ class Client(object): def fetchUnseen(self): """Fetch unseen / new threads. - :return: List of unseen thread ids - :rtype: list - :raises: FBchatException if request failed + Returns: + list: List of unseen thread ids + + Raises: + FBchatException: If request failed """ j = self._payload_post("/mercury/unseen_thread_ids/", None) @@ -874,11 +938,14 @@ class Client(object): def fetchImageUrl(self, image_id): """Fetch url to download the original image from an image attachment ID. - :param image_id: The image you want to fethc - :type image_id: str - :return: An url where you can download the original image - :rtype: str - :raises: FBchatException if request failed + Args: + image_id (str): The image you want to fethc + + Returns: + str: An url where you can download the original image + + Raises: + FBchatException: If request failed """ image_id = str(image_id) data = {"photo_id": str(image_id)} @@ -892,11 +959,15 @@ class Client(object): def fetchMessageInfo(self, mid, thread_id=None): """Fetch `Message` object from the given message id. - :param mid: Message ID to fetch from - :param thread_id: User/Group ID to get message info from. See :ref:`intro_threads` - :return: :class:`Message` object - :rtype: Message - :raises: FBchatException if request failed + Args: + mid: Message ID to fetch from + thread_id: User/Group ID to get message info from. See :ref:`intro_threads` + + Returns: + Message: :class:`Message` object + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) message_info = self._forcedFetch(thread_id, mid).get("message") @@ -905,9 +976,14 @@ class Client(object): def fetchPollOptions(self, poll_id): """Fetch list of `PollOption` objects from the poll id. - :param poll_id: Poll ID to fetch from - :rtype: list - :raises: FBchatException if request failed + Args: + poll_id: Poll ID to fetch from + + Returns: + list + + Raises: + FBchatException: If request failed """ data = {"question_id": poll_id} j = self._payload_post("/ajax/mercury/get_poll_options", data) @@ -916,10 +992,14 @@ class Client(object): def fetchPlanInfo(self, plan_id): """Fetch `Plan` object from the plan id. - :param plan_id: Plan ID to fetch from - :return: :class:`Plan` object - :rtype: Plan - :raises: FBchatException if request failed + Args: + plan_id: Plan ID to fetch from + + Returns: + Plan: :class:`Plan` object + + Raises: + FBchatException: If request failed """ data = {"event_reminder_id": plan_id} j = self._payload_post("/ajax/eventreminder", data) @@ -932,8 +1012,8 @@ class Client(object): def getPhoneNumbers(self): """Fetch list of user's phone numbers. - :return: List of phone numbers - :rtype: list + Returns: + list: List of phone numbers """ data = self._getPrivateData() return [ @@ -943,8 +1023,8 @@ class Client(object): def getEmails(self): """Fetch list of user's emails. - :return: List of emails - :rtype: list + Returns: + list: List of emails """ data = self._getPrivateData() return [j["display_email"] for j in data["all_emails"]] @@ -954,21 +1034,25 @@ class Client(object): Return ``None`` if status isn't known. - .. warning:: + Warning: Only works when listening. - :param user_id: ID of the user - :return: Given user active status - :rtype: ActiveStatus + Args: + user_id: ID of the user + + Returns: + ActiveStatus: Given user active status """ return self._buddylist.get(str(user_id)) def fetchThreadImages(self, thread_id=None): """Fetch images posted in thread. - :param thread_id: ID of the thread - :return: :class:`ImageAttachment` or :class:`VideoAttachment`. - :rtype: iterable + Args: + thread_id: ID of the thread + + Returns: + typing.Iterable: :class:`ImageAttachment` or :class:`VideoAttachment` """ thread_id, thread_type = self._getThread(thread_id, None) data = {"id": thread_id, "first": 48} @@ -1109,13 +1193,16 @@ class Client(object): def send(self, message, thread_id=None, thread_type=ThreadType.USER): """Send message to a thread. - :param message: Message to send - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type message: Message - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + Args: + message (Message): Message to send + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent message + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) data = self._getSendData( @@ -1146,12 +1233,16 @@ class Client(object): def wave(self, wave_first=True, thread_id=None, thread_type=None): """Wave hello to a thread. - :param wave_first: Whether to wave first or wave back - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + Args: + wave_first: Whether to wave first or wave back + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent message + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) data = self._getSendData(thread_id=thread_id, thread_type=thread_type) @@ -1167,14 +1258,17 @@ class Client(object): def quickReply(self, quick_reply, payload=None, thread_id=None, thread_type=None): """Reply to chosen quick reply. - :param quick_reply: Quick reply to reply to - :param payload: Optional answer to the quick reply - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type quick_reply: QuickReply - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + Args: + quick_reply (QuickReply): Quick reply to reply to + payload: Optional answer to the quick reply + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent message + + Raises: + FBchatException: If request failed """ quick_reply.is_response = True if isinstance(quick_reply, QuickReplyText): @@ -1205,7 +1299,8 @@ class Client(object): def unsend(self, mid): """Unsend message by it's ID (removes it for everyone). - :param mid: :ref:`Message ID ` of the message to unsend + Args: + mid: :ref:`Message ID ` of the message to unsend """ data = {"message_id": mid} j = self._payload_post("/messaging/unsend_message/?dpr=1", data) @@ -1226,15 +1321,17 @@ class Client(object): def sendLocation(self, location, message=None, thread_id=None, thread_type=None): """Send a given location to a thread as the user's current location. - :param location: Location to send - :param message: Additional message - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type location: LocationAttachment - :type message: Message - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + Args: + location (LocationAttachment): Location to send + message (Message): Additional message + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent message + + Raises: + FBchatException: If request failed """ self._sendLocation( location=location, @@ -1249,15 +1346,17 @@ class Client(object): ): """Send a given location to a thread as a pinned location. - :param location: Location to send - :param message: Additional message - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type location: LocationAttachment - :type message: Message - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + Args: + location (LocationAttachment): Location to send + message (Message): Additional message + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent message + + Raises: + FBchatException: If request failed """ self._sendLocation( location=location, @@ -1320,13 +1419,17 @@ class Client(object): ): """Send files from URLs to a thread. - :param file_urls: URLs of files to upload and send - :param message: Additional message - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent files - :raises: FBchatException if request failed + Args: + file_urls: URLs of files to upload and send + message: Additional message + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent files + + Raises: + FBchatException: If request failed """ file_urls = require_list(file_urls) files = self._upload(get_files_from_urls(file_urls)) @@ -1339,13 +1442,17 @@ class Client(object): ): """Send local files to a thread. - :param file_paths: Paths of files to upload and send - :param message: Additional message - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent files - :raises: FBchatException if request failed + Args: + file_paths: Paths of files to upload and send + message: Additional message + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent files + + Raises: + FBchatException: If request failed """ file_paths = require_list(file_paths) with get_files_from_paths(file_paths) as x: @@ -1359,13 +1466,17 @@ class Client(object): ): """Send voice clips from URLs to a thread. - :param clip_urls: URLs of clips to upload and send - :param message: Additional message - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent files - :raises: FBchatException if request failed + Args: + clip_urls: URLs of clips to upload and send + message: Additional message + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent files + + Raises: + FBchatException: If request failed """ clip_urls = require_list(clip_urls) files = self._upload(get_files_from_urls(clip_urls), voice_clip=True) @@ -1378,13 +1489,17 @@ class Client(object): ): """Send local voice clips to a thread. - :param clip_paths: Paths of clips to upload and send - :param message: Additional message - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType - :return: :ref:`Message ID ` of the sent files - :raises: FBchatException if request failed + Args: + clip_paths: Paths of clips to upload and send + message: Additional message + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Returns: + :ref:`Message ID ` of the sent files + + Raises: + FBchatException: If request failed """ clip_paths = require_list(clip_paths) with get_files_from_paths(clip_paths) as x: @@ -1438,9 +1553,12 @@ class Client(object): def forwardAttachment(self, attachment_id, thread_id=None): """Forward an attachment. - :param attachment_id: Attachment ID to forward - :param thread_id: User/Group ID to send to. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + attachment_id: Attachment ID to forward + thread_id: User/Group ID to send to. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) data = { @@ -1457,10 +1575,15 @@ class Client(object): def createGroup(self, message, user_ids): """Create a group with the given user ids. - :param message: The initial message - :param user_ids: A list of users to create the group with. - :return: ID of the new group - :raises: FBchatException if request failed + Args: + message: The initial message + user_ids: A list of users to create the group with. + + Returns: + ID of the new group + + Raises: + FBchatException: If request failed """ data = self._getSendData(message=self._oldMessage(message)) @@ -1480,10 +1603,12 @@ class Client(object): def addUsersToGroup(self, user_ids, thread_id=None): """Add users to a group. - :param user_ids: One or more user IDs to add - :param thread_id: Group ID to add people to. See :ref:`intro_threads` - :type user_ids: list - :raises: FBchatException if request failed + Args: + user_ids (list): One or more user IDs to add + thread_id: Group ID to add people to. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) data = self._getSendData(thread_id=thread_id, thread_type=ThreadType.GROUP) @@ -1508,9 +1633,12 @@ class Client(object): def removeUserFromGroup(self, user_id, thread_id=None): """Remove user from a group. - :param user_id: User ID to remove - :param thread_id: Group ID to remove people from. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + user_id: User ID to remove + thread_id: Group ID to remove people from. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1532,27 +1660,36 @@ class Client(object): def addGroupAdmins(self, admin_ids, thread_id=None): """Set specifed users as group admins. - :param admin_ids: One or more user IDs to set admin - :param thread_id: Group ID to remove people from. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + admin_ids: One or more user IDs to set admin + thread_id: Group ID to remove people from. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ self._adminStatus(admin_ids, True, thread_id) def removeGroupAdmins(self, admin_ids, thread_id=None): """Remove admin status from specifed users. - :param admin_ids: One or more user IDs to remove admin - :param thread_id: Group ID to remove people from. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + admin_ids: One or more user IDs to remove admin + thread_id: Group ID to remove people from. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ self._adminStatus(admin_ids, False, thread_id) def changeGroupApprovalMode(self, require_admin_approval, thread_id=None): """Change group's approval mode. - :param require_admin_approval: True or False - :param thread_id: Group ID to remove people from. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + require_admin_approval: True or False + thread_id: Group ID to remove people from. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1579,27 +1716,36 @@ class Client(object): def acceptUsersToGroup(self, user_ids, thread_id=None): """Accept users to the group from the group's approval. - :param user_ids: One or more user IDs to accept - :param thread_id: Group ID to accept users to. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + user_ids: One or more user IDs to accept + thread_id: Group ID to accept users to. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ self._usersApproval(user_ids, True, thread_id) def denyUsersFromGroup(self, user_ids, thread_id=None): """Deny users from joining the group. - :param user_ids: One or more user IDs to deny - :param thread_id: Group ID to deny users from. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + user_ids: One or more user IDs to deny + thread_id: Group ID to deny users from. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ self._usersApproval(user_ids, False, thread_id) def _changeGroupImage(self, image_id, thread_id=None): """Change a thread image from an image id. - :param image_id: ID of uploaded image - :param thread_id: User/Group ID to change image. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + image_id: ID of uploaded image + thread_id: User/Group ID to change image. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1611,9 +1757,12 @@ class Client(object): def changeGroupImageRemote(self, image_url, thread_id=None): """Change a thread image from a URL. - :param image_url: URL of an image to upload and change - :param thread_id: User/Group ID to change image. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + image_url: URL of an image to upload and change + thread_id: User/Group ID to change image. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ (image_id, mimetype), = self._upload(get_files_from_urls([image_url])) return self._changeGroupImage(image_id, thread_id) @@ -1621,9 +1770,12 @@ class Client(object): def changeGroupImageLocal(self, image_path, thread_id=None): """Change a thread image from a local path. - :param image_path: Path of an image to upload and change - :param thread_id: User/Group ID to change image. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + image_path: Path of an image to upload and change + thread_id: User/Group ID to change image. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ with get_files_from_paths([image_path]) as files: (image_id, mimetype), = self._upload(files) @@ -1636,11 +1788,13 @@ class Client(object): If this is executed on a user thread, this will change the nickname of that user, effectively changing the title. - :param title: New group thread title - :param thread_id: Group ID to change title of. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType - :raises: FBchatException if request failed + Args: + title: New group thread title + thread_id: Group ID to change title of. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -1658,12 +1812,14 @@ class Client(object): ): """Change the nickname of a user in a thread. - :param nickname: New nickname - :param user_id: User that will have their nickname changed - :param thread_id: User/Group ID to change color of. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType - :raises: FBchatException if request failed + Args: + nickname: New nickname + user_id: User that will have their nickname changed + thread_id: User/Group ID to change color of. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -1679,10 +1835,12 @@ class Client(object): def changeThreadColor(self, color, thread_id=None): """Change thread color. - :param color: New thread color - :param thread_id: User/Group ID to change color of. See :ref:`intro_threads` - :type color: ThreadColor - :raises: FBchatException if request failed + Args: + color (ThreadColor): New thread color + thread_id: User/Group ID to change color of. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1697,13 +1855,16 @@ class Client(object): def changeThreadEmoji(self, emoji, thread_id=None): """Change thread color. - .. note:: + Note: While changing the emoji, the Facebook web client actually sends multiple different requests, though only this one is required to make the change. - :param color: New thread emoji - :param thread_id: User/Group ID to change emoji of. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + color: New thread emoji + thread_id: User/Group ID to change emoji of. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1715,10 +1876,12 @@ class Client(object): def reactToMessage(self, message_id, reaction): """React to a message, or removes reaction. - :param message_id: :ref:`Message ID ` to react to - :param reaction: Reaction emoji to use, if None removes reaction - :type reaction: MessageReaction or None - :raises: FBchatException if request failed + Args: + message_id: :ref:`Message ID ` to react to + reaction (MessageReaction): Reaction emoji to use, if None removes reaction + + Raises: + FBchatException: If request failed """ data = { "action": "ADD_REACTION" if reaction else "REMOVE_REACTION", @@ -1734,10 +1897,12 @@ class Client(object): def createPlan(self, plan, thread_id=None): """Set a plan. - :param plan: Plan to set - :param thread_id: User/Group ID to send plan to. See :ref:`intro_threads` - :type plan: Plan - :raises: FBchatException if request failed + Args: + plan (Plan): Plan to set + thread_id: User/Group ID to send plan to. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1760,10 +1925,12 @@ class Client(object): def editPlan(self, plan, new_plan): """Edit a plan. - :param plan: Plan to edit - :param new_plan: New plan - :type plan: Plan - :raises: FBchatException if request failed + Args: + plan (Plan): Plan to edit + new_plan: New plan + + Raises: + FBchatException: If request failed """ data = { "event_reminder_id": plan.uid, @@ -1779,8 +1946,11 @@ class Client(object): def deletePlan(self, plan): """Delete a plan. - :param plan: Plan to delete - :raises: FBchatException if request failed + Args: + plan: Plan to delete + + Raises: + FBchatException: If request failed """ data = {"event_reminder_id": plan.uid, "delete": "true", "acontext": ACONTEXT} j = self._payload_post("/ajax/eventreminder/submit", data) @@ -1788,9 +1958,12 @@ class Client(object): def changePlanParticipation(self, plan, take_part=True): """Change participation in a plan. - :param plan: Plan to take part in or not - :param take_part: Whether to take part in the plan - :raises: FBchatException if request failed + Args: + plan: Plan to take part in or not + take_part: Whether to take part in the plan + + Raises: + FBchatException: If request failed """ data = { "event_reminder_id": plan.uid, @@ -1807,10 +1980,12 @@ class Client(object): def createPoll(self, poll, thread_id=None): """Create poll in a group thread. - :param poll: Poll to create - :param thread_id: User/Group ID to create poll in. See :ref:`intro_threads` - :type poll: Poll - :raises: FBchatException if request failed + Args: + poll (Poll): Poll to create + thread_id: User/Group ID to create poll in. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1834,13 +2009,15 @@ class Client(object): def updatePollVote(self, poll_id, option_ids=[], new_options=[]): """Update a poll vote. - :param poll_id: ID of the poll to update vote - :param option_ids: List of the option IDs to vote - :param new_options: List of the new option names - :param thread_id: User/Group ID to change status in. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType - :raises: FBchatException if request failed + Args: + poll_id: ID of the poll to update vote + option_ids: List of the option IDs to vote + new_options: List of the new option names + thread_id: User/Group ID to change status in. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ data = {"question_id": poll_id} @@ -1860,12 +2037,13 @@ class Client(object): def setTypingStatus(self, status, thread_id=None, thread_type=None): """Set users typing status in a thread. - :param status: Specify the typing status - :param thread_id: User/Group ID to change status in. See :ref:`intro_threads` - :param thread_type: See :ref:`intro_threads` - :type status: TypingStatus - :type thread_type: ThreadType - :raises: FBchatException if request failed + Args: + status (TypingStatus): Specify the typing status + thread_id: User/Group ID to change status in. See :ref:`intro_threads` + thread_type (ThreadType): See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -1884,10 +2062,15 @@ class Client(object): def markAsDelivered(self, thread_id, message_id): """Mark a message as delivered. - :param thread_id: User/Group ID to which the message belongs. See :ref:`intro_threads` - :param message_id: Message ID to set as delivered. See :ref:`intro_threads` - :return: True - :raises: FBchatException if request failed + Args: + thread_id: User/Group ID to which the message belongs. See :ref:`intro_threads` + message_id: Message ID to set as delivered. See :ref:`intro_threads` + + Returns: + True + + Raises: + FBchatException: If request failed """ data = { "message_ids[0]": message_id, @@ -1912,8 +2095,11 @@ class Client(object): All messages inside the specified threads will be marked as read. - :param thread_ids: User/Group IDs to set as read. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + thread_ids: User/Group IDs to set as read. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ self._readStatus(True, thread_ids) @@ -1922,21 +2108,24 @@ class Client(object): All messages inside the specified threads will be marked as unread. - :param thread_ids: User/Group IDs to set as unread. See :ref:`intro_threads` - :raises: FBchatException if request failed + Args: + thread_ids: User/Group IDs to set as unread. See :ref:`intro_threads` + + Raises: + FBchatException: If request failed """ self._readStatus(False, thread_ids) def markAsSeen(self): """ - .. todo:: + Todo: Documenting this """ j = self._payload_post("/ajax/mercury/mark_seen.php", {"seen_timestamp": now()}) def friendConnect(self, friend_id): """ - .. todo:: + Todo: Documenting this """ data = {"to_friend": friend_id, "action": "confirm"} @@ -1946,9 +2135,14 @@ class Client(object): def removeFriend(self, friend_id=None): """Remove a specifed friend from the client's friend list. - :param friend_id: The ID of the friend that you want to remove - :return: True - :raises: FBchatException if request failed + Args: + friend_id: The ID of the friend that you want to remove + + Returns: + True + + Raises: + FBchatException: If request failed """ data = {"uid": friend_id} j = self._payload_post("/ajax/profile/removefriendconfirm.php", data) @@ -1957,9 +2151,14 @@ class Client(object): def blockUser(self, user_id): """Block messages from a specifed user. - :param user_id: The ID of the user that you want to block - :return: True - :raises: FBchatException if request failed + Args: + user_id: The ID of the user that you want to block + + Returns: + True + + Raises: + FBchatException: If request failed """ data = {"fbid": user_id} j = self._payload_post("/messaging/block_messages/?dpr=1", data) @@ -1968,9 +2167,14 @@ class Client(object): def unblockUser(self, user_id): """Unblock a previously blocked user. - :param user_id: The ID of the user that you want to unblock - :return: Whether the request was successful - :raises: FBchatException if request failed + Args: + user_id: The ID of the user that you want to unblock + + Returns: + Whether the request was successful + + Raises: + FBchatException: If request failed """ data = {"fbid": user_id} j = self._payload_post("/messaging/unblock_messages/?dpr=1", data) @@ -1979,10 +2183,15 @@ class Client(object): def moveThreads(self, location, thread_ids): """Move threads to specifed location. - :param location: ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER - :param thread_ids: Thread IDs to move. See :ref:`intro_threads` - :return: True - :raises: FBchatException if request failed + Args: + location (ThreadLocation): INBOX, PENDING, ARCHIVED or OTHER + thread_ids: Thread IDs to move. See :ref:`intro_threads` + + Returns: + True + + Raises: + FBchatException: If request failed """ thread_ids = require_list(thread_ids) @@ -2011,9 +2220,14 @@ class Client(object): def deleteThreads(self, thread_ids): """Delete threads. - :param thread_ids: Thread IDs to delete. See :ref:`intro_threads` - :return: True - :raises: FBchatException if request failed + Args: + thread_ids: Thread IDs to delete. See :ref:`intro_threads` + + Returns: + True + + Raises: + FBchatException: If request failed """ thread_ids = require_list(thread_ids) @@ -2033,9 +2247,14 @@ class Client(object): def markAsSpam(self, thread_id=None): """Mark a thread as spam, and delete it. - :param thread_id: User/Group ID to mark as spam. See :ref:`intro_threads` - :return: True - :raises: FBchatException if request failed + Args: + thread_id: User/Group ID to mark as spam. See :ref:`intro_threads` + + Returns: + True + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) j = self._payload_post("/ajax/mercury/mark_spam.php?dpr=1", {"id": thread_id}) @@ -2044,9 +2263,14 @@ class Client(object): def deleteMessages(self, message_ids): """Delete specifed messages. - :param message_ids: Message IDs to delete - :return: True - :raises: FBchatException if request failed + Args: + message_ids: Message IDs to delete + + Returns: + True + + Raises: + FBchatException: If request failed """ message_ids = require_list(message_ids) data = dict() @@ -2058,8 +2282,9 @@ class Client(object): def muteThread(self, mute_time=-1, thread_id=None): """Mute thread. - :param mute_time: Mute time in seconds, leave blank to mute forever - :param thread_id: User/Group ID to mute. See :ref:`intro_threads` + Args: + mute_time: Mute time in seconds, leave blank to mute forever + thread_id: User/Group ID to mute. See :ref:`intro_threads` """ thread_id, thread_type = self._getThread(thread_id, None) data = {"mute_settings": str(mute_time), "thread_fbid": thread_id} @@ -2068,15 +2293,17 @@ class Client(object): def unmuteThread(self, thread_id=None): """Unmute thread. - :param thread_id: User/Group ID to unmute. See :ref:`intro_threads` + Args: + thread_id: User/Group ID to unmute. See :ref:`intro_threads` """ return self.muteThread(0, thread_id) def muteThreadReactions(self, mute=True, thread_id=None): """Mute thread reactions. - :param mute: Boolean. True to mute, False to unmute - :param thread_id: User/Group ID to mute. See :ref:`intro_threads` + Args: + mute: Boolean. True to mute, False to unmute + thread_id: User/Group ID to mute. See :ref:`intro_threads` """ thread_id, thread_type = self._getThread(thread_id, None) data = {"reactions_mute_mode": int(mute), "thread_fbid": thread_id} @@ -2087,15 +2314,17 @@ class Client(object): def unmuteThreadReactions(self, thread_id=None): """Unmute thread reactions. - :param thread_id: User/Group ID to unmute. See :ref:`intro_threads` + Args: + thread_id: User/Group ID to unmute. See :ref:`intro_threads` """ return self.muteThreadReactions(False, thread_id) def muteThreadMentions(self, mute=True, thread_id=None): """Mute thread mentions. - :param mute: Boolean. True to mute, False to unmute - :param thread_id: User/Group ID to mute. See :ref:`intro_threads` + Args: + mute: Boolean. True to mute, False to unmute + thread_id: User/Group ID to mute. See :ref:`intro_threads` """ thread_id, thread_type = self._getThread(thread_id, None) data = {"mentions_mute_mode": int(mute), "thread_fbid": thread_id} @@ -2104,7 +2333,8 @@ class Client(object): def unmuteThreadMentions(self, thread_id=None): """Unmute thread mentions. - :param thread_id: User/Group ID to unmute. See :ref:`intro_threads` + Args: + thread_id: User/Group ID to unmute. See :ref:`intro_threads` """ return self.muteThreadMentions(False, thread_id) @@ -2802,7 +3032,8 @@ class Client(object): def startListening(self): """Start listening from an external event loop. - :raises: FBchatException if request failed + Raises: + FBchatException: If request failed """ self.listening = True @@ -2811,12 +3042,12 @@ class Client(object): This method is useful if you want to control fbchat from an external event loop. - .. warning:: + Warning: ``markAlive`` parameter is deprecated, use :func:`Client.setActiveStatus` or ``markAlive`` parameter in :func:`Client.listen` instead. - :return: Whether the loop should keep running - :rtype: bool + Returns: + bool: Whether the loop should keep running """ if markAlive is not None: self._markAlive = markAlive @@ -2854,8 +3085,8 @@ class Client(object): def listen(self, markAlive=None): """Initialize and runs the listening loop continually. - :param markAlive: Whether this should ping the Facebook server each time the loop runs - :type markAlive: bool + Args: + markAlive (bool): Whether this should ping the Facebook server each time the loop runs """ if markAlive is not None: self.setActiveStatus(markAlive) @@ -2871,8 +3102,8 @@ class Client(object): def setActiveStatus(self, markAlive): """Change active status while listening. - :param markAlive: Whether to show if client is active - :type markAlive: bool + Args: + markAlive (bool): Whether to show if client is active """ self._markAlive = markAlive @@ -2887,7 +3118,8 @@ class Client(object): def onLoggingIn(self, email=None): """Called when the client is logging in. - :param email: The email of the client + Args: + email: The email of the client """ log.info("Logging in {}...".format(email)) @@ -2898,7 +3130,8 @@ class Client(object): def onLoggedIn(self, email=None): """Called when the client is successfully logged in. - :param email: The email of the client + Args: + email: The email of the client """ log.info("Login of {} successful.".format(email)) @@ -2909,8 +3142,11 @@ class Client(object): def onListenError(self, exception=None): """Called when an error was encountered while listening. - :param exception: The exception that was encountered - :return: Whether the loop should keep running + Args: + exception: The exception that was encountered + + Returns: + Whether the loop should keep running """ log.exception("Got exception while listening") return True @@ -2929,17 +3165,16 @@ class Client(object): ): """Called when the client is listening, and somebody sends a message. - :param mid: The message ID - :param author_id: The ID of the author - :param message: (deprecated. Use ``message_object.text`` instead) - :param message_object: The message (As a `Message` object) - :param thread_id: Thread ID that the message was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the message was sent to. See :ref:`intro_threads` - :param ts: The timestamp of the message - :param metadata: Extra metadata about the message - :param msg: A full set of the data recieved - :type message_object: Message - :type thread_type: ThreadType + Args: + mid: The message ID + author_id: The ID of the author + message: (deprecated. Use ``message_object.text`` instead) + message_object (Message): The message (As a `Message` object) + thread_id: Thread ID that the message was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the message was sent to. See :ref:`intro_threads` + ts: The timestamp of the message + metadata: Extra metadata about the message + msg: A full set of the data recieved """ log.info("{} from {} in {}".format(message_object, thread_id, thread_type.name)) @@ -2956,16 +3191,15 @@ class Client(object): ): """Called when the client is listening, and somebody changes a thread's color. - :param mid: The action ID - :param author_id: The ID of the person who changed the color - :param new_color: The new color - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type new_color: ThreadColor - :type thread_type: ThreadType + Args: + mid: The action ID + author_id: The ID of the person who changed the color + new_color (ThreadColor): The new color + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "Color change from {} in {} ({}): {}".format( @@ -2986,15 +3220,15 @@ class Client(object): ): """Called when the client is listening, and somebody changes a thread's emoji. - :param mid: The action ID - :param author_id: The ID of the person who changed the emoji - :param new_emoji: The new emoji - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: The action ID + author_id: The ID of the person who changed the emoji + new_emoji: The new emoji + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "Emoji change from {} in {} ({}): {}".format( @@ -3015,15 +3249,15 @@ class Client(object): ): """Called when the client is listening, and somebody changes a thread's title. - :param mid: The action ID - :param author_id: The ID of the person who changed the title - :param new_title: The new title - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: The action ID + author_id: The ID of the person who changed the title + new_title: The new title + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "Title change from {} in {} ({}): {}".format( @@ -3043,14 +3277,14 @@ class Client(object): ): """Called when the client is listening, and somebody changes a thread's image. - :param mid: The action ID - :param author_id: The ID of the person who changed the image - :param new_image: The ID of the new image - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: The action ID + author_id: The ID of the person who changed the image + new_image: The ID of the new image + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info("{} changed thread image in {}".format(author_id, thread_id)) @@ -3068,16 +3302,16 @@ class Client(object): ): """Called when the client is listening, and somebody changes a nickname. - :param mid: The action ID - :param author_id: The ID of the person who changed the nickname - :param changed_for: The ID of the person whom got their nickname changed - :param new_nickname: The new nickname - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: The action ID + author_id: The ID of the person who changed the nickname + changed_for: The ID of the person whom got their nickname changed + new_nickname: The new nickname + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "Nickname change from {} in {} ({}) for {}: {}".format( @@ -3097,12 +3331,13 @@ class Client(object): ): """Called when the client is listening, and somebody adds an admin to a group. - :param mid: The action ID - :param added_id: The ID of the admin who got added - :param author_id: The ID of the person who added the admins - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved + Args: + mid: The action ID + added_id: The ID of the admin who got added + author_id: The ID of the person who added the admins + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info("{} added admin: {} in {}".format(author_id, added_id, thread_id)) @@ -3118,12 +3353,13 @@ class Client(object): ): """Called when the client is listening, and somebody is removed as an admin in a group. - :param mid: The action ID - :param removed_id: The ID of the admin who got removed - :param author_id: The ID of the person who removed the admins - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved + Args: + mid: The action ID + removed_id: The ID of the admin who got removed + author_id: The ID of the person who removed the admins + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info("{} removed admin: {} in {}".format(author_id, removed_id, thread_id)) @@ -3139,12 +3375,13 @@ class Client(object): ): """Called when the client is listening, and somebody changes approval mode in a group. - :param mid: The action ID - :param approval_mode: True if approval mode is activated - :param author_id: The ID of the person who changed approval mode - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved + Args: + mid: The action ID + approval_mode: True if approval mode is activated + author_id: The ID of the person who changed approval mode + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ if approval_mode: log.info("{} activated approval mode in {}".format(author_id, thread_id)) @@ -3163,14 +3400,14 @@ class Client(object): ): """Called when the client is listening, and somebody marks a message as seen. - :param seen_by: The ID of the person who marked the message as seen - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param seen_ts: A timestamp of when the person saw the message - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + seen_by: The ID of the person who marked the message as seen + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + seen_ts: A timestamp of when the person saw the message + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "Messages seen by {} in {} ({}) at {}s".format( @@ -3190,14 +3427,14 @@ class Client(object): ): """Called when the client is listening, and somebody marks messages as delivered. - :param msg_ids: The messages that are marked as delivered - :param delivered_for: The person that marked the messages as delivered - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + msg_ids: The messages that are marked as delivered + delivered_for: The person that marked the messages as delivered + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "Messages {} delivered to {} in {} ({}) at {}s".format( @@ -3210,13 +3447,13 @@ class Client(object): ): """Called when the client is listening, and the client has successfully marked threads as seen. - :param threads: The threads that were marked - :param author_id: The ID of the person who changed the emoji - :param seen_ts: A timestamp of when the threads were seen - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + threads: The threads that were marked + author_id: The ID of the person who changed the emoji + seen_ts: A timestamp of when the threads were seen + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "Marked messages as seen in threads {} at {}s".format( @@ -3235,13 +3472,13 @@ class Client(object): ): """Called when the client is listening, and someone unsends (deletes for everyone) a message. - :param mid: ID of the unsent message - :param author_id: The ID of the person who unsent the message - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: ID of the unsent message + author_id: The ID of the person who unsent the message + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info( "{} unsent the message {} in {} ({}) at {}s".format( @@ -3260,12 +3497,13 @@ class Client(object): ): """Called when the client is listening, and somebody adds people to a group thread. - :param mid: The action ID - :param added_ids: The IDs of the people who got added - :param author_id: The ID of the person who added the people - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved + Args: + mid: The action ID + added_ids: The IDs of the people who got added + author_id: The ID of the person who added the people + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info( "{} added: {} in {}".format(author_id, ", ".join(added_ids), thread_id) @@ -3282,32 +3520,35 @@ class Client(object): ): """Called when the client is listening, and somebody removes a person from a group thread. - :param mid: The action ID - :param removed_id: The ID of the person who got removed - :param author_id: The ID of the person who removed the person - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved + Args: + mid: The action ID + removed_id: The ID of the person who got removed + author_id: The ID of the person who removed the person + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info("{} removed: {} in {}".format(author_id, removed_id, thread_id)) def onFriendRequest(self, from_id=None, msg=None): """Called when the client is listening, and somebody sends a friend request. - :param from_id: The ID of the person that sent the request - :param msg: A full set of the data recieved + Args: + from_id: The ID of the person that sent the request + msg: A full set of the data recieved """ log.info("Friend request from {}".format(from_id)) def onInbox(self, unseen=None, unread=None, recent_unread=None, msg=None): """ - .. todo:: + Todo: Documenting this - :param unseen: -- - :param unread: -- - :param recent_unread: -- - :param msg: A full set of the data recieved + Args: + unseen: -- + unread: -- + recent_unread: -- + msg: A full set of the data recieved """ log.info("Inbox event: {}, {}, {}".format(unseen, unread, recent_unread)) @@ -3316,13 +3557,12 @@ class Client(object): ): """Called when the client is listening, and somebody starts or stops typing into a chat. - :param author_id: The ID of the person who sent the action - :param status: The typing status - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param msg: A full set of the data recieved - :type typing_status: TypingStatus - :type thread_type: ThreadType + Args: + author_id: The ID of the person who sent the action + status (TypingStatus): The typing status + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + msg: A full set of the data recieved """ pass @@ -3342,18 +3582,18 @@ class Client(object): ): """Called when the client is listening, and somebody plays a game. - :param mid: The action ID - :param author_id: The ID of the person who played the game - :param game_id: The ID of the game - :param game_name: Name of the game - :param score: Score obtained in the game - :param leaderboard: Actual leaderboard of the game in the thread - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: The action ID + author_id: The ID of the person who played the game + game_id: The ID of the game + game_name: Name of the game + score: Score obtained in the game + leaderboard: Actual leaderboard of the game in the thread + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( '{} played "{}" in {} ({})'.format( @@ -3373,16 +3613,15 @@ class Client(object): ): """Called when the client is listening, and somebody reacts to a message. - :param mid: Message ID, that user reacted to - :param reaction: Reaction - :param add_reaction: Whether user added or removed reaction - :param author_id: The ID of the person who reacted to the message - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved - :type reaction: MessageReaction - :type thread_type: ThreadType + Args: + mid: Message ID, that user reacted to + reaction (MessageReaction): Reaction + add_reaction: Whether user added or removed reaction + author_id: The ID of the person who reacted to the message + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info( "{} reacted to message {} with {} in {} ({})".format( @@ -3401,13 +3640,13 @@ class Client(object): ): """Called when the client is listening, and somebody removes reaction from a message. - :param mid: Message ID, that user reacted to - :param author_id: The ID of the person who removed reaction - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: Message ID, that user reacted to + author_id: The ID of the person who removed reaction + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info( "{} removed reaction from {} message in {} ({})".format( @@ -3420,12 +3659,12 @@ class Client(object): ): """Called when the client is listening, and somebody blocks client. - :param author_id: The ID of the person who blocked - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + author_id: The ID of the person who blocked + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info( "{} blocked {} ({}) thread".format(author_id, thread_id, thread_type.name) @@ -3436,12 +3675,12 @@ class Client(object): ): """Called when the client is listening, and somebody blocks client. - :param author_id: The ID of the person who unblocked - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + author_id: The ID of the person who unblocked + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info( "{} unblocked {} ({}) thread".format(author_id, thread_id, thread_type.name) @@ -3459,15 +3698,14 @@ class Client(object): ): """Called when the client is listening and somebody sends live location info. - :param mid: The action ID - :param location: Sent location info - :param author_id: The ID of the person who sent location info - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param msg: A full set of the data recieved - :type location: LiveLocationAttachment - :type thread_type: ThreadType + Args: + mid: The action ID + location (LiveLocationAttachment): Sent location info + author_id: The ID of the person who sent location info + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + msg: A full set of the data recieved """ log.info( "{} sent live location info in {} ({}) with latitude {} and longitude {}".format( @@ -3488,18 +3726,18 @@ class Client(object): ): """Called when the client is listening, and somebody starts a call in a group. - .. todo:: + Todo: Make this work with private calls. - :param mid: The action ID - :param caller_id: The ID of the person who started the call - :param is_video_call: True if it's video call - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: The action ID + caller_id: The ID of the person who started the call + is_video_call: True if it's video call + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "{} started call in {} ({})".format(caller_id, thread_id, thread_type.name) @@ -3519,19 +3757,19 @@ class Client(object): ): """Called when the client is listening, and somebody ends a call in a group. - .. todo:: + Todo: Make this work with private calls. - :param mid: The action ID - :param caller_id: The ID of the person who ended the call - :param is_video_call: True if it was video call - :param call_duration: Call duration in seconds - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: The action ID + caller_id: The ID of the person who ended the call + is_video_call: True if it was video call + call_duration: Call duration in seconds + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "{} ended call in {} ({})".format(caller_id, thread_id, thread_type.name) @@ -3550,15 +3788,15 @@ class Client(object): ): """Called when the client is listening, and somebody joins a group call. - :param mid: The action ID - :param joined_id: The ID of the person who joined the call - :param is_video_call: True if it's video call - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type thread_type: ThreadType + Args: + mid: The action ID + joined_id: The ID of the person who joined the call + is_video_call: True if it's video call + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "{} joined call in {} ({})".format(joined_id, thread_id, thread_type.name) @@ -3577,16 +3815,15 @@ class Client(object): ): """Called when the client is listening, and somebody creates a group poll. - :param mid: The action ID - :param poll: Created poll - :param author_id: The ID of the person who created the poll - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type poll: Poll - :type thread_type: ThreadType + Args: + mid: The action ID + poll (Poll): Created poll + author_id: The ID of the person who created the poll + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "{} created poll {} in {} ({})".format( @@ -3609,16 +3846,15 @@ class Client(object): ): """Called when the client is listening, and somebody votes in a group poll. - :param mid: The action ID - :param poll: Poll, that user voted in - :param author_id: The ID of the person who voted in the poll - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type poll: Poll - :type thread_type: ThreadType + Args: + mid: The action ID + poll (Poll): Poll, that user voted in + author_id: The ID of the person who voted in the poll + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "{} voted in poll {} in {} ({})".format( @@ -3639,16 +3875,15 @@ class Client(object): ): """Called when the client is listening, and somebody creates a plan. - :param mid: The action ID - :param plan: Created plan - :param author_id: The ID of the person who created the plan - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type plan: Plan - :type thread_type: ThreadType + Args: + mid: The action ID + plan (Plan): Created plan + author_id: The ID of the person who created the plan + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "{} created plan {} in {} ({})".format( @@ -3668,15 +3903,14 @@ class Client(object): ): """Called when the client is listening, and a plan ends. - :param mid: The action ID - :param plan: Ended plan - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type plan: Plan - :type thread_type: ThreadType + Args: + mid: The action ID + plan (Plan): Ended plan + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "Plan {} has ended in {} ({})".format(plan, thread_id, thread_type.name) @@ -3695,16 +3929,15 @@ class Client(object): ): """Called when the client is listening, and somebody edits a plan. - :param mid: The action ID - :param plan: Edited plan - :param author_id: The ID of the person who edited the plan - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type plan: Plan - :type thread_type: ThreadType + Args: + mid: The action ID + plan (Plan): Edited plan + author_id: The ID of the person who edited the plan + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "{} edited plan {} in {} ({})".format( @@ -3725,16 +3958,15 @@ class Client(object): ): """Called when the client is listening, and somebody deletes a plan. - :param mid: The action ID - :param plan: Deleted plan - :param author_id: The ID of the person who deleted the plan - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type plan: Plan - :type thread_type: ThreadType + Args: + mid: The action ID + plan (Plan): Deleted plan + author_id: The ID of the person who deleted the plan + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ log.info( "{} deleted plan {} in {} ({})".format( @@ -3756,18 +3988,16 @@ class Client(object): ): """Called when the client is listening, and somebody takes part in a plan or not. - :param mid: The action ID - :param plan: Plan - :param take_part: Whether the person takes part in the plan or not - :param author_id: The ID of the person who will participate in the plan or not - :param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - :param thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` - :param ts: A timestamp of the action - :param metadata: Extra metadata about the action - :param msg: A full set of the data recieved - :type plan: Plan - :type take_part: bool - :type thread_type: ThreadType + Args: + mid: The action ID + plan (Plan): Plan + take_part (bool): Whether the person takes part in the plan or not + author_id: The ID of the person who will participate in the plan or not + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type (ThreadType): Type of thread that the action was sent to. See :ref:`intro_threads` + ts: A timestamp of the action + metadata: Extra metadata about the action + msg: A full set of the data recieved """ if take_part: log.info( @@ -3785,40 +4015,44 @@ class Client(object): def onQprimer(self, ts=None, msg=None): """Called when the client just started listening. - :param ts: A timestamp of the action - :param msg: A full set of the data recieved + Args: + ts: A timestamp of the action + msg: A full set of the data recieved """ pass def onChatTimestamp(self, buddylist=None, msg=None): """Called when the client receives chat online presence update. - :param buddylist: A list of dicts with friend id and last seen timestamp - :param msg: A full set of the data recieved + Args: + buddylist: A list of dicts with friend id and last seen timestamp + msg: A full set of the data recieved """ log.debug("Chat Timestamps received: {}".format(buddylist)) def onBuddylistOverlay(self, statuses=None, msg=None): """Called when the client is listening and client receives information about friend active status. - :param statuses: Dictionary with user IDs as keys and :class:`ActiveStatus` as values - :param msg: A full set of the data recieved - :type statuses: dict + Args: + statuses (dict): Dictionary with user IDs as keys and :class:`ActiveStatus` as values + msg: A full set of the data recieved """ log.debug("Buddylist overlay received: {}".format(statuses)) def onUnknownMesssageType(self, msg=None): """Called when the client is listening, and some unknown data was recieved. - :param msg: A full set of the data recieved + Args: + msg: A full set of the data recieved """ log.debug("Unknown message received: {}".format(msg)) def onMessageError(self, exception=None, msg=None): """Called when an error was encountered while parsing recieved data. - :param exception: The exception that was encountered - :param msg: A full set of the data recieved + Args: + exception: The exception that was encountered + msg: A full set of the data recieved """ log.exception("Exception in parsing of {}".format(msg))