Update CONTRIBUTING.rst and README.rst
This commit is contained in:
Mads Marquart
@@ -3,36 +3,40 @@ Contributing to ``fbchat``
|
||||
|
||||
Thanks for reading this, all contributions are very much welcome!
|
||||
|
||||
Please be aware that ``fbchat`` uses `Scemantic Versioning <https://semver.org/>`__
|
||||
Please be aware that ``fbchat`` uses `Scemantic Versioning <https://semver.org/>`__ quite rigorously!
|
||||
That means that if you're submitting a breaking change, it will probably take a while before it gets considered.
|
||||
|
||||
In that case, you can point your PR to the ``2.0.0-dev`` branch, where the API is being properly developed.
|
||||
Otherwise, just point it to ``master``.
|
||||
|
||||
Development Environment
|
||||
-----------------------
|
||||
|
||||
You can use `flit` to install the package as a symlink:
|
||||
This project uses ``flit`` to configure development environments. You can install it using:
|
||||
|
||||
.. code-block::
|
||||
.. code-block:: sh
|
||||
|
||||
$ pip install flit
|
||||
|
||||
And now you can install ``fbchat`` as a symlink:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ git clone https://github.com/carpedm20/fbchat.git
|
||||
$ cd fbchat
|
||||
$ # *nix:
|
||||
$ flit install --symlink
|
||||
$ # Windows:
|
||||
$ flit install --pth-file
|
||||
|
||||
This will also install required development tools like ``black``, ``pytest`` and ``sphinx``.
|
||||
|
||||
After that, you can ``import`` the module as normal.
|
||||
|
||||
Before committing, you should run ``black .`` in the main directory, to format your code.
|
||||
Checklist
|
||||
---------
|
||||
|
||||
Testing Environment
|
||||
-------------------
|
||||
Once you're done with your work, please follow the steps below:
|
||||
|
||||
The tests use `pytest <https://docs.pytest.org/>`__, and to work they need two Facebook accounts, and a group thread between these.
|
||||
To set these up, you should export the following environment variables:
|
||||
|
||||
``client1_email``, ``client1_password``, ``client2_email``, ``client2_password`` and ``group_id``
|
||||
|
||||
If you're not able to do this, consider simply running ``pytest -m offline``.
|
||||
|
||||
And if you're adding new functionality, if possible, make sure to create a new test for it.
|
||||
- Run `black .` to format your code.
|
||||
- Run `pytest` to test your code.
|
||||
- Run `make -C docs html` to verify that the docs still work.
|
||||
- Run `make -C docs spelling` to check your spelling in docstrings.
|
||||
- Create a pull request, and point it to ``master`` `here <https://github.com/carpedm20/fbchat/pulls/new>`__.
|
||||
|
||||
85
README.rst
85
README.rst
@@ -1,5 +1,5 @@
|
||||
``fbchat``: Facebook Chat (Messenger) for Python
|
||||
================================================
|
||||
``fbchat`` - Facebook Messenger for Python
|
||||
==========================================
|
||||
|
||||
.. image:: https://badgen.net/pypi/license/fbchat
|
||||
:target: https://github.com/carpedm20/fbchat/tree/master/LICENSE
|
||||
@@ -25,13 +25,23 @@
|
||||
:target: https://github.com/ambv/black
|
||||
:alt: Code style
|
||||
|
||||
Facebook Chat (`Messenger <https://www.facebook.com/messages/>`__) for Python.
|
||||
This project was inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`__.
|
||||
A powerful and efficient library to interact with
|
||||
`Facebook\'s Messenger <https://www.facebook.com/messages/>`__, using just your email and password.
|
||||
|
||||
**No XMPP or API key is needed**. Just use your email and password.
|
||||
This is *not* an official API, Facebook has that `over here <https://developers.facebook.com/docs/messenger-platform>`__ for chat bots. This library differs by using a normal Facebook account instead.
|
||||
|
||||
``fbchat`` currently support:
|
||||
|
||||
- Sending many types of messages, with files, stickers, mentions, etc.
|
||||
- Fetching all messages, threads and images in threads.
|
||||
- Searching for messages and threads.
|
||||
- Creating groups, setting the group emoji, changing nicknames, creating polls, etc.
|
||||
- Listening for, an reacting to events in real-time.
|
||||
- Type hints, and a modern codebase (e.g. only Python 3.5 and upwards).
|
||||
- ``async``/``await`` (COMING).
|
||||
|
||||
Essentially, everything you need to make an amazing Facebook bot!
|
||||
|
||||
Go to `Read the Docs <https://fbchat.readthedocs.io>`__ to see the full documentation,
|
||||
or jump right into the code by viewing the `examples <https://github.com/carpedm20/fbchat/tree/master/examples>`__
|
||||
|
||||
Version warning:
|
||||
----------------
|
||||
@@ -39,23 +49,64 @@ Version warning:
|
||||
|
||||
Additionally, you can view the project's progress `here <https://github.com/carpedm20/fbchat/projects/2>`__.
|
||||
|
||||
Installation:
|
||||
|
||||
Caveats
|
||||
-------
|
||||
|
||||
``fbchat`` works by imitating what the browser does, and thereby tricking Facebook into thinking it's accessing the website normally.
|
||||
|
||||
However, there's a catch! **Using this library may not comply with Facebook's Terms Of Service!**, so be responsible Facebook citizens! We are not responsible if your account gets banned!
|
||||
|
||||
Additionally, **the APIs the library is calling is undocumented!** In theory, this means that your code could break tomorrow, without the slightest warning!
|
||||
If this happens to you, please report it, so that we can fix it as soon as possible!
|
||||
|
||||
.. inclusion-marker-intro-end
|
||||
.. This message doesn't make sense in the docs at Read The Docs, so we exclude it
|
||||
|
||||
With that out of the way, you may go to `Read The Docs <https://fbchat.readthedocs.io/>`__ to see the full documentation!
|
||||
|
||||
.. inclusion-marker-installation-start
|
||||
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ pip install fbchat
|
||||
|
||||
If you don't have `pip <https://pip.pypa.io/>`_, `this guide <http://docs.python-guide.org/en/latest/starting/installation/>`_ can guide you through the process.
|
||||
|
||||
You can also install directly from source, provided you have ``pip>=19.0``:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ pip install git+https://github.com/carpedm20/fbchat.git
|
||||
|
||||
.. inclusion-marker-installation-end
|
||||
|
||||
|
||||
Example usage
|
||||
-------------
|
||||
|
||||
.. code-block::
|
||||
.. code-block:: python
|
||||
|
||||
$ pip install fbchat
|
||||
import getpass
|
||||
import fbchat
|
||||
session = fbchat.Session.login("<email/phone number>", getpass.getpass())
|
||||
user = fbchat.User(session=session, id=session.user_id)
|
||||
user.send_text("Test message!")
|
||||
|
||||
You can also install from source if you have ``pip>=19.0``:
|
||||
|
||||
.. code-block::
|
||||
|
||||
$ git clone https://github.com/carpedm20/fbchat.git
|
||||
$ pip install fbchat
|
||||
More examples are available `here <https://github.com/carpedm20/fbchat/tree/master/examples>`__.
|
||||
|
||||
|
||||
Maintainer
|
||||
----------
|
||||
|
||||
- Mads Marquart / `@madsmtm <https://github.com/madsmtm>`__
|
||||
- Taehoon Kim / `@carpedm20 <http://carpedm20.github.io/about/>`__
|
||||
|
||||
|
||||
Acknowledgements
|
||||
----------------
|
||||
|
||||
This project was originally inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`__.
|
||||
|
||||
@@ -1,49 +1,21 @@
|
||||
.. 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
|
||||
contain the root `toctree` directive.
|
||||
.. See README.rst for explanation of these markers
|
||||
|
||||
.. 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
|
||||
.. include:: ../README.rst
|
||||
:end-before: inclusion-marker-intro-end
|
||||
|
||||
``fbchat``: Facebook Chat (Messenger) for Python
|
||||
================================================
|
||||
With that said, let's get started!
|
||||
|
||||
Release v\ |version|. (:ref:`install`)
|
||||
|
||||
Facebook Chat (`Messenger <https://www.facebook.com/messages/>`_) for Python.
|
||||
This project was inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`_.
|
||||
|
||||
**No XMPP or API key is needed**. Just use your email and password.
|
||||
|
||||
Currently ``fbchat`` support Python 3.5, 3.6, 3.7 and 3.8:
|
||||
|
||||
``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
|
||||
|
||||
.. warning::
|
||||
We are not responsible if your account gets banned for spammy activities,
|
||||
such as sending lots of messages to people you don't know, sending messages very quickly,
|
||||
sending spammy looking URLs, logging in and out very quickly... Be responsible Facebook citizens.
|
||||
|
||||
.. 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.
|
||||
|
||||
If you're already familiar with the basics of how Facebook works internally, go to :ref:`examples` to see example usage of ``fbchat``
|
||||
.. include:: ../README.rst
|
||||
:start-after: inclusion-marker-installation-start
|
||||
:end-before: inclusion-marker-installation-end
|
||||
|
||||
|
||||
Overview
|
||||
--------
|
||||
Documentation Overview
|
||||
----------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
install
|
||||
intro
|
||||
examples
|
||||
testing
|
||||
|
||||
@@ -1,43 +0,0 @@
|
||||
.. _install:
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Install using pip
|
||||
-----------------
|
||||
|
||||
To install ``fbchat``, run this command:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ pip install fbchat
|
||||
|
||||
If you don't have `pip <https://pip.pypa.io>`_ installed,
|
||||
`this Python installation guide <http://docs.python-guide.org/en/latest/starting/installation/>`_
|
||||
can guide you through the process.
|
||||
|
||||
Get the Source Code
|
||||
-------------------
|
||||
|
||||
``fbchat`` is developed on GitHub, where the code is
|
||||
`always available <https://github.com/carpedm20/fbchat>`_.
|
||||
|
||||
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>`_:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ curl -OL https://github.com/carpedm20/fbchat/tarball/master
|
||||
# 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:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
$ python setup.py install
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Facebook Chat (Messenger) for Python
|
||||
"""Facebook Messenger for Python.
|
||||
|
||||
Copyright:
|
||||
(c) 2015 - 2018 by Taehoon Kim
|
||||
|
||||
Reference in New Issue
Block a user