Package: chatapi
Python Chat APIIf your Python application needs chat functionality, then use Python Chat API to easily add it, along with many other features from WhatsApp or Telegram or your favorite messaging app.Python Chat API works by creating a rich object model on top of any chat server and presenting intuitive behaviors in a modern async paradigm.The recommended chat server is the awesome open-sourceTinode chat server. Read more below.Why Tinode?The promise of XMPP was to deliver federated instant messaging: anyone would be able to spin up an IM server capable of exchanging messages with any other XMPP server in the world. Unfortunately, XMPP never delivered on this promise. Instant messengers are still a bunch of incompatible walled gardens, similar to what AoL of the late 1990s was to the open Internet.The goal of this project is to deliver on XMPP's original vision: create a modern open platform for federated instant messaging with an emphasis on mobile communication. A secondary goal is to create a decentralized IM platform that is much harder to track and block by the governments.Getting StartedThis guide explains how to run the Tinode chat server using Docker and how to use the Python Chat API to connect to it. The guide assumes a Linux environment.PrerequisitesDocker>= 1.8 becauseDocker networkingmay not work with earlier versionsPython >= 3.6 because this project usesasyncioforcooperative multitasking, as should youCreate aDocker bridge networkfor the backing store and the chat server:$dockernetworkcreatechatInstalling the backing store for TinodeWe'll useMySQLfor this example. Run the official MySQL container:$dockerrun\--namemysql\--networkchat\--restartalways\--envMYSQL_ALLOW_EMPTY_PASSWORD=yes\-d\mysql:5.7Version >= 5.7 is required. See MySQL Docker instructions for more options. Seedeployment notesfor more on running this in production or deploying to a Docker Swarm cluster.RethinkDB and MongoDB are also supported by the Tinode chat server, and there is ongoing development on a common SQL adapter to support, e.g., PostgreSQL.Running the Tinode chat serverRun the Tinode container that corresponds to our choice of MySQL for the backing store, exposing port 16060 for the gRPC channel.$dockerrun\--nametinode-server\--networkchat\-p16060:16060\-d\tinode/tinode-mysql:latestSeeTinode documentationfor more on deploying the Tinode chat server using Docker.Using Python Chat APIInstall Python Chat API into your environment using pip:$ pip install chatapiThe following example registers a new user, creates a new group topic and sends a"Hello, world!"message.importchatsession=chat.quick_connect('tinode-server',16060)token=awaitsession.register('arseniy:mypassword')topic_name=awaitsession.new_topic()awaitsession.publish_str(topic_name,'Hello, world!')For more examples, see thedocumentation.DeploymentFor serious projects, you might reconsider running the backing store in a container: managed database providers remove the hassle of upgrading, patching, backups and other maintenance, and you can concern yourself less with availability and more with application features.Deploying to a Docker Swarm clusterBridge networks are not supported on a Swarm cluster, so you would need to create aDocker overlay networkinstead:$dockernetworkcreate--driveroverlaychatIf you choose to run MySQL in a container on the Swarm cluster, then you may want to modify the instructions in this guide to run the MySQL container like this:$dockerrun\--namemysql\--networktinode-net\--restartalways\--envMYSQL_ALLOW_EMPTY_PASSWORD=yes\--envMYSQL_ROOT_HOST=%\-d\mysql:5.7\mysqld--bind-address=0.0.0.0TheMYSQL_ROOT_HOST=%environment variable allows therootuser to log in from anywhere (like another container's virtual IP address in the Swarm cluster). Themysqld --bind-address=0.0.0.0command starts the MySQL server daemon and tells it to listen on all IP addresses on the local host (and all virtual IP addresses of the container).Scaling the Tinode chat serverSeeTinode documentationfor more on scaling. This would need to be adapted for Docker Swarm.TestingIf you have the ports exposed properly after following theGetting startedguide above, then you can do:$pipinstallpytest-asyncio
$exportCHAT_HOST=tinode-server
$exportCHAT_HOST=16060$pytestTesting with docker-composeTests are easily run viadocker-compose. Thebuild-and-testworkflow runs automatically on GitHub and does everything mentioned below.First, set the environment variableGITHUB_RUN_IDto something on your local machine. (This is automatically set to a unique run ID in the GitHub workflow.)$exportGITHUB_RUN_ID=my_test_runThen, build the testing image with the expected tag. (The PYTHONVERSION build arg defaults to3.8, but it is set to all of[3.6, 3.7, 3.8]in the GitHub workflow.)$dockerbuild\-tchatapi-tests-$GITHUB_RUN_ID\--build-argPYTHONVERSION=3.7\-ftests.Dockerfile\.Thetests.docker-compose.ymlfile starts a MySQL container, a Tinode chat server container and a Python Chat API testing container, which automatically runspytestwhen the backing store and chat server are ready. The GitHub workflow does this after building the testing image:$docker-compose\-ftests.docker-compose.yml\up\--abort-on-container-exit\--exit-code-frompytestLintingThe testing image containsflake8which is used by the GitHub workflow. You can lint with:$ docker run chatapi-tests-$GITHUB_RUN_ID flake8 .You can also lint in your own environment with:$pipinstallflake8
$flake8.VersioningThis project usessemantic versioningfor versioning.LicenseThis project is licensed under the MIT License - see theLICENSEfile for detailsAcknowledgmentsor-else (Gene)for Tinode chat server