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

Merge pull request #440 from carpedm20/fix-docs

Browse Source 
Fix and clean up documentation
This commit is contained in:
Mads Marquart
2019-07-03 23:55:16 +02:00
committed by GitHub
parent 281a20f56a a9c681818a
commit 3a0b9867bc
19 changed files with 374 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
.readthedocs.yml Normal file
View File

@@ -0,0 +1,18 @@
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
version: 2
formats:
- pdf
- htmlzip
python:
version: 3.6
install:
- path: .
extra_requirements:
- docs
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
fail_on_warning: true

6
README.rst
View File

@@ -35,14 +35,12 @@ Installation:
$ pip install fbchat $ pip install fbchat
You can also install from source, by using `flit`: You can also install from source if you have ``pip>=19.0``:
.. code-block:: .. code-block::
$ pip install flit
$ git clone https://github.com/carpedm20/fbchat.git $ git clone https://github.com/carpedm20/fbchat.git
$ cd fbchat $ pip install fbchat
$ flit install
Maintainer Maintainer

3
docs/Makefile
View File

@@ -3,8 +3,7 @@
# You can set these variables from the command line. # You can set these variables from the command line.
SPHINXOPTS = SPHINXOPTS =
SPHINXBUILD = python3.6 -msphinx SPHINXBUILD = sphinx-build
SPHINXPROJ = fbchat
SOURCEDIR = . SOURCEDIR = .
BUILDDIR = _build BUILDDIR = _build

84
docs/api.rst
View File

@@ -1,33 +1,79 @@
.. module:: fbchat .. module:: fbchat
.. highlight:: python
.. _api: .. _api:
.. Note: we're using () to hide the __init__ method where relevant
Full API Full API
======== ========
If you are looking for information on a specific function, class, or method, this part of the documentation is for you. If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
.. _api_client:
Client Client
------ ------
This is the main class of `fbchat`, which contains all the methods you use to interact with Facebook. .. autoclass:: Client
You can extend this class, and overwrite the events, to provide custom event handling (mainly used while listening)
.. autoclass:: Client(email, password, user_agent=None, max_tries=5, session_cookies=None, logging_level=logging.INFO) Threads
:members: -------
.. autoclass:: Thread()
.. _api_models: .. autoclass:: ThreadType(Enum)
:undoc-members:
Models .. autoclass:: Page()
------ .. autoclass:: User()
.. autoclass:: Group()
These models are used in various functions, both as inputs and return values.
A good tip is to write ``from fbchat.models import *`` at the start of your source, so you can use these models freely Messages
--------
.. automodule:: fbchat.models
:members: .. autoclass:: Message
.. autoclass:: Mention
.. autoclass:: EmojiSize(Enum)
:undoc-members:
.. autoclass:: MessageReaction(Enum)
:undoc-members:
Exceptions
----------
.. autoexception:: FBchatException()
.. autoexception:: FBchatFacebookError()
.. autoexception:: FBchatUserError()
Attachments
-----------
.. autoclass:: Attachment()
.. autoclass:: ShareAttachment()
.. autoclass:: Sticker()
.. autoclass:: LocationAttachment()
.. autoclass:: LiveLocationAttachment()
.. autoclass:: FileAttachment()
.. autoclass:: AudioAttachment()
.. autoclass:: ImageAttachment()
.. autoclass:: VideoAttachment()
.. autoclass:: ImageAttachment()
Miscellaneous
-------------
.. autoclass:: ThreadLocation(Enum)
:undoc-members:
.. autoclass:: ThreadColor(Enum)
:undoc-members:
.. autoclass:: ActiveStatus()
.. autoclass:: TypingStatus(Enum)
:undoc-members:
.. autoclass:: QuickReply
.. autoclass:: QuickReplyText
.. autoclass:: QuickReplyLocation
.. autoclass:: QuickReplyPhoneNumber
.. autoclass:: QuickReplyEmail
.. autoclass:: Poll
.. autoclass:: PollOption
.. autoclass:: Plan
.. autoclass:: GuestStatus(Enum)
:undoc-members: :undoc-members:

236
docs/conf.py
View File

@@ -1,21 +1,12 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# #
# fbchat documentation build configuration file, created by # Configuration file for the Sphinx documentation builder.
# sphinx-quickstart on Thu May 25 15:43:01 2017.
# #
# This file is execfile()d with the current directory set to its # This file does only contain a selection of the most common options. For a
# containing dir. # full list see the documentation:
# # http://www.sphinx-doc.org/en/master/config
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory, # -- Path setup --------------------------------------------------------------
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import os import os
import sys import sys
@@ -23,15 +14,24 @@ import sys
sys.path.insert(0, os.path.abspath("..")) sys.path.insert(0, os.path.abspath(".."))
import fbchat import fbchat
import tests
from fbchat import __copyright__, __author__, __version__, __description__ # -- Project information -----------------------------------------------------
project = fbchat.__name__
copyright = fbchat.__copyright__
author = fbchat.__author__
# The short X.Y version
version = fbchat.__version__
# The full version, including alpha/beta/rc tags
release = fbchat.__version__
# -- General configuration ------------------------------------------------ # -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here. # If your documentation needs a minimal Sphinx version, state it here.
# #
# needs_sphinx = '1.0' needs_sphinx = "2.0"
# Add any Sphinx extension module names here, as strings. They can be # Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -46,122 +46,45 @@ extensions = [
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"] templates_path = ["_templates"]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = ".rst"
# The master toctree document. # The master toctree document.
master_doc = "index" master_doc = "index"
# General information about the project.
project = "fbchat"
title = "fbchat Documentation"
copyright = __copyright__
author = __author__
description = __description__
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = __version__
# The full version, including alpha/beta/rc tags.
release = __version__
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path # This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
# The name of the Pygments (syntax highlighting) style to use. rst_prolog = ".. currentmodule:: " + project
pygments_style = "sphinx"
# If true, `todo` and `todoList` produce output, else they produce nothing. # The reST default role (used for this markup: `text`) to use for all
todo_include_todos = True # documents.
#
default_role = "any"
# Make the reference parsing more strict
#
nitpicky = True
# Prefer strict Python highlighting
#
highlight_language = "python3"
# If true, '()' will be appended to :func: etc. cross-reference text.
#
add_function_parentheses = False
# -- Options for HTML output ---------------------------------------------- # -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # a list of builtin themes.
# #
html_theme = "alabaster" html_theme = "alabaster"
# Theme options are theme-specific and customize the look and feel of a theme # Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the # further. For a list of options available for each theme, see the
# documentation. # documentation.
# #
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = project + "doc"
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [(master_doc, project + ".tex", title, author, "manual")]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [(master_doc, project, title, [author], 1)]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, project, title, author, project, description, "Miscellaneous")
]
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {"https://docs.python.org/3/": None}
add_function_parentheses = False
html_theme_options = { html_theme_options = {
"show_powered_by": False, "show_powered_by": False,
"github_user": "carpedm20", "github_user": "carpedm20",
@@ -170,9 +93,92 @@ html_theme_options = {
"show_related": False, "show_related": False,
} }
html_extra_path = ["robots.txt"]
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
html_sidebars = {"**": ["sidebar.html", "searchbox.html"]} html_sidebars = {"**": ["sidebar.html", "searchbox.html"]}
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
html_show_sphinx = False html_show_sphinx = False
# If true, links to the reST sources are added to the pages.
#
html_show_sourcelink = False html_show_sourcelink = False
# A shorter title for the navigation bar. Default is the same as html_title.
#
html_short_title = fbchat.__description__
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = project + "doc"
# -- Options for LaTeX output ------------------------------------------------
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [(master_doc, project + ".tex", fbchat.__title__, author, "manual")]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, project, fbchat.__title__, [x.strip() for x in author.split(";")], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(
master_doc,
project,
fbchat.__title__,
author,
project,
fbchat.__description__,
"Miscellaneous",
)
]
# -- Options for Epub output -------------------------------------------------
# A list of files that should not be packed into the epub file.
epub_exclude_files = ["search.html"]
# -- Extension configuration -------------------------------------------------
# -- Options for autodoc extension ---------------------------------------
autoclass_content = "both" autoclass_content = "both"
html_short_title = description autodoc_member_order = "bysource"
autodoc_default_options = {"members": True}
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {"https://docs.python.org/": None}
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True

