diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index c32f920..3705320 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 `__ +Please be aware that ``fbchat`` uses `Scemantic Versioning `__ 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 `__, 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 `__. diff --git a/README.rst b/README.rst index eb3cc5f..dabc561 100644 --- a/README.rst +++ b/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 `__) for Python. -This project was inspired by `facebook-chat-api `__. +A powerful and efficient library to interact with +`Facebook\'s Messenger `__, 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 `__ 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 `__ to see the full documentation, -or jump right into the code by viewing the `examples `__ Version warning: ---------------- @@ -39,23 +49,64 @@ Version warning: Additionally, you can view the project's progress `here `__. -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 `__ to see the full documentation! + +.. inclusion-marker-installation-start + + +Installation +------------ + +.. code-block:: sh + + $ pip install fbchat + +If you don't have `pip `_, `this guide `_ 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("", 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 `__. Maintainer ---------- - Mads Marquart / `@madsmtm `__ -- Taehoon Kim / `@carpedm20 `__ + + +Acknowledgements +---------------- + +This project was originally inspired by `facebook-chat-api `__. diff --git a/docs/index.rst b/docs/index.rst index 020bd0f..7e5c710 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 `_) for Python. -This project was inspired by `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 `_ 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 diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index c8a1102..0000000 --- a/docs/install.rst +++ /dev/null @@ -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 `_ installed, -`this Python installation guide `_ -can guide you through the process. - -Get the Source Code -------------------- - -``fbchat`` is developed on GitHub, where the code is -`always available `_. - -You can either clone the public repository: - -.. code-block:: sh - - $ git clone git://github.com/carpedm20/fbchat.git - -Or, download a `tarball `_: - -.. 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 diff --git a/fbchat/__init__.py b/fbchat/__init__.py index 45f91f1..99feaad 100644 --- a/fbchat/__init__.py +++ b/fbchat/__init__.py @@ -1,4 +1,4 @@ -"""Facebook Chat (Messenger) for Python +"""Facebook Messenger for Python. Copyright: (c) 2015 - 2018 by Taehoon Kim