karaolidis/fbchat
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update CONTRIBUTING.rst and README.rst

Browse Source
This commit is contained in:
Mads Marquart
2020-01-22 03:01:11 +01:00
parent b6fd7e2cf2
commit 03cc95e755
5 changed files with 99 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
CONTRIBUTING.rst
View File

@@ -3,36 +3,40 @@ Contributing to ``fbchat``
Thanks for reading this, all contributions are very much welcome! 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. 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 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: $ # *nix:
$ flit install --symlink $ flit install --symlink
$ # Windows: $ # Windows:
$ flit install --pth-file $ 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. 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. - Run `black .` to format your code.
To set these up, you should export the following environment variables: - Run `pytest` to test your code.
- Run `make -C docs html` to verify that the docs still work.
``client1_email``, ``client1_password``, ``client2_email``, ``client2_password`` and ``group_id`` - 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>`__.
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.

85
README.rst
View File

@@ -1,5 +1,5 @@
``fbchat``: Facebook Chat (Messenger) for Python ``fbchat`` - Facebook Messenger for Python
================================================ ==========================================
.. image:: https://badgen.net/pypi/license/fbchat .. image:: https://badgen.net/pypi/license/fbchat
:target: https://github.com/carpedm20/fbchat/tree/master/LICENSE :target: https://github.com/carpedm20/fbchat/tree/master/LICENSE
@@ -25,13 +25,23 @@
:target: https://github.com/ambv/black :target: https://github.com/ambv/black
:alt: Code style :alt: Code style
Facebook Chat (`Messenger <https://www.facebook.com/messages/>`__) for Python. A powerful and efficient library to interact with
This project was inspired by `facebook-chat-api <https://github.com/Schmavery/facebook-chat-api>`__. `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: Version warning:
---------------- ----------------
@@ -39,23 +49,64 @@ Version warning:
Additionally, you can view the project's progress `here <https://github.com/carpedm20/fbchat/projects/2>`__. 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``: More examples are available `here <https://github.com/carpedm20/fbchat/tree/master/examples>`__.
.. code-block::
$ git clone https://github.com/carpedm20/fbchat.git
$ pip install fbchat
Maintainer Maintainer
---------- ----------
- Mads Marquart / `@madsmtm <https://github.com/madsmtm>`__ - 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>`__.

46
docs/index.rst
View File

@@ -1,49 +1,21 @@
.. fbchat documentation master file, created by .. See README.rst for explanation of these markers
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.
.. This documentation's layout is heavily inspired by requests' layout: https://requests.readthedocs.io .. include:: ../README.rst
Some documentation is also partially copied from facebook-chat-api: https://github.com/Schmavery/facebook-chat-api :end-before: inclusion-marker-intro-end
``fbchat``: Facebook Chat (Messenger) for Python With that said, let's get started!
================================================
Release v\ |version|. (:ref:`install`) .. include:: ../README.rst
:start-after: inclusion-marker-installation-start
Facebook Chat (`Messenger <https://www.facebook.com/messages/>`_) for Python. :end-before: inclusion-marker-installation-end
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``
Overview Documentation Overview
-------- ----------------------
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
install
intro intro
examples examples
testing testing

43
docs/install.rst
View File

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

2
fbchat/__init__.py
View File

@@ -1,4 +1,4 @@
"""Facebook Chat (Messenger) for Python """Facebook Messenger for Python.
Copyright: Copyright:
(c) 2015 - 2018 by Taehoon Kim (c) 2015 - 2018 by Taehoon Kim