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))
-fbchat.models.FBchatUserError: Login failed. Check email/password. (Failed on url: https://m.facebook.com/login.php?login_attempt=1)
+    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)
 ```
 
 ## 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
-    $ flit install
+    $ pip install fbchat
 
 
 Maintainer

docs/Makefile

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

docs/api.rst

@@ -1,44 +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.
-You can extend this class, and overwrite the events, to provide custom event handling (mainly used while listening)
+.. autoclass:: Client
 
-.. autoclass:: Client(email, password, user_agent=None, max_tries=5, session_cookies=None, logging_level=logging.INFO)
-    :members:
+Threads
+-------
 
+.. autoclass:: Thread()
+.. autoclass:: ThreadType(Enum)
+    :undoc-members:
+.. autoclass:: Page()
+.. autoclass:: User()
+.. autoclass:: Group()
 
-.. _api_models:
+Messages
+--------
 
-Models
-------
-
-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
-
-.. automodule:: fbchat.models
-    :members:
+.. autoclass:: Message
+.. autoclass:: Mention
+.. autoclass:: EmojiSize(Enum)
+    :undoc-members:
+.. autoclass:: MessageReaction(Enum)
     :undoc-members:
 
+Exceptions
+----------
 
-.. _api_utils:
+.. autoexception:: FBchatException()
+.. autoexception:: FBchatFacebookError()
+.. autoexception:: FBchatUserError()
 
-Utils
------
+Attachments
+-----------
 
-These functions and values are used internally by fbchat, and are subject to change. Do **NOT** rely on these to be backwards compatible!
+.. autoclass:: Attachment()
+.. autoclass:: ShareAttachment()
+.. autoclass:: Sticker()
+.. autoclass:: LocationAttachment()
+.. autoclass:: LiveLocationAttachment()
+.. autoclass:: FileAttachment()
+.. autoclass:: AudioAttachment()
+.. autoclass:: ImageAttachment()
+.. autoclass:: VideoAttachment()
+.. autoclass:: ImageAttachment()
 
-.. automodule:: fbchat.utils
-    :members:
+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
-# sphinx-quickstart on Thu May 25 15:43:01 2017.
+# Configuration file for the Sphinx documentation builder.
 #
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# 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.
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# 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.
+# -- Path setup --------------------------------------------------------------
 
 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.
-pygments_style = "sphinx"
+rst_prolog = ".. currentmodule:: " + project
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+# The reST default role (used for this markup: `text`) to use for all
+# 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 following snippet will, as you've probably already figured out, send the message `test message` to your account::
+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::
 
     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 main url: {}".format(user.url))
+    print("User's profile picture URL: {}".format(user.photo))
+    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.then set the SPHINXBUILD environment variable to point to the full
-	echo.path of the 'sphinx-build' executable. Alternatively you may add the
-	echo.Sphinx directory to PATH.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	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
-    - This will use the graphql request API
+- Implement ``Client.searchForMessage``
+    - 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

@@ -7,13 +7,13 @@
 from __future__ import unicode_literals
 
 # These imports are far too general, but they're needed for backwards compatbility.
-from .utils import *
-from .graphql import *
 from .models import *
+
 from ._client import Client
+from ._util import log  # TODO: Remove this (from examples too)
 
 __title__ = "fbchat"
-__version__ = "1.6.5"
+__version__ = "1.8.0"
 __description__ = "Facebook Chat (Messenger) for Python"
 
 __copyright__ = "Copyright 2015 - 2019 by Taehoon Kim"

fbchat/_attachment.py

@@ -2,11 +2,12 @@
 from __future__ import unicode_literals
 
 import attr
+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)
@@ -14,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)
@@ -35,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)
@@ -46,3 +47,40 @@ class ShareAttachment(Attachment):
 
     # Put here for backwards compatibility, so that the init argument order is preserved
     uid = attr.ib(None)
+
+    @classmethod
+    def _from_graphql(cls, data):
+        from . import _file
+
+        url = data.get("url")
+        rtn = cls(
+            uid=data.get("deduplication_key"),
+            author=data["target"]["actors"][0]["id"]
+            if data["target"].get("actors")
+            else None,
+            url=url,
+            original_url=_util.get_url_parameter(url, "u")
+            if "/l.php?u=" in url
+            else url,
+            title=data["title_with_entities"].get("text"),
+            description=data["description"].get("text")
+            if data.get("description")
+            else None,
+            source=data["source"].get("text") if data.get("source") else None,
+            attachments=[
+                _file.graphql_to_subattachment(attachment)
+                for attachment in data.get("subattachments")
+            ],
+        )
+        media = data.get("media")
+        if media and media.get("image"):
+            image = media["image"]
+            rtn.image_url = image.get("uri")
+            rtn.original_image_url = (
+                _util.get_url_parameter(rtn.image_url, "url")
+                if "/safe_image.php" in rtn.image_url
+                else rtn.image_url
+            )
+            rtn.image_width = image.get("width")
+            rtn.image_height = image.get("height")
+        return rtn

fbchat/_core.py

@@ -1,12 +1,26 @@
 # -*- coding: UTF-8 -*-
 from __future__ import unicode_literals
 
+import logging
 import aenum
 
+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:
         return "{}.{}".format(type(self).__name__, self.name)
+
+    @classmethod
+    def _extend_if_invalid(cls, value):
+        try:
+            return cls(value)
+        except ValueError:
+            log.warning(
+                "Failed parsing {.__name__}({!r}). Extending enum.".format(cls, value)
+            )
+            aenum.extend_enum(cls, "UNKNOWN_{}".format(value).upper(), value)
+            return cls(value)

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)
@@ -21,16 +21,25 @@ class FileAttachment(Attachment):
     # Put here for backwards compatibility, so that the init argument order is preserved
     uid = attr.ib(None)
 
+    @classmethod
+    def _from_graphql(cls, data):
+        return cls(
+            url=data.get("url"),
+            name=data.get("filename"),
+            is_malicious=data.get("is_malicious"),
+            uid=data.get("message_file_fbid"),
+        )
+
 
 @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)
@@ -38,16 +47,25 @@ class AudioAttachment(Attachment):
     # Put here for backwards compatibility, so that the init argument order is preserved
     uid = attr.ib(None)
 
+    @classmethod
+    def _from_graphql(cls, data):
+        return cls(
+            filename=data.get("filename"),
+            url=data.get("playable_url"),
+            duration=data.get("playable_duration_in_ms"),
+            audio_type=data.get("audio_type"),
+        )
+
 
 @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
-    it the uid of the image attachment
+    To retrieve the full image URL, use: `Client.fetchImageUrl`, and pass it the id of
+    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))
@@ -74,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)
@@ -122,10 +140,37 @@ class ImageAttachment(Attachment):
         self.animated_preview_width = animated_preview.get("width")
         self.animated_preview_height = animated_preview.get("height")
 
+    @classmethod
+    def _from_graphql(cls, data):
+        return cls(
+            original_extension=data.get("original_extension")
+            or (data["filename"].split("-")[0] if data.get("filename") else None),
+            width=data.get("original_dimensions", {}).get("width"),
+            height=data.get("original_dimensions", {}).get("height"),
+            is_animated=data["__typename"] == "MessageAnimatedImage",
+            thumbnail_url=data.get("thumbnail", {}).get("uri"),
+            preview=data.get("preview") or data.get("preview_image"),
+            large_preview=data.get("large_preview"),
+            animated_preview=data.get("animated_image"),
+            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)
@@ -195,3 +240,62 @@ class VideoAttachment(Attachment):
         self.large_image_url = large_image.get("uri")
         self.large_image_width = large_image.get("width")
         self.large_image_height = large_image.get("height")
+
+    @classmethod
+    def _from_graphql(cls, data):
+        return cls(
+            width=data.get("original_dimensions", {}).get("width"),
+            height=data.get("original_dimensions", {}).get("height"),
+            duration=data.get("playable_duration_in_ms"),
+            preview_url=data.get("playable_url"),
+            small_image=data.get("chat_image"),
+            medium_image=data.get("inbox_image"),
+            large_image=data.get("large_image"),
+            uid=data.get("legacy_attachment_id"),
+        )
+
+    @classmethod
+    def _from_subattachment(cls, data):
+        media = data["media"]
+        return cls(
+            duration=media.get("playable_duration_in_ms"),
+            preview_url=media.get("playable_url"),
+            medium_image=media.get("image"),
+            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"]
+    if _type in ["MessageImage", "MessageAnimatedImage"]:
+        return ImageAttachment._from_graphql(data)
+    elif _type == "MessageVideo":
+        return VideoAttachment._from_graphql(data)
+    elif _type == "MessageAudio":
+        return AudioAttachment._from_graphql(data)
+    elif _type == "MessageFile":
+        return FileAttachment._from_graphql(data)
+
+    return Attachment(uid=data.get("legacy_attachment_id"))
+
+
+def graphql_to_subattachment(data):
+    target = data.get("target")
+    type_ = target.get("__typename") if target else None
+
+    if type_ == "Video":
+        return VideoAttachment._from_subattachment(data)
+
+    return None

fbchat/_graphql.py

@@ -1,10 +1,10 @@
 # -*- coding: UTF-8 -*-
-
 from __future__ import unicode_literals
+
 import json
 import re
-from .models import *
-from ._util import *
+from . import _util
+from ._exception import FBchatException
 
 # Shameless copy from https://stackoverflow.com/a/8730674
 FLAGS = re.VERBOSE | re.MULTILINE | re.DOTALL
@@ -27,595 +27,18 @@ class ConcatJSONDecoder(json.JSONDecoder):
 # End shameless copy
 
 
-def graphql_color_to_enum(color):
-    if color is None:
-        return None
-    if not color:
-        return ThreadColor.MESSENGER_BLUE
-    color = color[2:]  # Strip the alpha value
-    color_value = "#{}".format(color.lower())
-    return enum_extend_if_invalid(ThreadColor, color_value)
-
-
-def get_customization_info(thread):
-    if thread is None or thread.get("customization_info") is None:
-        return {}
-    info = thread["customization_info"]
-
-    rtn = {
-        "emoji": info.get("emoji"),
-        "color": graphql_color_to_enum(info.get("outgoing_bubble_color")),
-    }
-    if (
-        thread.get("thread_type") == "GROUP"
-        or thread.get("is_group_thread")
-        or thread.get("thread_key", {}).get("thread_fbid")
-    ):
-        rtn["nicknames"] = {}
-        for k in info.get("participant_customizations", []):
-            rtn["nicknames"][k["participant_id"]] = k.get("nickname")
-    elif info.get("participant_customizations"):
-        uid = thread.get("thread_key", {}).get("other_user_id") or thread.get("id")
-        pc = info["participant_customizations"]
-        if len(pc) > 0:
-            if pc[0].get("participant_id") == uid:
-                rtn["nickname"] = pc[0].get("nickname")
-            else:
-                rtn["own_nickname"] = pc[0].get("nickname")
-        if len(pc) > 1:
-            if pc[1].get("participant_id") == uid:
-                rtn["nickname"] = pc[1].get("nickname")
-            else:
-                rtn["own_nickname"] = pc[1].get("nickname")
-    return rtn
-
-
-def graphql_to_sticker(s):
-    if not s:
-        return None
-    sticker = Sticker(uid=s["id"])
-    if s.get("pack"):
-        sticker.pack = s["pack"].get("id")
-    if s.get("sprite_image"):
-        sticker.is_animated = True
-        sticker.medium_sprite_image = s["sprite_image"].get("uri")
-        sticker.large_sprite_image = s["sprite_image_2x"].get("uri")
-        sticker.frames_per_row = s.get("frames_per_row")
-        sticker.frames_per_col = s.get("frames_per_column")
-        sticker.frame_rate = s.get("frame_rate")
-    sticker.url = s.get("url")
-    sticker.width = s.get("width")
-    sticker.height = s.get("height")
-    if s.get("label"):
-        sticker.label = s["label"]
-    return sticker
-
-
-def graphql_to_attachment(a):
-    _type = a["__typename"]
-    if _type in ["MessageImage", "MessageAnimatedImage"]:
-        return ImageAttachment(
-            original_extension=a.get("original_extension")
-            or (a["filename"].split("-")[0] if a.get("filename") else None),
-            width=a.get("original_dimensions", {}).get("width"),
-            height=a.get("original_dimensions", {}).get("height"),
-            is_animated=_type == "MessageAnimatedImage",
-            thumbnail_url=a.get("thumbnail", {}).get("uri"),
-            preview=a.get("preview") or a.get("preview_image"),
-            large_preview=a.get("large_preview"),
-            animated_preview=a.get("animated_image"),
-            uid=a.get("legacy_attachment_id"),
-        )
-    elif _type == "MessageVideo":
-        return VideoAttachment(
-            width=a.get("original_dimensions", {}).get("width"),
-            height=a.get("original_dimensions", {}).get("height"),
-            duration=a.get("playable_duration_in_ms"),
-            preview_url=a.get("playable_url"),
-            small_image=a.get("chat_image"),
-            medium_image=a.get("inbox_image"),
-            large_image=a.get("large_image"),
-            uid=a.get("legacy_attachment_id"),
-        )
-    elif _type == "MessageAudio":
-        return AudioAttachment(
-            filename=a.get("filename"),
-            url=a.get("playable_url"),
-            duration=a.get("playable_duration_in_ms"),
-            audio_type=a.get("audio_type"),
-        )
-    elif _type == "MessageFile":
-        return FileAttachment(
-            url=a.get("url"),
-            name=a.get("filename"),
-            is_malicious=a.get("is_malicious"),
-            uid=a.get("message_file_fbid"),
-        )
-    else:
-        return Attachment(uid=a.get("legacy_attachment_id"))
-
-
-def graphql_to_extensible_attachment(a):
-    story = a.get("story_attachment")
-    if story:
-        target = story.get("target")
-        if target:
-            _type = target["__typename"]
-            if _type == "MessageLocation":
-                url = story.get("url")
-                address = get_url_parameter(get_url_parameter(url, "u"), "where1")
-                try:
-                    latitude, longitude = [float(x) for x in address.split(", ")]
-                    address = None
-                except ValueError:
-                    latitude, longitude = None, None
-                rtn = LocationAttachment(
-                    uid=int(story["deduplication_key"]),
-                    latitude=latitude,
-                    longitude=longitude,
-                    address=address,
-                )
-                media = story.get("media")
-                if media and media.get("image"):
-                    image = media["image"]
-                    rtn.image_url = image.get("uri")
-                    rtn.image_width = image.get("width")
-                    rtn.image_height = image.get("height")
-                rtn.url = url
-                return rtn
-            elif _type == "MessageLiveLocation":
-                rtn = LiveLocationAttachment(
-                    uid=int(story["target"]["live_location_id"]),
-                    latitude=story["target"]["coordinate"]["latitude"]
-                    if story["target"].get("coordinate")
-                    else None,
-                    longitude=story["target"]["coordinate"]["longitude"]
-                    if story["target"].get("coordinate")
-                    else None,
-                    name=story["title_with_entities"]["text"],
-                    expiration_time=story["target"].get("expiration_time"),
-                    is_expired=story["target"].get("is_expired"),
-                )
-                media = story.get("media")
-                if media and media.get("image"):
-                    image = media["image"]
-                    rtn.image_url = image.get("uri")
-                    rtn.image_width = image.get("width")
-                    rtn.image_height = image.get("height")
-                rtn.url = story.get("url")
-                return rtn
-            elif _type in ["ExternalUrl", "Story"]:
-                url = story.get("url")
-                rtn = ShareAttachment(
-                    uid=a.get("legacy_attachment_id"),
-                    author=story["target"]["actors"][0]["id"]
-                    if story["target"].get("actors")
-                    else None,
-                    url=url,
-                    original_url=get_url_parameter(url, "u")
-                    if "/l.php?u=" in url
-                    else url,
-                    title=story["title_with_entities"].get("text"),
-                    description=story["description"].get("text")
-                    if story.get("description")
-                    else None,
-                    source=story["source"].get("text"),
-                    attachments=[
-                        graphql_to_subattachment(attachment)
-                        for attachment in story.get("subattachments")
-                    ],
-                )
-                media = story.get("media")
-                if media and media.get("image"):
-                    image = media["image"]
-                    rtn.image_url = image.get("uri")
-                    rtn.original_image_url = (
-                        get_url_parameter(rtn.image_url, "url")
-                        if "/safe_image.php" in rtn.image_url
-                        else rtn.image_url
-                    )
-                    rtn.image_width = image.get("width")
-                    rtn.image_height = image.get("height")
-                return rtn
-        else:
-            return UnsentMessage(uid=a.get("legacy_attachment_id"))
-
-
-def graphql_to_subattachment(a):
-    _type = a["target"]["__typename"]
-    if _type == "Video":
-        media = a["media"]
-        return VideoAttachment(
-            duration=media.get("playable_duration_in_ms"),
-            preview_url=media.get("playable_url"),
-            medium_image=media.get("image"),
-            uid=a["target"].get("video_id"),
-        )
-
-
-def graphql_to_live_location(a):
-    return LiveLocationAttachment(
-        uid=a["id"],
-        latitude=a["coordinate"]["latitude"] / (10 ** 8)
-        if not a.get("stopReason")
-        else None,
-        longitude=a["coordinate"]["longitude"] / (10 ** 8)
-        if not a.get("stopReason")
-        else None,
-        name=a.get("locationTitle"),
-        expiration_time=a["expirationTime"],
-        is_expired=bool(a.get("stopReason")),
-    )
-
-
-def graphql_to_poll(a):
-    rtn = Poll(
-        title=a.get("title") if a.get("title") else a.get("text"),
-        options=[graphql_to_poll_option(m) for m in a.get("options")],
-    )
-    rtn.uid = int(a["id"])
-    rtn.options_count = a.get("total_count")
-    return rtn
-
-
-def graphql_to_poll_option(a):
-    if a.get("viewer_has_voted") is None:
-        vote = None
-    elif isinstance(a["viewer_has_voted"], bool):
-        vote = a["viewer_has_voted"]
-    else:
-        vote = a["viewer_has_voted"] == "true"
-    rtn = PollOption(text=a.get("text"), vote=vote)
-    rtn.uid = int(a["id"])
-    rtn.voters = (
-        [m.get("node").get("id") for m in a.get("voters").get("edges")]
-        if isinstance(a.get("voters"), dict)
-        else a.get("voters")
-    )
-    rtn.votes_count = (
-        a.get("voters").get("count")
-        if isinstance(a.get("voters"), dict)
-        else a.get("total_count")
-    )
-    return rtn
-
-
-def graphql_to_plan(a):
-    if a.get("event_members"):
-        rtn = Plan(
-            time=a.get("event_time"),
-            title=a.get("title"),
-            location=a.get("location_name"),
-        )
-        if a.get("location_id") != 0:
-            rtn.location_id = str(a.get("location_id"))
-        rtn.uid = a.get("oid")
-        rtn.author_id = a.get("creator_id")
-        guests = a.get("event_members")
-        rtn.going = [uid for uid in guests if guests[uid] == "GOING"]
-        rtn.declined = [uid for uid in guests if guests[uid] == "DECLINED"]
-        rtn.invited = [uid for uid in guests if guests[uid] == "INVITED"]
-        return rtn
-    elif a.get("id") is None:
-        rtn = Plan(
-            time=a.get("event_time"),
-            title=a.get("event_title"),
-            location=a.get("event_location_name"),
-            location_id=a.get("event_location_id"),
-        )
-        rtn.uid = a.get("event_id")
-        rtn.author_id = a.get("event_creator_id")
-        guests = json.loads(a.get("guest_state_list"))
-    else:
-        rtn = Plan(
-            time=a.get("time"),
-            title=a.get("event_title"),
-            location=a.get("location_name"),
-        )
-        rtn.uid = a.get("id")
-        rtn.author_id = a.get("lightweight_event_creator").get("id")
-        guests = a.get("event_reminder_members").get("edges")
-    rtn.going = [
-        m.get("node").get("id") for m in guests if m.get("guest_list_state") == "GOING"
-    ]
-    rtn.declined = [
-        m.get("node").get("id")
-        for m in guests
-        if m.get("guest_list_state") == "DECLINED"
-    ]
-    rtn.invited = [
-        m.get("node").get("id")
-        for m in guests
-        if m.get("guest_list_state") == "INVITED"
-    ]
-    return rtn
-
-
-def graphql_to_quick_reply(q, is_response=False):
-    data = dict()
-    _type = q.get("content_type").lower()
-    if q.get("payload"):
-        data["payload"] = q["payload"]
-    if q.get("data"):
-        data["data"] = q["data"]
-    if q.get("image_url") and _type is not QuickReplyLocation._type:
-        data["image_url"] = q["image_url"]
-    data["is_response"] = is_response
-    if _type == QuickReplyText._type:
-        if q.get("title") is not None:
-            data["title"] = q["title"]
-        rtn = QuickReplyText(**data)
-    elif _type == QuickReplyLocation._type:
-        rtn = QuickReplyLocation(**data)
-    elif _type == QuickReplyPhoneNumber._type:
-        rtn = QuickReplyPhoneNumber(**data)
-    elif _type == QuickReplyEmail._type:
-        rtn = QuickReplyEmail(**data)
-    return rtn
-
-
-def graphql_to_message(message):
-    if message.get("message_sender") is None:
-        message["message_sender"] = {}
-    if message.get("message") is None:
-        message["message"] = {}
-    rtn = Message(
-        text=message.get("message").get("text"),
-        mentions=[
-            Mention(
-                m.get("entity", {}).get("id"),
-                offset=m.get("offset"),
-                length=m.get("length"),
-            )
-            for m in message.get("message").get("ranges", [])
-        ],
-        emoji_size=get_emojisize_from_tags(message.get("tags_list")),
-        sticker=graphql_to_sticker(message.get("sticker")),
-    )
-    rtn.uid = str(message.get("message_id"))
-    rtn.author = str(message.get("message_sender").get("id"))
-    rtn.timestamp = message.get("timestamp_precise")
-    rtn.unsent = False
-    if message.get("unread") is not None:
-        rtn.is_read = not message["unread"]
-    rtn.reactions = {
-        str(r["user"]["id"]): enum_extend_if_invalid(MessageReaction, r["reaction"])
-        for r in message.get("message_reactions")
-    }
-    if message.get("blob_attachments") is not None:
-        rtn.attachments = [
-            graphql_to_attachment(attachment)
-            for attachment in message["blob_attachments"]
-        ]
-    if message.get("platform_xmd_encoded"):
-        quick_replies = json.loads(message["platform_xmd_encoded"]).get("quick_replies")
-        if isinstance(quick_replies, list):
-            rtn.quick_replies = [graphql_to_quick_reply(q) for q in quick_replies]
-        elif isinstance(quick_replies, dict):
-            rtn.quick_replies = [
-                graphql_to_quick_reply(quick_replies, is_response=True)
-            ]
-    if message.get("extensible_attachment") is not None:
-        attachment = graphql_to_extensible_attachment(message["extensible_attachment"])
-        if isinstance(attachment, UnsentMessage):
-            rtn.unsent = True
-        elif attachment:
-            rtn.attachments.append(attachment)
-    if message.get("replied_to_message") is not None:
-        rtn.replied_to = graphql_to_message(message["replied_to_message"]["message"])
-    return rtn
-
-
-def graphql_to_message_reply(message):
-    rtn = Message(
-        text=message.get("body"),
-        mentions=[
-            Mention(m.get("i"), offset=m.get("o"), length=m.get("l"))
-            for m in json.loads(message.get("data", {}).get("prng", "[]"))
-        ],
-        emoji_size=get_emojisize_from_tags(message["messageMetadata"].get("tags")),
-    )
-    metadata = message.get("messageMetadata", {})
-    rtn.uid = metadata.get("messageId")
-    rtn.author = str(metadata.get("actorFbId"))
-    rtn.timestamp = metadata.get("timestamp")
-    rtn.unsent = False
-    if message.get("data", {}).get("platform_xmd"):
-        quick_replies = json.loads(message["data"]["platform_xmd"]).get("quick_replies")
-        if isinstance(quick_replies, list):
-            rtn.quick_replies = [graphql_to_quick_reply(q) for q in quick_replies]
-        elif isinstance(quick_replies, dict):
-            rtn.quick_replies = [
-                graphql_to_quick_reply(quick_replies, is_response=True)
-            ]
-    if message.get("attachments") is not None:
-        for attachment in message["attachments"]:
-            attachment = json.loads(attachment["mercuryJSON"])
-            if attachment.get("blob_attachment"):
-                rtn.attachments.append(
-                    graphql_to_attachment(attachment["blob_attachment"])
-                )
-            if attachment.get("extensible_attachment"):
-                extensible_attachment = graphql_to_extensible_attachment(
-                    attachment["extensible_attachment"]
-                )
-                if isinstance(extensible_attachment, UnsentMessage):
-                    rtn.unsent = True
-                else:
-                    rtn.attachments.append(extensible_attachment)
-            if attachment.get("sticker_attachment"):
-                rtn.sticker = graphql_to_sticker(attachment["sticker_attachment"])
-    return rtn
-
-
-def graphql_to_user(user):
-    if user.get("profile_picture") is None:
-        user["profile_picture"] = {}
-    c_info = get_customization_info(user)
-    plan = None
-    if user.get("event_reminders"):
-        plan = (
-            graphql_to_plan(user["event_reminders"]["nodes"][0])
-            if user["event_reminders"].get("nodes")
-            else None
-        )
-    return User(
-        user["id"],
-        url=user.get("url"),
-        first_name=user.get("first_name"),
-        last_name=user.get("last_name"),
-        is_friend=user.get("is_viewer_friend"),
-        gender=GENDERS.get(user.get("gender")),
-        affinity=user.get("affinity"),
-        nickname=c_info.get("nickname"),
-        color=c_info.get("color"),
-        emoji=c_info.get("emoji"),
-        own_nickname=c_info.get("own_nickname"),
-        photo=user["profile_picture"].get("uri"),
-        name=user.get("name"),
-        message_count=user.get("messages_count"),
-        plan=plan,
-    )
-
-
-def graphql_to_thread(thread):
-    if thread["thread_type"] == "GROUP":
-        return graphql_to_group(thread)
-    elif thread["thread_type"] == "ONE_TO_ONE":
-        if thread.get("big_image_src") is None:
-            thread["big_image_src"] = {}
-        c_info = get_customization_info(thread)
-        participants = [
-            node["messaging_actor"] for node in thread["all_participants"]["nodes"]
-        ]
-        user = next(
-            p for p in participants if p["id"] == thread["thread_key"]["other_user_id"]
-        )
-        last_message_timestamp = None
-        if "last_message" in thread:
-            last_message_timestamp = thread["last_message"]["nodes"][0][
-                "timestamp_precise"
-            ]
-
-        first_name = user.get("short_name")
-        if first_name is None:
-            last_name = None
-        else:
-            last_name = user.get("name").split(first_name, 1).pop().strip()
-
-        plan = None
-        if thread.get("event_reminders"):
-            plan = (
-                graphql_to_plan(thread["event_reminders"]["nodes"][0])
-                if thread["event_reminders"].get("nodes")
-                else None
-            )
-
-        return User(
-            user["id"],
-            url=user.get("url"),
-            name=user.get("name"),
-            first_name=first_name,
-            last_name=last_name,
-            is_friend=user.get("is_viewer_friend"),
-            gender=GENDERS.get(user.get("gender")),
-            affinity=user.get("affinity"),
-            nickname=c_info.get("nickname"),
-            color=c_info.get("color"),
-            emoji=c_info.get("emoji"),
-            own_nickname=c_info.get("own_nickname"),
-            photo=user["big_image_src"].get("uri"),
-            message_count=thread.get("messages_count"),
-            last_message_timestamp=last_message_timestamp,
-            plan=plan,
-        )
-    else:
-        raise FBchatException(
-            "Unknown thread type: {}, with data: {}".format(
-                thread.get("thread_type"), thread
-            )
-        )
-
-
-def graphql_to_group(group):
-    if group.get("image") is None:
-        group["image"] = {}
-    c_info = get_customization_info(group)
-    last_message_timestamp = None
-    if "last_message" in group:
-        last_message_timestamp = group["last_message"]["nodes"][0]["timestamp_precise"]
-    plan = None
-    if group.get("event_reminders"):
-        plan = (
-            graphql_to_plan(group["event_reminders"]["nodes"][0])
-            if group["event_reminders"].get("nodes")
-            else None
-        )
-    return Group(
-        group["thread_key"]["thread_fbid"],
-        participants=set(
-            [
-                node["messaging_actor"]["id"]
-                for node in group["all_participants"]["nodes"]
-            ]
-        ),
-        nicknames=c_info.get("nicknames"),
-        color=c_info.get("color"),
-        emoji=c_info.get("emoji"),
-        admins=set([node.get("id") for node in group.get("thread_admins")]),
-        approval_mode=bool(group.get("approval_mode"))
-        if group.get("approval_mode") is not None
-        else None,
-        approval_requests=set(
-            node["requester"]["id"] for node in group["group_approval_queue"]["nodes"]
-        )
-        if group.get("group_approval_queue")
-        else None,
-        join_link=group["joinable_mode"].get("link"),
-        photo=group["image"].get("uri"),
-        name=group.get("name"),
-        message_count=group.get("messages_count"),
-        last_message_timestamp=last_message_timestamp,
-        plan=plan,
-    )
-
-
-def graphql_to_page(page):
-    if page.get("profile_picture") is None:
-        page["profile_picture"] = {}
-    if page.get("city") is None:
-        page["city"] = {}
-    plan = None
-    if page.get("event_reminders"):
-        plan = (
-            graphql_to_plan(page["event_reminders"]["nodes"][0])
-            if page["event_reminders"].get("nodes")
-            else None
-        )
-    return Page(
-        page["id"],
-        url=page.get("url"),
-        city=page.get("city").get("name"),
-        category=page.get("category_type"),
-        photo=page["profile_picture"].get("uri"),
-        name=page.get("name"),
-        message_count=page.get("messages_count"),
-        plan=plan,
-    )
-
-
-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):
-    content = strip_to_json(content)  # Usually only needed in some error cases
+def response_to_json(content):
+    content = _util.strip_json_cruft(content)  # Usually only needed in some error cases
     try:
         j = json.loads(content, cls=ConcatJSONDecoder)
     except Exception:
@@ -626,184 +49,189 @@ def graphql_response_to_json(content):
         if "error_results" in x:
             del rtn[-1]
             continue
-        check_json(x)
+        _util.handle_payload_error(x)
         [(key, value)] = x.items()
-        check_json(value)
+        _util.handle_graphql_errors(value)
         if "response" in value:
             rtn[int(key[1:])] = value["response"]
         else:
             rtn[int(key[1:])] = value["data"]
 
-    log.debug(rtn)
+    _util.log.debug(rtn)
 
     return rtn
 
 
-class GraphQL(object):
-    def __init__(self, query=None, doc_id=None, params=None):
-        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")
+def from_query(query, params):
+    return {"priority": 0, "q": query, "query_params": params}
 
-    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 = """
-    QueryFragment Group: MessageThread {
-        name,
-        thread_key {
-            thread_fbid
-        },
-        image {
-            uri
-        },
-        is_group_thread,
-        all_participants {
-            nodes {
-                messaging_actor {
-                    id
-                }
+def from_query_id(query_id, params):
+    return {"query_id": query_id, "query_params": params}
+
+
+def from_doc(doc, params):
+    return {"doc": doc, "query_params": params}
+
+
+def from_doc_id(doc_id, params):
+    return {"doc_id": doc_id, "query_params": params}
+
+
+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 = """
+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 {
-            participant_customizations {
-                participant_id,
-                nickname
+        outgoing_bubble_color,
+        emoji
+    },
+    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,
-            emoji
-        },
-        thread_admins {
-            id
-        },
-        group_approval_queue {
+            time,
+            location_name,
+            event_title,
+            event_reminder_members {
+                edges {
+                    node {
+                        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 {
-                    id
-                }
+                @User
             }
-        },
-        approval_mode,
-        joinable_mode {
-            mode,
-            link
-        },
-        event_reminders {
+        }
+    }
+}
+"""
+    + FRAGMENT_USER
+)
+
+SEARCH_GROUP = (
+    """
+Query SearchGroup(<search> = '', <limit> = 10, <pic_size> = 32) {
+    viewer() {
+        message_threads.with_thread_name(<search>).last(<limit>) as groups {
             nodes {
-                id,
-                lightweight_event_creator {
-                    id
-                },
-                time,
-                location_name,
-                event_title,
-                event_reminder_members {
-                    edges {
-                        node {
-                            id
-                        },
-                        guest_list_state
-                    }
-                }
+                @Group
             }
         }
     }
-    """
+}
+"""
+    + FRAGMENT_GROUP
+)
 
-    FRAGMENT_PAGE = """
-    QueryFragment Page: Page {
-        id,
-        name,
-        profile_picture.width(32).height(32) {
-            uri
-        },
-        url,
-        category_type,
-        city {
-            name
-        }
-    }
+SEARCH_PAGE = (
     """
-
-    SEARCH_USER = (
-        """
-    Query SearchUser(<search> = '', <limit> = 10) {
-        entities_named(<search>) {
-            search_results.of_type(user).first(<limit>) as users {
-                nodes {
-                    @User
-                }
+Query SearchPage(<search> = '', <limit> = 10) {
+    entities_named(<search>) {
+        search_results.of_type(page).first(<limit>) as pages {
+            nodes {
+                @Page
             }
         }
     }
-    """
-        + FRAGMENT_USER
-    )
+}
+"""
+    + FRAGMENT_PAGE
+)
 
-    SEARCH_GROUP = (
-        """
-    Query SearchGroup(<search> = '', <limit> = 10, <pic_size> = 32) {
-        viewer() {
-            message_threads.with_thread_name(<search>).last(<limit>) as groups {
-                nodes {
-                    @Group
-                }
+SEARCH_THREAD = (
+    """
+Query SearchThread(<search> = '', <limit> = 10) {
+    entities_named(<search>) {
+        search_results.first(<limit>) as threads {
+            nodes {
+                __typename,
+                @User,
+                @Group,
+                @Page
             }
         }
     }
-    """
-        + FRAGMENT_GROUP
-    )
-
-    SEARCH_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
-    )
+}
+"""
+    + FRAGMENT_USER
+    + FRAGMENT_GROUP
+    + FRAGMENT_PAGE
+)

fbchat/_group.py

@@ -2,16 +2,17 @@
 from __future__ import unicode_literals
 
 import attr
+from . import _plan
 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)
@@ -60,10 +61,53 @@ class Group(Thread):
         self.approval_requests = approval_requests
         self.join_link = join_link
 
+    @classmethod
+    def _from_graphql(cls, data):
+        if data.get("image") is None:
+            data["image"] = {}
+        c_info = cls._parse_customization_info(data)
+        last_message_timestamp = None
+        if "last_message" in data:
+            last_message_timestamp = data["last_message"]["nodes"][0][
+                "timestamp_precise"
+            ]
+        plan = None
+        if data.get("event_reminders") and data["event_reminders"].get("nodes"):
+            plan = _plan.Plan._from_graphql(data["event_reminders"]["nodes"][0])
+
+        return cls(
+            data["thread_key"]["thread_fbid"],
+            participants=set(
+                [
+                    node["messaging_actor"]["id"]
+                    for node in data["all_participants"]["nodes"]
+                ]
+            ),
+            nicknames=c_info.get("nicknames"),
+            color=c_info.get("color"),
+            emoji=c_info.get("emoji"),
+            admins=set([node.get("id") for node in data.get("thread_admins")]),
+            approval_mode=bool(data.get("approval_mode"))
+            if data.get("approval_mode") is not None
+            else None,
+            approval_requests=set(
+                node["requester"]["id"]
+                for node in data["group_approval_queue"]["nodes"]
+            )
+            if data.get("group_approval_queue")
+            else None,
+            join_link=data["joinable_mode"].get("link"),
+            photo=data["image"].get("uri"),
+            name=data.get("name"),
+            message_count=data.get("messages_count"),
+            last_message_timestamp=last_message_timestamp,
+            plan=plan,
+        )
+
 
 @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

@@ -3,13 +3,14 @@ from __future__ import unicode_literals
 
 import attr
 from ._attachment import Attachment
+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
@@ -30,10 +31,34 @@ class LocationAttachment(Attachment):
     # Put here for backwards compatibility, so that the init argument order is preserved
     uid = attr.ib(None)
 
+    @classmethod
+    def _from_graphql(cls, data):
+        url = data.get("url")
+        address = _util.get_url_parameter(_util.get_url_parameter(url, "u"), "where1")
+        try:
+            latitude, longitude = [float(x) for x in address.split(", ")]
+            address = None
+        except ValueError:
+            latitude, longitude = None, None
+        rtn = cls(
+            uid=int(data["deduplication_key"]),
+            latitude=latitude,
+            longitude=longitude,
+            address=address,
+        )
+        media = data.get("media")
+        if media and media.get("image"):
+            image = media["image"]
+            rtn.image_url = image.get("uri")
+            rtn.image_width = image.get("width")
+            rtn.image_height = image.get("height")
+        rtn.url = url
+        return rtn
+
 
 @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)
@@ -46,3 +71,42 @@ class LiveLocationAttachment(LocationAttachment):
         super(LiveLocationAttachment, self).__init__(**kwargs)
         self.expiration_time = expiration_time
         self.is_expired = is_expired
+
+    @classmethod
+    def _from_pull(cls, data):
+        return cls(
+            uid=data["id"],
+            latitude=data["coordinate"]["latitude"] / (10 ** 8)
+            if not data.get("stopReason")
+            else None,
+            longitude=data["coordinate"]["longitude"] / (10 ** 8)
+            if not data.get("stopReason")
+            else None,
+            name=data.get("locationTitle"),
+            expiration_time=data["expirationTime"],
+            is_expired=bool(data.get("stopReason")),
+        )
+
+    @classmethod
+    def _from_graphql(cls, data):
+        target = data["target"]
+        rtn = cls(
+            uid=int(target["live_location_id"]),
+            latitude=target["coordinate"]["latitude"]
+            if target.get("coordinate")
+            else None,
+            longitude=target["coordinate"]["longitude"]
+            if target.get("coordinate")
+            else None,
+            name=data["title_with_entities"]["text"],
+            expiration_time=target.get("expiration_time"),
+            is_expired=target.get("is_expired"),
+        )
+        media = data.get("media")
+        if media and media.get("image"):
+            image = media["image"]
+            rtn.image_url = image.get("uri")
+            rtn.image_width = image.get("width")
+            rtn.image_height = image.get("height")
+        rtn.url = data.get("url")
+        return rtn

fbchat/_message.py

@@ -2,21 +2,40 @@
 from __future__ import unicode_literals
 
 import attr
+import json
 from string import Formatter
+from . import _util, _attachment, _location, _file, _quick_reply, _sticker
 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"
     SMALL = "369239263222822"
 
+    @classmethod
+    def _from_tags(cls, tags):
+        string_to_emojisize = {
+            "large": cls.LARGE,
+            "medium": cls.MEDIUM,
+            "small": cls.SMALL,
+            "l": cls.LARGE,
+            "m": cls.MEDIUM,
+            "s": cls.SMALL,
+        }
+        for tag in tags or ():
+            data = tag.split(":", maxsplit=1)
+            if len(data) > 1 and data[0] == "hot_emoji_size":
+                return string_to_emojisize.get(data[1])
+        return None
+
 
 class MessageReaction(Enum):
-    """Used to specify a message reaction"""
+    """Used to specify a message reaction."""
 
+    HEART = "❤"
     LOVE = "😍"
     SMILE = "😆"
     WOW = "😮"
@@ -28,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()
@@ -40,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)
@@ -56,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)
@@ -72,20 +91,20 @@ class Message(object):
     reply_to_id = attr.ib(None)
     #: Replied message
     replied_to = attr.ib(None, init=False)
+    #: Whether the message was forwarded
+    forwarded = attr.ib(False, init=False)
 
     @classmethod
     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()
@@ -125,3 +144,203 @@ class Message(object):
 
         message = cls(text=result, mentions=mentions)
         return message
+
+    @staticmethod
+    def _get_forwarded_from_tags(tags):
+        if tags is None:
+            return False
+        return any(map(lambda tag: "forward" in tag or "copy" in tag, tags))
+
+    @classmethod
+    def _from_graphql(cls, data):
+        if data.get("message_sender") is None:
+            data["message_sender"] = {}
+        if data.get("message") is None:
+            data["message"] = {}
+        tags = data.get("tags_list")
+        rtn = cls(
+            text=data["message"].get("text"),
+            mentions=[
+                Mention(
+                    m.get("entity", {}).get("id"),
+                    offset=m.get("offset"),
+                    length=m.get("length"),
+                )
+                for m in data["message"].get("ranges") or ()
+            ],
+            emoji_size=EmojiSize._from_tags(tags),
+            sticker=_sticker.Sticker._from_graphql(data.get("sticker")),
+        )
+        rtn.forwarded = cls._get_forwarded_from_tags(tags)
+        rtn.uid = str(data["message_id"])
+        rtn.author = str(data["message_sender"]["id"])
+        rtn.timestamp = data.get("timestamp_precise")
+        rtn.unsent = False
+        if data.get("unread") is not None:
+            rtn.is_read = not data["unread"]
+        rtn.reactions = {
+            str(r["user"]["id"]): MessageReaction._extend_if_invalid(r["reaction"])
+            for r in data["message_reactions"]
+        }
+        if data.get("blob_attachments") is not None:
+            rtn.attachments = [
+                _file.graphql_to_attachment(attachment)
+                for attachment in data["blob_attachments"]
+            ]
+        if data.get("platform_xmd_encoded"):
+            quick_replies = json.loads(data["platform_xmd_encoded"]).get(
+                "quick_replies"
+            )
+            if isinstance(quick_replies, list):
+                rtn.quick_replies = [
+                    _quick_reply.graphql_to_quick_reply(q) for q in quick_replies
+                ]
+            elif isinstance(quick_replies, dict):
+                rtn.quick_replies = [
+                    _quick_reply.graphql_to_quick_reply(quick_replies, is_response=True)
+                ]
+        if data.get("extensible_attachment") is not None:
+            attachment = graphql_to_extensible_attachment(data["extensible_attachment"])
+            if isinstance(attachment, _attachment.UnsentMessage):
+                rtn.unsent = True
+            elif attachment:
+                rtn.attachments.append(attachment)
+        if data.get("replied_to_message") is not None:
+            rtn.replied_to = cls._from_graphql(data["replied_to_message"]["message"])
+            rtn.reply_to_id = rtn.replied_to.uid
+        return rtn
+
+    @classmethod
+    def _from_reply(cls, data):
+        tags = data["messageMetadata"].get("tags")
+        rtn = cls(
+            text=data.get("body"),
+            mentions=[
+                Mention(m.get("i"), offset=m.get("o"), length=m.get("l"))
+                for m in json.loads(data.get("data", {}).get("prng", "[]"))
+            ],
+            emoji_size=EmojiSize._from_tags(tags),
+        )
+        metadata = data.get("messageMetadata", {})
+        rtn.forwarded = cls._get_forwarded_from_tags(tags)
+        rtn.uid = metadata.get("messageId")
+        rtn.author = str(metadata.get("actorFbId"))
+        rtn.timestamp = metadata.get("timestamp")
+        rtn.unsent = False
+        if data.get("data", {}).get("platform_xmd"):
+            quick_replies = json.loads(data["data"]["platform_xmd"]).get(
+                "quick_replies"
+            )
+            if isinstance(quick_replies, list):
+                rtn.quick_replies = [
+                    _quick_reply.graphql_to_quick_reply(q) for q in quick_replies
+                ]
+            elif isinstance(quick_replies, dict):
+                rtn.quick_replies = [
+                    _quick_reply.graphql_to_quick_reply(quick_replies, is_response=True)
+                ]
+        if data.get("attachments") is not None:
+            for attachment in data["attachments"]:
+                attachment = json.loads(attachment["mercuryJSON"])
+                if attachment.get("blob_attachment"):
+                    rtn.attachments.append(
+                        _file.graphql_to_attachment(attachment["blob_attachment"])
+                    )
+                if attachment.get("extensible_attachment"):
+                    extensible_attachment = graphql_to_extensible_attachment(
+                        attachment["extensible_attachment"]
+                    )
+                    if isinstance(extensible_attachment, _attachment.UnsentMessage):
+                        rtn.unsent = True
+                    else:
+                        rtn.attachments.append(extensible_attachment)
+                if attachment.get("sticker_attachment"):
+                    rtn.sticker = _sticker.Sticker._from_graphql(
+                        attachment["sticker_attachment"]
+                    )
+        return rtn
+
+    @classmethod
+    def _from_pull(cls, data, mid=None, tags=None, author=None, timestamp=None):
+        rtn = cls(text=data.get("body"))
+        rtn.uid = mid
+        rtn.author = author
+        rtn.timestamp = timestamp
+
+        if data.get("data") and data["data"].get("prng"):
+            try:
+                rtn.mentions = [
+                    Mention(
+                        str(mention.get("i")),
+                        offset=mention.get("o"),
+                        length=mention.get("l"),
+                    )
+                    for mention in _util.parse_json(data["data"]["prng"])
+                ]
+            except Exception:
+                _util.log.exception("An exception occured while reading attachments")
+
+        if data.get("attachments"):
+            try:
+                for a in data["attachments"]:
+                    mercury = a["mercury"]
+                    if mercury.get("blob_attachment"):
+                        image_metadata = a.get("imageMetadata", {})
+                        attach_type = mercury["blob_attachment"]["__typename"]
+                        attachment = _file.graphql_to_attachment(
+                            mercury["blob_attachment"]
+                        )
+
+                        if attach_type in [
+                            "MessageFile",
+                            "MessageVideo",
+                            "MessageAudio",
+                        ]:
+                            # TODO: Add more data here for audio files
+                            attachment.size = int(a["fileSize"])
+                        rtn.attachments.append(attachment)
+
+                    elif mercury.get("sticker_attachment"):
+                        rtn.sticker = _sticker.Sticker._from_graphql(
+                            mercury["sticker_attachment"]
+                        )
+
+                    elif mercury.get("extensible_attachment"):
+                        attachment = graphql_to_extensible_attachment(
+                            mercury["extensible_attachment"]
+                        )
+                        if isinstance(attachment, _attachment.UnsentMessage):
+                            rtn.unsent = True
+                        elif attachment:
+                            rtn.attachments.append(attachment)
+
+            except Exception:
+                _util.log.exception(
+                    "An exception occured while reading attachments: {}".format(
+                        data["attachments"]
+                    )
+                )
+
+        rtn.emoji_size = EmojiSize._from_tags(tags)
+        rtn.forwarded = cls._get_forwarded_from_tags(tags)
+        return rtn
+
+
+def graphql_to_extensible_attachment(data):
+    story = data.get("story_attachment")
+    if not story:
+        return None
+
+    target = story.get("target")
+    if not target:
+        return _attachment.UnsentMessage(uid=data.get("legacy_attachment_id"))
+
+    _type = target["__typename"]
+    if _type == "MessageLocation":
+        return _location.LocationAttachment._from_graphql(story)
+    elif _type == "MessageLiveLocation":
+        return _location.LiveLocationAttachment._from_graphql(story)
+    elif _type in ["ExternalUrl", "Story"]:
+        return _attachment.ShareAttachment._from_graphql(story)
+
+    return None

fbchat/_page.py

@@ -2,14 +2,15 @@
 from __future__ import unicode_literals
 
 import attr
+from . import _plan
 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)
@@ -36,3 +37,24 @@ class Page(Thread):
         self.likes = likes
         self.sub_title = sub_title
         self.category = category
+
+    @classmethod
+    def _from_graphql(cls, data):
+        if data.get("profile_picture") is None:
+            data["profile_picture"] = {}
+        if data.get("city") is None:
+            data["city"] = {}
+        plan = None
+        if data.get("event_reminders") and data["event_reminders"].get("nodes"):
+            plan = _plan.Plan._from_graphql(data["event_reminders"]["nodes"][0])
+
+        return cls(
+            data["id"],
+            url=data.get("url"),
+            city=data.get("city").get("name"),
+            category=data.get("category_type"),
+            photo=data["profile_picture"].get("uri"),
+            name=data.get("name"),
+            message_count=data.get("messages_count"),
+            plan=plan,
+        )

fbchat/_plan.py

@@ -2,15 +2,23 @@
 from __future__ import unicode_literals
 
 import attr
+import json
+from ._core import Enum
+
+
+class GuestStatus(Enum):
+    INVITED = 1
+    GOING = 2
+    DECLINED = 3
 
 
 @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()
@@ -20,9 +28,76 @@ 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)
-    #: List of the people IDs who will take part in the plan
-    going = attr.ib(factory=list, init=False)
-    #: List of the people IDs who won't take part in the plan
-    declined = attr.ib(factory=list, init=False)
-    #: List of the people IDs who are invited to the plan
-    invited = attr.ib(factory=list, init=False)
+    #: Dictionary of `User` IDs mapped to their `GuestStatus`
+    guests = attr.ib(None, init=False)
+
+    @property
+    def going(self):
+        """List of the `User` IDs who will take part in the plan."""
+        return [
+            id_
+            for id_, status in (self.guests or {}).items()
+            if status is GuestStatus.GOING
+        ]
+
+    @property
+    def declined(self):
+        """List of the `User` IDs who won't take part in the plan."""
+        return [
+            id_
+            for id_, status in (self.guests or {}).items()
+            if status is GuestStatus.DECLINED
+        ]
+
+    @property
+    def invited(self):
+        """List of the `User` IDs who are invited to the plan."""
+        return [
+            id_
+            for id_, status in (self.guests or {}).items()
+            if status is GuestStatus.INVITED
+        ]
+
+    @classmethod
+    def _from_pull(cls, data):
+        rtn = cls(
+            time=data.get("event_time"),
+            title=data.get("event_title"),
+            location=data.get("event_location_name"),
+            location_id=data.get("event_location_id"),
+        )
+        rtn.uid = data.get("event_id")
+        rtn.author_id = data.get("event_creator_id")
+        rtn.guests = {
+            x["node"]["id"]: GuestStatus[x["guest_list_state"]]
+            for x in json.loads(data["guest_state_list"])
+        }
+        return rtn
+
+    @classmethod
+    def _from_fetch(cls, data):
+        rtn = cls(
+            time=data.get("event_time"),
+            title=data.get("title"),
+            location=data.get("location_name"),
+            location_id=str(data["location_id"]) if data.get("location_id") else None,
+        )
+        rtn.uid = data.get("oid")
+        rtn.author_id = data.get("creator_id")
+        rtn.guests = {id_: GuestStatus[s] for id_, s in data["event_members"].items()}
+        return rtn
+
+    @classmethod
+    def _from_graphql(cls, data):
+        rtn = cls(
+            time=data.get("time"),
+            title=data.get("event_title"),
+            location=data.get("location_name"),
+        )
+        rtn.uid = data.get("id")
+        rtn.author_id = data["lightweight_event_creator"].get("id")
+        rtn.guests = {
+            x["node"]["id"]: GuestStatus[x["guest_list_state"]]
+            for x in data["event_reminder_members"]["edges"]
+        }
+        return rtn

fbchat/_poll.py

@@ -6,29 +6,62 @@ import attr
 
 @attr.s(cmp=False)
 class Poll(object):
-    """Represents a poll"""
+    """Represents a poll."""
 
-    #: ID of the poll
-    uid = attr.ib(None, init=False)
     #: Title of the poll
     title = attr.ib()
     #: List of :class:`PollOption`, can be fetched with :func:`fbchat.Client.fetchPollOptions`
     options = attr.ib()
     #: Options count
-    options_count = attr.ib(None, init=False)
+    options_count = attr.ib(None)
+    #: ID of the poll
+    uid = attr.ib(None)
+
+    @classmethod
+    def _from_graphql(cls, data):
+        return cls(
+            uid=int(data["id"]),
+            title=data.get("title") if data.get("title") else data.get("text"),
+            options=[PollOption._from_graphql(m) for m in data.get("options")],
+            options_count=data.get("total_count"),
+        )
 
 
 @attr.s(cmp=False)
 class PollOption(object):
-    """Represents a poll option"""
+    """Represents a poll option."""
 
-    #: ID of the poll option
-    uid = attr.ib(None, init=False)
     #: Text of the poll option
     text = attr.ib()
     #: Whether vote when creating or client voted
     vote = attr.ib(False)
     #: ID of the users who voted for this poll option
-    voters = attr.ib(None, init=False)
+    voters = attr.ib(None)
     #: Votes count
-    votes_count = attr.ib(None, init=False)
+    votes_count = attr.ib(None)
+    #: ID of the poll option
+    uid = attr.ib(None)
+
+    @classmethod
+    def _from_graphql(cls, data):
+        if data.get("viewer_has_voted") is None:
+            vote = None
+        elif isinstance(data["viewer_has_voted"], bool):
+            vote = data["viewer_has_voted"]
+        else:
+            vote = data["viewer_has_voted"] == "true"
+        return cls(
+            uid=int(data["id"]),
+            text=data.get("text"),
+            vote=vote,
+            voters=(
+                [m.get("node").get("id") for m in data.get("voters").get("edges")]
+                if isinstance(data.get("voters"), dict)
+                else data.get("voters")
+            ),
+            votes_count=(
+                data.get("voters").get("count")
+                if isinstance(data.get("voters"), dict)
+                else data.get("total_count")
+            ),
+        )

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)
@@ -74,3 +74,26 @@ class QuickReplyEmail(QuickReply):
     def __init__(self, image_url=None, **kwargs):
         super(QuickReplyEmail, self).__init__(**kwargs)
         self.image_url = image_url
+
+
+def graphql_to_quick_reply(q, is_response=False):
+    data = dict()
+    _type = q.get("content_type").lower()
+    if q.get("payload"):
+        data["payload"] = q["payload"]
+    if q.get("data"):
+        data["data"] = q["data"]
+    if q.get("image_url") and _type is not QuickReplyLocation._type:
+        data["image_url"] = q["image_url"]
+    data["is_response"] = is_response
+    if _type == QuickReplyText._type:
+        if q.get("title") is not None:
+            data["title"] = q["title"]
+        rtn = QuickReplyText(**data)
+    elif _type == QuickReplyLocation._type:
+        rtn = QuickReplyLocation(**data)
+    elif _type == QuickReplyPhoneNumber._type:
+        rtn = QuickReplyPhoneNumber(**data)
+    elif _type == QuickReplyEmail._type:
+        rtn = QuickReplyEmail(**data)
+    return rtn

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)
@@ -37,3 +37,24 @@ class Sticker(Attachment):
 
     def __init__(self, uid=None):
         super(Sticker, self).__init__(uid=uid)
+
+    @classmethod
+    def _from_graphql(cls, data):
+        if not data:
+            return None
+        self = cls(uid=data["id"])
+        if data.get("pack"):
+            self.pack = data["pack"].get("id")
+        if data.get("sprite_image"):
+            self.is_animated = True
+            self.medium_sprite_image = data["sprite_image"].get("uri")
+            self.large_sprite_image = data["sprite_image_2x"].get("uri")
+            self.frames_per_row = data.get("frames_per_row")
+            self.frames_per_col = data.get("frames_per_column")
+            self.frame_rate = data.get("frame_rate")
+        self.url = data.get("url")
+        self.width = data.get("width")
+        self.height = data.get("height")
+        if data.get("label"):
+            self.label = data["label"]
+        return self

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"
@@ -47,16 +50,26 @@ class ThreadColor(Enum):
     DARK_TANGERINE = "#ff9c19"
     BRIGHT_TURQUOISE = "#0edcde"
 
+    @classmethod
+    def _from_graphql(cls, color):
+        if color is None:
+            return None
+        if not color:
+            return cls.MESSENGER_BLUE
+        color = color[2:]  # Strip the alpha value
+        value = "#{}".format(color.lower())
+        return cls._extend_if_invalid(value)
+
 
 @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)
@@ -84,3 +97,36 @@ class Thread(object):
         self.last_message_timestamp = last_message_timestamp
         self.message_count = message_count
         self.plan = plan
+
+    @staticmethod
+    def _parse_customization_info(data):
+        if data is None or data.get("customization_info") is None:
+            return {}
+        info = data["customization_info"]
+
+        rtn = {
+            "emoji": info.get("emoji"),
+            "color": ThreadColor._from_graphql(info.get("outgoing_bubble_color")),
+        }
+        if (
+            data.get("thread_type") == "GROUP"
+            or data.get("is_group_thread")
+            or data.get("thread_key", {}).get("thread_fbid")
+        ):
+            rtn["nicknames"] = {}
+            for k in info.get("participant_customizations", []):
+                rtn["nicknames"][k["participant_id"]] = k.get("nickname")
+        elif info.get("participant_customizations"):
+            uid = data.get("thread_key", {}).get("other_user_id") or data.get("id")
+            pc = info["participant_customizations"]
+            if len(pc) > 0:
+                if pc[0].get("participant_id") == uid:
+                    rtn["nickname"] = pc[0].get("nickname")
+                else:
+                    rtn["own_nickname"] = pc[0].get("nickname")
+            if len(pc) > 1:
+                if pc[1].get("participant_id") == uid:
+                    rtn["nickname"] = pc[1].get("nickname")
+                else:
+                    rtn["own_nickname"] = pc[1].get("nickname")
+        return rtn

fbchat/_user.py

@@ -3,11 +3,42 @@ from __future__ import unicode_literals
 
 import attr
 from ._core import Enum
+from . import _plan
 from ._thread import ThreadType, Thread
 
 
+GENDERS = {
+    # For standard requests
+    0: "unknown",
+    1: "female_singular",
+    2: "male_singular",
+    3: "female_singular_guess",
+    4: "male_singular_guess",
+    5: "mixed",
+    6: "neuter_singular",
+    7: "unknown_singular",
+    8: "female_plural",
+    9: "male_plural",
+    10: "neuter_plural",
+    11: "unknown_plural",
+    # For graphql requests
+    "UNKNOWN": "unknown",
+    "FEMALE": "female_singular",
+    "MALE": "male_singular",
+    # '': 'female_singular_guess',
+    # '': 'male_singular_guess',
+    # '': 'mixed',
+    "NEUTER": "neuter_singular",
+    # '': 'unknown_singular',
+    # '': 'female_plural',
+    # '': 'male_plural',
+    # '': 'neuter_plural',
+    # '': 'unknown_plural',
+}
+
+
 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
@@ -15,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)
@@ -65,6 +96,91 @@ class User(Thread):
         self.color = color
         self.emoji = emoji
 
+    @classmethod
+    def _from_graphql(cls, data):
+        if data.get("profile_picture") is None:
+            data["profile_picture"] = {}
+        c_info = cls._parse_customization_info(data)
+        plan = None
+        if data.get("event_reminders") and data["event_reminders"].get("nodes"):
+            plan = _plan.Plan._from_graphql(data["event_reminders"]["nodes"][0])
+
+        return cls(
+            data["id"],
+            url=data.get("url"),
+            first_name=data.get("first_name"),
+            last_name=data.get("last_name"),
+            is_friend=data.get("is_viewer_friend"),
+            gender=GENDERS.get(data.get("gender")),
+            affinity=data.get("affinity"),
+            nickname=c_info.get("nickname"),
+            color=c_info.get("color"),
+            emoji=c_info.get("emoji"),
+            own_nickname=c_info.get("own_nickname"),
+            photo=data["profile_picture"].get("uri"),
+            name=data.get("name"),
+            message_count=data.get("messages_count"),
+            plan=plan,
+        )
+
+    @classmethod
+    def _from_thread_fetch(cls, data):
+        if data.get("big_image_src") is None:
+            data["big_image_src"] = {}
+        c_info = cls._parse_customization_info(data)
+        participants = [
+            node["messaging_actor"] for node in data["all_participants"]["nodes"]
+        ]
+        user = next(
+            p for p in participants if p["id"] == data["thread_key"]["other_user_id"]
+        )
+        last_message_timestamp = None
+        if "last_message" in data:
+            last_message_timestamp = data["last_message"]["nodes"][0][
+                "timestamp_precise"
+            ]
+
+        first_name = user.get("short_name")
+        if first_name is None:
+            last_name = None
+        else:
+            last_name = user.get("name").split(first_name, 1).pop().strip()
+
+        plan = None
+        if data.get("event_reminders") and data["event_reminders"].get("nodes"):
+            plan = _plan.Plan._from_graphql(data["event_reminders"]["nodes"][0])
+
+        return cls(
+            user["id"],
+            url=user.get("url"),
+            name=user.get("name"),
+            first_name=first_name,
+            last_name=last_name,
+            is_friend=user.get("is_viewer_friend"),
+            gender=GENDERS.get(user.get("gender")),
+            affinity=user.get("affinity"),
+            nickname=c_info.get("nickname"),
+            color=c_info.get("color"),
+            emoji=c_info.get("emoji"),
+            own_nickname=c_info.get("own_nickname"),
+            photo=user["big_image_src"].get("uri"),
+            message_count=data.get("messages_count"),
+            last_message_timestamp=last_message_timestamp,
+            plan=plan,
+        )
+
+    @classmethod
+    def _from_all_fetch(cls, data):
+        return cls(
+            data["id"],
+            first_name=data.get("firstName"),
+            url=data.get("uri"),
+            photo=data.get("thumbSrc"),
+            name=data.get("name"),
+            is_friend=data.get("is_friend"),
+            gender=GENDERS.get(data.get("gender")),
+        )
+
 
 @attr.s(cmp=False)
 class ActiveStatus(object):
@@ -74,3 +190,19 @@ class ActiveStatus(object):
     last_active = attr.ib(None)
     #: Whether the user is playing Messenger game now
     in_game = attr.ib(None)
+
+    @classmethod
+    def _from_chatproxy_presence(cls, id_, data):
+        return cls(
+            active=data["p"] in [2, 3] if "p" in data else None,
+            last_active=data.get("lat"),
+            in_game=int(id_) in data.get("gamers", {}),
+        )
+
+    @classmethod
+    def _from_buddylist_overlay(cls, data, in_game=None):
+        return cls(
+            active=data["a"] in [2, 3] if "a" in data else None,
+            last_active=data.get("la"),
+            in_game=None,
+        )

fbchat/_util.py

@@ -11,8 +11,13 @@ from os.path import basename
 import warnings
 import logging
 import requests
-import aenum
-from .models import *
+from ._exception import (
+    FBchatException,
+    FBchatFacebookError,
+    FBchatInvalidParameters,
+    FBchatNotLoggedIn,
+    FBchatPleaseRefresh,
+)
 
 try:
     from urllib.parse import urlencode, parse_qs, urlparse
@@ -47,135 +52,13 @@ USER_AGENTS = [
     "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.6 (KHTML, like Gecko) Chrome/20.0.1092.0 Safari/536.6",
 ]
 
-LIKES = {
-    "large": EmojiSize.LARGE,
-    "medium": EmojiSize.MEDIUM,
-    "small": EmojiSize.SMALL,
-    "l": EmojiSize.LARGE,
-    "m": EmojiSize.MEDIUM,
-    "s": EmojiSize.SMALL,
-}
-
-
-GENDERS = {
-    # For standard requests
-    0: "unknown",
-    1: "female_singular",
-    2: "male_singular",
-    3: "female_singular_guess",
-    4: "male_singular_guess",
-    5: "mixed",
-    6: "neuter_singular",
-    7: "unknown_singular",
-    8: "female_plural",
-    9: "male_plural",
-    10: "neuter_plural",
-    11: "unknown_plural",
-    # For graphql requests
-    "UNKNOWN": "unknown",
-    "FEMALE": "female_singular",
-    "MALE": "male_singular",
-    # '': 'female_singular_guess',
-    # '': 'male_singular_guess',
-    # '': 'mixed',
-    "NEUTER": "neuter_singular",
-    # '': 'unknown_singular',
-    # '': 'female_plural',
-    # '': 'male_plural',
-    # '': 'neuter_plural',
-    # '': 'unknown_plural',
-}
-
-
-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"
-
-    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:
@@ -187,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)
-
-
-def get_json(r):
-    return json.loads(strip_to_json(get_decoded_r(r)))
+    try:
+        return json.loads(content)
+    except ValueError:
+        raise FBchatFacebookError("Error while parsing JSON: {!r}".format(content))
 
 
 def digitToChar(digit):
@@ -231,55 +113,74 @@ def generateOfflineThreadingID():
     return str(int(msgs, 2))
 
 
-def check_json(j):
-    if j.get("error") is None:
+def handle_payload_error(j):
+    if "error" not in j:
         return
-    if "errorDescription" in j:
-        # 'errorDescription' is in the users own language!
-        raise FBchatFacebookError(
-            "Error #{} when sending request: {}".format(
-                j["error"], j["errorDescription"]
-            ),
-            fb_error_code=j["error"],
-            fb_error_message=j["errorDescription"],
-        )
-    elif "debug_info" in j["error"] and "code" in j["error"]:
-        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"],
-        )
+    error = j["error"]
+    if j["error"] == 1357001:
+        error_cls = FBchatNotLoggedIn
+    elif j["error"] == 1357004:
+        error_cls = FBchatPleaseRefresh
+    elif j["error"] in (1357031, 1545010, 1545003):
+        error_cls = FBchatInvalidParameters
     else:
+        error_cls = FBchatFacebookError
+    # TODO: Use j["errorSummary"]
+    # "errorDescription" is in the users own language!
+    raise error_cls(
+        "Error #{} when sending request: {}".format(error, j["errorDescription"]),
+        fb_error_code=error,
+        fb_error_message=j["errorDescription"],
+    )
+
+
+def handle_graphql_errors(j):
+    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".format(j["error"]), fb_error_code=j["error"]
+            "GraphQL error #{}: {} / {!r}".format(
+                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, as_json=True):
-    if not r.ok:
-        raise FBchatFacebookError(
-            "Error when sending request: Got {} response".format(r.status_code),
-            request_status_code=r.status_code,
-        )
-
+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)
-        try:
-            j = json.loads(content)
-        except ValueError:
-            raise FBchatFacebookError("Error while parsing JSON: {!r}".format(content))
-        check_json(j)
-        log.debug(j)
-        return j
-    else:
-        return content
+
+def to_json(content):
+    content = strip_json_cruft(content)
+    j = parse_json(content)
+    log.debug(j)
+    return j
 
 
 def get_jsmods_require(j, index):
@@ -288,23 +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(
-                    j
-                )
-            )
-    return None
-
-
-def get_emojisize_from_tags(tags):
-    if tags is None:
-        return None
-    tmp = [tag for tag in tags if tag.startswith("hot_emoji_size:")]
-    if len(tmp) > 0:
-        try:
-            return LIKES[tmp[0].split(":")[1]]
-        except (KeyError, IndexError):
-            log.exception(
-                "Could not determine emoji size from {} - {}".format(tags, tmp)
+                "Error when getting jsmods_require: "
+                "{}. Facebook might have changed protocol".format(j)
             )
     return None
 
@@ -335,7 +221,7 @@ def get_files_from_urls(file_urls):
         # https://stackoverflow.com/a/37060758
         files.append(
             (
-                basename(file_url),
+                basename(file_url).split("?")[0].split("#")[0],
                 r.content,
                 r.headers.get("Content-Type") or guess_type(file_url)[0],
             )
@@ -355,19 +241,6 @@ def get_files_from_paths(filenames):
         fp.close()
 
 
-def enum_extend_if_invalid(enumeration, value):
-    try:
-        return enumeration(value)
-    except ValueError:
-        log.warning(
-            "Failed parsing {.__name__}({!r}). Extending enum.".format(
-                enumeration, value
-            )
-        )
-        aenum.extend_enum(enumeration, "UNKNOWN_{}".format(value).upper(), value)
-        return enumeration(value)
-
-
 def get_url_parameters(url, *args):
     params = parse_qs(urlparse(url).query)
     return [params[arg][0] for arg in args if params.get(arg)]
@@ -375,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

fbchat/client.py

@@ -1,8 +0,0 @@
-# -*- coding: UTF-8 -*-
-"""This file is here to maintain backwards compatability."""
-from __future__ import unicode_literals
-
-from .utils import *
-from .models import *
-from .graphql import *
-from ._client import Client

fbchat/graphql.py

@@ -1,31 +0,0 @@
-# -*- coding: UTF-8 -*-
-"""This file is here to maintain backwards compatability."""
-from __future__ import unicode_literals
-
-from .models import *
-from .utils import *
-from ._graphql import (
-    FLAGS,
-    WHITESPACE,
-    ConcatJSONDecoder,
-    graphql_color_to_enum,
-    get_customization_info,
-    graphql_to_sticker,
-    graphql_to_attachment,
-    graphql_to_extensible_attachment,
-    graphql_to_subattachment,
-    graphql_to_live_location,
-    graphql_to_poll,
-    graphql_to_poll_option,
-    graphql_to_plan,
-    graphql_to_quick_reply,
-    graphql_to_message,
-    graphql_to_message_reply,
-    graphql_to_user,
-    graphql_to_thread,
-    graphql_to_group,
-    graphql_to_page,
-    graphql_queries_to_json,
-    graphql_response_to_json,
-    GraphQL,
-)

fbchat/models.py

@@ -26,4 +26,4 @@ from ._quick_reply import (
     QuickReplyEmail,
 )
 from ._poll import Poll, PollOption
-from ._plan import Plan
+from ._plan import GuestStatus, Plan

fbchat/utils.py

@@ -1,36 +0,0 @@
-# -*- coding: UTF-8 -*-
-"""This file is here to maintain backwards compatability."""
-from __future__ import unicode_literals
-
-from .models import *
-from ._util import (
-    log,
-    handler,
-    USER_AGENTS,
-    LIKES,
-    GENDERS,
-    ReqUrl,
-    facebookEncoding,
-    now,
-    strip_to_json,
-    get_decoded_r,
-    get_decoded,
-    parse_json,
-    get_json,
-    digitToChar,
-    str_base,
-    generateMessageID,
-    getSignatureID,
-    generateOfflineThreadingID,
-    check_json,
-    check_request,
-    get_jsmods_require,
-    get_emojisize_from_tags,
-    require_list,
-    mimetype_to_key,
-    get_files_from_urls,
-    get_files_from_paths,
-    enum_extend_if_invalid,
-    get_url_parameters,
-    get_url_parameter,
-)

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",
-    "attrs~=18.2.0",
-    "requests",
-    "beautifulsoup4",
+    "aenum~=2.0",
+    "attrs>=18.2",
+    "requests~=2.19",
+    "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",
 ]