diff --git a/docs/intro.rst b/docs/intro.rst index 6a9e956..873fc7e 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -13,8 +13,8 @@ You should also make sure that the file's access control is appropriately restri Logging In ---------- -Simply create an instance of :class:`Client`. If you have two factor authentication enabled, type the code in the terminal prompt -(If you want to supply the code in another fashion, overwrite :func:`Client.on_2fa_code`):: +Simply create an instance of `Client`. If you have two factor authentication enabled, type the code in the terminal prompt +(If you want to supply the code in another fashion, overwrite `Client.on_2fa_code`):: from fbchat import Client from fbchat.models import * @@ -26,15 +26,15 @@ Replace ```` and ```` with your email and password respectively For ease of use then most of the code snippets in this document will assume you've already completed the login process Though the second line, ``from fbchat.models import *``, is not strictly necessary here, later code snippets will assume you've done this -If you want to change how verbose ``fbchat`` is, change the logging level (in :class:`Client`) +If you want to change how verbose ``fbchat`` is, change the logging level (in `Client`) -Throughout your code, if you want to check whether you are still logged in, use :func:`Client.is_logged_in`. -An example would be to login again if you've been logged out, using :func:`Client.login`:: +Throughout your code, if you want to check whether you are still logged in, use `Client.is_logged_in`. +An example would be to login again if you've been logged out, using `Client.login`:: if not client.is_logged_in(): client.login('', '') -When you're done using the client, and want to securely logout, use :func:`Client.logout`:: +When you're done using the client, and want to securely logout, use `Client.logout`:: client.logout() @@ -46,14 +46,14 @@ Threads A thread can refer to two things: A Messenger group chat or a single Facebook user -:class:`ThreadType` is an enumerator with two values: ``USER`` and ``GROUP``. +`ThreadType` is an enumerator with two values: ``USER`` and ``GROUP``. These will specify whether the thread is a single user chat or a group chat. This is required for many of ``fbchat``'s functions, since Facebook differentiates between these two internally -Searching for group chats and finding their ID can be done via. :func:`Client.search_for_groups`, -and searching for users is possible via. :func:`Client.search_for_users`. See :ref:`intro_fetching` +Searching for group chats and finding their ID can be done via. `Client.search_for_groups`, +and searching for users is possible via. `Client.search_for_users`. See :ref:`intro_fetching` -You can get your own user ID by using :any:`Client.uid` +You can get your own user ID by using `Client.uid` Getting the ID of a group chat is fairly trivial otherwise, since you only need to navigate to ``_, click on the group you want to find the ID of, and then read the id from the address bar. @@ -71,7 +71,7 @@ corresponds to the ID of a single user, and the ID of a group respectively:: client.send(Message(text=''), thread_id='', thread_type=ThreadType.USER) client.send(Message(text=''), thread_id='', thread_type=ThreadType.GROUP) -Some functions (e.g. :func:`Client.change_thread_color`) don't require a thread type, so in these cases you just provide the thread ID:: +Some functions (e.g. `Client.change_thread_color`) don't require a thread type, so in these cases you just provide the thread ID:: client.change_thread_color(ThreadColor.BILOBA_FLOWER, thread_id='') client.change_thread_color(ThreadColor.MESSENGER_BLUE, thread_id='') @@ -85,8 +85,8 @@ Message IDs Every message you send on Facebook has a unique ID, and every action you do in a thread, like changing a nickname or adding a person, has a unique ID too. -Some of ``fbchat``'s functions require these ID's, like :func:`Client.react_to_message`, -and some of then provide this ID, like :func:`Client.send`. +Some of ``fbchat``'s functions require these ID's, like `Client.react_to_message`, +and some of then provide this ID, like `Client.send`. This snippet shows how to send a message, and then use the returned ID to react to that message with a 😍 emoji:: message_id = client.send(Message(text='message'), thread_id=thread_id, thread_type=thread_type) @@ -118,7 +118,7 @@ Fetching Information You can use ``fbchat`` to fetch basic information like user names, profile pictures, thread names and user IDs -You can retrieve a user's ID with :func:`Client.search_for_users`. +You can retrieve a user's ID with `Client.search_for_users`. The following snippet will search for users by their name, take the first (and most likely) user, and then get their user ID from the result:: users = client.search_for_users('') @@ -140,11 +140,11 @@ Sessions ``fbchat`` provides functions to retrieve and set the session cookies. This will enable you to store the session cookies in a separate file, so that you don't have to login each time you start your script. -Use :func:`Client.get_gession` to retrieve the cookies:: +Use `Client.get_gession` to retrieve the cookies:: session_cookies = client.get_gession() -Then you can use :func:`Client.set_gession`:: +Then you can use `Client.set_gession`:: client.set_gession(session_cookies) @@ -162,7 +162,7 @@ Or you can set the ``session_cookies`` on your initial login. Listening & Events ------------------ -To use the listening functions ``fbchat`` offers (like :func:`Client.listen`), +To use the listening functions ``fbchat`` offers (like `Client.listen`), you have to define what should be executed when certain events happen. By default, (most) events will just be a `logging.info` statement, meaning it will simply print information to the console when an event happens @@ -170,7 +170,7 @@ meaning it will simply print information to the console when an event happens .. note:: You can identify the event methods by their ``on`` prefix, e.g. ``on_message`` -The event actions can be changed by subclassing the :class:`Client`, and then overwriting the event methods:: +The event actions can be changed by subclassing the `Client`, and then overwriting the event methods:: class CustomClient(Client): def on_message(self, mid, author_id, message_object, thread_id, thread_type, ts, metadata, msg, **kwargs): diff --git a/fbchat/_client.py b/fbchat/_client.py index a2841aa..0b14591 100644 --- a/fbchat/_client.py +++ b/fbchat/_client.py @@ -38,9 +38,9 @@ ACONTEXT = { class Client: """A client for the Facebook Chat (Messenger). - This is the main class of ``fbchat``, which contains all the methods you use to - interact with Facebook. You can extend this class, and overwrite the ``on`` methods, - to provide custom event handling (mainly useful while listening). + This is the main class, which contains all the methods you use to interact with + Facebook. You can extend this class, and overwrite the ``on`` methods, to provide + custom event handling (mainly useful while listening). """ @property @@ -215,7 +215,7 @@ class Client: limit: The max. amount of threads to fetch (default all threads) Returns: - list: :class:`Thread` objects + list: `Thread` objects Raises: FBchatException: If request failed @@ -266,7 +266,7 @@ class Client: threads: Thread: List of threads to check for users Returns: - list: :class:`User` objects + list: `User` objects Raises: FBchatException: If request failed @@ -292,7 +292,7 @@ class Client: """Fetch all users the client is currently chatting with. Returns: - list: :class:`User` objects + list: `User` objects Raises: FBchatException: If request failed @@ -317,7 +317,7 @@ class Client: limit: The max. amount of users to fetch Returns: - list: :class:`User` objects, ordered by relevance + list: `User` objects, ordered by relevance Raises: FBchatException: If request failed @@ -334,7 +334,7 @@ class Client: name: Name of the page Returns: - list: :class:`Page` objects, ordered by relevance + list: `Page` objects, ordered by relevance Raises: FBchatException: If request failed @@ -352,7 +352,7 @@ class Client: limit: The max. amount of groups to fetch Returns: - list: :class:`Group` objects, ordered by relevance + list: `Group` objects, ordered by relevance Raises: FBchatException: If request failed @@ -370,7 +370,7 @@ class Client: limit: The max. amount of groups to fetch Returns: - list: :class:`User`, :class:`Group` and :class:`Page` objects, ordered by relevance + list: `User`, `Group` and `Page` objects, ordered by relevance Raises: FBchatException: If request failed @@ -441,7 +441,7 @@ class Client: thread_id: User/Group ID to search in. See :ref:`intro_threads` Returns: - typing.Iterable: Found :class:`Message` objects + typing.Iterable: Found `Message` objects Raises: FBchatException: If request failed @@ -457,7 +457,7 @@ class Client: Args: query: Text to search for - fetch_messages: Whether to fetch :class:`Message` objects or IDs only + fetch_messages: Whether to fetch `Message` objects or IDs only thread_limit (int): Max. number of threads to retrieve message_limit (int): Max. number of messages to retrieve @@ -531,7 +531,7 @@ class Client: user_ids: One or more user ID(s) to query Returns: - dict: :class:`User` objects, labeled by their ID + dict: `User` objects, labeled by their ID Raises: FBchatException: If request failed @@ -556,7 +556,7 @@ class Client: page_ids: One or more page ID(s) to query Returns: - dict: :class:`Page` objects, labeled by their ID + dict: `Page` objects, labeled by their ID Raises: FBchatException: If request failed @@ -578,7 +578,7 @@ class Client: group_ids: One or more group ID(s) to query Returns: - dict: :class:`Group` objects, labeled by their ID + dict: `Group` objects, labeled by their ID Raises: FBchatException: If request failed @@ -603,7 +603,7 @@ class Client: thread_ids: One or more thread ID(s) to query Returns: - dict: :class:`Thread` objects, labeled by their ID + dict: `Thread` objects, labeled by their ID Raises: FBchatException: If request failed @@ -669,7 +669,7 @@ class Client: before (datetime.datetime): The point from which to retrieve messages Returns: - list: :class:`Message` objects + list: `Message` objects Raises: FBchatException: If request failed @@ -707,7 +707,7 @@ class Client: before (datetime.datetime): The point from which to retrieve threads Returns: - list: :class:`Thread` objects + list: `Thread` objects Raises: FBchatException: If request failed @@ -806,7 +806,7 @@ class Client: thread_id: User/Group ID to get message info from. See :ref:`intro_threads` Returns: - Message: :class:`Message` object + Message: `Message` object Raises: FBchatException: If request failed @@ -837,7 +837,7 @@ class Client: plan_id: Plan ID to fetch from Returns: - Plan: :class:`Plan` object + Plan: `Plan` object Raises: FBchatException: If request failed @@ -893,7 +893,7 @@ class Client: thread_id: ID of the thread Returns: - typing.Iterable: :class:`ImageAttachment` or :class:`VideoAttachment` + typing.Iterable: `ImageAttachment` or `VideoAttachment` """ data = {"id": thread_id, "first": 48} thread_id = str(thread_id) @@ -1013,9 +1013,7 @@ class Client: return self.send(Message(text=quick_reply.title, quick_replies=[new])) elif isinstance(quick_reply, QuickReplyLocation): if not isinstance(payload, LocationAttachment): - raise TypeError( - "Payload must be an instance of `fbchat.LocationAttachment`" - ) + raise TypeError("Payload must be an instance of `LocationAttachment`") return self.send_location( payload, thread_id=thread_id, thread_type=thread_type ) @@ -3655,7 +3653,7 @@ class Client: """Called when the client is listening and client receives information about friend active status. Args: - statuses (dict): Dictionary with user IDs as keys and :class:`ActiveStatus` as values + statuses (dict): Dictionary with user IDs as keys and `ActiveStatus` as values msg: A full set of the data received """ log.debug("Buddylist overlay received: {}".format(statuses)) diff --git a/fbchat/_core.py b/fbchat/_core.py index 9161ef6..3f03a4b 100644 --- a/fbchat/_core.py +++ b/fbchat/_core.py @@ -13,7 +13,7 @@ attrs_default = attr.s(slots=True, kw_only=kw_only) class Enum(aenum.Enum): - """Used internally by ``fbchat`` to support enumerations""" + """Used internally to support enumerations""" def __repr__(self): # For documentation: diff --git a/fbchat/_exception.py b/fbchat/_exception.py index 64632cb..92c654d 100644 --- a/fbchat/_exception.py +++ b/fbchat/_exception.py @@ -8,7 +8,7 @@ attrs_exception = attr.s(slots=True, auto_exc=True) class FBchatException(Exception): """Custom exception thrown by ``fbchat``. - All exceptions in the ``fbchat`` module inherits this. + All exceptions in the module inherits this. """ message = attr.ib() diff --git a/fbchat/_group.py b/fbchat/_group.py index eef0b0a..10d1666 100644 --- a/fbchat/_group.py +++ b/fbchat/_group.py @@ -14,7 +14,7 @@ class Group(Thread): participants = attr.ib(factory=set) #: A dictionary, containing user nicknames mapped to their IDs nicknames = attr.ib(factory=dict) - #: A :class:`ThreadColor`. The groups's message color + #: A `ThreadColor`. The groups's message color color = attr.ib(None) #: The groups's default emoji emoji = attr.ib(None) diff --git a/fbchat/_message.py b/fbchat/_message.py index d9fee2c..9c7380a 100644 --- a/fbchat/_message.py +++ b/fbchat/_message.py @@ -80,9 +80,9 @@ class Message: #: The actual message text = attr.ib(None) - #: A list of :class:`Mention` objects + #: A list of `Mention` objects mentions = attr.ib(factory=list) - #: A :class:`EmojiSize`. Size of a sent emoji + #: A `EmojiSize`. Size of a sent emoji emoji_size = attr.ib(None) #: The message ID uid = attr.ib(None) @@ -92,15 +92,15 @@ class Message: created_at = attr.ib(None) #: Whether the message is read is_read = attr.ib(None) - #: A list of people IDs who read the message, works only with :func:`fbchat.Client.fetch_thread_messages` + #: A list of people IDs who read the message, works only with `Client.fetch_thread_messages` read_by = attr.ib(factory=list) - #: A dictionary with user's IDs as keys, and their :class:`MessageReaction` as values + #: A dictionary with user's IDs as keys, and their `MessageReaction` as values reactions = attr.ib(factory=dict) - #: A :class:`Sticker` + #: A `Sticker` sticker = attr.ib(None) #: A list of attachments attachments = attr.ib(factory=list) - #: A list of :class:`QuickReply` + #: A list of `QuickReply` quick_replies = attr.ib(factory=list) #: Whether the message is unsent (deleted for everyone) unsent = attr.ib(False) diff --git a/fbchat/_poll.py b/fbchat/_poll.py index 3273484..8f31575 100644 --- a/fbchat/_poll.py +++ b/fbchat/_poll.py @@ -8,7 +8,7 @@ class Poll: #: Title of the poll title = attr.ib() - #: List of :class:`PollOption`, can be fetched with :func:`fbchat.Client.fetch_poll_options` + #: List of `PollOption`, can be fetched with `Client.fetch_poll_options` options = attr.ib() #: Options count options_count = attr.ib(None) diff --git a/fbchat/_thread.py b/fbchat/_thread.py index b517d1b..3369df4 100644 --- a/fbchat/_thread.py +++ b/fbchat/_thread.py @@ -83,7 +83,7 @@ class Thread: last_active = attr.ib(None) #: Number of messages in the thread message_count = attr.ib(None) - #: Set :class:`Plan` + #: Set `Plan` plan = attr.ib(None) @staticmethod diff --git a/fbchat/_user.py b/fbchat/_user.py index 5071c38..4dcfbf4 100644 --- a/fbchat/_user.py +++ b/fbchat/_user.py @@ -63,7 +63,7 @@ class User(Thread): nickname = attr.ib(None) #: The clients nickname, as seen by the user own_nickname = attr.ib(None) - #: A :class:`ThreadColor`. The message color + #: A `ThreadColor`. The message color color = attr.ib(None) #: The default emoji emoji = attr.ib(None)