.. mechanical_bull documentation master file, created by
   sphinx-quickstart on Sun Apr 23 09:33:34 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Usage
=====

Running mechanical bull can be accomplished via

.. code-block:: bash

   python -mmechanical_bull.run

which will not do much as no users are configured. The user configuration is stored in `config.toml`

.. code-block:: toml

   logfile = "mechanical_bull.log"
   management = "https://manage.domain"

   [user]
   private_key = "z3u2Yxcowsarethebestcowsarethebestcowsarethebest"
   host = "domain"

   [user.handlers]
   "mechanical_bull.actions.handle_follow_request" = true

`management` points to the location of bovine_management that can be used to make adding did keys to bovine easier. Both the logfile and management parameters are optional. This starts a process that connects to the event sources of the configured accounts and reacts appropriately to them.


Adding users
------------

One can add new users to bovine using the following command

.. argparse::
   :module: mechanical_bull.add_user
   :func: build_parser
   :prog: python -mmechanical_bull.add_user

This will create an entry of the following form in `config.toml`

.. code-block:: toml

   [username]
   private_key = "z3u2Yxcowsarethebestcowsarethebestcowsarethebest"
   host = "example.tld"

   [username.handlers]
   "mechanical_bull.actions.accept_follow_request" = false

Note the configuration variable on the right is either false to disable the handler, true to enable the handler, or a dictionary to enable the handler and pass further configuration variables

.. code-block:: toml

   "mechanical_bull.actions.log_to_file" = { filename = "cow.txt" }

Adding new handlers
-------------------

mechanical_bull is meant to be extensible with new handlers. These can be defined as a python module containing a function

.. code-block:: python

   async def handle(client: bovine.BovineClient, data: dict, **kwargs):
      return

For further details see the Moo Cow tutorial.