From 5b69ced1e8455352f081ff2d1f6df48923195f75 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 23 Jul 2019 18:53:53 +0200 Subject: [PATCH 1/6] Add ability to use Google style docstrings Use and configure the `napoleon` Sphinx extension --- docs/conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 40cd0c9..96ad6bb 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. @@ -184,3 +185,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 From 3806f01d2f5687f98e292109806063a55f8ffb9f Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 23 Jul 2019 18:54:32 +0200 Subject: [PATCH 2/6] Convert :param: roles to `Args` sections --- fbchat/_client.py | 956 ++++++++++++++++++++++++++-------------------- 1 file changed, 538 insertions(+), 418 deletions(-) diff --git a/fbchat/_client.py b/fbchat/_client.py index ec70f87..d8b9a17 100644 --- a/fbchat/_client.py +++ b/fbchat/_client.py @@ -74,12 +74,13 @@ 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`` + 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: Maximum number of times to try logging in + session_cookies: Cookies from a previous session (Will default to login if these are invalid) + logging_level: Configures the `logging level `_. Defaults to ``logging.INFO`` :type max_tries: int :type session_cookies: dict :type logging_level: int @@ -169,7 +170,8 @@ class Client(object): def graphql_requests(self, *queries): """Execute graphql queries. - :param queries: Zero or more dictionaries + Args: + queries: Zero or more dictionaries :type queries: dict :raises: FBchatException if request failed @@ -217,7 +219,8 @@ class Client(object): def setSession(self, session_cookies, user_agent=None): """Load session cookies. - :param session_cookies: A dictionay containing session cookies + Args: + session_cookies: A dictionay containing session cookies :type session_cookies: dict :return: False if ``session_cookies`` does not contain proper cookies :rtype: bool @@ -241,9 +244,10 @@ 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 + Args: + email: Facebook ``email`` or ``id`` or ``phone number`` + password: Facebook account password + max_tries: Maximum number of times to try logging in :type max_tries: int :raises: FBchatException on failed login """ @@ -315,8 +319,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` + Args: + thread_id: User/Group ID to default to. See :ref:`intro_threads` + thread_type: See :ref:`intro_threads` :type thread_type: ThreadType """ self._default_thread_id = thread_id @@ -343,10 +348,11 @@ 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) + 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) :return: :class:`Thread` objects :rtype: list :raises: FBchatException if request failed @@ -394,7 +400,8 @@ class Client(object): def fetchAllUsersFromThreads(self, threads): """Fetch all users involved in given threads. - :param threads: Thread: List of threads to check for users + Args: + threads: Thread: List of threads to check for users :return: :class:`User` objects :rtype: list :raises: FBchatException if request failed @@ -438,8 +445,9 @@ 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 + Args: + name: Name of the user + limit: The max. amount of users to fetch :return: :class:`User` objects, ordered by relevance :rtype: list :raises: FBchatException if request failed @@ -452,7 +460,8 @@ class Client(object): def searchForPages(self, name, limit=10): """Find and get pages by their name. - :param name: Name of the page + Args: + name: Name of the page :return: :class:`Page` objects, ordered by relevance :rtype: list :raises: FBchatException if request failed @@ -465,8 +474,9 @@ 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 + Args: + name: Name of the group thread + limit: The max. amount of groups to fetch :return: :class:`Group` objects, ordered by relevance :rtype: list :raises: FBchatException if request failed @@ -479,8 +489,9 @@ 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 + Args: + name: Name of the thread + 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 @@ -510,10 +521,11 @@ 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` + Args: + query: Text to search for + offset: Number of messages to skip + limit: Max. number of messages to retrieve + thread_id: User/Group ID to search in. See :ref:`intro_threads` :type offset: int :type limit: int :return: Found Message IDs @@ -542,10 +554,11 @@ class Client(object): .. 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` + Args: + query: Text to search for + offset: Number of messages to skip + limit: Max. number of messages to retrieve + thread_id: User/Group ID to search in. See :ref:`intro_threads` :type offset: int :type limit: int :return: Found :class:`Message` objects @@ -561,10 +574,11 @@ 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 + Args: + query: Text to search for + fetch_messages: Whether to fetch :class:`Message` objects or IDs only + thread_limit: Max. number of threads to retrieve + 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 @@ -631,7 +645,8 @@ class Client(object): .. warning:: Sends two requests, to fetch all available info! - :param user_ids: One or more user ID(s) to query + Args: + 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 @@ -652,7 +667,8 @@ class Client(object): .. warning:: Sends two requests, to fetch all available info! - :param page_ids: One or more page ID(s) to query + Args: + 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 @@ -670,7 +686,8 @@ 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 + Args: + 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 @@ -691,7 +708,8 @@ class Client(object): .. 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 + Args: + 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 @@ -751,9 +769,10 @@ 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 + Args: + thread_id: User/Group ID to get messages from. See :ref:`intro_threads` + limit: Max. number of messages to retrieve + before: A timestamp, indicating from which point to retrieve messages :type limit: int :type before: int :return: :class:`Message` objects @@ -794,10 +813,11 @@ 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 + Args: + offset: Deprecated. Do not use! + limit: Max. number of threads to retrieve. Capped at 20 + thread_location (ThreadLocation): INBOX, PENDING, ARCHIVED or OTHER + before: A timestamp (in milliseconds), indicating from which point to retrieve threads :type limit: int :type before: int :return: :class:`Thread` objects @@ -874,7 +894,8 @@ 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 + Args: + image_id: The image you want to fethc :type image_id: str :return: An url where you can download the original image :rtype: str @@ -892,8 +913,9 @@ 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` + Args: + mid: Message ID to fetch from + 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 @@ -905,7 +927,8 @@ 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 + Args: + poll_id: Poll ID to fetch from :rtype: list :raises: FBchatException if request failed """ @@ -916,7 +939,8 @@ class Client(object): def fetchPlanInfo(self, plan_id): """Fetch `Plan` object from the plan id. - :param plan_id: Plan ID to fetch from + Args: + plan_id: Plan ID to fetch from :return: :class:`Plan` object :rtype: Plan :raises: FBchatException if request failed @@ -957,7 +981,8 @@ class Client(object): .. warning:: Only works when listening. - :param user_id: ID of the user + Args: + user_id: ID of the user :return: Given user active status :rtype: ActiveStatus """ @@ -966,7 +991,8 @@ class Client(object): def fetchThreadImages(self, thread_id=None): """Fetch images posted in thread. - :param thread_id: ID of the thread + Args: + thread_id: ID of the thread :return: :class:`ImageAttachment` or :class:`VideoAttachment`. :rtype: iterable """ @@ -1109,9 +1135,10 @@ 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` + Args: + message: Message to send + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type: See :ref:`intro_threads` :type message: Message :type thread_type: ThreadType :return: :ref:`Message ID ` of the sent message @@ -1146,9 +1173,10 @@ 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` + Args: + wave_first: Whether to wave first or wave back + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type: See :ref:`intro_threads` :type thread_type: ThreadType :return: :ref:`Message ID ` of the sent message :raises: FBchatException if request failed @@ -1167,10 +1195,11 @@ 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` + Args: + quick_reply: 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: See :ref:`intro_threads` :type quick_reply: QuickReply :type thread_type: ThreadType :return: :ref:`Message ID ` of the sent message @@ -1205,7 +1234,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,10 +1256,11 @@ 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` + Args: + location: Location to send + message: Additional message + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type: See :ref:`intro_threads` :type location: LocationAttachment :type message: Message :type thread_type: ThreadType @@ -1249,10 +1280,11 @@ 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` + Args: + location: Location to send + message: Additional message + thread_id: User/Group ID to send to. See :ref:`intro_threads` + thread_type: See :ref:`intro_threads` :type location: LocationAttachment :type message: Message :type thread_type: ThreadType @@ -1320,10 +1352,11 @@ 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` + 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: See :ref:`intro_threads` :type thread_type: ThreadType :return: :ref:`Message ID ` of the sent files :raises: FBchatException if request failed @@ -1339,10 +1372,11 @@ 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` + 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: See :ref:`intro_threads` :type thread_type: ThreadType :return: :ref:`Message ID ` of the sent files :raises: FBchatException if request failed @@ -1359,10 +1393,11 @@ 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` + 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: See :ref:`intro_threads` :type thread_type: ThreadType :return: :ref:`Message ID ` of the sent files :raises: FBchatException if request failed @@ -1378,10 +1413,11 @@ 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` + 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: See :ref:`intro_threads` :type thread_type: ThreadType :return: :ref:`Message ID ` of the sent files :raises: FBchatException if request failed @@ -1438,8 +1474,9 @@ 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` + 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) @@ -1457,8 +1494,9 @@ 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. + Args: + message: The initial message + user_ids: A list of users to create the group with. :return: ID of the new group :raises: FBchatException if request failed """ @@ -1480,8 +1518,9 @@ 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` + Args: + user_ids: One or more user IDs to add + thread_id: Group ID to add people to. See :ref:`intro_threads` :type user_ids: list :raises: FBchatException if request failed """ @@ -1508,8 +1547,9 @@ 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` + 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,8 +1572,9 @@ 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` + 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) @@ -1541,8 +1582,9 @@ class Client(object): 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` + 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) @@ -1550,8 +1592,9 @@ class Client(object): 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` + 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,8 +1622,9 @@ 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` + 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) @@ -1588,8 +1632,9 @@ class Client(object): 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` + 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) @@ -1597,8 +1642,9 @@ class Client(object): 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` + 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,8 +1657,9 @@ 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` + 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])) @@ -1621,8 +1668,9 @@ 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` + 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: @@ -1636,9 +1684,10 @@ 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` + Args: + title: New group thread title + thread_id: Group ID to change title of. See :ref:`intro_threads` + thread_type: See :ref:`intro_threads` :type thread_type: ThreadType :raises: FBchatException if request failed """ @@ -1658,10 +1707,11 @@ 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` + 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: See :ref:`intro_threads` :type thread_type: ThreadType :raises: FBchatException if request failed """ @@ -1679,8 +1729,9 @@ 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` + Args: + color: New thread color + thread_id: User/Group ID to change color of. See :ref:`intro_threads` :type color: ThreadColor :raises: FBchatException if request failed """ @@ -1701,8 +1752,9 @@ class Client(object): 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` + 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,8 +1767,9 @@ 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 + Args: + message_id: :ref:`Message ID ` to react to + reaction: Reaction emoji to use, if None removes reaction :type reaction: MessageReaction or None :raises: FBchatException if request failed """ @@ -1734,8 +1787,9 @@ 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` + Args: + plan: Plan to set + thread_id: User/Group ID to send plan to. See :ref:`intro_threads` :type plan: Plan :raises: FBchatException if request failed """ @@ -1760,8 +1814,9 @@ class Client(object): def editPlan(self, plan, new_plan): """Edit a plan. - :param plan: Plan to edit - :param new_plan: New plan + Args: + plan: Plan to edit + new_plan: New plan :type plan: Plan :raises: FBchatException if request failed """ @@ -1779,7 +1834,8 @@ class Client(object): def deletePlan(self, plan): """Delete a plan. - :param plan: Plan to delete + Args: + plan: Plan to delete :raises: FBchatException if request failed """ data = {"event_reminder_id": plan.uid, "delete": "true", "acontext": ACONTEXT} @@ -1788,8 +1844,9 @@ 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 + Args: + plan: Plan to take part in or not + take_part: Whether to take part in the plan :raises: FBchatException if request failed """ data = { @@ -1807,8 +1864,9 @@ 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` + Args: + poll: Poll to create + thread_id: User/Group ID to create poll in. See :ref:`intro_threads` :type poll: Poll :raises: FBchatException if request failed """ @@ -1834,11 +1892,12 @@ 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` + 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: See :ref:`intro_threads` :type thread_type: ThreadType :raises: FBchatException if request failed """ @@ -1860,9 +1919,10 @@ 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` + Args: + status: Specify the typing status + thread_id: User/Group ID to change status in. See :ref:`intro_threads` + thread_type: See :ref:`intro_threads` :type status: TypingStatus :type thread_type: ThreadType :raises: FBchatException if request failed @@ -1884,8 +1944,9 @@ 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` + 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` :return: True :raises: FBchatException if request failed """ @@ -1912,7 +1973,8 @@ 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` + 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,7 +1984,8 @@ 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` + Args: + thread_ids: User/Group IDs to set as unread. See :ref:`intro_threads` :raises: FBchatException if request failed """ self._readStatus(False, thread_ids) @@ -1946,7 +2009,8 @@ 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 + Args: + friend_id: The ID of the friend that you want to remove :return: True :raises: FBchatException if request failed """ @@ -1957,7 +2021,8 @@ 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 + Args: + user_id: The ID of the user that you want to block :return: True :raises: FBchatException if request failed """ @@ -1968,7 +2033,8 @@ 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 + Args: + user_id: The ID of the user that you want to unblock :return: Whether the request was successful :raises: FBchatException if request failed """ @@ -1979,8 +2045,9 @@ 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` + Args: + location (ThreadLocation): INBOX, PENDING, ARCHIVED or OTHER + thread_ids: Thread IDs to move. See :ref:`intro_threads` :return: True :raises: FBchatException if request failed """ @@ -2011,7 +2078,8 @@ class Client(object): def deleteThreads(self, thread_ids): """Delete threads. - :param thread_ids: Thread IDs to delete. See :ref:`intro_threads` + Args: + thread_ids: Thread IDs to delete. See :ref:`intro_threads` :return: True :raises: FBchatException if request failed """ @@ -2033,7 +2101,8 @@ 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` + Args: + thread_id: User/Group ID to mark as spam. See :ref:`intro_threads` :return: True :raises: FBchatException if request failed """ @@ -2044,7 +2113,8 @@ class Client(object): def deleteMessages(self, message_ids): """Delete specifed messages. - :param message_ids: Message IDs to delete + Args: + message_ids: Message IDs to delete :return: True :raises: FBchatException if request failed """ @@ -2058,8 +2128,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 +2139,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 +2160,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 +2179,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) @@ -2854,7 +2930,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 + Args: + markAlive: Whether this should ping the Facebook server each time the loop runs :type markAlive: bool """ if markAlive is not None: @@ -2871,7 +2948,8 @@ class Client(object): def setActiveStatus(self, markAlive): """Change active status while listening. - :param markAlive: Whether to show if client is active + Args: + markAlive: Whether to show if client is active :type markAlive: bool """ self._markAlive = markAlive @@ -2887,7 +2965,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 +2977,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,7 +2989,8 @@ class Client(object): def onListenError(self, exception=None): """Called when an error was encountered while listening. - :param exception: The exception that was encountered + Args: + exception: The exception that was encountered :return: Whether the loop should keep running """ log.exception("Got exception while listening") @@ -2929,15 +3010,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 + Args: + mid: The message ID + author_id: The ID of the author + message: (deprecated. Use ``message_object.text`` instead) + message_object: The message (As a `Message` object) + thread_id: Thread ID that the message was sent to. See :ref:`intro_threads` + thread_type: 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 :type message_object: Message :type thread_type: ThreadType """ @@ -2956,14 +3038,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 + Args: + mid: The action ID + author_id: The ID of the person who changed the color + new_color: The new color + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type: 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 :type new_color: ThreadColor :type thread_type: ThreadType """ @@ -2986,14 +3069,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3015,14 +3099,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3043,13 +3128,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 + 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: 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 :type thread_type: ThreadType """ log.info("{} changed thread image in {}".format(author_id, thread_id)) @@ -3068,15 +3154,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3097,12 +3184,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 +3206,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 +3228,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,13 +3253,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3190,13 +3281,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3210,12 +3302,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 + 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 :type thread_type: ThreadType """ log.info( @@ -3235,12 +3328,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3260,12 +3354,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,20 +3377,22 @@ 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)) @@ -3304,10 +3401,11 @@ class Client(object): .. 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,11 +3414,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 + Args: + author_id: The ID of the person who sent the action + status: The typing status + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type: Type of thread that the action was sent to. See :ref:`intro_threads` + msg: A full set of the data recieved :type typing_status: TypingStatus :type thread_type: ThreadType """ @@ -3342,17 +3441,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3373,14 +3473,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 + Args: + mid: Message ID, that user reacted to + reaction: 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: 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 :type reaction: MessageReaction :type thread_type: ThreadType """ @@ -3401,12 +3502,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3420,11 +3522,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3436,11 +3539,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3459,13 +3563,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 + Args: + mid: The action ID + location: 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: 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 :type location: LiveLocationAttachment :type thread_type: ThreadType """ @@ -3491,14 +3596,15 @@ class Client(object): .. 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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3522,15 +3628,16 @@ class Client(object): .. 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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3550,14 +3657,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 + 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: 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 :type thread_type: ThreadType """ log.info( @@ -3577,14 +3685,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 + Args: + mid: The action ID + 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: 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 :type poll: Poll :type thread_type: ThreadType """ @@ -3609,14 +3718,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 + Args: + mid: The action ID + 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: 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 :type poll: Poll :type thread_type: ThreadType """ @@ -3639,14 +3749,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 + Args: + mid: The action ID + 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: 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 :type plan: Plan :type thread_type: ThreadType """ @@ -3668,13 +3779,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 + Args: + mid: The action ID + plan: Ended plan + thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` + thread_type: 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 :type plan: Plan :type thread_type: ThreadType """ @@ -3695,14 +3807,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 + Args: + mid: The action ID + 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: 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 :type plan: Plan :type thread_type: ThreadType """ @@ -3725,14 +3838,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 + Args: + mid: The action ID + 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: 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 :type plan: Plan :type thread_type: ThreadType """ @@ -3756,15 +3870,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 + Args: + mid: The action ID + plan: Plan + take_part: 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: 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 :type plan: Plan :type take_part: bool :type thread_type: ThreadType @@ -3785,24 +3900,27 @@ 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 + Args: + statuses: Dictionary with user IDs as keys and :class:`ActiveStatus` as values + msg: A full set of the data recieved :type statuses: dict """ log.debug("Buddylist overlay received: {}".format(statuses)) @@ -3810,15 +3928,17 @@ class Client(object): 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)) From ed05d16a31e1ac190b51718ac0a6f3470f0111ce Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 23 Jul 2019 21:15:30 +0200 Subject: [PATCH 3/6] Move :type: roles into the `Args` sections --- fbchat/_client.py | 259 +++++++++++++++------------------------------- 1 file changed, 86 insertions(+), 173 deletions(-) diff --git a/fbchat/_client.py b/fbchat/_client.py index d8b9a17..800d706 100644 --- a/fbchat/_client.py +++ b/fbchat/_client.py @@ -78,12 +78,9 @@ class Client(object): 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: Maximum number of times to try logging in - session_cookies: Cookies from a previous session (Will default to login if these are invalid) - logging_level: Configures the `logging level `_. Defaults to ``logging.INFO`` - :type max_tries: int - :type session_cookies: dict - :type logging_level: int + 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) @@ -171,8 +168,7 @@ class Client(object): """Execute graphql queries. Args: - queries: Zero or more dictionaries - :type queries: dict + queries (dict): Zero or more dictionaries :raises: FBchatException if request failed :return: A tuple containing json graphql queries @@ -220,8 +216,7 @@ class Client(object): """Load session cookies. Args: - session_cookies: A dictionay containing session cookies - :type session_cookies: dict + session_cookies (dict): A dictionay containing session cookies :return: False if ``session_cookies`` does not contain proper cookies :rtype: bool """ @@ -247,8 +242,7 @@ class Client(object): Args: email: Facebook ``email`` or ``id`` or ``phone number`` password: Facebook account password - max_tries: Maximum number of times to try logging in - :type max_tries: int + max_tries (int): Maximum number of times to try logging in :raises: FBchatException on failed login """ self.onLoggingIn(email=email) @@ -321,8 +315,7 @@ class Client(object): Args: thread_id: User/Group ID to default to. See :ref:`intro_threads` - thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` """ self._default_thread_id = thread_id self._default_thread_type = thread_type @@ -523,11 +516,9 @@ class Client(object): Args: query: Text to search for - offset: Number of messages to skip - limit: Max. number of messages to retrieve + 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` - :type offset: int - :type limit: int :return: Found Message IDs :rtype: typing.Iterable :raises: FBchatException if request failed @@ -556,11 +547,9 @@ class Client(object): Args: query: Text to search for - offset: Number of messages to skip - limit: Max. number of messages to retrieve + 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` - :type offset: int - :type limit: int :return: Found :class:`Message` objects :rtype: typing.Iterable :raises: FBchatException if request failed @@ -577,10 +566,8 @@ class Client(object): Args: query: Text to search for fetch_messages: Whether to fetch :class:`Message` objects or IDs only - thread_limit: Max. number of threads to retrieve - message_limit: Max. number of messages to retrieve - :type thread_limit: int - :type message_limit: int + thread_limit (int): Max. number of threads to retrieve + message_limit (int): Max. number of messages to retrieve :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 @@ -771,10 +758,8 @@ class Client(object): Args: thread_id: User/Group ID to get messages from. See :ref:`intro_threads` - limit: Max. number of messages to retrieve - before: A timestamp, indicating from which point to retrieve messages - :type limit: int - :type before: int + limit (int): Max. number of messages to retrieve + before (int): A timestamp, indicating from which point to retrieve messages :return: :class:`Message` objects :rtype: list :raises: FBchatException if request failed @@ -815,11 +800,9 @@ class Client(object): Args: offset: Deprecated. Do not use! - limit: Max. number of threads to retrieve. Capped at 20 + limit (int): Max. number of threads to retrieve. Capped at 20 thread_location (ThreadLocation): INBOX, PENDING, ARCHIVED or OTHER - before: A timestamp (in milliseconds), indicating from which point to retrieve threads - :type limit: int - :type before: int + before (int): A timestamp (in milliseconds), indicating from which point to retrieve threads :return: :class:`Thread` objects :rtype: list :raises: FBchatException if request failed @@ -895,8 +878,7 @@ class Client(object): """Fetch url to download the original image from an image attachment ID. Args: - image_id: The image you want to fethc - :type image_id: str + image_id (str): The image you want to fethc :return: An url where you can download the original image :rtype: str :raises: FBchatException if request failed @@ -1136,11 +1118,9 @@ class Client(object): """Send message to a thread. Args: - message: Message to send + message (Message): Message to send thread_id: User/Group ID to send to. See :ref:`intro_threads` - thread_type: See :ref:`intro_threads` - :type message: Message - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message :raises: FBchatException if request failed """ @@ -1176,8 +1156,7 @@ class Client(object): Args: wave_first: Whether to wave first or wave back thread_id: User/Group ID to send to. See :ref:`intro_threads` - thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message :raises: FBchatException if request failed """ @@ -1196,12 +1175,10 @@ class Client(object): """Reply to chosen quick reply. Args: - quick_reply: Quick reply to reply to + 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: See :ref:`intro_threads` - :type quick_reply: QuickReply - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message :raises: FBchatException if request failed """ @@ -1257,13 +1234,10 @@ class Client(object): """Send a given location to a thread as the user's current location. Args: - location: Location to send - message: Additional message + location (LocationAttachment): Location to send + message (Message): Additional message thread_id: User/Group ID to send to. See :ref:`intro_threads` - thread_type: See :ref:`intro_threads` - :type location: LocationAttachment - :type message: Message - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message :raises: FBchatException if request failed """ @@ -1281,13 +1255,10 @@ class Client(object): """Send a given location to a thread as a pinned location. Args: - location: Location to send - message: Additional message + location (LocationAttachment): Location to send + message (Message): Additional message thread_id: User/Group ID to send to. See :ref:`intro_threads` - thread_type: See :ref:`intro_threads` - :type location: LocationAttachment - :type message: Message - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message :raises: FBchatException if request failed """ @@ -1356,8 +1327,7 @@ class Client(object): 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: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent files :raises: FBchatException if request failed """ @@ -1376,8 +1346,7 @@ class Client(object): 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: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent files :raises: FBchatException if request failed """ @@ -1397,8 +1366,7 @@ class Client(object): 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: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent files :raises: FBchatException if request failed """ @@ -1417,8 +1385,7 @@ class Client(object): 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: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent files :raises: FBchatException if request failed """ @@ -1519,9 +1486,8 @@ class Client(object): """Add users to a group. Args: - user_ids: One or more user IDs to add + user_ids (list): One or more user IDs to add thread_id: Group ID to add people to. See :ref:`intro_threads` - :type user_ids: list :raises: FBchatException if request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1687,8 +1653,7 @@ class Client(object): Args: title: New group thread title thread_id: Group ID to change title of. See :ref:`intro_threads` - thread_type: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :raises: FBchatException if request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -1711,8 +1676,7 @@ class Client(object): 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: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :raises: FBchatException if request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -1730,9 +1694,8 @@ class Client(object): """Change thread color. Args: - color: New thread color + color (ThreadColor): New thread color thread_id: User/Group ID to change color of. See :ref:`intro_threads` - :type color: ThreadColor :raises: FBchatException if request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1769,8 +1732,7 @@ class Client(object): Args: message_id: :ref:`Message ID ` to react to - reaction: Reaction emoji to use, if None removes reaction - :type reaction: MessageReaction or None + reaction (MessageReaction): Reaction emoji to use, if None removes reaction :raises: FBchatException if request failed """ data = { @@ -1788,9 +1750,8 @@ class Client(object): """Set a plan. Args: - plan: Plan to set + plan (Plan): Plan to set thread_id: User/Group ID to send plan to. See :ref:`intro_threads` - :type plan: Plan :raises: FBchatException if request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1815,9 +1776,8 @@ class Client(object): """Edit a plan. Args: - plan: Plan to edit + plan (Plan): Plan to edit new_plan: New plan - :type plan: Plan :raises: FBchatException if request failed """ data = { @@ -1865,9 +1825,8 @@ class Client(object): """Create poll in a group thread. Args: - poll: Poll to create + poll (Poll): Poll to create thread_id: User/Group ID to create poll in. See :ref:`intro_threads` - :type poll: Poll :raises: FBchatException if request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1897,8 +1856,7 @@ class Client(object): 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: See :ref:`intro_threads` - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :raises: FBchatException if request failed """ data = {"question_id": poll_id} @@ -1920,11 +1878,9 @@ class Client(object): """Set users typing status in a thread. Args: - status: Specify the typing status + status (TypingStatus): Specify the typing status thread_id: User/Group ID to change status in. See :ref:`intro_threads` - thread_type: See :ref:`intro_threads` - :type status: TypingStatus - :type thread_type: ThreadType + thread_type (ThreadType): See :ref:`intro_threads` :raises: FBchatException if request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -2931,8 +2887,7 @@ class Client(object): """Initialize and runs the listening loop continually. Args: - markAlive: Whether this should ping the Facebook server each time the loop runs - :type markAlive: bool + markAlive (bool): Whether this should ping the Facebook server each time the loop runs """ if markAlive is not None: self.setActiveStatus(markAlive) @@ -2949,8 +2904,7 @@ class Client(object): """Change active status while listening. Args: - markAlive: Whether to show if client is active - :type markAlive: bool + markAlive (bool): Whether to show if client is active """ self._markAlive = markAlive @@ -3014,14 +2968,12 @@ class Client(object): mid: The message ID author_id: The ID of the author message: (deprecated. Use ``message_object.text`` instead) - message_object: The message (As a `Message` object) + 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: Type of thread 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 - :type message_object: Message - :type thread_type: ThreadType """ log.info("{} from {} in {}".format(message_object, thread_id, thread_type.name)) @@ -3041,14 +2993,12 @@ class Client(object): Args: mid: The action ID author_id: The ID of the person who changed the color - new_color: The new color + new_color (ThreadColor): The new color thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - thread_type: Type of thread 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 - :type new_color: ThreadColor - :type thread_type: ThreadType """ log.info( "Color change from {} in {} ({}): {}".format( @@ -3074,11 +3024,10 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "Emoji change from {} in {} ({}): {}".format( @@ -3104,11 +3053,10 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "Title change from {} in {} ({}): {}".format( @@ -3133,10 +3081,9 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info("{} changed thread image in {}".format(author_id, thread_id)) @@ -3160,11 +3107,10 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "Nickname change from {} in {} ({}) for {}: {}".format( @@ -3256,12 +3202,11 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "Messages seen by {} in {} ({}) at {}s".format( @@ -3285,11 +3230,10 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "Messages {} delivered to {} in {} ({}) at {}s".format( @@ -3309,7 +3253,6 @@ class Client(object): ts: A timestamp of the action metadata: Extra metadata about the action msg: A full set of the data recieved - :type thread_type: ThreadType """ log.info( "Marked messages as seen in threads {} at {}s".format( @@ -3332,10 +3275,9 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "{} unsent the message {} in {} ({}) at {}s".format( @@ -3416,12 +3358,10 @@ class Client(object): Args: author_id: The ID of the person who sent the action - status: The typing status + status (TypingStatus): The typing status thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - thread_type: Type of thread 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 - :type typing_status: TypingStatus - :type thread_type: ThreadType """ pass @@ -3449,11 +3389,10 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( '{} played "{}" in {} ({})'.format( @@ -3475,15 +3414,13 @@ class Client(object): Args: mid: Message ID, that user reacted to - reaction: Reaction + 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: Type of thread 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 - :type reaction: MessageReaction - :type thread_type: ThreadType """ log.info( "{} reacted to message {} with {} in {} ({})".format( @@ -3506,10 +3443,9 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "{} removed reaction from {} message in {} ({})".format( @@ -3525,10 +3461,9 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "{} blocked {} ({}) thread".format(author_id, thread_id, thread_type.name) @@ -3542,10 +3477,9 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "{} unblocked {} ({}) thread".format(author_id, thread_id, thread_type.name) @@ -3565,14 +3499,12 @@ class Client(object): Args: mid: The action ID - location: Sent location info + 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: Type of thread 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 - :type location: LiveLocationAttachment - :type thread_type: ThreadType """ log.info( "{} sent live location info in {} ({}) with latitude {} and longitude {}".format( @@ -3601,11 +3533,10 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "{} started call in {} ({})".format(caller_id, thread_id, thread_type.name) @@ -3634,11 +3565,10 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "{} ended call in {} ({})".format(caller_id, thread_id, thread_type.name) @@ -3662,11 +3592,10 @@ class Client(object): 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: Type of thread 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 - :type thread_type: ThreadType """ log.info( "{} joined call in {} ({})".format(joined_id, thread_id, thread_type.name) @@ -3687,15 +3616,13 @@ class Client(object): Args: mid: The action ID - poll: Created poll + 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: Type of thread 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 - :type poll: Poll - :type thread_type: ThreadType """ log.info( "{} created poll {} in {} ({})".format( @@ -3720,15 +3647,13 @@ class Client(object): Args: mid: The action ID - poll: Poll, that user voted in + 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: Type of thread 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 - :type poll: Poll - :type thread_type: ThreadType """ log.info( "{} voted in poll {} in {} ({})".format( @@ -3751,15 +3676,13 @@ class Client(object): Args: mid: The action ID - plan: Created plan + 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: Type of thread 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 - :type plan: Plan - :type thread_type: ThreadType """ log.info( "{} created plan {} in {} ({})".format( @@ -3781,14 +3704,12 @@ class Client(object): Args: mid: The action ID - plan: Ended plan + plan (Plan): Ended plan thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` - thread_type: Type of thread 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 - :type plan: Plan - :type thread_type: ThreadType """ log.info( "Plan {} has ended in {} ({})".format(plan, thread_id, thread_type.name) @@ -3809,15 +3730,13 @@ class Client(object): Args: mid: The action ID - plan: Edited plan + 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: Type of thread 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 - :type plan: Plan - :type thread_type: ThreadType """ log.info( "{} edited plan {} in {} ({})".format( @@ -3840,15 +3759,13 @@ class Client(object): Args: mid: The action ID - plan: Deleted plan + 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: Type of thread 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 - :type plan: Plan - :type thread_type: ThreadType """ log.info( "{} deleted plan {} in {} ({})".format( @@ -3872,17 +3789,14 @@ class Client(object): Args: mid: The action ID - plan: Plan - take_part: Whether the person takes part in the plan or not + 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: Type of thread 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 - :type plan: Plan - :type take_part: bool - :type thread_type: ThreadType """ if take_part: log.info( @@ -3919,9 +3833,8 @@ class Client(object): """Called when the client is listening and client receives information about friend active status. Args: - statuses: Dictionary with user IDs as keys and :class:`ActiveStatus` as values + statuses (dict): Dictionary with user IDs as keys and :class:`ActiveStatus` as values msg: A full set of the data recieved - :type statuses: dict """ log.debug("Buddylist overlay received: {}".format(statuses)) From d6876ce13bc6c3a7dc17f4fea603e7dceda28c11 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 23 Jul 2019 22:04:50 +0200 Subject: [PATCH 4/6] Convert :raises: roles to `Raises` sections --- fbchat/_client.py | 283 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 211 insertions(+), 72 deletions(-) diff --git a/fbchat/_client.py b/fbchat/_client.py index 800d706..09bf24e 100644 --- a/fbchat/_client.py +++ b/fbchat/_client.py @@ -81,7 +81,9 @@ class Client(object): 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 + + Raises: + FBchatException: On failed login """ self._sticky, self._pool = (None, None) self._seq = "0" @@ -169,10 +171,11 @@ class Client(object): Args: queries (dict): Zero or more dictionaries - - :raises: FBchatException if request failed :return: A tuple containing json graphql queries :rtype: tuple + + Raises: + FBchatException: If request failed """ data = { "method": "GET", @@ -184,7 +187,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] @@ -243,7 +247,9 @@ class Client(object): 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 + + Raises: + FBchatException: On failed login """ self.onLoggingIn(email=email) @@ -298,9 +304,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 + + 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: @@ -348,7 +356,9 @@ class Client(object): limit: The max. amount of threads to fetch (default all threads) :return: :class:`Thread` objects :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ threads = [] @@ -397,7 +407,9 @@ class Client(object): threads: Thread: List of threads to check for users :return: :class:`User` objects :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ users = [] users_to_fetch = [] # It's more efficient to fetch all users in one request @@ -421,7 +433,9 @@ class Client(object): :return: :class:`User` objects :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = {"viewer": self._uid} j = self._payload_post("/chat/user_info_all", data) @@ -443,7 +457,9 @@ class Client(object): limit: The max. amount of users to fetch :return: :class:`User` objects, ordered by relevance :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ params = {"search": name, "limit": limit} j = self.graphql_request(_graphql.from_query(_graphql.SEARCH_USER, params)) @@ -457,7 +473,9 @@ class Client(object): name: Name of the page :return: :class:`Page` objects, ordered by relevance :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ params = {"search": name, "limit": limit} j = self.graphql_request(_graphql.from_query(_graphql.SEARCH_PAGE, params)) @@ -472,7 +490,9 @@ class Client(object): limit: The max. amount of groups to fetch :return: :class:`Group` objects, ordered by relevance :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ params = {"search": name, "limit": limit} j = self.graphql_request(_graphql.from_query(_graphql.SEARCH_GROUP, params)) @@ -487,7 +507,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ params = {"search": name, "limit": limit} j = self.graphql_request(_graphql.from_query(_graphql.SEARCH_THREAD, params)) @@ -521,7 +543,9 @@ class Client(object): thread_id: User/Group ID to search in. See :ref:`intro_threads` :return: Found Message IDs :rtype: typing.Iterable - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -552,7 +576,9 @@ class Client(object): thread_id: User/Group ID to search in. See :ref:`intro_threads` :return: Found :class:`Message` objects :rtype: typing.Iterable - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ message_ids = self.searchForMessageIDs( query, offset=offset, limit=limit, thread_id=thread_id @@ -570,7 +596,9 @@ class Client(object): message_limit (int): Max. number of messages to retrieve :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 + + Raises: + FBchatException: If request failed """ data = {"query": query, "snippetLimit": thread_limit} j = self._payload_post("/ajax/mercury/search_snippets.php?dpr=1", data) @@ -636,7 +664,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ threads = self.fetchThreadInfo(*user_ids) users = {} @@ -658,7 +688,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ threads = self.fetchThreadInfo(*page_ids) pages = {} @@ -677,7 +709,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ threads = self.fetchThreadInfo(*group_ids) groups = {} @@ -699,7 +733,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ queries = [] for thread_id in thread_ids: @@ -762,7 +798,9 @@ class Client(object): before (int): A timestamp, indicating from which point to retrieve messages :return: :class:`Message` objects :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -805,7 +843,9 @@ class Client(object): before (int): A timestamp (in milliseconds), indicating from which point to retrieve threads :return: :class:`Thread` objects :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ if offset is not None: log.warning( @@ -849,7 +889,9 @@ class Client(object): :return: List of unread thread ids :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ form = { "folders[0]": "inbox", @@ -867,7 +909,9 @@ class Client(object): :return: List of unseen thread ids :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ j = self._payload_post("/mercury/unseen_thread_ids/", None) @@ -881,7 +925,9 @@ class Client(object): image_id (str): The image you want to fethc :return: An url where you can download the original image :rtype: str - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ image_id = str(image_id) data = {"photo_id": str(image_id)} @@ -900,7 +946,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) message_info = self._forcedFetch(thread_id, mid).get("message") @@ -912,7 +960,9 @@ class Client(object): Args: poll_id: Poll ID to fetch from :rtype: list - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = {"question_id": poll_id} j = self._payload_post("/ajax/mercury/get_poll_options", data) @@ -925,7 +975,9 @@ class Client(object): plan_id: Plan ID to fetch from :return: :class:`Plan` object :rtype: Plan - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = {"event_reminder_id": plan_id} j = self._payload_post("/ajax/eventreminder", data) @@ -1122,7 +1174,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) data = self._getSendData( @@ -1158,7 +1212,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + + 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) @@ -1180,7 +1236,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ quick_reply.is_response = True if isinstance(quick_reply, QuickReplyText): @@ -1239,7 +1297,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ self._sendLocation( location=location, @@ -1260,7 +1320,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent message - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ self._sendLocation( location=location, @@ -1329,7 +1391,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent files - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ file_urls = require_list(file_urls) files = self._upload(get_files_from_urls(file_urls)) @@ -1348,7 +1412,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent files - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ file_paths = require_list(file_paths) with get_files_from_paths(file_paths) as x: @@ -1368,7 +1434,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent files - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ clip_urls = require_list(clip_urls) files = self._upload(get_files_from_urls(clip_urls), voice_clip=True) @@ -1387,7 +1455,9 @@ class Client(object): thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` :return: :ref:`Message ID ` of the sent files - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ clip_paths = require_list(clip_paths) with get_files_from_paths(clip_paths) as x: @@ -1444,7 +1514,9 @@ class Client(object): Args: attachment_id: Attachment ID to forward thread_id: User/Group ID to send to. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) data = { @@ -1465,7 +1537,9 @@ class Client(object): message: The initial message user_ids: A list of users to create the group with. :return: ID of the new group - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = self._getSendData(message=self._oldMessage(message)) @@ -1488,7 +1562,9 @@ class Client(object): 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 + + 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) @@ -1516,7 +1592,9 @@ class Client(object): Args: user_id: User ID to remove thread_id: Group ID to remove people from. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1541,7 +1619,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ self._adminStatus(admin_ids, True, thread_id) @@ -1551,7 +1631,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ self._adminStatus(admin_ids, False, thread_id) @@ -1561,7 +1643,9 @@ class Client(object): Args: require_admin_approval: True or False thread_id: Group ID to remove people from. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1591,7 +1675,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ self._usersApproval(user_ids, True, thread_id) @@ -1601,7 +1687,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ self._usersApproval(user_ids, False, thread_id) @@ -1611,7 +1699,9 @@ class Client(object): Args: image_id: ID of uploaded image thread_id: User/Group ID to change image. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1626,7 +1716,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ (image_id, mimetype), = self._upload(get_files_from_urls([image_url])) return self._changeGroupImage(image_id, thread_id) @@ -1637,7 +1729,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ with get_files_from_paths([image_path]) as files: (image_id, mimetype), = self._upload(files) @@ -1654,7 +1748,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -1677,7 +1773,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -1696,7 +1794,9 @@ class Client(object): Args: color (ThreadColor): New thread color thread_id: User/Group ID to change color of. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1718,7 +1818,9 @@ class Client(object): Args: color: New thread emoji thread_id: User/Group ID to change emoji of. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1733,7 +1835,9 @@ class Client(object): Args: message_id: :ref:`Message ID ` to react to reaction (MessageReaction): Reaction emoji to use, if None removes reaction - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = { "action": "ADD_REACTION" if reaction else "REMOVE_REACTION", @@ -1752,7 +1856,9 @@ class Client(object): Args: plan (Plan): Plan to set thread_id: User/Group ID to send plan to. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1778,7 +1884,9 @@ class Client(object): Args: plan (Plan): Plan to edit new_plan: New plan - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = { "event_reminder_id": plan.uid, @@ -1796,7 +1904,9 @@ class Client(object): Args: plan: Plan to delete - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = {"event_reminder_id": plan.uid, "delete": "true", "acontext": ACONTEXT} j = self._payload_post("/ajax/eventreminder/submit", data) @@ -1807,7 +1917,9 @@ class Client(object): Args: plan: Plan to take part in or not take_part: Whether to take part in the plan - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = { "event_reminder_id": plan.uid, @@ -1827,7 +1939,9 @@ class Client(object): Args: poll (Poll): Poll to create thread_id: User/Group ID to create poll in. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, None) @@ -1857,7 +1971,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ data = {"question_id": poll_id} @@ -1881,7 +1997,9 @@ class Client(object): 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 + + Raises: + FBchatException: If request failed """ thread_id, thread_type = self._getThread(thread_id, thread_type) @@ -1904,7 +2022,9 @@ class Client(object): 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` :return: True - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = { "message_ids[0]": message_id, @@ -1931,7 +2051,9 @@ class Client(object): Args: thread_ids: User/Group IDs to set as read. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ self._readStatus(True, thread_ids) @@ -1942,7 +2064,9 @@ class Client(object): Args: thread_ids: User/Group IDs to set as unread. See :ref:`intro_threads` - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ self._readStatus(False, thread_ids) @@ -1968,7 +2092,9 @@ class Client(object): Args: friend_id: The ID of the friend that you want to remove :return: True - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = {"uid": friend_id} j = self._payload_post("/ajax/profile/removefriendconfirm.php", data) @@ -1980,7 +2106,9 @@ class Client(object): Args: user_id: The ID of the user that you want to block :return: True - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = {"fbid": user_id} j = self._payload_post("/messaging/block_messages/?dpr=1", data) @@ -1992,7 +2120,9 @@ class Client(object): Args: user_id: The ID of the user that you want to unblock :return: Whether the request was successful - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ data = {"fbid": user_id} j = self._payload_post("/messaging/unblock_messages/?dpr=1", data) @@ -2005,7 +2135,9 @@ class Client(object): location (ThreadLocation): INBOX, PENDING, ARCHIVED or OTHER thread_ids: Thread IDs to move. See :ref:`intro_threads` :return: True - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_ids = require_list(thread_ids) @@ -2037,7 +2169,9 @@ class Client(object): Args: thread_ids: Thread IDs to delete. See :ref:`intro_threads` :return: True - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ thread_ids = require_list(thread_ids) @@ -2060,7 +2194,9 @@ class Client(object): Args: thread_id: User/Group ID to mark as spam. See :ref:`intro_threads` :return: True - :raises: FBchatException if request failed + + 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}) @@ -2072,7 +2208,9 @@ class Client(object): Args: message_ids: Message IDs to delete :return: True - :raises: FBchatException if request failed + + Raises: + FBchatException: If request failed """ message_ids = require_list(message_ids) data = dict() @@ -2834,7 +2972,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 From beee209249b6bf9c87ac08c1466c34bb9459416c Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 23 Jul 2019 22:12:56 +0200 Subject: [PATCH 5/6] Convert :return: / :rtype: roles to `Returns` sections --- fbchat/_client.py | 230 +++++++++++++++++++++++++++++----------------- 1 file changed, 146 insertions(+), 84 deletions(-) diff --git a/fbchat/_client.py b/fbchat/_client.py index 09bf24e..2e7735b 100644 --- a/fbchat/_client.py +++ b/fbchat/_client.py @@ -171,8 +171,9 @@ class Client(object): Args: queries (dict): Zero or more dictionaries - :return: A tuple containing json graphql queries - :rtype: tuple + + Returns: + tuple: A tuple containing json graphql queries Raises: FBchatException: If request failed @@ -203,16 +204,16 @@ 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() @@ -221,8 +222,9 @@ class Client(object): Args: session_cookies (dict): A dictionay containing session cookies - :return: False if ``session_cookies`` does not contain proper cookies - :rtype: bool + + Returns: + bool: False if ``session_cookies`` does not contain proper cookies """ try: # Load cookies into current session @@ -284,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 @@ -304,8 +306,8 @@ 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. - :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 @@ -354,8 +356,9 @@ class Client(object): 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) - :return: :class:`Thread` objects - :rtype: list + + Returns: + list: :class:`Thread` objects Raises: FBchatException: If request failed @@ -405,8 +408,9 @@ class Client(object): Args: threads: Thread: List of threads to check for users - :return: :class:`User` objects - :rtype: list + + Returns: + list: :class:`User` objects Raises: FBchatException: If request failed @@ -431,8 +435,8 @@ class Client(object): def fetchAllUsers(self): """Fetch all users the client is currently chatting with. - :return: :class:`User` objects - :rtype: list + Returns: + list: :class:`User` objects Raises: FBchatException: If request failed @@ -455,8 +459,9 @@ class Client(object): Args: name: Name of the user limit: The max. amount of users to fetch - :return: :class:`User` objects, ordered by relevance - :rtype: list + + Returns: + list: :class:`User` objects, ordered by relevance Raises: FBchatException: If request failed @@ -471,8 +476,9 @@ class Client(object): Args: name: Name of the page - :return: :class:`Page` objects, ordered by relevance - :rtype: list + + Returns: + list: :class:`Page` objects, ordered by relevance Raises: FBchatException: If request failed @@ -488,8 +494,9 @@ class Client(object): Args: name: Name of the group thread limit: The max. amount of groups to fetch - :return: :class:`Group` objects, ordered by relevance - :rtype: list + + Returns: + list: :class:`Group` objects, ordered by relevance Raises: FBchatException: If request failed @@ -505,8 +512,9 @@ class Client(object): Args: name: Name of the thread limit: The max. amount of groups to fetch - :return: :class:`User`, :class:`Group` and :class:`Page` objects, ordered by relevance - :rtype: list + + Returns: + list: :class:`User`, :class:`Group` and :class:`Page` objects, ordered by relevance Raises: FBchatException: If request failed @@ -541,8 +549,9 @@ class Client(object): 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` - :return: Found Message IDs - :rtype: typing.Iterable + + Returns: + typing.Iterable: Found Message IDs Raises: FBchatException: If request failed @@ -574,8 +583,9 @@ class Client(object): 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` - :return: Found :class:`Message` objects - :rtype: typing.Iterable + + Returns: + typing.Iterable: Found :class:`Message` objects Raises: FBchatException: If request failed @@ -594,8 +604,9 @@ class Client(object): 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 - :return: Dictionary with thread IDs as keys and iterables to get messages as values - :rtype: typing.Dict[str, typing.Iterable] + + Returns: + typing.Dict[str, typing.Iterable]: Dictionary with thread IDs as keys and iterables to get messages as values Raises: FBchatException: If request failed @@ -662,8 +673,9 @@ class Client(object): Args: user_ids: One or more user ID(s) to query - :return: :class:`User` objects, labeled by their ID - :rtype: dict + + Returns: + dict: :class:`User` objects, labeled by their ID Raises: FBchatException: If request failed @@ -686,8 +698,9 @@ class Client(object): Args: page_ids: One or more page ID(s) to query - :return: :class:`Page` objects, labeled by their ID - :rtype: dict + + Returns: + dict: :class:`Page` objects, labeled by their ID Raises: FBchatException: If request failed @@ -707,8 +720,9 @@ class Client(object): Args: group_ids: One or more group ID(s) to query - :return: :class:`Group` objects, labeled by their ID - :rtype: dict + + Returns: + dict: :class:`Group` objects, labeled by their ID Raises: FBchatException: If request failed @@ -731,8 +745,9 @@ class Client(object): Args: thread_ids: One or more thread ID(s) to query - :return: :class:`Thread` objects, labeled by their ID - :rtype: dict + + Returns: + dict: :class:`Thread` objects, labeled by their ID Raises: FBchatException: If request failed @@ -796,8 +811,9 @@ class Client(object): 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 - :return: :class:`Message` objects - :rtype: list + + Returns: + list: :class:`Message` objects Raises: FBchatException: If request failed @@ -841,8 +857,9 @@ class Client(object): 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 - :return: :class:`Thread` objects - :rtype: list + + Returns: + list: :class:`Thread` objects Raises: FBchatException: If request failed @@ -887,8 +904,8 @@ class Client(object): def fetchUnread(self): """Fetch unread threads. - :return: List of unread thread ids - :rtype: list + Returns: + list: List of unread thread ids Raises: FBchatException: If request failed @@ -907,8 +924,8 @@ class Client(object): def fetchUnseen(self): """Fetch unseen / new threads. - :return: List of unseen thread ids - :rtype: list + Returns: + list: List of unseen thread ids Raises: FBchatException: If request failed @@ -923,8 +940,9 @@ class Client(object): Args: image_id (str): The image you want to fethc - :return: An url where you can download the original image - :rtype: str + + Returns: + str: An url where you can download the original image Raises: FBchatException: If request failed @@ -944,8 +962,9 @@ class Client(object): Args: mid: Message ID to fetch from thread_id: User/Group ID to get message info from. See :ref:`intro_threads` - :return: :class:`Message` object - :rtype: Message + + Returns: + Message: :class:`Message` object Raises: FBchatException: If request failed @@ -959,7 +978,9 @@ class Client(object): Args: poll_id: Poll ID to fetch from - :rtype: list + + Returns: + list Raises: FBchatException: If request failed @@ -973,8 +994,9 @@ class Client(object): Args: plan_id: Plan ID to fetch from - :return: :class:`Plan` object - :rtype: Plan + + Returns: + Plan: :class:`Plan` object Raises: FBchatException: If request failed @@ -990,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 [ @@ -1001,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"]] @@ -1017,8 +1039,9 @@ class Client(object): Args: user_id: ID of the user - :return: Given user active status - :rtype: ActiveStatus + + Returns: + ActiveStatus: Given user active status """ return self._buddylist.get(str(user_id)) @@ -1027,8 +1050,9 @@ class Client(object): Args: thread_id: ID of the thread - :return: :class:`ImageAttachment` or :class:`VideoAttachment`. - :rtype: iterable + + Returns: + typing.Iterable: :class:`ImageAttachment` or :class:`VideoAttachment` """ thread_id, thread_type = self._getThread(thread_id, None) data = {"id": thread_id, "first": 48} @@ -1173,7 +1197,9 @@ class Client(object): message (Message): Message to send thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` - :return: :ref:`Message ID ` of the sent message + + Returns: + :ref:`Message ID ` of the sent message Raises: FBchatException: If request failed @@ -1211,7 +1237,9 @@ class Client(object): 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` - :return: :ref:`Message ID ` of the sent message + + Returns: + :ref:`Message ID ` of the sent message Raises: FBchatException: If request failed @@ -1235,7 +1263,9 @@ class Client(object): 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` - :return: :ref:`Message ID ` of the sent message + + Returns: + :ref:`Message ID ` of the sent message Raises: FBchatException: If request failed @@ -1296,7 +1326,9 @@ class Client(object): message (Message): Additional message thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` - :return: :ref:`Message ID ` of the sent message + + Returns: + :ref:`Message ID ` of the sent message Raises: FBchatException: If request failed @@ -1319,7 +1351,9 @@ class Client(object): message (Message): Additional message thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` - :return: :ref:`Message ID ` of the sent message + + Returns: + :ref:`Message ID ` of the sent message Raises: FBchatException: If request failed @@ -1390,7 +1424,9 @@ class Client(object): message: Additional message thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` - :return: :ref:`Message ID ` of the sent files + + Returns: + :ref:`Message ID ` of the sent files Raises: FBchatException: If request failed @@ -1411,7 +1447,9 @@ class Client(object): message: Additional message thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` - :return: :ref:`Message ID ` of the sent files + + Returns: + :ref:`Message ID ` of the sent files Raises: FBchatException: If request failed @@ -1433,7 +1471,9 @@ class Client(object): message: Additional message thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` - :return: :ref:`Message ID ` of the sent files + + Returns: + :ref:`Message ID ` of the sent files Raises: FBchatException: If request failed @@ -1454,7 +1494,9 @@ class Client(object): message: Additional message thread_id: User/Group ID to send to. See :ref:`intro_threads` thread_type (ThreadType): See :ref:`intro_threads` - :return: :ref:`Message ID ` of the sent files + + Returns: + :ref:`Message ID ` of the sent files Raises: FBchatException: If request failed @@ -1536,7 +1578,9 @@ class Client(object): Args: message: The initial message user_ids: A list of users to create the group with. - :return: ID of the new group + + Returns: + ID of the new group Raises: FBchatException: If request failed @@ -2021,7 +2065,9 @@ class Client(object): 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` - :return: True + + Returns: + True Raises: FBchatException: If request failed @@ -2091,7 +2137,9 @@ class Client(object): Args: friend_id: The ID of the friend that you want to remove - :return: True + + Returns: + True Raises: FBchatException: If request failed @@ -2105,7 +2153,9 @@ class Client(object): Args: user_id: The ID of the user that you want to block - :return: True + + Returns: + True Raises: FBchatException: If request failed @@ -2119,7 +2169,9 @@ class Client(object): Args: user_id: The ID of the user that you want to unblock - :return: Whether the request was successful + + Returns: + Whether the request was successful Raises: FBchatException: If request failed @@ -2134,7 +2186,9 @@ class Client(object): Args: location (ThreadLocation): INBOX, PENDING, ARCHIVED or OTHER thread_ids: Thread IDs to move. See :ref:`intro_threads` - :return: True + + Returns: + True Raises: FBchatException: If request failed @@ -2168,7 +2222,9 @@ class Client(object): Args: thread_ids: Thread IDs to delete. See :ref:`intro_threads` - :return: True + + Returns: + True Raises: FBchatException: If request failed @@ -2193,7 +2249,9 @@ class Client(object): Args: thread_id: User/Group ID to mark as spam. See :ref:`intro_threads` - :return: True + + Returns: + True Raises: FBchatException: If request failed @@ -2207,7 +2265,9 @@ class Client(object): Args: message_ids: Message IDs to delete - :return: True + + Returns: + True Raises: FBchatException: If request failed @@ -2986,8 +3046,8 @@ class Client(object): ``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 @@ -3084,7 +3144,9 @@ class Client(object): Args: exception: The exception that was encountered - :return: Whether the loop should keep running + + Returns: + Whether the loop should keep running """ log.exception("Got exception while listening") return True From dbb20b1fdcf95c811f5127b43197a426445b8f37 Mon Sep 17 00:00:00 2001 From: Mads Marquart Date: Tue, 23 Jul 2019 22:20:41 +0200 Subject: [PATCH 6/6] Convert various directives to Google style sections --- fbchat/_client.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/fbchat/_client.py b/fbchat/_client.py index 2e7735b..aeced3b 100644 --- a/fbchat/_client.py +++ b/fbchat/_client.py @@ -575,7 +575,7 @@ 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. Args: @@ -668,7 +668,7 @@ class Client(object): def fetchUserInfo(self, *user_ids): """Fetch users' info from IDs, unordered. - .. warning:: + Warning: Sends two requests, to fetch all available info! Args: @@ -693,7 +693,7 @@ class Client(object): def fetchPageInfo(self, *page_ids): """Fetch pages' info from IDs, unordered. - .. warning:: + Warning: Sends two requests, to fetch all available info! Args: @@ -740,7 +740,7 @@ 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! Args: @@ -1034,7 +1034,7 @@ class Client(object): Return ``None`` if status isn't known. - .. warning:: + Warning: Only works when listening. Args: @@ -1855,7 +1855,7 @@ 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. @@ -2118,14 +2118,14 @@ class Client(object): 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"} @@ -3042,7 +3042,7 @@ 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. @@ -3541,7 +3541,7 @@ class Client(object): def onInbox(self, unseen=None, unread=None, recent_unread=None, msg=None): """ - .. todo:: + Todo: Documenting this Args: @@ -3726,7 +3726,7 @@ 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. Args: @@ -3757,7 +3757,7 @@ 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. Args: