Bump version: 1.7.3 → 1.8.0

Make Client._get and Client._post require a query input

.bumpversion.cfg

@@ -0,0 +1,7 @@
+[bumpversion]
+current_version = 1.8.0
+commit = True
+tag = True
+
+[bumpversion:file:fbchat/__init__.py]
+

.github/ISSUE_TEMPLATE/bug_report.md

@@ -21,8 +21,8 @@ Traceback (most recent call last):
   File "[site-packages]/fbchat/client.py", line 78, in __init__
     self.login(email, password, max_tries)
   File "[site-packages]/fbchat/client.py", line 407, in login
-    raise FBchatUserError('Login failed. Check email/password. (Failed on url: {})'.format(login_url))
+    raise FBchatUserError('Login failed. Check email/password. (Failed on URL: {})'.format(login_url))
-fbchat.models.FBchatUserError: Login failed. Check email/password. (Failed on url: https://m.facebook.com/login.php?login_attempt=1)
+fbchat.models.FBchatUserError: Login failed. Check email/password. (Failed on URL: https://m.facebook.com/login.php?login_attempt=1)
 ```
 
 ## Environment information

.gitignore

@@ -35,3 +35,4 @@ tests.data
 
 # Virtual environment
 venv/
+.venv*/

.readthedocs.yml

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

.travis.yml

@@ -30,7 +30,7 @@ jobs:
     script: black --check --verbose .
 
   - stage: deploy
-    name: Github Releases
+    name: GitHub Releases
     if: tag IS present
     install: skip
     script: flit build

CONTRIBUTING.rst

@@ -1,5 +1,5 @@
-Contributing to fbchat
+Contributing to ``fbchat``
-======================
+==========================
 
 Thanks for reading this, all contributions are very much welcome!
 

README.rst

@@ -1,5 +1,5 @@
-fbchat: Facebook Chat (Messenger) for Python
+``fbchat``: Facebook Chat (Messenger) for Python
-============================================
+================================================
 
 .. image:: https://img.shields.io/badge/license-BSD-blue.svg
     :target: https://github.com/carpedm20/fbchat/tree/master/LICENSE
@@ -9,7 +9,7 @@ fbchat: Facebook Chat (Messenger) for Python
     :target: https://pypi.python.org/pypi/fbchat
     :alt: Supported python versions: 2.7, 3.4, 3.5, 3.6, 3.7 and pypy
 
-.. image:: https://readthedocs.org/projects/fbchat/badge/?version=master
+.. image:: https://readthedocs.org/projects/fbchat/badge/?version=latest
     :target: https://fbchat.readthedocs.io
     :alt: Documentation
 
@@ -35,14 +35,12 @@ Installation:
 
     $ 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::
 
-    $ pip install flit
     $ git clone https://github.com/carpedm20/fbchat.git
-    $ cd fbchat
+    $ pip install fbchat
-    $ flit install
 
 
 Maintainer

docs/Makefile

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

docs/api.rst

@@ -1,33 +1,79 @@
 .. module:: fbchat
-.. highlight:: python
 .. _api:
 
+.. Note: we're using () to hide the __init__ method where relevant
+
 Full API
 ========
 
 If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
 
-
-.. _api_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:

docs/conf.py

@@ -1,21 +1,12 @@
-#!/usr/bin/env python3
 # -*- 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 sys
@@ -23,15 +14,24 @@ import sys
 sys.path.insert(0, os.path.abspath(".."))
 
 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.
 #
-# needs_sphinx = '1.0'
+needs_sphinx = "2.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -41,127 +41,52 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.spelling",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 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.
 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
 # 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"]
 
-# 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
 # a list of builtin themes.
 #
-
 html_theme = "alabaster"
 
 # 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
 # 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 = {
     "show_powered_by": False,
     "github_user": "carpedm20",
@@ -170,9 +95,114 @@ html_theme_options = {
     "show_related": False,
 }
 
+# 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"]}
 
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#
 html_show_sphinx = False
+
+# If true, links to the reST sources are added to the pages.
+#
 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"
-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
+
+todo_link_only = True
+
+# -- Options for napoleon extension ----------------------------------------------
+
+# Use Google style docstrings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+
+# napoleon_use_admonition_for_examples = False
+# napoleon_use_admonition_for_notes = False
+# napoleon_use_admonition_for_references = False
+
+# -- Options for spelling extension ----------------------------------------------
+
+spelling_word_list_filename = [
+    "spelling/names.txt",
+    "spelling/technical.txt",
+    "spelling/fixes.txt",
+]
+spelling_ignore_wiki_words = False
+# spelling_ignore_acronyms = False
+spelling_ignore_python_builtins = False
+spelling_ignore_importable_modules = False

docs/examples.rst

@@ -1,16 +1,15 @@
-.. highlight:: python
 .. _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
 -------------
 
-This will show basic usage of `fbchat`
+This will show basic usage of ``fbchat``
 
 .. literalinclude:: ../examples/basic_usage.py
 
@@ -18,7 +17,7 @@ This will show basic usage of `fbchat`
 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
 
@@ -31,8 +30,8 @@ This will show the different ways of fetching information about users and thread
 .. literalinclude:: ../examples/fetch.py
 
 
-Echobot
+``Echobot``
--------
+-----------
 
 This will reply to any message with the same message
 
@@ -42,7 +41,7 @@ This will reply to any message with the same message
 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
 

docs/faq.rst

@@ -1,5 +1,3 @@
-.. highlight:: python
-.. module:: fbchat
 .. _faq:
 
 FAQ
@@ -11,7 +9,7 @@ Version X broke my installation
 We try to provide backwards compatibility where possible, but since we're not part of Facebook,
 most of the things may be broken at any point in time
 
-Downgrade to an earlier version of fbchat, run this command
+Downgrade to an earlier version of ``fbchat``, run this command
 
 .. code-block:: sh
 
@@ -23,14 +21,14 @@ Where you replace ``<X>`` with the version you want to use
 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
 -----------------
 
 If you're having trouble with some of the snippets, or you think some of the functionality is broken,
-please feel free to submit an issue on `Github <https://github.com/carpedm20/fbchat>`_.
+please feel free to submit an issue on `GitHub <https://github.com/carpedm20/fbchat>`_.
 You should first login with ``logging_level`` set to ``logging.DEBUG``::
 
     from fbchat import Client

docs/index.rst

@@ -1,5 +1,3 @@
-.. highlight:: python
-.. module:: fbchat
 .. fbchat documentation master file, created by
    sphinx-quickstart on Thu May 25 15:43:01 2017.
    You can adapt this file completely to your liking, but it should at least
@@ -8,8 +6,8 @@
 .. This documentation's layout is heavily inspired by requests' layout: https://requests.readthedocs.io
    Some documentation is also partially copied from facebook-chat-api: https://github.com/Schmavery/facebook-chat-api
 
-fbchat: Facebook Chat (Messenger) for Python
+``fbchat``: Facebook Chat (Messenger) for Python
-============================================
+================================================
 
 Release v\ |version|. (:ref:`install`)
 
@@ -30,14 +28,14 @@ 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.
 
-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.
 Therefore, this API requires the credentials of a Facebook account.
 
 .. note::
-    If you're having problems, please check the :ref:`faq`, before asking questions on Github
+    If you're having problems, please check the :ref:`faq`, before asking questions on GitHub
 
 .. warning::
     We are not responsible if your account gets banned for spammy activities,
@@ -46,9 +44,9 @@ Therefore, this API requires the credentials of a Facebook account.
 
 .. note::
     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

docs/install.rst

@@ -1,13 +1,14 @@
-.. highlight:: sh
 .. _install:
 
 Installation
 ============
 
-Pip Install fbchat
+Install using pip
-------------------
+-----------------
 
-To install fbchat, run this command::
+To install ``fbchat``, run this command:
+
+.. code-block:: sh
 
     $ pip install fbchat
 
@@ -18,19 +19,25 @@ can guide you through the process.
 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>`_.
 
-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
 
-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
-      # 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
-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

docs/intro.rst

@@ -1,11 +1,9 @@
-.. highlight:: python
-.. module:: fbchat
 .. _intro:
 
 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.
 You should also make sure that the file's access control is appropriately restrictive
 
@@ -26,9 +24,9 @@ Replace ``<email>`` and ``<password>`` with your email and password respectively
 
 .. note::
     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 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 :class:`Client`)
 
 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`::
@@ -48,9 +46,9 @@ Threads
 
 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.
-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`,
 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,
 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`.
 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
 ------------------------
 
-`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,
 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)
 
-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:
@@ -118,7 +116,7 @@ You can see a full example showing all the possible thread interactions with `fb
 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`.
 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::
@@ -127,12 +125,12 @@ The following snippet will search for users by their name, take the first (and m
     user = users[0]
     print("User's ID: {}".format(user.uid))
     print("User's name: {}".format(user.name))
-    print("User's profile picture url: {}".format(user.photo))
+    print("User's profile picture URL: {}".format(user.photo))
-    print("User's main url: {}".format(user.url))
+    print("User's main URL: {}".format(user.url))
 
 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:
@@ -140,7 +138,7 @@ You can see a full example showing all the possible ways to fetch information wi
 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.
 Use :func:`Client.getSession` to retrieve the cookies::
 
@@ -156,7 +154,7 @@ Or you can set the ``session_cookies`` on your initial login.
     client = Client('<email>', '<password>', session_cookies=session_cookies)
 
 .. warning::
-    You session cookies can be just as valueable as you password, so store them with equal care
+    You session cookies can be just as valuable as you password, so store them with equal care
 
 
 .. _intro_events:
@@ -164,13 +162,13 @@ 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 :func:`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
 
 .. 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::
 
@@ -194,7 +192,7 @@ The change was in the parameters that our `onMessage` method took: ``message_obj
 and ``mid``, ``ts``, ``metadata`` and ``msg`` got removed, but the function still works, since we included ``**kwargs``
 
 .. note::
-    Therefore, for both backwards and forwards compatability,
+    Therefore, for both backwards and forwards compatibility,
     the API actually requires that you include ``**kwargs`` as your final argument.
 
 View the :ref:`examples` to see some more examples illustrating the event system

docs/make.bat

@@ -5,21 +5,20 @@ pushd %~dp0
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=python -msphinx
+	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=.
 set BUILDDIR=_build
-set SPHINXPROJ=fbchat
 
 if "%1" == "" goto help
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	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.If you don't have Sphinx installed, grab it from
 	echo.http://sphinx-doc.org/

docs/spelling/fixes.txt

@@ -0,0 +1,3 @@
+premade
+todo
+emoji

docs/spelling/names.txt

@@ -0,0 +1,3 @@
+Facebook
+GraphQL
+GitHub

docs/spelling/technical.txt

@@ -0,0 +1,14 @@
+iterables
+timestamp
+metadata
+spam
+spammy
+admin
+admins
+unsend
+unsends
+unmute
+spritemap
+online
+inbox
+subclassing

docs/testing.rst

@@ -1,5 +1,3 @@
-.. highlight:: sh
-.. module:: fbchat
 .. _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.
 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
 
@@ -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!
     (You should execute the script at max about 10 times a day)
-
-.. automodule:: tests
-    :members: TestFbchat
-    :undoc-members: TestFbchat

docs/todo.rst

@@ -1,5 +1,3 @@
-.. highlight:: python
-.. module:: fbchat
 .. _todo:
 
 Todo
@@ -11,11 +9,11 @@ This page will be periodically updated to show missing features and documentatio
 Missing Functionality
 ---------------------
 
-- Implement Client.searchForMessage
+- Implement ``Client.searchForMessage``
-    - This will use the graphql request API
+    - This will use the GraphQL request API
 - Implement chatting with pages properly
 - Write better FAQ
-- Explain usage of graphql
+- Explain usage of GraphQL
 
 
 Documentation

examples/fetch.py

@@ -1,5 +1,6 @@
 # -*- coding: UTF-8 -*-
 
+from itertools import islice
 from fbchat import Client
 from fbchat.models import *
 
@@ -62,3 +63,9 @@ print("thread's type: {}".format(thread.type))
 
 
 # Here should be an example of `getUnread`
+
+
+# Print image url for 20 last images from thread.
+images = client.fetchThreadImages("<thread id>")
+for image in islice(image, 20):
+    print(image.large_preview_url)

examples/interract.py

@@ -47,7 +47,7 @@ client.sendLocalImage(
     thread_type=thread_type,
 )
 
-# Will download the image at the url `<image url>`, and then send it
+# Will download the image at the URL `<image url>`, and then send it
 client.sendRemoteImage(
     "<image url>",
     message=Message(text="This is a remote image"),

fbchat/__init__.py

@@ -13,7 +13,7 @@ from ._client import Client
 from ._util import log  # TODO: Remove this (from examples too)
 
 __title__ = "fbchat"
-__version__ = "1.7.0"
+__version__ = "1.8.0"
 __description__ = "Facebook Chat (Messenger) for Python"
 
 __copyright__ = "Copyright 2015 - 2019 by Taehoon Kim"

fbchat/_attachment.py

@@ -7,7 +7,7 @@ from . import _util
 
 @attr.s(cmp=False)
 class Attachment(object):
-    """Represents a Facebook attachment"""
+    """Represents a Facebook attachment."""
 
     #: The attachment ID
     uid = attr.ib(None)
@@ -15,12 +15,12 @@ class Attachment(object):
 
 @attr.s(cmp=False)
 class UnsentMessage(Attachment):
-    """Represents an unsent message attachment"""
+    """Represents an unsent message attachment."""
 
 
 @attr.s(cmp=False)
 class ShareAttachment(Attachment):
-    """Represents a shared item (eg. URL) that has been sent as a Facebook attachment"""
+    """Represents a shared item (e.g. URL) attachment."""
 
     #: ID of the author of the shared post
     author = attr.ib(None)
@@ -36,7 +36,7 @@ class ShareAttachment(Attachment):
     source = attr.ib(None)
     #: URL of the attachment image
     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)
     #: Width of the image
     image_width = attr.ib(None)

fbchat/_core.py

@@ -8,7 +8,7 @@ log = logging.getLogger("client")
 
 
 class Enum(aenum.Enum):
-    """Used internally by fbchat to support enumerations"""
+    """Used internally by ``fbchat`` to support enumerations"""
 
     def __repr__(self):
         # For documentation:

fbchat/_exception.py

@@ -3,7 +3,10 @@ from __future__ import unicode_literals
 
 
 class FBchatException(Exception):
-    """Custom exception thrown by fbchat. All exceptions in the fbchat module inherits this"""
+    """Custom exception thrown by ``fbchat``.
+
+    All exceptions in the ``fbchat`` module inherits this.
+    """
 
 
 class FBchatFacebookError(FBchatException):
@@ -11,7 +14,7 @@ class FBchatFacebookError(FBchatException):
     fb_error_code = None
     #: The error message that Facebook returned (In the user's own language)
     fb_error_message = None
-    #: The status code that was sent in the http response (eg. 404) (Usually only set if not successful, aka. not 200)
+    #: The status code that was sent in the HTTP response (e.g. 404) (Usually only set if not successful, aka. not 200)
     request_status_code = None
 
     def __init__(
@@ -22,11 +25,36 @@ class FBchatFacebookError(FBchatException):
         request_status_code=None,
     ):
         super(FBchatFacebookError, self).__init__(message)
-        """Thrown by fbchat when Facebook returns an error"""
+        """Thrown by ``fbchat`` when Facebook returns an error"""
         self.fb_error_code = str(fb_error_code)
         self.fb_error_message = fb_error_message
         self.request_status_code = request_status_code
 
 
+class FBchatInvalidParameters(FBchatFacebookError):
+    """Raised by Facebook if:
+
+    - Some function supplied invalid parameters.
+    - Some content is not found.
+    - Some content is no longer available.
+    """
+
+
+class FBchatNotLoggedIn(FBchatFacebookError):
+    """Raised by Facebook if the client has been logged out."""
+
+    fb_error_code = "1357001"
+
+
+class FBchatPleaseRefresh(FBchatFacebookError):
+    """Raised by Facebook if the client has been inactive for too long.
+
+    This error usually happens after 1-2 days of inactivity.
+    """
+
+    fb_error_code = "1357004"
+    fb_error_message = "Please try closing and re-opening your browser window."
+
+
 class FBchatUserError(FBchatException):
-    """Thrown by fbchat when wrong values are entered"""
+    """Thrown by ``fbchat`` when wrong values are entered."""

fbchat/_file.py

@@ -7,9 +7,9 @@ from ._attachment import Attachment
 
 @attr.s(cmp=False)
 class FileAttachment(Attachment):
-    """Represents a file that has been sent as a Facebook attachment"""
+    """Represents a file that has been sent as a Facebook attachment."""
 
-    #: Url where you can download the file
+    #: URL where you can download the file
     url = attr.ib(None)
     #: Size of the file in bytes
     size = attr.ib(None)
@@ -33,13 +33,13 @@ class FileAttachment(Attachment):
 
 @attr.s(cmp=False)
 class AudioAttachment(Attachment):
-    """Represents an audio file that has been sent as a Facebook attachment"""
+    """Represents an audio file that has been sent as a Facebook attachment."""
 
     #: Name of the file
     filename = attr.ib(None)
-    #: Url of the audio file
+    #: URL of the audio file
     url = attr.ib(None)
-    #: Duration of the audioclip in milliseconds
+    #: Duration of the audio clip in milliseconds
     duration = attr.ib(None)
     #: Audio type
     audio_type = attr.ib(None)
@@ -59,13 +59,13 @@ class AudioAttachment(Attachment):
 
 @attr.s(cmp=False, init=False)
 class ImageAttachment(Attachment):
-    """Represents an image that has been sent as a Facebook attachment
+    """Represents an image that has been sent as a Facebook attachment.
 
-    To retrieve the full image url, use: :func:`fbchat.Client.fetchImageUrl`, and pass
+    To retrieve the full image URL, use: `Client.fetchImageUrl`, and pass it the id of
-    it the uid of the image attachment
+    the image attachment.
     """
 
-    #: The extension of the original image (eg. 'png')
+    #: The extension of the original image (e.g. ``png``)
     original_extension = attr.ib(None)
     #: Width of original image
     width = attr.ib(None, converter=lambda x: None if x is None else int(x))
@@ -92,7 +92,7 @@ class ImageAttachment(Attachment):
     #: Height of the large preview image
     large_preview_height = attr.ib(None)
 
-    #: URL to an animated preview of the image (eg. for gifs)
+    #: URL to an animated preview of the image (e.g. for GIFs)
     animated_preview_url = attr.ib(None)
     #: Width of the animated preview image
     animated_preview_width = attr.ib(None)
@@ -155,10 +155,22 @@ class ImageAttachment(Attachment):
             uid=data.get("legacy_attachment_id"),
         )
 
+    @classmethod
+    def _from_list(cls, data):
+        data = data["node"]
+        return cls(
+            width=data["original_dimensions"].get("x"),
+            height=data["original_dimensions"].get("y"),
+            thumbnail_url=data["image"].get("uri"),
+            large_preview=data["image2"],
+            preview=data["image1"],
+            uid=data["legacy_attachment_id"],
+        )
+
 
 @attr.s(cmp=False, init=False)
 class VideoAttachment(Attachment):
-    """Represents a video that has been sent as a Facebook attachment"""
+    """Represents a video that has been sent as a Facebook attachment."""
 
     #: Size of the original video in bytes
     size = attr.ib(None)
@@ -252,6 +264,18 @@ class VideoAttachment(Attachment):
             uid=data["target"].get("video_id"),
         )
 
+    @classmethod
+    def _from_list(cls, data):
+        data = data["node"]
+        return cls(
+            width=data["original_dimensions"].get("x"),
+            height=data["original_dimensions"].get("y"),
+            small_image=data["image"],
+            medium_image=data["image1"],
+            large_image=data["image2"],
+            uid=data["legacy_attachment_id"],
+        )
+
 
 def graphql_to_attachment(data):
     _type = data["__typename"]

fbchat/_graphql.py

@@ -4,7 +4,7 @@ from __future__ import unicode_literals
 import json
 import re
 from . import _util
-from ._exception import FBchatException, FBchatUserError
+from ._exception import FBchatException
 
 # Shameless copy from https://stackoverflow.com/a/8730674
 FLAGS = re.VERBOSE | re.MULTILINE | re.DOTALL
@@ -27,18 +27,18 @@ class ConcatJSONDecoder(json.JSONDecoder):
 # End shameless copy
 
 
-def graphql_queries_to_json(*queries):
+def queries_to_json(*queries):
     """
     Queries should be a list of GraphQL objects
     """
     rtn = {}
     for i, query in enumerate(queries):
-        rtn["q{}".format(i)] = query.value
+        rtn["q{}".format(i)] = query
     return json.dumps(rtn)
 
 
-def graphql_response_to_json(content):
+def response_to_json(content):
-    content = _util.strip_to_json(content)  # Usually only needed in some error cases
+    content = _util.strip_json_cruft(content)  # Usually only needed in some error cases
     try:
         j = json.loads(content, cls=ConcatJSONDecoder)
     except Exception:
@@ -49,9 +49,9 @@ def graphql_response_to_json(content):
         if "error_results" in x:
             del rtn[-1]
             continue
-        _util.check_json(x)
+        _util.handle_payload_error(x)
         [(key, value)] = x.items()
-        _util.check_json(value)
+        _util.handle_graphql_errors(value)
         if "response" in value:
             rtn[int(key[1:])] = value["response"]
         else:
@@ -62,171 +62,176 @@ def graphql_response_to_json(content):
     return rtn
 
 
-class GraphQL(object):
+def from_query(query, params):
-    def __init__(self, query=None, doc_id=None, params=None):
+    return {"priority": 0, "q": query, "query_params": params}
-        if params is None:
-            params = {}
-        if query is not None:
-            self.value = {"priority": 0, "q": query, "query_params": params}
-        elif doc_id is not None:
-            self.value = {"doc_id": doc_id, "query_params": params}
-        else:
-            raise FBchatUserError("A query or doc_id must be specified")
 
-    FRAGMENT_USER = """
-    QueryFragment User: User {
-        id,
-        name,
-        first_name,
-        last_name,
-        profile_picture.width(<pic_size>).height(<pic_size>) {
-            uri
-        },
-        is_viewer_friend,
-        url,
-        gender,
-        viewer_affinity
-    }
-    """
 
-    FRAGMENT_GROUP = """
+def from_query_id(query_id, params):
-    QueryFragment Group: MessageThread {
+    return {"query_id": query_id, "query_params": params}
-        name,
+
-        thread_key {
+
-            thread_fbid
+def from_doc(doc, params):
-        },
+    return {"doc": doc, "query_params": params}
-        image {
+
-            uri
+
-        },
+def from_doc_id(doc_id, params):
-        is_group_thread,
+    return {"doc_id": doc_id, "query_params": params}
-        all_participants {
+
-            nodes {
+
-                messaging_actor {
+FRAGMENT_USER = """
-                    id
+QueryFragment User: User {
-                }
+    id,
+    name,
+    first_name,
+    last_name,
+    profile_picture.width(<pic_size>).height(<pic_size>) {
+        uri
+    },
+    is_viewer_friend,
+    url,
+    gender,
+    viewer_affinity
+}
+"""
+
+FRAGMENT_GROUP = """
+QueryFragment Group: MessageThread {
+    name,
+    thread_key {
+        thread_fbid
+    },
+    image {
+        uri
+    },
+    is_group_thread,
+    all_participants {
+        nodes {
+            messaging_actor {
+                id
             }
+        }
+    },
+    customization_info {
+        participant_customizations {
+            participant_id,
+            nickname
         },
-        customization_info {
+        outgoing_bubble_color,
-            participant_customizations {
+        emoji
-                participant_id,
+    },
-                nickname
+    thread_admins {
+        id
+    },
+    group_approval_queue {
+        nodes {
+            requester {
+                id
+            }
+        }
+    },
+    approval_mode,
+    joinable_mode {
+        mode,
+        link
+    },
+    event_reminders {
+        nodes {
+            id,
+            lightweight_event_creator {
+                id
             },
-            outgoing_bubble_color,
+            time,
-            emoji
+            location_name,
-        },
+            event_title,
-        thread_admins {
+            event_reminder_members {
-            id
+                edges {
-        },
+                    node {
-        group_approval_queue {
+                        id
+                    },
+                    guest_list_state
+                }
+            }
+        }
+    }
+}
+"""
+
+FRAGMENT_PAGE = """
+QueryFragment Page: Page {
+    id,
+    name,
+    profile_picture.width(32).height(32) {
+        uri
+    },
+    url,
+    category_type,
+    city {
+        name
+    }
+}
+"""
+
+SEARCH_USER = (
+    """
+Query SearchUser(<search> = '', <limit> = 10) {
+    entities_named(<search>) {
+        search_results.of_type(user).first(<limit>) as users {
             nodes {
-                requester {
+                @User
-                    id
-                }
             }
-        },
+        }
-        approval_mode,
+    }
-        joinable_mode {
+}
-            mode,
+"""
-            link
+    + FRAGMENT_USER
-        },
+)
-        event_reminders {
+
+SEARCH_GROUP = (
+    """
+Query SearchGroup(<search> = '', <limit> = 10, <pic_size> = 32) {
+    viewer() {
+        message_threads.with_thread_name(<search>).last(<limit>) as groups {
             nodes {
-                id,
+                @Group
-                lightweight_event_creator {
-                    id
-                },
-                time,
-                location_name,
-                event_title,
-                event_reminder_members {
-                    edges {
-                        node {
-                            id
-                        },
-                        guest_list_state
-                    }
-                }
             }
         }
     }
-    """
+}
+"""
+    + FRAGMENT_GROUP
+)
 
-    FRAGMENT_PAGE = """
+SEARCH_PAGE = (
-    QueryFragment Page: Page {
-        id,
-        name,
-        profile_picture.width(32).height(32) {
-            uri
-        },
-        url,
-        category_type,
-        city {
-            name
-        }
-    }
     """
-
+Query SearchPage(<search> = '', <limit> = 10) {
-    SEARCH_USER = (
+    entities_named(<search>) {
-        """
+        search_results.of_type(page).first(<limit>) as pages {
-    Query SearchUser(<search> = '', <limit> = 10) {
+            nodes {
-        entities_named(<search>) {
+                @Page
-            search_results.of_type(user).first(<limit>) as users {
-                nodes {
-                    @User
-                }
             }
         }
     }
-    """
+}
-        + FRAGMENT_USER
+"""
-    )
+    + FRAGMENT_PAGE
+)
 
-    SEARCH_GROUP = (
+SEARCH_THREAD = (
-        """
+    """
-    Query SearchGroup(<search> = '', <limit> = 10, <pic_size> = 32) {
+Query SearchThread(<search> = '', <limit> = 10) {
-        viewer() {
+    entities_named(<search>) {
-            message_threads.with_thread_name(<search>).last(<limit>) as groups {
+        search_results.first(<limit>) as threads {
-                nodes {
+            nodes {
-                    @Group
+                __typename,
-                }
+                @User,
+                @Group,
+                @Page
             }
         }
     }
-    """
+}
-        + FRAGMENT_GROUP
+"""
-    )
+    + FRAGMENT_USER
-
+    + FRAGMENT_GROUP
-    SEARCH_PAGE = (
+    + FRAGMENT_PAGE
-        """
+)
-    Query SearchPage(<search> = '', <limit> = 10) {
-        entities_named(<search>) {
-            search_results.of_type(page).first(<limit>) as pages {
-                nodes {
-                    @Page
-                }
-            }
-        }
-    }
-    """
-        + FRAGMENT_PAGE
-    )
-
-    SEARCH_THREAD = (
-        """
-    Query SearchThread(<search> = '', <limit> = 10) {
-        entities_named(<search>) {
-            search_results.first(<limit>) as threads {
-                nodes {
-                    __typename,
-                    @User,
-                    @Group,
-                    @Page
-                }
-            }
-        }
-    }
-    """
-        + FRAGMENT_USER
-        + FRAGMENT_GROUP
-        + FRAGMENT_PAGE
-    )

fbchat/_group.py

@@ -8,11 +8,11 @@ from ._thread import ThreadType, Thread
 
 @attr.s(cmp=False, init=False)
 class Group(Thread):
-    """Represents a Facebook group. Inherits `Thread`"""
+    """Represents a Facebook group. Inherits `Thread`."""
 
     #: Unique list (set) of the group thread's participant user IDs
     participants = attr.ib(factory=set, converter=lambda x: set() if x is None else x)
-    #: A dict, containing user nicknames mapped to their IDs
+    #: A dictionary, containing user nicknames mapped to their IDs
     nicknames = attr.ib(factory=dict, converter=lambda x: {} if x is None else x)
     #: A :class:`ThreadColor`. The groups's message color
     color = attr.ib(None)
@@ -107,7 +107,7 @@ class Group(Thread):
 
 @attr.s(cmp=False, init=False)
 class Room(Group):
-    """Deprecated. Use :class:`Group` instead"""
+    """Deprecated. Use `Group` instead."""
 
     # True is room is not discoverable
     privacy_mode = attr.ib(None)

fbchat/_location.py

@@ -8,9 +8,9 @@ from . import _util
 
 @attr.s(cmp=False)
 class LocationAttachment(Attachment):
-    """Represents a user location
+    """Represents a user location.
 
-    Latitude and longitude OR address is provided by Facebook
+    Latitude and longitude OR address is provided by Facebook.
     """
 
     #: Latitude of the location
@@ -58,7 +58,7 @@ class LocationAttachment(Attachment):
 
 @attr.s(cmp=False, init=False)
 class LiveLocationAttachment(LocationAttachment):
-    """Represents a live user location"""
+    """Represents a live user location."""
 
     #: Name of the location
     name = attr.ib(None)

fbchat/_message.py

@@ -9,7 +9,7 @@ from ._core import Enum
 
 
 class EmojiSize(Enum):
-    """Used to specify the size of a sent emoji"""
+    """Used to specify the size of a sent emoji."""
 
     LARGE = "369239383222810"
     MEDIUM = "369239343222814"
@@ -33,8 +33,9 @@ class EmojiSize(Enum):
 
 
 class MessageReaction(Enum):
-    """Used to specify a message reaction"""
+    """Used to specify a message reaction."""
 
+    HEART = "❤"
     LOVE = "😍"
     SMILE = "😆"
     WOW = "😮"
@@ -46,7 +47,7 @@ class MessageReaction(Enum):
 
 @attr.s(cmp=False)
 class Mention(object):
-    """Represents a @mention"""
+    """Represents a ``@mention``."""
 
     #: The thread ID the mention is pointing at
     thread_id = attr.ib()
@@ -58,7 +59,7 @@ class Mention(object):
 
 @attr.s(cmp=False)
 class Message(object):
-    """Represents a Facebook message"""
+    """Represents a Facebook message."""
 
     #: The actual message
     text = attr.ib(None)
@@ -74,9 +75,9 @@ class Message(object):
     timestamp = attr.ib(None, init=False)
     #: Whether the message is read
     is_read = attr.ib(None, init=False)
-    #: A list of pepole IDs who read the message, works only with :func:`fbchat.Client.fetchThreadMessages`
+    #: A list of people IDs who read the message, works only with :func:`fbchat.Client.fetchThreadMessages`
     read_by = attr.ib(factory=list, init=False)
-    #: A dict with user's IDs as keys, and their :class:`MessageReaction` as values
+    #: A dictionary with user's IDs as keys, and their :class:`MessageReaction` as values
     reactions = attr.ib(factory=dict, init=False)
     #: A :class:`Sticker`
     sticker = attr.ib(None)
@@ -97,15 +98,13 @@ class Message(object):
     def formatMentions(cls, text, *args, **kwargs):
         """Like `str.format`, but takes tuples with a thread id and text instead.
 
-        Returns a `Message` object, with the formatted string and relevant mentions.
+        Return a `Message` object, with the formatted string and relevant mentions.
 
-        ```
         >>> 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.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=[]>
-        ```
         """
         result = ""
         mentions = list()

fbchat/_page.py

@@ -8,9 +8,9 @@ from ._thread import ThreadType, Thread
 
 @attr.s(cmp=False, init=False)
 class Page(Thread):
-    """Represents a Facebook page. Inherits `Thread`"""
+    """Represents a Facebook page. Inherits `Thread`."""
 
-    #: The page's custom url
+    #: The page's custom URL
     url = attr.ib(None)
     #: The name of the page's location city
     city = attr.ib(None)

fbchat/_plan.py

@@ -14,11 +14,11 @@ class GuestStatus(Enum):
 
 @attr.s(cmp=False)
 class Plan(object):
-    """Represents a plan"""
+    """Represents a plan."""
 
     #: ID of the plan
     uid = attr.ib(None, init=False)
-    #: Plan time (unix time stamp), only precise down to the minute
+    #: Plan time (timestamp), only precise down to the minute
     time = attr.ib(converter=int)
     #: Plan title
     title = attr.ib()
@@ -28,7 +28,7 @@ class Plan(object):
     location_id = attr.ib(None, converter=lambda x: x or "")
     #: ID of the plan creator
     author_id = attr.ib(None, init=False)
-    #: Dict of `User` IDs mapped to their `GuestStatus`
+    #: Dictionary of `User` IDs mapped to their `GuestStatus`
     guests = attr.ib(None, init=False)
 
     @property

fbchat/_poll.py

@@ -6,7 +6,7 @@ import attr
 
 @attr.s(cmp=False)
 class Poll(object):
-    """Represents a poll"""
+    """Represents a poll."""
 
     #: Title of the poll
     title = attr.ib()
@@ -29,7 +29,7 @@ class Poll(object):
 
 @attr.s(cmp=False)
 class PollOption(object):
-    """Represents a poll option"""
+    """Represents a poll option."""
 
     #: Text of the poll option
     text = attr.ib()

fbchat/_quick_reply.py

@@ -7,7 +7,7 @@ from ._attachment import Attachment
 
 @attr.s(cmp=False)
 class QuickReply(object):
-    """Represents a quick reply"""
+    """Represents a quick reply."""
 
     #: Payload of the quick reply
     payload = attr.ib(None)
@@ -21,7 +21,7 @@ class QuickReply(object):
 
 @attr.s(cmp=False, init=False)
 class QuickReplyText(QuickReply):
-    """Represents a text quick reply"""
+    """Represents a text quick reply."""
 
     #: Title of the quick reply
     title = attr.ib(None)
@@ -38,7 +38,7 @@ class QuickReplyText(QuickReply):
 
 @attr.s(cmp=False, init=False)
 class QuickReplyLocation(QuickReply):
-    """Represents a location quick reply (Doesn't work on mobile)"""
+    """Represents a location quick reply (Doesn't work on mobile)."""
 
     #: Type of the quick reply
     _type = "location"
@@ -50,7 +50,7 @@ class QuickReplyLocation(QuickReply):
 
 @attr.s(cmp=False, init=False)
 class QuickReplyPhoneNumber(QuickReply):
-    """Represents a phone number quick reply (Doesn't work on mobile)"""
+    """Represents a phone number quick reply (Doesn't work on mobile)."""
 
     #: URL of the quick reply image (optional)
     image_url = attr.ib(None)
@@ -64,7 +64,7 @@ class QuickReplyPhoneNumber(QuickReply):
 
 @attr.s(cmp=False, init=False)
 class QuickReplyEmail(QuickReply):
-    """Represents an email quick reply (Doesn't work on mobile)"""
+    """Represents an email quick reply (Doesn't work on mobile)."""
 
     #: URL of the quick reply image (optional)
     image_url = attr.ib(None)

fbchat/_state.py

@@ -0,0 +1,193 @@
+# -*- coding: UTF-8 -*-
+from __future__ import unicode_literals
+
+import attr
+import bs4
+import re
+import requests
+import random
+
+from . import _util, _exception
+
+FB_DTSG_REGEX = re.compile(r'name="fb_dtsg" value="(.*?)"')
+
+
+def find_input_fields(html):
+    return bs4.BeautifulSoup(html, "html.parser", parse_only=bs4.SoupStrainer("input"))
+
+
+def session_factory(user_agent=None):
+    session = requests.session()
+    session.headers["Referer"] = "https://www.facebook.com"
+    # TODO: Deprecate setting the user agent manually
+    session.headers["User-Agent"] = user_agent or random.choice(_util.USER_AGENTS)
+    return session
+
+
+def is_home(url):
+    parts = _util.urlparse(url)
+    # Check the urls `/home.php` and `/`
+    return "home" in parts.path or "/" == parts.path
+
+
+def _2fa_helper(session, code, r):
+    soup = find_input_fields(r.text)
+    data = dict()
+
+    url = "https://m.facebook.com/login/checkpoint/"
+
+    data["approvals_code"] = code
+    data["fb_dtsg"] = soup.find("input", {"name": "fb_dtsg"})["value"]
+    data["nh"] = soup.find("input", {"name": "nh"})["value"]
+    data["submit[Submit Code]"] = "Submit Code"
+    data["codes_submitted"] = 0
+    _util.log.info("Submitting 2FA code.")
+
+    r = session.post(url, data=data)
+
+    if is_home(r.url):
+        return r
+
+    del data["approvals_code"]
+    del data["submit[Submit Code]"]
+    del data["codes_submitted"]
+
+    data["name_action_selected"] = "save_device"
+    data["submit[Continue]"] = "Continue"
+    _util.log.info("Saving browser.")
+    # At this stage, we have dtsg, nh, name_action_selected, submit[Continue]
+    r = session.post(url, data=data)
+
+    if is_home(r.url):
+        return r
+
+    del data["name_action_selected"]
+    _util.log.info("Starting Facebook checkup flow.")
+    # At this stage, we have dtsg, nh, submit[Continue]
+    r = session.post(url, data=data)
+
+    if is_home(r.url):
+        return r
+
+    del data["submit[Continue]"]
+    data["submit[This was me]"] = "This Was Me"
+    _util.log.info("Verifying login attempt.")
+    # At this stage, we have dtsg, nh, submit[This was me]
+    r = session.post(url, data=data)
+
+    if is_home(r.url):
+        return r
+
+    del data["submit[This was me]"]
+    data["submit[Continue]"] = "Continue"
+    data["name_action_selected"] = "save_device"
+    _util.log.info("Saving device again.")
+    # At this stage, we have dtsg, nh, submit[Continue], name_action_selected
+    r = session.post(url, data=data)
+    return r
+
+
+@attr.s(slots=True)  # TODO i Python 3: Add kw_only=True
+class State(object):
+    """Stores and manages state required for most Facebook requests."""
+
+    fb_dtsg = attr.ib()
+    _revision = attr.ib()
+    _session = attr.ib(factory=session_factory)
+    _counter = attr.ib(0)
+    _logout_h = attr.ib(None)
+
+    def get_user_id(self):
+        rtn = self.get_cookies().get("c_user")
+        if rtn is None:
+            return None
+        return str(rtn)
+
+    def get_params(self):
+        self._counter += 1  # TODO: Make this operation atomic / thread-safe
+        return {
+            "__a": 1,
+            "__req": _util.str_base(self._counter, 36),
+            "__rev": self._revision,
+            "fb_dtsg": self.fb_dtsg,
+        }
+
+    @classmethod
+    def login(cls, email, password, on_2fa_callback, user_agent=None):
+        session = session_factory(user_agent=user_agent)
+
+        soup = find_input_fields(session.get("https://m.facebook.com/").text)
+        data = dict(
+            (elem["name"], elem["value"])
+            for elem in soup
+            if elem.has_attr("value") and elem.has_attr("name")
+        )
+        data["email"] = email
+        data["pass"] = password
+        data["login"] = "Log In"
+
+        r = session.post("https://m.facebook.com/login.php?login_attempt=1", data=data)
+
+        # Usually, 'Checkpoint' will refer to 2FA
+        if "checkpoint" in r.url and ('id="approvals_code"' in r.text.lower()):
+            code = on_2fa_callback()
+            r = _2fa_helper(session, code, r)
+
+        # Sometimes Facebook tries to show the user a "Save Device" dialog
+        if "save-device" in r.url:
+            r = session.get("https://m.facebook.com/login/save-device/cancel/")
+
+        if is_home(r.url):
+            return cls.from_session(session=session)
+        else:
+            raise _exception.FBchatUserError(
+                "Login failed. Check email/password. "
+                "(Failed on url: {})".format(r.url)
+            )
+
+    def is_logged_in(self):
+        # Send a request to the login url, to see if we're directed to the home page
+        url = "https://m.facebook.com/login.php?login_attempt=1"
+        r = self._session.get(url, allow_redirects=False)
+        return "Location" in r.headers and is_home(r.headers["Location"])
+
+    def logout(self):
+        logout_h = self._logout_h
+        if not logout_h:
+            url = _util.prefix_url("/bluebar/modern_settings_menu/")
+            h_r = self._session.post(url, data={"pmid": "4"})
+            logout_h = re.search(r'name=\\"h\\" value=\\"(.*?)\\"', h_r.text).group(1)
+
+        url = _util.prefix_url("/logout.php")
+        return self._session.get(url, params={"ref": "mb", "h": logout_h}).ok
+
+    @classmethod
+    def from_session(cls, session):
+        r = session.get(_util.prefix_url("/"))
+
+        soup = find_input_fields(r.text)
+
+        fb_dtsg_element = soup.find("input", {"name": "fb_dtsg"})
+        if fb_dtsg_element:
+            fb_dtsg = fb_dtsg_element["value"]
+        else:
+            # Fall back to searching with a regex
+            fb_dtsg = FB_DTSG_REGEX.search(r.text).group(1)
+
+        revision = int(r.text.split('"client_revision":', 1)[1].split(",", 1)[0])
+
+        logout_h_element = soup.find("input", {"name": "h"})
+        logout_h = logout_h_element["value"] if logout_h_element else None
+
+        return cls(
+            fb_dtsg=fb_dtsg, revision=revision, session=session, logout_h=logout_h
+        )
+
+    def get_cookies(self):
+        return self._session.cookies.get_dict()
+
+    @classmethod
+    def from_cookies(cls, cookies, user_agent=None):
+        session = session_factory(user_agent=user_agent)
+        session.cookies = requests.cookies.merge_cookies(session.cookies, cookies)
+        return cls.from_session(session=session)

fbchat/_sticker.py

@@ -7,7 +7,7 @@ from ._attachment import Attachment
 
 @attr.s(cmp=False, init=False)
 class Sticker(Attachment):
-    """Represents a Facebook sticker that has been sent to a thread as an attachment"""
+    """Represents a Facebook sticker that has been sent to a thread as an attachment."""
 
     #: The sticker-pack's ID
     pack = attr.ib(None)
@@ -21,7 +21,7 @@ class Sticker(Attachment):
     large_sprite_image = attr.ib(None)
     #: The amount of frames present in the spritemap pr. row
     frames_per_row = attr.ib(None)
-    #: The amount of frames present in the spritemap pr. coloumn
+    #: The amount of frames present in the spritemap pr. column
     frames_per_col = attr.ib(None)
     #: The frame rate the spritemap is intended to be played in
     frame_rate = attr.ib(None)

fbchat/_thread.py

@@ -6,7 +6,10 @@ from ._core import Enum
 
 
 class ThreadType(Enum):
-    """Used to specify what type of Facebook thread is being used. See :ref:`intro_threads` for more info"""
+    """Used to specify what type of Facebook thread is being used.
+
+    See :ref:`intro_threads` for more info.
+    """
 
     USER = 1
     GROUP = 2
@@ -24,7 +27,7 @@ class ThreadLocation(Enum):
 
 
 class ThreadColor(Enum):
-    """Used to specify a thread colors"""
+    """Used to specify a thread colors."""
 
     MESSENGER_BLUE = "#0084ff"
     VIKING = "#44bec7"
@@ -60,13 +63,13 @@ class ThreadColor(Enum):
 
 @attr.s(cmp=False, init=False)
 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)
-    #: 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()
-    #: A url to the thread's picture
+    #: A URL to the thread's picture
     photo = attr.ib(None)
     #: The name of the thread
     name = attr.ib(None)

fbchat/_user.py

@@ -38,7 +38,7 @@ GENDERS = {
 
 
 class TypingStatus(Enum):
-    """Used to specify whether the user is typing or has stopped typing"""
+    """Used to specify whether the user is typing or has stopped typing."""
 
     STOPPED = 0
     TYPING = 1
@@ -46,9 +46,9 @@ class TypingStatus(Enum):
 
 @attr.s(cmp=False, init=False)
 class User(Thread):
-    """Represents a Facebook user. Inherits `Thread`"""
+    """Represents a Facebook user. Inherits `Thread`."""
 
-    #: The profile url
+    #: The profile URL
     url = attr.ib(None)
     #: The users first name
     first_name = attr.ib(None)

fbchat/_util.py

@@ -11,7 +11,13 @@ from os.path import basename
 import warnings
 import logging
 import requests
-from ._exception import FBchatException, FBchatFacebookError
+from ._exception import (
+    FBchatException,
+    FBchatFacebookError,
+    FBchatInvalidParameters,
+    FBchatNotLoggedIn,
+    FBchatPleaseRefresh,
+)
 
 try:
     from urllib.parse import urlencode, parse_qs, urlparse
@@ -47,96 +53,12 @@ USER_AGENTS = [
 ]
 
 
-class ReqUrl(object):
-    """A class containing all urls used by `fbchat`"""
-
-    SEARCH = "https://www.facebook.com/ajax/typeahead/search.php"
-    LOGIN = "https://m.facebook.com/login.php?login_attempt=1"
-    SEND = "https://www.facebook.com/messaging/send/"
-    UNREAD_THREADS = "https://www.facebook.com/ajax/mercury/unread_threads.php"
-    UNSEEN_THREADS = "https://www.facebook.com/mercury/unseen_thread_ids/"
-    THREADS = "https://www.facebook.com/ajax/mercury/threadlist_info.php"
-    MOVE_THREAD = "https://www.facebook.com/ajax/mercury/move_thread.php"
-    ARCHIVED_STATUS = (
-        "https://www.facebook.com/ajax/mercury/change_archived_status.php?dpr=1"
-    )
-    PINNED_STATUS = (
-        "https://www.facebook.com/ajax/mercury/change_pinned_status.php?dpr=1"
-    )
-    MESSAGES = "https://www.facebook.com/ajax/mercury/thread_info.php"
-    READ_STATUS = "https://www.facebook.com/ajax/mercury/change_read_status.php"
-    DELIVERED = "https://www.facebook.com/ajax/mercury/delivery_receipts.php"
-    MARK_SEEN = "https://www.facebook.com/ajax/mercury/mark_seen.php"
-    BASE = "https://www.facebook.com"
-    MOBILE = "https://m.facebook.com/"
-    STICKY = "https://0-edge-chat.facebook.com/pull"
-    PING = "https://0-edge-chat.facebook.com/active_ping"
-    UPLOAD = "https://upload.facebook.com/ajax/mercury/upload.php"
-    INFO = "https://www.facebook.com/chat/user_info/"
-    CONNECT = "https://www.facebook.com/ajax/add_friend/action.php?dpr=1"
-    REMOVE_USER = "https://www.facebook.com/chat/remove_participants/"
-    LOGOUT = "https://www.facebook.com/logout.php"
-    ALL_USERS = "https://www.facebook.com/chat/user_info_all"
-    SAVE_DEVICE = "https://m.facebook.com/login/save-device/cancel/"
-    CHECKPOINT = "https://m.facebook.com/login/checkpoint/"
-    THREAD_COLOR = "https://www.facebook.com/messaging/save_thread_color/?source=thread_settings&dpr=1"
-    THREAD_NICKNAME = "https://www.facebook.com/messaging/save_thread_nickname/?source=thread_settings&dpr=1"
-    THREAD_EMOJI = "https://www.facebook.com/messaging/save_thread_emoji/?source=thread_settings&dpr=1"
-    THREAD_IMAGE = "https://www.facebook.com/messaging/set_thread_image/?dpr=1"
-    THREAD_NAME = "https://www.facebook.com/messaging/set_thread_name/?dpr=1"
-    MESSAGE_REACTION = "https://www.facebook.com/webgraphql/mutation"
-    TYPING = "https://www.facebook.com/ajax/messaging/typ.php"
-    GRAPHQL = "https://www.facebook.com/api/graphqlbatch/"
-    ATTACHMENT_PHOTO = "https://www.facebook.com/mercury/attachments/photo/"
-    PLAN_CREATE = "https://www.facebook.com/ajax/eventreminder/create"
-    PLAN_INFO = "https://www.facebook.com/ajax/eventreminder"
-    PLAN_CHANGE = "https://www.facebook.com/ajax/eventreminder/submit"
-    PLAN_PARTICIPATION = "https://www.facebook.com/ajax/eventreminder/rsvp"
-    MODERN_SETTINGS_MENU = "https://www.facebook.com/bluebar/modern_settings_menu/"
-    REMOVE_FRIEND = "https://m.facebook.com/a/removefriend.php"
-    BLOCK_USER = "https://www.facebook.com/messaging/block_messages/?dpr=1"
-    UNBLOCK_USER = "https://www.facebook.com/messaging/unblock_messages/?dpr=1"
-    SAVE_ADMINS = "https://www.facebook.com/messaging/save_admins/?dpr=1"
-    APPROVAL_MODE = "https://www.facebook.com/messaging/set_approval_mode/?dpr=1"
-    CREATE_GROUP = "https://m.facebook.com/messages/send/?icm=1"
-    DELETE_THREAD = "https://www.facebook.com/ajax/mercury/delete_thread.php?dpr=1"
-    DELETE_MESSAGES = "https://www.facebook.com/ajax/mercury/delete_messages.php?dpr=1"
-    MUTE_THREAD = "https://www.facebook.com/ajax/mercury/change_mute_thread.php?dpr=1"
-    MUTE_REACTIONS = (
-        "https://www.facebook.com/ajax/mercury/change_reactions_mute_thread/?dpr=1"
-    )
-    MUTE_MENTIONS = (
-        "https://www.facebook.com/ajax/mercury/change_mentions_mute_thread/?dpr=1"
-    )
-    CREATE_POLL = "https://www.facebook.com/messaging/group_polling/create_poll/?dpr=1"
-    UPDATE_VOTE = "https://www.facebook.com/messaging/group_polling/update_vote/?dpr=1"
-    GET_POLL_OPTIONS = "https://www.facebook.com/ajax/mercury/get_poll_options"
-    SEARCH_MESSAGES = "https://www.facebook.com/ajax/mercury/search_snippets.php?dpr=1"
-    MARK_SPAM = "https://www.facebook.com/ajax/mercury/mark_spam.php?dpr=1"
-    UNSEND = "https://www.facebook.com/messaging/unsend_message/?dpr=1"
-    FORWARD_ATTACHMENT = "https://www.facebook.com/mercury/attachments/forward/"
-
-    pull_channel = 0
-
-    def change_pull_channel(self, channel=None):
-        if channel is None:
-            self.pull_channel = (self.pull_channel + 1) % 5  # Pull channel will be 0-4
-        else:
-            self.pull_channel = channel
-        self.STICKY = "https://{}-edge-chat.facebook.com/pull".format(self.pull_channel)
-        self.PING = "https://{}-edge-chat.facebook.com/active_ping".format(
-            self.pull_channel
-        )
-
-
-facebookEncoding = "UTF-8"
-
-
 def now():
     return int(time() * 1000)
 
 
-def strip_to_json(text):
+def strip_json_cruft(text):
+    """Removes `for(;;);` (and other cruft) that preceeds JSON responses."""
     try:
         return text[text.index("{") :]
     except ValueError:
@@ -148,15 +70,14 @@ def get_decoded_r(r):
 
 
 def get_decoded(content):
-    return content.decode(facebookEncoding)
+    return content.decode("utf-8")
 
 
 def parse_json(content):
-    return json.loads(content)
+    try:
-
+        return json.loads(content)
-
+    except ValueError:
-def get_json(r):
+        raise FBchatFacebookError("Error while parsing JSON: {!r}".format(content))
-    return json.loads(strip_to_json(get_decoded_r(r)))
 
 
 def digitToChar(digit):
@@ -192,61 +113,74 @@ def generateOfflineThreadingID():
     return str(int(msgs, 2))
 
 
-def check_json(j):
+def handle_payload_error(j):
-    if hasattr(j.get("payload"), "get") and j["payload"].get("error"):
+    if "error" not in j:
-        raise FBchatFacebookError(
+        return
-            "Error when sending request: {}".format(j["payload"]["error"]),
+    error = j["error"]
-            fb_error_code=None,
+    if j["error"] == 1357001:
-            fb_error_message=j["payload"]["error"],
+        error_cls = FBchatNotLoggedIn
-        )
+    elif j["error"] == 1357004:
-    elif j.get("error"):
+        error_cls = FBchatPleaseRefresh
-        if "errorDescription" in j:
+    elif j["error"] in (1357031, 1545010, 1545003):
-            # 'errorDescription' is in the users own language!
+        error_cls = FBchatInvalidParameters
-            raise FBchatFacebookError(
+    else:
-                "Error #{} when sending request: {}".format(
+        error_cls = FBchatFacebookError
-                    j["error"], j["errorDescription"]
+    # TODO: Use j["errorSummary"]
-                ),
+    # "errorDescription" is in the users own language!
-                fb_error_code=j["error"],
+    raise error_cls(
-                fb_error_message=j["errorDescription"],
+        "Error #{} when sending request: {}".format(error, j["errorDescription"]),
-            )
+        fb_error_code=error,
-        elif "debug_info" in j["error"] and "code" in j["error"]:
+        fb_error_message=j["errorDescription"],
-            raise FBchatFacebookError(
+    )
-                "Error #{} when sending request: {}".format(
-                    j["error"]["code"], repr(j["error"]["debug_info"])
-                ),
-                fb_error_code=j["error"]["code"],
-                fb_error_message=j["error"]["debug_info"],
-            )
-        else:
-            raise FBchatFacebookError(
-                "Error {} when sending request".format(j["error"]),
-                fb_error_code=j["error"],
-            )
 
 
-def check_request(r, as_json=True):
+def handle_graphql_errors(j):
-    if not r.ok:
+    errors = []
+    if j.get("error"):
+        errors = [j["error"]]
+    if "errors" in j:
+        errors = j["errors"]
+    if errors:
+        error = errors[0]  # TODO: Handle multiple errors
+        # TODO: Use `summary`, `severity` and `description`
         raise FBchatFacebookError(
-            "Error when sending request: Got {} response".format(r.status_code),
+            "GraphQL error #{}: {} / {!r}".format(
-            request_status_code=r.status_code,
+                error.get("code"), error.get("message"), error.get("debug_info")
+            ),
+            fb_error_code=error.get("code"),
+            fb_error_message=error.get("message"),
         )
 
+
+def check_request(r):
+    check_http_code(r.status_code)
     content = get_decoded_r(r)
+    check_content(content)
+    return content
 
+
+def check_http_code(code):
+    msg = "Error when sending request: Got {} response.".format(code)
+    if code == 404:
+        raise FBchatFacebookError(
+            msg + " This is either because you specified an invalid URL, or because"
+            " you provided an invalid id (Facebook usually requires integer ids).",
+            request_status_code=code,
+        )
+    if 400 <= code < 600:
+        raise FBchatFacebookError(msg, request_status_code=code)
+
+
+def check_content(content, as_json=True):
     if content is None or len(content) == 0:
         raise FBchatFacebookError("Error when sending request: Got empty response")
 
-    if as_json:
+
-        content = strip_to_json(content)
+def to_json(content):
-        try:
+    content = strip_json_cruft(content)
-            j = json.loads(content)
+    j = parse_json(content)
-        except ValueError:
+    log.debug(j)
-            raise FBchatFacebookError("Error while parsing JSON: {!r}".format(content))
+    return j
-        check_json(j)
-        log.debug(j)
-        return j
-    else:
-        return content
 
 
 def get_jsmods_require(j, index):
@@ -255,9 +189,8 @@ def get_jsmods_require(j, index):
             return j["jsmods"]["require"][0][index][0]
         except (KeyError, IndexError) as e:
             log.warning(
-                "Error when getting jsmods_require: {}. Facebook might have changed protocol".format(
+                "Error when getting jsmods_require: "
-                    j
+                "{}. Facebook might have changed protocol".format(j)
-                )
             )
     return None
 
@@ -315,3 +248,9 @@ def get_url_parameters(url, *args):
 
 def get_url_parameter(url, param):
     return get_url_parameters(url, param)[0]
+
+
+def prefix_url(url):
+    if url.startswith("/"):
+        return "https://www.facebook.com" + url
+    return url

pyproject.toml

@@ -1,14 +1,5 @@
 [tool.black]
 line-length = 88
-exclude = '''
-/(
-    \.git
-  | \.pytest_cache
-  | build
-  | dist
-  | venv
-)/
-'''
 
 [build-system]
 requires = ["flit"]
@@ -22,10 +13,10 @@ maintainer = "Mads Marquart"
 maintainer-email = "madsmtm@gmail.com"
 home-page = "https://github.com/carpedm20/fbchat/"
 requires = [
-    "aenum",
+    "aenum~=2.0",
-    "attrs~=18.2.0",
+    "attrs>=18.2",
-    "requests",
+    "requests~=2.19",
-    "beautifulsoup4",
+    "beautifulsoup4~=4.0",
 ]
 description-file = "README.rst"
 classifiers = [
@@ -61,5 +52,16 @@ Repository = "https://github.com/carpedm20/fbchat/"
 [tool.flit.metadata.requires-extra]
 test = [
     "pytest~=4.0",
-    "six",
+    "six~=1.0",
+]
+docs = [
+    "sphinx~=2.0",
+    "sphinxcontrib-spelling~=4.0"
+]
+lint = [
+    "black",
+]
+tools = [
+    # Fork of bumpversion, see https://github.com/c4urself/bump2version
+    "bump2version~=0.5.0",
 ]