No description
  • Python 95.6%
  • Dockerfile 2.1%
  • Just 1.7%
  • Shell 0.6%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-07 23:16:51 +01:00
.woodpecker Bump base image to python:3.11-slim-bullseye 2023-02-17 20:28:31 +01:00
docs Import openapi specification 2021-04-19 19:13:32 +02:00
extra Add a multi stage docker file for deploy 2021-04-04 06:31:39 +02:00
src/poetrybot Update quote command 2023-02-17 23:34:27 +01:00
tests Fix test __version__ 2023-02-20 16:44:10 +01:00
.dockerignore Add a multi stage docker file for deploy 2021-04-04 06:31:39 +02:00
.editorconfig Configure indent_style, indent_size and max_line_length 2021-02-27 01:55:52 +01:00
.flake8 Set max-line-length and max-complexity 2021-02-27 02:09:35 +01:00
.gitignore Ignore dist directory 2021-04-04 05:31:19 +02:00
Dockerfile Bump poetry to 1.3.2 2023-02-17 21:45:38 +01:00
justfile Update also the test for the version 2023-02-20 16:48:28 +01:00
LICENSE Switch to EUPL 1.2 2021-04-02 23:42:43 +02:00
poetry.lock Fix GHSA-6q48-6c7w-9gw2 2026-11-07 23:16:51 +01:00
pyproject.toml Bump version to 0.2.0 2023-02-17 22:56:49 +01:00
README.rst Remove a trailing space 2021-11-19 19:12:40 +01:00

poetrybot
=========

poetrybot is a Telegram bot to quote poems between friends. It's written in
Python and it is released under the EUPL 1.2 license.

Friends are defined by an allow list in which every account have to be in order
to to use the bot.
The management of the bot is provided by a REST API defined in the subpackage
``poetrybot.web``.


Installation
------------

1. Create your bot using Telegram `@BotFather <https://t.me/botfather>`_.
2. Install (preferably inside a virtualenv) the bot using:

   .. code-block::

      pip install poetrybot

3. The bot uses environment variables as configuration, you have to export the
   following before starting it:

   .. code-block::

      export AUTH_TOKEN=<my secret auth token>
      export DATABASE_URL=sqlite:////absolute/path/to/poetrybot.db
      export TELEGRAM_TOKEN=<telegram bot API key>

   ``AUTH_TOKEN`` is used to authenticate to the REST API used to manage the
   bot. Full specification is in the ``docs/openapi.yml`` file.
   Just create a long enough random string, for example using ``pwgen -sy 50``.
4. Launch the bot:

   .. code-block::

      poetrybot
5. To use the REST API install a WSGI HTTP Server, for example gunicorn, and
   then:

   .. code-block::

      gunicorn poetrybot.web.wsgi:app

6. Use the REST API to insert allowed friends, poets and poems. The fastest way
   to look at the API is to load the API specification into
   https://editor.swagger.io

An alternative is to clone the repository and use the provided ``Dockerfile``.

Usage
-----

To use the bot you only have to use the ``/quote`` command. The bot can be
added to one or more channels but it's not required. But remember that only
friends in allow list will be able to interact with the bot.

The ``/quote`` command used without parameters will make the bot to quote a
random poem, but optionally the author and the argument can be specified:

* ``/quote`` returns a random poem;
* ``/quote AUTHOR`` returns a random poem by ``AUTHOR``.

  ``AUTHOR`` is the name or part of the name of the poet case insensitive:

  .. code-block::

     /quote Giovanni Pascoli
     /quote pascoli
     /quote ascol

  will return a random poem by Giovanni Pascoli, if you don't have another
  poet with *ascol* inside the name;
* ``/quote AUTHOR about ARGUMENT`` returns a random poem by ``AUTHOR`` about
  ``ARGUMENT``.

  ``ARGUMENT`` is, like ``AUTHOR``, case insensitive and can be part of a word.
  ``about`` is, instead, case sensitive;
* ``/quote about ARGUMENT`` returns a random poem about ``ARGUMENT``.