9
docs/examples.rst
View File

@@ -1,16 +1,15 @@
.. highlight:: python
.. _examples: .. _examples:
Examples Examples
======== ========
These are a few examples on how to use `fbchat`. Remember to swap out `<email>` and `<password>` for your email and password These are a few examples on how to use ``fbchat``. Remember to swap out ``<email>`` and ``<password>`` for your email and password
Basic example Basic example
------------- -------------
This will show basic usage of `fbchat` This will show basic usage of ``fbchat``
.. literalinclude:: ../examples/basic_usage.py .. literalinclude:: ../examples/basic_usage.py
@@ -18,7 +17,7 @@ This will show basic usage of `fbchat`
Interacting with Threads Interacting with Threads
------------------------ ------------------------
This will interact with the thread in every way `fbchat` supports This will interact with the thread in every way ``fbchat`` supports
.. literalinclude:: ../examples/interract.py .. literalinclude:: ../examples/interract.py
@@ -42,7 +41,7 @@ This will reply to any message with the same message
Remove Bot Remove Bot
---------- ----------
This will remove a user from a group if they write the message `Remove me!` This will remove a user from a group if they write the message ``Remove me!``
.. literalinclude:: ../examples/removebot.py .. literalinclude:: ../examples/removebot.py

4
docs/faq.rst
View File

@@ -1,5 +1,3 @@
.. highlight:: python
.. module:: fbchat
.. _faq: .. _faq:
FAQ FAQ
@@ -23,7 +21,7 @@ Where you replace ``<X>`` with the version you want to use
Will you be supporting creating posts/events/pages and so on? Will you be supporting creating posts/events/pages and so on?
------------------------------------------------------------- -------------------------------------------------------------
We won't be focusing on anything else than chat-related things. This API is called `fbCHAT`, after all ;) We won't be focusing on anything else than chat-related things. This API is called ``fbCHAT``, after all ;)
Submitting Issues Submitting Issues

8
docs/index.rst
View File

@@ -1,5 +1,3 @@
.. highlight:: python
.. module:: fbchat
.. fbchat documentation master file, created by .. fbchat documentation master file, created by
sphinx-quickstart on Thu May 25 15:43:01 2017. sphinx-quickstart on Thu May 25 15:43:01 2017.
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
@@ -30,9 +28,9 @@ This project was inspired by `facebook-chat-api <https://github.com/Schmavery/fa
**No XMPP or API key is needed**. Just use your email and password. **No XMPP or API key is needed**. Just use your email and password.
Currently `fbchat` support Python 2.7, 3.4, 3.5 and 3.6: Currently ``fbchat`` support Python 2.7, 3.4, 3.5 and 3.6:
`fbchat` works by emulating the browser. ``fbchat`` works by emulating the browser.
This means doing the exact same GET/POST requests and tricking Facebook into thinking it's accessing the website normally. This means doing the exact same GET/POST requests and tricking Facebook into thinking it's accessing the website normally.
Therefore, this API requires the credentials of a Facebook account. Therefore, this API requires the credentials of a Facebook account.
@@ -48,7 +46,7 @@ Therefore, this API requires the credentials of a Facebook account.
Facebook now has an `official API <https://developers.facebook.com/docs/messenger-platform>`_ for chat bots, Facebook now has an `official API <https://developers.facebook.com/docs/messenger-platform>`_ for chat bots,
so if you're familiar with node.js, this might be what you're looking for. so if you're familiar with node.js, this might be what you're looking for.
If you're already familiar with the basics of how Facebook works internally, go to :ref:`examples` to see example usage of `fbchat` If you're already familiar with the basics of how Facebook works internally, go to :ref:`examples` to see example usage of ``fbchat``
Overview Overview

19
docs/install.rst
View File

@@ -1,4 +1,3 @@
.. highlight:: sh
.. _install: .. _install:
Installation Installation
@@ -7,7 +6,9 @@ Installation
Pip Install fbchat Pip Install fbchat
------------------ ------------------
To install fbchat, run this command:: To install fbchat, run this command:
.. code-block:: sh
$ pip install fbchat $ pip install fbchat
@@ -21,16 +22,22 @@ Get the Source Code
fbchat is developed on GitHub, where the code is fbchat is developed on GitHub, where the code is
`always available <https://github.com/carpedm20/fbchat>`_. `always available <https://github.com/carpedm20/fbchat>`_.
You can either clone the public repository:: You can either clone the public repository:
.. code-block:: sh
$ git clone git://github.com/carpedm20/fbchat.git $ git clone git://github.com/carpedm20/fbchat.git
Or, download a `tarball <https://github.com/carpedm20/fbchat/tarball/master>`_:: Or, download a `tarball <https://github.com/carpedm20/fbchat/tarball/master>`_:
.. code-block:: sh
$ curl -OL https://github.com/carpedm20/fbchat/tarball/master $ curl -OL https://github.com/carpedm20/fbchat/tarball/master
# optionally, zipball is also available (for Windows users). # optionally, zipball is also available (for Windows users).
Once you have a copy of the source, you can embed it in your own Python Once you have a copy of the source, you can embed it in your own Python
package, or install it into your site-packages easily:: package, or install it into your site-packages easily:
.. code-block:: sh
$ python setup.py install $ python setup.py install

