2.0.0 dev

docs/api/base.rst

@@ -0,0 +1,4 @@
+Base class
+==========
+
+.. autoclass:: Base()

docs/api/get.rst

@@ -0,0 +1,4 @@
+Retrieving information
+======================
+
+.. autoclass:: Get(Base)

docs/api/index.rst

@@ -0,0 +1,16 @@
+API
+===
+
+.. toctree::
+
+   base
+   get
+   listener
+   message_management
+   search
+   send
+   thread_control
+   thread_interraction
+   thread_options
+
+   models

docs/api/listener.rst

@@ -0,0 +1,4 @@
+Event Listening
+===============
+
+.. autoclass:: Listener(Base)

docs/api/message_management.rst

@@ -0,0 +1,4 @@
+Management of Messages
+======================
+
+.. autoclass:: MessageManagement(Listener)

docs/api/models.rst

@@ -0,0 +1,5 @@
+Various Data Models
+===================
+
+.. automodule:: fbchat.models
+	:undoc-members:

docs/api/search.rst

@@ -0,0 +1,4 @@
+Searching for information
+=========================
+
+.. autoclass:: Search(Base)

docs/api/send.rst

@@ -0,0 +1,4 @@
+Sending messages
+================
+
+.. autoclass:: Send(Listener)

docs/api/thread_control.rst

@@ -0,0 +1,4 @@
+Controlling Threads
+===================
+
+.. autoclass:: ThreadControl(Listener)

docs/api/thread_interraction.rst

@@ -0,0 +1,4 @@
+Interraction with Threads
+=========================
+
+.. autoclass:: ThreadInterraction(Listener)

docs/api/thread_options.rst

@@ -0,0 +1,4 @@
+Configuring Thread Options
+==========================
+
+.. autoclass:: ThreadOptions(Base)

docs/conf.py

@@ -21,9 +21,7 @@
 import sys
 sys.path.insert(0, os.path.abspath('..'))
 
-import fbchat
-import tests
-from fbchat import __copyright__, __author__, __version__, __description__
+from fbchat import __copyright__, __author__, __version__, __description__ # noqa
 
 
 # -- General configuration ------------------------------------------------
@@ -39,7 +37,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -187,5 +186,14 @@
 
 html_show_sphinx = False
 html_show_sourcelink = False
-autoclass_content = 'init'
+autoclass_content = 'class'
+autodoc_member_order = 'bysource'
+autodoc_default_flags = ['members']
 html_short_title = description
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = True
+napoleon_use_rtype = False
+rst_prolog = '''
+.. module:: fbchat
+'''
+default_role = 'class'

docs/examples.rst

@@ -1,4 +1,3 @@
-.. highlight:: python
 .. _examples:
 
 Examples
@@ -28,23 +27,23 @@ Fetching Information
 
 This will show the different ways of fetching information about users and threads
 
-.. literalinclude:: ../examples/fetch.py
+.. literalinclude:: ../examples/retrieve.py
 
 
 Echobot
 -------
 
 This will reply to any message with the same message
 
-.. literalinclude:: ../examples/echobot.py
+.. literalinclude:: ../examples/echo_bot.py
 
 
 Remove Bot
 ----------
 
 This will remove a user from a group if they write the message `Remove me!`
 
-.. literalinclude:: ../examples/removebot.py
+.. literalinclude:: ../examples/remove_bot.py
 
 
 "Prevent changes"-Bot
@@ -53,4 +52,4 @@ This will remove a user from a group if they write the message `Remove me!`
 This will prevent chat color, emoji, nicknames and chat name from being changed.
 It will also prevent people from being added and removed
 
-.. literalinclude:: ../examples/keepbot.py
+.. literalinclude:: ../examples/keep_bot.py

docs/faq.rst

@@ -1,5 +1,3 @@
-.. highlight:: python
-.. module:: fbchat
 .. _faq:
 
 FAQ

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
@@ -61,6 +59,6 @@ Overview
     intro
     examples
     testing
