karaolidis/fbchat
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up doc references

Browse Source
This commit is contained in:
Mads Marquart
2019-12-11 15:18:26 +01:00
parent aaf26691d6
commit d1fbf0ba0a
9 changed files with 53 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/intro.rst
View File

@@ -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 ``<email>`` and ``<password>`` 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('<email>', '<password>')
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 `<https://www.facebook.com/messages/>`_,
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='<message>'), thread_id='<user id>', thread_type=ThreadType.USER)
client.send(Message(text='<message>'), thread_id='<group 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='<user id>')
client.change_thread_color(ThreadColor.MESSENGER_BLUE, thread_id='<group 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('<name of user>')
@@ -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):

48
fbchat/_client.py
View File

@@ -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))

2
fbchat/_core.py
View File

@@ -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:

2
fbchat/_exception.py
View File

@@ -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()

2
fbchat/_group.py
View File

@@ -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)

12
fbchat/_message.py
View File

@@ -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)

2
fbchat/_poll.py
View File

@@ -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)

2
fbchat/_thread.py
View File

@@ -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

2
fbchat/_user.py
View File

@@ -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)