Bump version: 1.8.1 → 1.8.2

Fixes #469

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.7.2
+current_version = 1.8.2
 commit = True
 tag = True
 

.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

.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
 

docs/conf.py

@@ -41,6 +41,8 @@ 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.
@@ -93,8 +95,6 @@ html_theme_options = {
     "show_related": False,
 }
 
-html_extra_path = ["robots.txt"]
-
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -182,3 +182,27 @@ intersphinx_mapping = {"https://docs.python.org/": None}
 
 # 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

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

docs/faq.rst

@@ -9,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
 
@@ -28,7 +28,7 @@ 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

@@ -6,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`)
 
@@ -35,7 +35,7 @@ This means doing the exact same GET/POST requests and tricking Facebook into thi
 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,
@@ -44,7 +44,7 @@ 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``
 

docs/install.rst

@@ -3,10 +3,10 @@
 Installation
 ============
 
-Pip Install fbchat
-------------------
+Install using pip
+-----------------
 
-To install fbchat, run this command:
+To install ``fbchat``, run this command:
 
 .. code-block:: sh
 
@@ -19,7 +19,7 @@ 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:

docs/intro.rst

@@ -24,7 +24,7 @@ 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`)
 
@@ -125,8 +125,8 @@ 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
 
@@ -154,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:
@@ -192,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/robots.txt

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

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/todo.rst

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

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

fbchat/_attachment.py

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

fbchat/_core.py

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

fbchat/_exception.py

@@ -3,7 +3,10 @@ from __future__ import unicode_literals
 
 
 class FBchatException(Exception):
-    """Custom exception thrown by fbchat. All exceptions in the fbchat module inherits this"""
+    """Custom exception thrown by ``fbchat``.
+
+    All exceptions in the ``fbchat`` module inherits this.
+    """
 
 
 class FBchatFacebookError(FBchatException):
@@ -11,7 +14,7 @@ class FBchatFacebookError(FBchatException):
     fb_error_code = None
     #: The error message that Facebook returned (In the user's own language)
     fb_error_message = None
-    #: The status code that was sent in the http response (eg. 404) (Usually only set if not successful, aka. not 200)
+    #: The status code that was sent in the HTTP response (e.g. 404) (Usually only set if not successful, aka. not 200)
     request_status_code = None
 
     def __init__(
@@ -22,7 +25,7 @@ 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
@@ -54,4 +57,4 @@ class FBchatPleaseRefresh(FBchatFacebookError):
 
 
 class FBchatUserError(FBchatException):
-    """Thrown by fbchat when wrong values are entered"""
+    """Thrown by ``fbchat`` when wrong values are entered."""

fbchat/_file.py

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

fbchat/_group.py

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

fbchat/_location.py

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

fbchat/_message.py

@@ -9,7 +9,7 @@ from ._core import Enum
 
 
 class EmojiSize(Enum):
-    """Used to specify the size of a sent emoji"""
+    """Used to specify the size of a sent emoji."""
 
     LARGE = "369239383222810"
     MEDIUM = "369239343222814"
@@ -26,15 +26,16 @@ class EmojiSize(Enum):
             "s": cls.SMALL,
         }
         for tag in tags or ():