30
docs/intro.rst
View File

@@ -1,11 +1,9 @@
.. highlight:: python
.. module:: fbchat
.. _intro: .. _intro:
Introduction Introduction
============ ============
`fbchat` uses your email and password to communicate with the Facebook server. ``fbchat`` uses your email and password to communicate with the Facebook server.
That means that you should always store your password in a separate file, in case e.g. someone looks over your shoulder while you're writing code. That means that you should always store your password in a separate file, in case e.g. someone looks over your shoulder while you're writing code.
You should also make sure that the file's access control is appropriately restrictive You should also make sure that the file's access control is appropriately restrictive
@@ -28,7 +26,7 @@ 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 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 neccesary here, later code snippets will assume you've done this Though the second line, ``from fbchat.models import *``, is not strictly neccesary 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 :class:`Client`)
Throughout your code, if you want to check whether you are still logged in, use :func:`Client.isLoggedIn`. Throughout your code, if you want to check whether you are still logged in, use :func:`Client.isLoggedIn`.
An example would be to login again if you've been logged out, using :func:`Client.login`:: An example would be to login again if you've been logged out, using :func:`Client.login`::
@@ -48,9 +46,9 @@ Threads
A thread can refer to two things: A Messenger group chat or a single Facebook user A thread can refer to two things: A Messenger group chat or a single Facebook user
:class:`models.ThreadType` is an enumerator with two values: ``USER`` and ``GROUP``. :class:`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. 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 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.searchForGroups`, Searching for group chats and finding their ID can be done via. :func:`Client.searchForGroups`,
and searching for users is possible via. :func:`Client.searchForUsers`. See :ref:`intro_fetching` and searching for users is possible via. :func:`Client.searchForUsers`. See :ref:`intro_fetching`
@@ -87,7 +85,7 @@ Message IDs
Every message you send on Facebook has a unique ID, and every action you do in a thread, 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. 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.reactToMessage`, Some of ``fbchat``'s functions require these ID's, like :func:`Client.reactToMessage`,
and some of then provide this ID, like :func:`Client.sendMessage`. and some of then provide this ID, like :func:`Client.sendMessage`.
This snippet shows how to send a message, and then use the returned ID to react to that message with a 😍 emoji:: This snippet shows how to send a message, and then use the returned ID to react to that message with a 😍 emoji::
@@ -100,17 +98,17 @@ This snippet shows how to send a message, and then use the returned ID to react
Interacting with Threads Interacting with Threads
------------------------ ------------------------
`fbchat` provides multiple functions for interacting with threads ``fbchat`` provides multiple functions for interacting with threads
Most functionality works on all threads, though some things, Most functionality works on all threads, though some things,
like adding users to and removing users from a group chat, logically only works on group chats like adding users to and removing users from a group chat, logically only works on group chats
The simplest way of using `fbchat` is to send a message. The simplest way of using ``fbchat`` is to send a message.
The following snippet will, as you've probably already figured out, send the message `test message` to your account:: The following snippet will, as you've probably already figured out, send the message ``test message`` to your account::
message_id = client.send(Message(text='test message'), thread_id=client.uid, thread_type=ThreadType.USER) message_id = client.send(Message(text='test message'), thread_id=client.uid, thread_type=ThreadType.USER)
You can see a full example showing all the possible thread interactions with `fbchat` by going to :ref:`examples` You can see a full example showing all the possible thread interactions with ``fbchat`` by going to :ref:`examples`
.. _intro_fetching: .. _intro_fetching:
@@ -118,7 +116,7 @@ You can see a full example showing all the possible thread interactions with `fb
Fetching Information Fetching Information
-------------------- --------------------
You can use `fbchat` to fetch basic information like user names, profile pictures, thread names and user IDs 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.searchForUsers`. You can retrieve a user's ID with :func:`Client.searchForUsers`.
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:: 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::
@@ -132,7 +130,7 @@ The following snippet will search for users by their name, take the first (and m
Since this uses Facebook's search functions, you don't have to specify the whole name, first names will usually be enough Since this uses Facebook's search functions, you don't have to specify the whole name, first names will usually be enough
You can see a full example showing all the possible ways to fetch information with `fbchat` by going to :ref:`examples` You can see a full example showing all the possible ways to fetch information with ``fbchat`` by going to :ref:`examples`
.. _intro_sessions: .. _intro_sessions:
@@ -140,7 +138,7 @@ You can see a full example showing all the possible ways to fetch information wi
Sessions Sessions
-------- --------
`fbchat` provides functions to retrieve and set the session cookies. ``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. 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.getSession` to retrieve the cookies:: Use :func:`Client.getSession` to retrieve the cookies::
@@ -164,13 +162,13 @@ Or you can set the ``session_cookies`` on your initial login.
Listening & Events Listening & Events
------------------ ------------------
To use the listening functions `fbchat` offers (like :func:`Client.listen`), To use the listening functions ``fbchat`` offers (like :func:`Client.listen`),
you have to define what should be executed when certain events happen. you have to define what should be executed when certain events happen.
By default, (most) events will just be a `logging.info` statement, By default, (most) events will just be a `logging.info` statement,
meaning it will simply print information to the console when an event happens meaning it will simply print information to the console when an event happens
.. note:: .. note::
You can identify the event methods by their `on` prefix, e.g. `onMessage` You can identify the event methods by their ``on`` prefix, e.g. `onMessage`
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 :class:`Client`, and then overwriting the event methods::

11
docs/make.bat
View File