-    api
+    api/index
     todo
     faq

docs/intro.rst

@@ -1,5 +1,3 @@
-.. highlight:: python
-.. module:: fbchat
 .. _intro:
 
 Introduction

docs/testing.rst

@@ -1,5 +1,4 @@
 .. highlight:: sh
-.. module:: fbchat
 .. _testing:
 
 Testing

docs/todo.rst

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

examples/advanced_bot.py

@@ -0,0 +1,69 @@
+# -*- coding: UTF-8 -*-
+
+from fbchat import Client, Group, Message
+
+
+class Bot(Client):
+
+    def on_message(self, message):
+        thread = message.thread
+
+        # Prevent the bot from answering the bot's own messages
+        if message in self.sent_messages:
+            return
+
+        # If the message-text contains the letters 'admin'
+        if 'admin' in message.text.lower():
+            # Send various messages, based on the thread and the admin-status
+            if not isinstance(thread, Group):
+                self.send_text(thread, "This isn't a group, no admins here!")
+            elif self in thread.admins:
+                self.send_text(thread, "Yup, I'm an admin")
+            else:
+                self.send_text(thread, "Nope :'(")
+
+        # If the message-text contains the letters 'like'
+        if 'like' in message.text.lower():
+            # React to the message with a thumbs up
+            self.set_reaction(message, reaction='👍')
+
+        # If the message contains any images
+        if message.images:
+            # Send a message with the same images
+            self.send(thread, Message(images=message.images,
+                                      text='Here, have your images back!'))
+
+        # If the message contains a video
+        if message.video:
+            print(message.video, dict(message.video))
+
+        # If the message contains a file
+        if message.file:
+            print(message.file, dict(message.file))
+
+        # If you're mentioned
+        if self in (mention.thread for mention in message.mentions):
+            print('{.name} tagged me!'.format(message.author))
+
+    def on_user_removed(self, thread, actor, subject):
+        # If you're the subject or the actor
+        if self in [subject, actor]:
+            return
+
+        # If the subject is one of your friends
+        if subject.is_friend:
+            self.send_text(thread, 'Aww, this person was my friend!')
+
+    def on_users_added(self, thread, actor, subject):
+        # If you've been added to the thread
+        if subject == self:
+            self.send_text(thread, 'Thanks for adding me!')
+
+    def on_reaction_set(self, actor, message, old_reaction):
+        # If old_reaction is set, the reaction was changed
+        if old_reaction:
+            self.send_text(message.thread, 'Stop changing your reactions!')
+
+
+bot = Bot("<email>", "<password>")
+bot.listen()

examples/basic_usage.py

@@ -1,12 +1,16 @@
 # -*- coding: UTF-8 -*-
 
-from fbchat import Client
-from fbchat.models import *
+# Imports Client, Thread, Group, Page, User and Message
+from fbchat import *
 
+# Login, using your email and credentials
 client = Client('<email>', '<password>')
 
-print('Own id: {}'.format(client.uid))
+# Display data about you
+print(client, vars(client))
 
-client.send(Message(text='Hi me!'), thread_id=client.uid, thread_type=ThreadType.USER)
+# Send a message to yourself
+message = client.send_text(client, 'Hi me!')
 
-client.logout()
+# Display data about the sent message
+print(message, vars(message))

examples/echo_bot.py

@@ -0,0 +1,22 @@
+# -*- coding: UTF-8 -*-
+
+from fbchat import *
+
+
+# Subclass the Client
+class EchoBot(Client):
+
+    # And override the on_message method
+    def on_message(self, message):
+        # If the author isn't you
+        if message.author != self:
+            # Send the message back to the thread
+            self.send(message.thread, message)
+
+
+# Login and initialize
+bot = EchoBot("<email>", "<password>")
+
+# Start listening for messages, and when a message is recieved, on_message
+# will be called
+bot.listen()