-            data = tag.split(":", maxsplit=1)
+            data = tag.split(":", 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 = "😮"
@@ -46,7 +47,7 @@ class MessageReaction(Enum):
 
 @attr.s(cmp=False)
 class Mention(object):
-    """Represents a @mention"""
+    """Represents a ``@mention``."""
 
     #: The thread ID the mention is pointing at
     thread_id = attr.ib()
@@ -58,7 +59,7 @@ class Mention(object):
 
 @attr.s(cmp=False)
 class Message(object):
-    """Represents a Facebook message"""
+    """Represents a Facebook message."""
 
     #: The actual message
     text = attr.ib(None)
@@ -74,9 +75,9 @@ class Message(object):
     timestamp = attr.ib(None, init=False)
     #: Whether the message is read
     is_read = attr.ib(None, init=False)
-    #: A list of pepole IDs who read the message, works only with :func:`fbchat.Client.fetchThreadMessages`
+    #: A list of people IDs who read the message, works only with :func:`fbchat.Client.fetchThreadMessages`
     read_by = attr.ib(factory=list, init=False)
-    #: A dict with user's IDs as keys, and their :class:`MessageReaction` as values
+    #: A dictionary with user's IDs as keys, and their :class:`MessageReaction` as values
     reactions = attr.ib(factory=dict, init=False)
     #: A :class:`Sticker`
     sticker = attr.ib(None)
@@ -97,7 +98,7 @@ class Message(object):
     def formatMentions(cls, text, *args, **kwargs):
         """Like `str.format`, but takes tuples with a thread id and text instead.
 
-        Returns a `Message` object, with the formatted string and relevant mentions.
+        Return a `Message` object, with the formatted string and relevant mentions.
 
         >>> Message.formatMentions("Hey {!r}! My name is {}", ("1234", "Peter"), ("4321", "Michael"))
         <Message (None): "Hey 'Peter'! My name is Michael", mentions=[<Mention 1234: offset=4 length=7>, <Mention 4321: offset=24 length=7>] emoji_size=None attachments=[]>
@@ -150,6 +151,55 @@ class Message(object):
             return False
         return any(map(lambda tag: "forward" in tag or "copy" in tag, tags))
 
+    def _to_send_data(self):
+        data = {}
+
+        if self.text or self.sticker or self.emoji_size:
+            data["action_type"] = "ma-type:user-generated-message"
+
+        if self.text:
+            data["body"] = self.text
+
+        for i, mention in enumerate(self.mentions):
+            data["profile_xmd[{}][id]".format(i)] = mention.thread_id
+            data["profile_xmd[{}][offset]".format(i)] = mention.offset
+            data["profile_xmd[{}][length]".format(i)] = mention.length
+            data["profile_xmd[{}][type]".format(i)] = "p"
+
+        if self.emoji_size:
+            if self.text:
+                data["tags[0]"] = "hot_emoji_size:" + self.emoji_size.name.lower()
+            else:
+                data["sticker_id"] = self.emoji_size.value
+
+        if self.sticker:
+            data["sticker_id"] = self.sticker.uid
+
+        if self.quick_replies:
+            xmd = {"quick_replies": []}
+            for quick_reply in self.quick_replies:
+                # TODO: Move this to `_quick_reply.py`
+                q = dict()
+                q["content_type"] = quick_reply._type
+                q["payload"] = quick_reply.payload
+                q["external_payload"] = quick_reply.external_payload
+                q["data"] = quick_reply.data
+                if quick_reply.is_response:
+                    q["ignore_for_webhook"] = False
+                if isinstance(quick_reply, _quick_reply.QuickReplyText):
+                    q["title"] = quick_reply.title
+                if not isinstance(quick_reply, _quick_reply.QuickReplyLocation):
+                    q["image_url"] = quick_reply.image_url
+                xmd["quick_replies"].append(q)
+            if len(self.quick_replies) == 1 and self.quick_replies[0].is_response:
+                xmd["quick_replies"] = xmd["quick_replies"][0]
+            data["platform_xmd"] = json.dumps(xmd)
+
+        if self.reply_to_id:
+            data["replied_to_message_id"] = self.reply_to_id
+
+        return data
+
     @classmethod
     def _from_graphql(cls, data):
         if data.get("message_sender") is None:

fbchat/_page.py

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

fbchat/_plan.py

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

fbchat/_poll.py

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

fbchat/_quick_reply.py

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

fbchat/_state.py

@@ -7,11 +7,19 @@ import re
 import requests
 import random
 
-from . import _util, _exception
+from . import _graphql, _util, _exception
 
 FB_DTSG_REGEX = re.compile(r'name="fb_dtsg" value="(.*?)"')
 
 
+def get_user_id(session):
+    # TODO: Optimize this `.get_dict()` call!
+    rtn = session.cookies.get_dict().get("c_user")
+    if rtn is None:
+        raise _exception.FBchatException("Could not find user id")
+    return str(rtn)
+
+
 def find_input_fields(html):
     return bs4.BeautifulSoup(html, "html.parser", parse_only=bs4.SoupStrainer("input"))
 
@@ -24,6 +32,16 @@ def session_factory(user_agent=None):
     return session
 
 
+def client_id_factory():
+    return hex(int(random.random() * 2 ** 31))[2:]
+
+
+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()
@@ -39,7 +57,7 @@ def _2fa_helper(session, code, r):
 
     r = session.post(url, data=data)
 
-    if "home" in r.url:
+    if is_home(r.url):
         return r
 
     del data["approvals_code"]
@@ -52,7 +70,7 @@ def _2fa_helper(session, code, r):
     # At this stage, we have dtsg, nh, name_action_selected, submit[Continue]
     r = session.post(url, data=data)
 
-    if "home" in r.url:
+    if is_home(r.url):
         return r
 
     del data["name_action_selected"]
@@ -60,7 +78,7 @@ def _2fa_helper(session, code, r):
     # At this stage, we have dtsg, nh, submit[Continue]
     r = session.post(url, data=data)
 
-    if "home" in r.url:
+    if is_home(r.url):
         return r
 
     del data["submit[Continue]"]
@@ -69,7 +87,7 @@ def _2fa_helper(session, code, r):
     # At this stage, we have dtsg, nh, submit[This was me]
     r = session.post(url, data=data)
 
-    if "home" in r.url:
+    if is_home(r.url):
         return r
 
     del data["submit[This was me]"]
@@ -85,29 +103,25 @@ def _2fa_helper(session, code, r):
 class State(object):
     """Stores and manages state required for most Facebook requests."""
 
-    fb_dtsg = attr.ib()
+    user_id = attr.ib()
+    _fb_dtsg = attr.ib()
     _revision = attr.ib()
     _session = attr.ib(factory=session_factory)
     _counter = attr.ib(0)
+    _client_id = attr.ib(factory=client_id_factory)
     _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,
+            "fb_dtsg": self._fb_dtsg,
         }
 
     @classmethod
-    def login(cls, email, password, user_agent=None):
+    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)
@@ -131,7 +145,7 @@ class State(object):
         if "save-device" in r.url:
             r = session.get("https://m.facebook.com/login/save-device/cancel/")
 
-        if "home" in r.url:
+        if is_home(r.url):
             return cls.from_session(session=session)
         else:
             raise _exception.FBchatUserError(
@@ -143,7 +157,7 @@ class State(object):
         # 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 "home" in r.headers["Location"]
+        return "Location" in r.headers and is_home(r.headers["Location"])
 
     def logout(self):
         logout_h = self._logout_h
@@ -157,6 +171,9 @@ class State(object):
 
     @classmethod
     def from_session(cls, session):
+        # TODO: Automatically set user_id when the cookie changes in the session
+        user_id = get_user_id(session)
+
         r = session.get(_util.prefix_url("/"))
 
         soup = find_input_fields(r.text)
@@ -174,7 +191,11 @@ class State(object):
         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
+            user_id=user_id,
+            fb_dtsg=fb_dtsg,
+            revision=revision,
+            session=session,
+            logout_h=logout_h,
         )
 
     def get_cookies(self):
@@ -185,3 +206,126 @@ class State(object):
         session = session_factory(user_agent=user_agent)
         session.cookies = requests.cookies.merge_cookies(session.cookies, cookies)
         return cls.from_session(session=session)
+
+    def _do_refresh(self):
+        # TODO: Raise the error instead, and make the user do the refresh manually
+        # It may be a bad idea to do this in an exception handler, if you have a better method, please suggest it!
+        _util.log.warning("Refreshing state and resending request")
+        new = State.from_session(session=self._session)
+        self.user_id = new.user_id
+        self._fb_dtsg = new._fb_dtsg
+        self._revision = new._revision
+        self._counter = new._counter
+        self._logout_h = new._logout_h or self._logout_h
+
+    def _get(self, url, params, error_retries=3):
+        params.update(self.get_params())
+        r = self._session.get(_util.prefix_url(url), params=params)
+        content = _util.check_request(r)
+        j = _util.to_json(content)
+        try:
+            _util.handle_payload_error(j)
+        except _exception.FBchatPleaseRefresh:
+            if error_retries > 0:
+                self._do_refresh()
+                return self._get(url, params, error_retries=error_retries - 1)
+            raise
+        return j
+
+    def _post(self, url, data, files=None, as_graphql=False, error_retries=3):
+        data.update(self.get_params())
+        r = self._session.post(_util.prefix_url(url), data=data, files=files)
+        content = _util.check_request(r)
+        try:
+            if as_graphql:
+                return _graphql.response_to_json(content)
+            else:
+                j = _util.to_json(content)
+                # TODO: Remove this, and move it to _payload_post instead
+                # We can't yet, since errors raised in here need to be caught below
+                _util.handle_payload_error(j)
+                return j
+        except _exception.FBchatPleaseRefresh:
+            if error_retries > 0:
+                self._do_refresh()
+                return self._post(
+                    url,
+                    data,
+                    files=files,
+                    as_graphql=as_graphql,
+                    error_retries=error_retries - 1,
+                )
+            raise
+
+    def _payload_post(self, url, data, files=None):
+        j = self._post(url, data, files=files)
+        try:
+            return j["payload"]
+        except (KeyError, TypeError):
+            raise _exception.FBchatException("Missing payload: {}".format(j))
+
+    def _graphql_requests(self, *queries):
+        data = {
+            "method": "GET",
+            "response_format": "json",
+            "queries": _graphql.queries_to_json(*queries),
+        }
+        return self._post("/api/graphqlbatch/", data, as_graphql=True)
+
+    def _upload(self, files, voice_clip=False):
+        """Upload files to Facebook.
+
+        `files` should be a list of files that requests can upload, see
+        `requests.request <https://docs.python-requests.org/en/master/api/#requests.request>`_.
+
+        Return a list of tuples with a file's ID and mimetype.
+        """
+        file_dict = {"upload_{}".format(i): f for i, f in enumerate(files)}
+
+        data = {"voice_clip": voice_clip}
+
+        j = self._payload_post(
+            "https://upload.facebook.com/ajax/mercury/upload.php", data, files=file_dict
+        )
+
+        if len(j["metadata"]) != len(files):
+            raise _exception.FBchatException(
+                "Some files could not be uploaded: {}, {}".format(j, files)
+            )
+
+        return [
+            (data[_util.mimetype_to_key(data["filetype"])], data["filetype"])
+            for data in j["metadata"]
+        ]
+
+    def _do_send_request(self, data):
+        offline_threading_id = _util.generateOfflineThreadingID()
+        data["client"] = "mercury"
+        data["author"] = "fbid:{}".format(self.user_id)
+        data["timestamp"] = _util.now()
+        data["source"] = "source:chat:web"
+        data["offline_threading_id"] = offline_threading_id
+        data["message_id"] = offline_threading_id
+        data["threading_id"] = _util.generateMessageID(self._client_id)
+        data["ephemeral_ttl_mode:"] = "0"
+        j = self._post("/messaging/send/", data)
+
+        # update JS token if received in response
+        fb_dtsg = _util.get_jsmods_require(j, 2)
+        if fb_dtsg is not None:
+            self._fb_dtsg = fb_dtsg
+
+        try:
+            message_ids = [
+                (action["message_id"], action["thread_fbid"])
+                for action in j["payload"]["actions"]
+                if "message_id" in action
+            ]
+            if len(message_ids) != 1:
+                log.warning("Got multiple message ids' back: {}".format(message_ids))
+            return message_ids[0]
+        except (KeyError, IndexError, TypeError) as e:
+            raise _exception.FBchatException(
+                "Error when sending message: "
+                "No message IDs could be found: {}".format(j)
+            )

fbchat/_sticker.py

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

fbchat/_thread.py

@@ -6,13 +6,27 @@ 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
     ROOM = 2
     PAGE = 3
 
+    def _to_class(self):
+        """Convert this enum value to the corresponding class."""
+        from . import _user, _group, _page
+
+        return {
+            ThreadType.USER: _user.User,
+            ThreadType.GROUP: _group.Group,
+            ThreadType.ROOM: _group.Room,
+            ThreadType.PAGE: _page.Page,
+        }[self]
+
 
 class ThreadLocation(Enum):
     """Used to specify where a thread is located (inbox, pending, archived, other)."""
@@ -24,7 +38,7 @@ class ThreadLocation(Enum):
 
 
 class ThreadColor(Enum):
-    """Used to specify a thread colors"""
+    """Used to specify a thread colors."""
 
     MESSENGER_BLUE = "#0084ff"
     VIKING = "#44bec7"
@@ -60,13 +74,13 @@ class ThreadColor(Enum):
 
 @attr.s(cmp=False, init=False)
 class Thread(object):
-    """Represents a Facebook thread"""
+    """Represents a Facebook thread."""
 
     #: The unique identifier of the thread. Can be used a ``thread_id``. See :ref:`intro_threads` for more info
     uid = attr.ib(converter=str)
     #: 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)
@@ -127,3 +141,7 @@ class Thread(object):
                 else:
                     rtn["own_nickname"] = pc[1].get("nickname")
         return rtn
+
+    def _to_send_data(self):
+        # TODO: Only implement this in subclasses
+        return {"other_user_fbid": self.uid}

fbchat/_user.py

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

pyproject.toml

@@ -56,6 +56,7 @@ test = [
 ]
 docs = [
     "sphinx~=2.0",
+    "sphinxcontrib-spelling~=4.0"
 ]
 lint = [
     "black",