@@ -5,21 +5,20 @@ pushd %~dp0
REM Command file for Sphinx documentation REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" ( if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=python -msphinx set SPHINXBUILD=sphinx-build
) )
set SOURCEDIR=. set SOURCEDIR=.
set BUILDDIR=_build set BUILDDIR=_build
set SPHINXPROJ=fbchat
if "%1" == "" goto help if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL %SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 ( if errorlevel 9009 (
echo. echo.
echo.The Sphinx module was not found. Make sure you have Sphinx installed, echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.then set the SPHINXBUILD environment variable to point to the full echo.installed, then set the SPHINXBUILD environment variable to point
echo.path of the 'sphinx-build' executable. Alternatively you may add the echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.Sphinx directory to PATH. echo.may add the Sphinx directory to PATH.
echo. echo.
echo.If you don't have Sphinx installed, grab it from echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/ echo.http://sphinx-doc.org/

2
docs/robots.txt Normal file
View File

@@ -0,0 +1,2 @@
User-agent: *
Disallow: /en/master/

10
docs/testing.rst
View File

@@ -1,5 +1,3 @@
.. highlight:: sh
.. module:: fbchat
.. _testing: .. _testing:
Testing Testing
@@ -15,7 +13,9 @@ To use the tests, copy ``tests/data.json`` to ``tests/my_data.json`` or type the
Please remember to test all supported python versions. Please remember to test all supported python versions.
If you've made any changes to the 2FA functionality, test it with a 2FA enabled account. If you've made any changes to the 2FA functionality, test it with a 2FA enabled account.
If you only want to execute specific tests, pass the function names in the command line (not including the `test_` prefix). Example:: If you only want to execute specific tests, pass the function names in the command line (not including the ``test_`` prefix). Example:
.. code-block:: sh
$ python tests.py sendMessage sessions sendEmoji $ python tests.py sendMessage sessions sendEmoji
@@ -23,7 +23,3 @@ If you only want to execute specific tests, pass the function names in the comma
Do not execute the full set of tests in too quick succession. This can get your account temporarily blocked for spam! Do not execute the full set of tests in too quick succession. This can get your account temporarily blocked for spam!
(You should execute the script at max about 10 times a day) (You should execute the script at max about 10 times a day)
.. automodule:: tests
:members: TestFbchat
:undoc-members: TestFbchat

2
docs/todo.rst
View File

@@ -1,5 +1,3 @@
.. highlight:: python
.. module:: fbchat
.. _todo: .. _todo:
Todo Todo

2
fbchat/_attachment.py
View File

@@ -36,7 +36,7 @@ class ShareAttachment(Attachment):
source = attr.ib(None) source = attr.ib(None)
#: URL of the attachment image #: URL of the attachment image
image_url = attr.ib(None) image_url = attr.ib(None)
#: URL of the original image if Facebook uses `safe_image` #: URL of the original image if Facebook uses ``safe_image``
original_image_url = attr.ib(None) original_image_url = attr.ib(None)
#: Width of the image #: Width of the image
image_width = attr.ib(None) image_width = attr.ib(None)

232
fbchat/_client.py
View File

@@ -31,7 +31,9 @@ ACONTEXT = {
class Client(object): class Client(object):
"""A client for the Facebook Chat (Messenger). """A client for the Facebook Chat (Messenger).
See https://fbchat.readthedocs.io for complete documentation of the API. 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).
""" """
listening = False listening = False
@@ -51,7 +53,7 @@ class Client(object):
def uid(self): def uid(self):
"""The ID of the client. """The ID of the client.
Can be used as `thread_id`. See :ref:`intro_threads` for more info. Can be used as ``thread_id``. See :ref:`intro_threads` for more info.
""" """
return self._uid return self._uid
@@ -64,14 +66,14 @@ class Client(object):
session_cookies=None, session_cookies=None,
logging_level=logging.INFO, logging_level=logging.INFO,
): ):
"""Initializes and logs in the client """Initialize and log in the client.
:param email: Facebook `email`, `id` or `phone number` :param email: Facebook ``email``, ``id`` or ``phone number``
:param password: Facebook account password :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 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 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 session_cookies: Cookies from a previous session (Will default to login if these are invalid)
:param logging_level: Configures the `logging level <https://docs.python.org/3/library/logging.html#logging-levels>`_. Defaults to `INFO` :param logging_level: Configures the `logging level <https://docs.python.org/3/library/logging.html#logging-levels>`_. Defaults to ``logging.INFO``
:type max_tries: int :type max_tries: int
:type session_cookies: dict :type session_cookies: dict
:type logging_level: int :type logging_level: int
@@ -176,7 +178,7 @@ class Client(object):
def graphql_request(self, query): def graphql_request(self, query):
""" """
Shorthand for `graphql_requests(query)[0]` Shorthand for ``graphql_requests(query)[0]``
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -212,7 +214,7 @@ class Client(object):
:param session_cookies: A dictionay containing session cookies :param session_cookies: A dictionay containing session cookies
:type session_cookies: dict :type session_cookies: dict
:return: False if `session_cookies` does not contain proper cookies :return: False if ``session_cookies`` does not contain proper cookies
:rtype: bool :rtype: bool
""" """
try: try:
@@ -231,9 +233,9 @@ class Client(object):
def login(self, email, password, max_tries=5, user_agent=None): def login(self, email, password, max_tries=5, user_agent=None):
""" """
Uses `email` and `password` to login the user (If the user is already logged in, this will do a re-login) Uses ``email`` and ``password`` to login the user (If the user is already logged in, this will do a re-login)
:param email: Facebook `email` or `id` or `phone number` :param email: Facebook ``email`` or ``id`` or ``phone number``
:param password: Facebook account password :param password: Facebook account password
:param max_tries: Maximum number of times to try logging in :param max_tries: Maximum number of times to try logging in
:type max_tries: int :type max_tries: int
@@ -307,7 +309,7 @@ class Client(object):
:param thread_id: User/Group ID to default to. See :ref:`intro_threads` :param thread_id: User/Group ID to default to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
self._default_thread_id = thread_id self._default_thread_id = thread_id
self._default_thread_type = thread_type self._default_thread_type = thread_type
@@ -333,11 +335,11 @@ class Client(object):
Get all threads in thread_location. Get all threads in thread_location.
Threads will be sorted from newest to oldest. Threads will be sorted from newest to oldest.
:param thread_location: models.ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER :param thread_location: ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER
:param before: Fetch only thread before this epoch (in ms) (default all threads) :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 after: Fetch only thread after this epoch (in ms) (default all threads)
:param limit: The max. amount of threads to fetch (default all threads) :param limit: The max. amount of threads to fetch (default all threads)
:return: :class:`models.Thread` objects :return: :class:`Thread` objects
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -385,8 +387,8 @@ class Client(object):
""" """
Get all users involved in threads. Get all users involved in threads.
:param threads: models.Thread: List of threads to check for users :param threads: Thread: List of threads to check for users
:return: :class:`models.User` objects :return: :class:`User` objects
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -411,7 +413,7 @@ class Client(object):
""" """
Gets all users the client is currently chatting with Gets all users the client is currently chatting with
:return: :class:`models.User` objects :return: :class:`User` objects
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -433,7 +435,7 @@ class Client(object):
:param name: Name of the user :param name: Name of the user
:param limit: The max. amount of users to fetch :param limit: The max. amount of users to fetch
:return: :class:`models.User` objects, ordered by relevance :return: :class:`User` objects, ordered by relevance
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -447,7 +449,7 @@ class Client(object):
Find and get page by its name Find and get page by its name
:param name: Name of the page :param name: Name of the page
:return: :class:`models.Page` objects, ordered by relevance :return: :class:`Page` objects, ordered by relevance
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -462,7 +464,7 @@ class Client(object):
:param name: Name of the group thread :param name: Name of the group thread
:param limit: The max. amount of groups to fetch :param limit: The max. amount of groups to fetch
:return: :class:`models.Group` objects, ordered by relevance :return: :class:`Group` objects, ordered by relevance
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -477,7 +479,7 @@ class Client(object):
:param name: Name of the thread :param name: Name of the thread
:param limit: The max. amount of groups to fetch :param limit: The max. amount of groups to fetch
:return: :class:`models.User`, :class:`models.Group` and :class:`models.Page` objects, ordered by relevance :return: :class:`User`, :class:`Group` and :class:`Page` objects, ordered by relevance
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -514,7 +516,7 @@ class Client(object):
:type offset: int :type offset: int
:type limit: int :type limit: int
:return: Found Message IDs :return: Found Message IDs
:rtype: generator :rtype: typing.Iterable
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
thread_id, thread_type = self._getThread(thread_id, None) thread_id, thread_type = self._getThread(thread_id, None)
@@ -535,7 +537,7 @@ class Client(object):
def searchForMessages(self, query, offset=0, limit=5, thread_id=None): def searchForMessages(self, query, offset=0, limit=5, thread_id=None):
""" """
Find and get :class:`models.Message` objects by query Find and get :class:`Message` objects by query
.. warning:: .. warning::
This method sends request for every found message ID. This method sends request for every found message ID.
@@ -546,8 +548,8 @@ class Client(object):
:param thread_id: User/Group ID to search in. See :ref:`intro_threads` :param thread_id: User/Group ID to search in. See :ref:`intro_threads`
:type offset: int :type offset: int
:type limit: int :type limit: int
:return: Found :class:`models.Message` objects :return: Found :class:`Message` objects
:rtype: generator :rtype: typing.Iterable
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
message_ids = self.searchForMessageIDs( message_ids = self.searchForMessageIDs(
@@ -561,13 +563,13 @@ class Client(object):
Searches for messages in all threads Searches for messages in all threads
:param query: Text to search for :param query: Text to search for
:param fetch_messages: Whether to fetch :class:`models.Message` objects or IDs only :param fetch_messages: Whether to fetch :class:`Message` objects or IDs only
:param thread_limit: Max. number of threads to retrieve :param thread_limit: Max. number of threads to retrieve
:param message_limit: Max. number of messages to retrieve :param message_limit: Max. number of messages to retrieve
:type thread_limit: int :type thread_limit: int
:type message_limit: int :type message_limit: int
:return: Dictionary with thread IDs as keys and generators to get messages as values :return: Dictionary with thread IDs as keys and iterables to get messages as values
:rtype: generator :rtype: typing.Dict[str, typing.Iterable]
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
data = {"query": query, "snippetLimit": thread_limit} data = {"query": query, "snippetLimit": thread_limit}
@@ -632,7 +634,7 @@ class Client(object):
Sends two requests, to fetch all available info! Sends two requests, to fetch all available info!
:param user_ids: One or more user ID(s) to query :param user_ids: One or more user ID(s) to query
:return: :class:`models.User` objects, labeled by their ID :return: :class:`User` objects, labeled by their ID
:rtype: dict :rtype: dict
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -654,7 +656,7 @@ class Client(object):
Sends two requests, to fetch all available info! Sends two requests, to fetch all available info!
:param page_ids: One or more page ID(s) to query :param page_ids: One or more page ID(s) to query
:return: :class:`models.Page` objects, labeled by their ID :return: :class:`Page` objects, labeled by their ID
:rtype: dict :rtype: dict
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -673,7 +675,7 @@ class Client(object):
Get groups' info from IDs, unordered Get groups' info from IDs, unordered
:param group_ids: One or more group ID(s) to query :param group_ids: One or more group ID(s) to query
:return: :class:`models.Group` objects, labeled by their ID :return: :class:`Group` objects, labeled by their ID
:rtype: dict :rtype: dict
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -695,7 +697,7 @@ class Client(object):
Sends two requests if users or pages are present, to fetch all available info! 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 :param thread_ids: One or more thread ID(s) to query
:return: :class:`models.Thread` objects, labeled by their ID :return: :class:`Thread` objects, labeled by their ID
:rtype: dict :rtype: dict
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -760,7 +762,7 @@ class Client(object):
:param before: A timestamp, indicating from which point to retrieve messages :param before: A timestamp, indicating from which point to retrieve messages
:type limit: int :type limit: int
:type before: int :type before: int
:return: :class:`models.Message` objects :return: :class:`Message` objects
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -800,11 +802,11 @@ class Client(object):
:param offset: Deprecated. Do not use! :param offset: Deprecated. Do not use!
:param limit: Max. number of threads to retrieve. Capped at 20 :param limit: Max. number of threads to retrieve. Capped at 20
:param thread_location: models.ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER :param thread_location: ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER
:param before: A timestamp (in milliseconds), indicating from which point to retrieve threads :param before: A timestamp (in milliseconds), indicating from which point to retrieve threads
:type limit: int :type limit: int
:type before: int :type before: int
:return: :class:`models.Thread` objects :return: :class:`Thread` objects
:rtype: list :rtype: list
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -897,12 +899,12 @@ class Client(object):
def fetchMessageInfo(self, mid, thread_id=None): def fetchMessageInfo(self, mid, thread_id=None):
""" """
Fetches :class:`models.Message` object from the message id Fetches :class:`Message` object from the message id
:param mid: Message ID to fetch from :param mid: Message ID to fetch from
:param thread_id: User/Group ID to get message info from. See :ref:`intro_threads` :param thread_id: User/Group ID to get message info from. See :ref:`intro_threads`
:return: :class:`models.Message` object :return: :class:`Message` object
:rtype: models.Message :rtype: Message
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
thread_id, thread_type = self._getThread(thread_id, None) thread_id, thread_type = self._getThread(thread_id, None)
@@ -911,7 +913,7 @@ class Client(object):
def fetchPollOptions(self, poll_id): def fetchPollOptions(self, poll_id):
""" """
Fetches list of :class:`models.PollOption` objects from the poll id Fetches list of :class:`PollOption` objects from the poll id
:param poll_id: Poll ID to fetch from :param poll_id: Poll ID to fetch from
:rtype: list :rtype: list
@@ -923,11 +925,11 @@ class Client(object):
def fetchPlanInfo(self, plan_id): def fetchPlanInfo(self, plan_id):
""" """
Fetches a :class:`models.Plan` object from the plan id Fetches a :class:`Plan` object from the plan id
:param plan_id: Plan ID to fetch from :param plan_id: Plan ID to fetch from
:return: :class:`models.Plan` object :return: :class:`Plan` object
:rtype: models.Plan :rtype: Plan
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
data = {"event_reminder_id": plan_id} data = {"event_reminder_id": plan_id}
@@ -962,15 +964,15 @@ class Client(object):
def getUserActiveStatus(self, user_id): def getUserActiveStatus(self, user_id):
""" """
Gets friend active status as an :class:`models.ActiveStatus` object. Gets friend active status as an :class:`ActiveStatus` object.
Returns `None` if status isn't known. Returns ``None`` if status isn't known.
.. warning:: .. warning::
Only works when listening. Only works when listening.
:param user_id: ID of the user :param user_id: ID of the user
:return: Given user active status :return: Given user active status
:rtype: models.ActiveStatus :rtype: ActiveStatus
""" """
return self._buddylist.get(str(user_id)) return self._buddylist.get(str(user_id))
@@ -1088,8 +1090,8 @@ class Client(object):
:param message: Message to send :param message: Message to send
:param thread_id: User/Group ID to send to. See :ref:`intro_threads` :param thread_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type message: models.Message :type message: Message
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent message :return: :ref:`Message ID <intro_message_ids>` of the sent message
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1130,7 +1132,7 @@ class Client(object):
:param wave_first: Whether to wave first or wave back :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_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent message :return: :ref:`Message ID <intro_message_ids>` of the sent message
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1153,8 +1155,8 @@ class Client(object):
:param payload: Optional answer to the quick reply :param payload: Optional answer to the quick reply
:param thread_id: User/Group ID to send to. See :ref:`intro_threads` :param thread_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type quick_reply: models.QuickReply :type quick_reply: QuickReply
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent message :return: :ref:`Message ID <intro_message_ids>` of the sent message
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1166,7 +1168,7 @@ class Client(object):
elif isinstance(quick_reply, QuickReplyLocation): elif isinstance(quick_reply, QuickReplyLocation):
if not isinstance(payload, LocationAttachment): if not isinstance(payload, LocationAttachment):
raise ValueError( raise ValueError(
"Payload must be an instance of `fbchat.models.LocationAttachment`" "Payload must be an instance of `fbchat.LocationAttachment`"
) )
return self.sendLocation( return self.sendLocation(
payload, thread_id=thread_id, thread_type=thread_type payload, thread_id=thread_id, thread_type=thread_type
@@ -1214,9 +1216,9 @@ class Client(object):
:param message: Additional message :param message: Additional message
:param thread_id: User/Group ID to send to. See :ref:`intro_threads` :param thread_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type location: models.LocationAttachment :type location: LocationAttachment
:type message: models.Message :type message: Message
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent message :return: :ref:`Message ID <intro_message_ids>` of the sent message
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1238,9 +1240,9 @@ class Client(object):
:param message: Additional message :param message: Additional message
:param thread_id: User/Group ID to send to. See :ref:`intro_threads` :param thread_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type location: models.LocationAttachment :type location: LocationAttachment
:type message: models.Message :type message: Message
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent message :return: :ref:`Message ID <intro_message_ids>` of the sent message
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1312,7 +1314,7 @@ class Client(object):
:param message: Additional message :param message: Additional message
:param thread_id: User/Group ID to send to. See :ref:`intro_threads` :param thread_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent files :return: :ref:`Message ID <intro_message_ids>` of the sent files
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1332,7 +1334,7 @@ class Client(object):
:param message: Additional message :param message: Additional message
:param thread_id: User/Group ID to send to. See :ref:`intro_threads` :param thread_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent files :return: :ref:`Message ID <intro_message_ids>` of the sent files
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1353,7 +1355,7 @@ class Client(object):
:param message: Additional message :param message: Additional message
:param thread_id: User/Group ID to send to. See :ref:`intro_threads` :param thread_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent files :return: :ref:`Message ID <intro_message_ids>` of the sent files
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1373,7 +1375,7 @@ class Client(object):
:param message: Additional message :param message: Additional message
:param thread_id: User/Group ID to send to. See :ref:`intro_threads` :param thread_id: User/Group ID to send to. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
:return: :ref:`Message ID <intro_message_ids>` of the sent files :return: :ref:`Message ID <intro_message_ids>` of the sent files
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
@@ -1392,9 +1394,7 @@ class Client(object):
thread_type=ThreadType.USER, thread_type=ThreadType.USER,
is_gif=False, is_gif=False,
): ):
""" """Deprecated."""
Deprecated. Use :func:`fbchat.Client._sendFiles` instead
"""
if is_gif: if is_gif:
mimetype = "image/gif" mimetype = "image/gif"
else: else:
@@ -1647,7 +1647,7 @@ class Client(object):
:param title: New group thread title :param title: New group thread title
:param thread_id: Group ID to change title of. See :ref:`intro_threads` :param thread_id: Group ID to change title of. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
thread_id, thread_type = self._getThread(thread_id, thread_type) thread_id, thread_type = self._getThread(thread_id, thread_type)
@@ -1671,7 +1671,7 @@ class Client(object):
:param user_id: User that will have their nickname changed :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_id: User/Group ID to change color of. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
thread_id, thread_type = self._getThread(thread_id, thread_type) thread_id, thread_type = self._getThread(thread_id, thread_type)
@@ -1691,7 +1691,7 @@ class Client(object):
:param color: New thread color :param color: New thread color
:param thread_id: User/Group ID to change color of. See :ref:`intro_threads` :param thread_id: User/Group ID to change color of. See :ref:`intro_threads`
:type color: models.ThreadColor :type color: ThreadColor
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
thread_id, thread_type = self._getThread(thread_id, None) thread_id, thread_type = self._getThread(thread_id, None)
@@ -1727,7 +1727,7 @@ class Client(object):
:param message_id: :ref:`Message ID <intro_message_ids>` to react to :param message_id: :ref:`Message ID <intro_message_ids>` to react to
:param reaction: Reaction emoji to use, if None removes reaction :param reaction: Reaction emoji to use, if None removes reaction
:type reaction: models.MessageReaction or None :type reaction: MessageReaction or None
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
data = { data = {
@@ -1747,7 +1747,7 @@ class Client(object):
:param plan: Plan to set :param plan: Plan to set
:param thread_id: User/Group ID to send plan to. See :ref:`intro_threads` :param thread_id: User/Group ID to send plan to. See :ref:`intro_threads`
:type plan: models.Plan :type plan: Plan
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
thread_id, thread_type = self._getThread(thread_id, None) thread_id, thread_type = self._getThread(thread_id, None)
@@ -1774,7 +1774,7 @@ class Client(object):
:param plan: Plan to edit :param plan: Plan to edit
:param new_plan: New plan :param new_plan: New plan
:type plan: models.Plan :type plan: Plan
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
data = { data = {
@@ -1826,7 +1826,7 @@ class Client(object):
:param poll: Poll to create :param poll: Poll to create
:param thread_id: User/Group ID to create poll in. See :ref:`intro_threads` :param thread_id: User/Group ID to create poll in. See :ref:`intro_threads`
:type poll: models.Poll :type poll: Poll
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
thread_id, thread_type = self._getThread(thread_id, None) thread_id, thread_type = self._getThread(thread_id, None)
@@ -1857,7 +1857,7 @@ class Client(object):
:param new_options: List of the new option names :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_id: User/Group ID to change status in. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type thread_type: models.ThreadType :type thread_type: ThreadType
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
data = {"question_id": poll_id} data = {"question_id": poll_id}
@@ -1882,8 +1882,8 @@ class Client(object):
:param status: Specify the typing status :param status: Specify the typing status
:param thread_id: User/Group ID to change status in. See :ref:`intro_threads` :param thread_id: User/Group ID to change status in. See :ref:`intro_threads`
:param thread_type: See :ref:`intro_threads` :param thread_type: See :ref:`intro_threads`
:type status: models.TypingStatus :type status: TypingStatus
:type thread_type: models.ThreadType :type thread_type: ThreadType
:raises: FBchatException if request failed :raises: FBchatException if request failed
""" """
thread_id, thread_type = self._getThread(thread_id, thread_type) thread_id, thread_type = self._getThread(thread_id, thread_type)
@@ -2003,7 +2003,7 @@ class Client(object):
""" """
Moves threads to specifed location Moves threads to specifed location
:param location: models.ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER :param location: ThreadLocation: INBOX, PENDING, ARCHIVED or OTHER
:param thread_ids: Thread IDs to move. See :ref:`intro_threads` :param thread_ids: Thread IDs to move. See :ref:`intro_threads`
:return: True :return: True
:raises: FBchatException if request failed :raises: FBchatException if request failed
@@ -2843,8 +2843,8 @@ class Client(object):
This method is useful if you want to control fbchat from an external event loop This method is useful if you want to control fbchat from an external event loop
.. warning:: .. warning::
`markAlive` parameter is deprecated now, use :func:`fbchat.Client.setActiveStatus` ``markAlive`` parameter is deprecated, use :func:`Client.setActiveStatus`
or `markAlive` parameter in :func:`fbchat.Client.listen` instead. or ``markAlive`` parameter in :func:`Client.listen` instead.
:return: Whether the loop should keep running :return: Whether the loop should keep running
:rtype: bool :rtype: bool
@@ -2968,15 +2968,15 @@ class Client(object):
:param mid: The message ID :param mid: The message ID
:param author_id: The ID of the author :param author_id: The ID of the author
:param message: (deprecated. Use `message_object.text` instead) :param message: (deprecated. Use ``message_object.text`` instead)
:param message_object: The message (As a `Message` object) :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_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 thread_type: Type of thread that the message was sent to. See :ref:`intro_threads`
:param ts: The timestamp of the message :param ts: The timestamp of the message
:param metadata: Extra metadata about the message :param metadata: Extra metadata about the message
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type message_object: models.Message :type message_object: Message
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info("{} from {} in {}".format(message_object, thread_id, thread_type.name)) log.info("{} from {} in {}".format(message_object, thread_id, thread_type.name))
@@ -3002,8 +3002,8 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type new_color: models.ThreadColor :type new_color: ThreadColor
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"Color change from {} in {} ({}): {}".format( "Color change from {} in {} ({}): {}".format(
@@ -3033,7 +3033,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"Emoji change from {} in {} ({}): {}".format( "Emoji change from {} in {} ({}): {}".format(
@@ -3063,7 +3063,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"Title change from {} in {} ({}): {}".format( "Title change from {} in {} ({}): {}".format(
@@ -3091,7 +3091,7 @@ class Client(object):
:param thread_type: Type of thread 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 ts: A timestamp of the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info("{} changed thread image in {}".format(author_id, thread_id)) log.info("{} changed thread image in {}".format(author_id, thread_id))
@@ -3119,7 +3119,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"Nickname change from {} in {} ({}) for {}: {}".format( "Nickname change from {} in {} ({}) for {}: {}".format(
@@ -3216,7 +3216,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"Messages seen by {} in {} ({}) at {}s".format( "Messages seen by {} in {} ({}) at {}s".format(
@@ -3244,7 +3244,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"Messages {} delivered to {} in {} ({}) at {}s".format( "Messages {} delivered to {} in {} ({}) at {}s".format(
@@ -3264,7 +3264,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"Marked messages as seen in threads {} at {}s".format( "Marked messages as seen in threads {} at {}s".format(
@@ -3290,7 +3290,7 @@ class Client(object):
:param thread_type: Type of thread 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 ts: A timestamp of the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} unsent the message {} in {} ({}) at {}s".format( "{} unsent the message {} in {} ({}) at {}s".format(
@@ -3374,8 +3374,8 @@ class Client(object):
:param thread_id: Thread ID that the action was sent to. See :ref:`intro_threads` :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 thread_type: Type of thread that the action was sent to. See :ref:`intro_threads`
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type typing_status: models.TypingStatus :type typing_status: TypingStatus
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
pass pass
@@ -3407,7 +3407,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
'{} played "{}" in {} ({})'.format( '{} played "{}" in {} ({})'.format(
@@ -3436,8 +3436,8 @@ class Client(object):
:param thread_type: Type of thread 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 ts: A timestamp of the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type reaction: models.MessageReaction :type reaction: MessageReaction
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} reacted to message {} with {} in {} ({})".format( "{} reacted to message {} with {} in {} ({})".format(
@@ -3463,7 +3463,7 @@ class Client(object):
:param thread_type: Type of thread 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 ts: A timestamp of the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} removed reaction from {} message in {} ({})".format( "{} removed reaction from {} message in {} ({})".format(
@@ -3482,7 +3482,7 @@ class Client(object):
:param thread_type: Type of thread 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 ts: A timestamp of the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} blocked {} ({}) thread".format(author_id, thread_id, thread_type.name) "{} blocked {} ({}) thread".format(author_id, thread_id, thread_type.name)
@@ -3499,7 +3499,7 @@ class Client(object):
:param thread_type: Type of thread 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 ts: A timestamp of the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} unblocked {} ({}) thread".format(author_id, thread_id, thread_type.name) "{} unblocked {} ({}) thread".format(author_id, thread_id, thread_type.name)
@@ -3525,8 +3525,8 @@ class Client(object):
:param thread_type: Type of thread 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 ts: A timestamp of the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type location: models.LiveLocationAttachment :type location: LiveLocationAttachment
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} sent live location info in {} ({}) with latitude {} and longitude {}".format( "{} sent live location info in {} ({}) with latitude {} and longitude {}".format(
@@ -3559,7 +3559,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} started call in {} ({})".format(caller_id, thread_id, thread_type.name) "{} started call in {} ({})".format(caller_id, thread_id, thread_type.name)
@@ -3592,7 +3592,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} ended call in {} ({})".format(caller_id, thread_id, thread_type.name) "{} ended call in {} ({})".format(caller_id, thread_id, thread_type.name)
@@ -3620,7 +3620,7 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} joined call in {} ({})".format(joined_id, thread_id, thread_type.name) "{} joined call in {} ({})".format(joined_id, thread_id, thread_type.name)
@@ -3648,8 +3648,8 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type poll: models.Poll :type poll: Poll
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} created poll {} in {} ({})".format( "{} created poll {} in {} ({})".format(
@@ -3681,8 +3681,8 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type poll: models.Poll :type poll: Poll
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} voted in poll {} in {} ({})".format( "{} voted in poll {} in {} ({})".format(
@@ -3712,8 +3712,8 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type plan: models.Plan :type plan: Plan
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} created plan {} in {} ({})".format( "{} created plan {} in {} ({})".format(
@@ -3741,8 +3741,8 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type plan: models.Plan :type plan: Plan
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"Plan {} has ended in {} ({})".format(plan, thread_id, thread_type.name) "Plan {} has ended in {} ({})".format(plan, thread_id, thread_type.name)
@@ -3770,8 +3770,8 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type plan: models.Plan :type plan: Plan
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} edited plan {} in {} ({})".format( "{} edited plan {} in {} ({})".format(
@@ -3801,8 +3801,8 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type plan: models.Plan :type plan: Plan
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
log.info( log.info(
"{} deleted plan {} in {} ({})".format( "{} deleted plan {} in {} ({})".format(
@@ -3834,9 +3834,9 @@ class Client(object):
:param ts: A timestamp of the action :param ts: A timestamp of the action
:param metadata: Extra metadata about the action :param metadata: Extra metadata about the action
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type plan: models.Plan :type plan: Plan
:type take_part: bool :type take_part: bool
:type thread_type: models.ThreadType :type thread_type: ThreadType
""" """
if take_part: if take_part:
log.info( log.info(
@@ -3873,7 +3873,7 @@ class Client(object):
""" """
Called when the client is listening and client receives information about friend active status Called when the client is listening and client receives information about friend active status
:param statuses: Dictionary with user IDs as keys and :class:`models.ActiveStatus` as values :param statuses: Dictionary with user IDs as keys and :class:`ActiveStatus` as values
:param msg: A full set of the data recieved :param msg: A full set of the data recieved
:type statuses: dict :type statuses: dict
""" """

2
fbchat/_message.py
View File

@@ -99,13 +99,11 @@ class Message(object):
Returns a `Message` object, with the formatted string and relevant mentions. Returns a `Message` object, with the formatted string and relevant mentions.
```
>>> Message.formatMentions("Hey {!r}! My name is {}", ("1234", "Peter"), ("4321", "Michael")) >>> Message.formatMentions("Hey {!r}! My name is {}", ("1234", "Peter"), ("4321", "Michael"))
<Message (None): "Hey 'Peter'! My name is Michael", mentions=[<Mention 1234: offset=4 length=7>, <Mention 4321: offset=24 length=7>] emoji_size=None attachments=[]> <Message (None): "Hey 'Peter'! My name is Michael", mentions=[<Mention 1234: offset=4 length=7>, <Mention 4321: offset=24 length=7>] emoji_size=None attachments=[]>
>>> Message.formatMentions("Hey {p}! My name is {}", ("1234", "Michael"), p=("4321", "Peter")) >>> Message.formatMentions("Hey {p}! My name is {}", ("1234", "Michael"), p=("4321", "Peter"))
<Message (None): 'Hey Peter! My name is Michael', mentions=[<Mention 4321: offset=4 length=5>, <Mention 1234: offset=22 length=7>] emoji_size=None attachments=[]> <Message (None): 'Hey Peter! My name is Michael', mentions=[<Mention 4321: offset=4 length=5>, <Mention 1234: offset=22 length=7>] emoji_size=None attachments=[]>
```
""" """
result = "" result = ""
mentions = list() mentions = list()

4
fbchat/_thread.py
View File

@@ -62,9 +62,9 @@ class ThreadColor(Enum):
class Thread(object): class Thread(object):
"""Represents a Facebook thread""" """Represents a Facebook thread"""
#: The unique identifier of the thread. Can be used a `thread_id`. See :ref:`intro_threads` for more info #: The unique identifier of the thread. Can be used a ``thread_id``. See :ref:`intro_threads` for more info
uid = attr.ib(converter=str) uid = attr.ib(converter=str)
#: Specifies the type of thread. Can be used a `thread_type`. See :ref:`intro_threads` for more info #: Specifies the type of thread. Can be used a ``thread_type``. See :ref:`intro_threads` for more info
type = attr.ib() type = attr.ib()
#: A url to the thread's picture #: A url to the thread's picture
photo = attr.ib(None) photo = attr.ib(None)

3
pyproject.toml
View File

@@ -54,6 +54,9 @@ test = [
"pytest~=4.0", "pytest~=4.0",
"six~=1.0", "six~=1.0",
] ]
docs = [
"sphinx~=2.0",
]
lint = [ lint = [
"black", "black",
] ]