# Mechanical Bull
Mechanical Bull is an ActivityPub Client application build based on [bovine](https://codeberg.org/bovine/bovine/). It's main goal is to provide a platform for automating activities undertaking in the FediVerse. Furthermore, it serves as a demonstration how ActivityPub Clients can be build with bovine.
## Installation
One can simply install mechanical_bull with pip via
```bash
pip install mechanical-bull
```
Once can then add a new user by running
```bash
python -m mechanical_bull.add_user [--accept] name hostname
```
This will then prompt you to add a new did:key to your ActivityPub Actor. This did:key will be used to authenticate mechanical_bull against your server. Once you have added the key, press enter, and mechanical_bull is running. This method of authentication is called Moo-Auth-1 and described [here](https://blog.mymath.rocks/2023-03-15/BIN1_Moo_Authentication_and_Authoriation).
The configuration is saved in `config.toml`. bovine also supports authentication through private keys and HTTP signatures. For the details on how to configure this, please consult bovine. You can add further automations there.
Then you should be able to run mechanical bull via
```bash
python -m mechanical_bull.run
```
## Configuration
First by adding `log_file = "mechanical_bull.log"` to your `config.toml` you can make mechanical_bull write log entries to a file. Second, the config file has the following format
```toml
logfile = "mechanical_bull.log"
[cow]
private_key = "z3u2Yxcowsarethebestcowsarethebestcowsarethebest"
host = "cows.rocks"
[cow.handlers]
"mechanical_bull.actions.reject_follow_request" = true
# "mechanical_bull.actions.accept_follow_request" = true
"mechanical_bull.actions.log_to_file" = { filename = "cow.txt" }
```
The listed handlers are provided by mechanical_bull. They allow to accept / reject follow requests automatically, and the final one logs all traffic on the event source to "cow.txt".
## Writing automations
The examples of `mechanical_bull.actions.accept_follow_request` and `mechanical_bull.actions.log_to_file` should show how to write a new automation. The basic idea is that each file contains a function handle with signature
```python
async def handle(client: BovineClient, data: dict, **kwargs):
return
```
here the kwargs are the dict given by the definiton in the handler block, i.e.
```toml
[user.handlers]
"my.package" = { arg1 = "value1", arg2 = "value2 }
```
## Contibuting
Please report bugs, etc. to the [issue tracker](https://codeberg.org/bovine/mechanical_bull/issues). Contributings in the form of pull requests are welcome. You can also contact me on the FediVerse at `@helge@mymath.rocks`.
Finally, I plan a multi-user "server" version of this project called __mechanical_herd__. The functionality should be similar, but updating the configuration should not require a restart. One might also think hooking into the redis from [bovine_pubsub](https://codeberg.org/bovine/bovine/src/branch/dev/bovine_pubsub) for this. mechanical_herd will probably be part of the bovine user management interface.
Raw data
{
"_id": null,
"home_page": "https://codeberg.org/bovine/mechanical_bull",
"name": "mechanical-bull",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Helge",
"author_email": "helge.krueger@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/66/f5/bd630db64297a85005839c27fb4e1761b5fcdb923002bc19c1a67f8de611/mechanical_bull-0.2.6.tar.gz",
"platform": null,
"description": "# Mechanical Bull\n\nMechanical Bull is an ActivityPub Client application build based on [bovine](https://codeberg.org/bovine/bovine/). It's main goal is to provide a platform for automating activities undertaking in the FediVerse. Furthermore, it serves as a demonstration how ActivityPub Clients can be build with bovine.\n\n## Installation\n\nOne can simply install mechanical_bull with pip via\n\n```bash\npip install mechanical-bull\n```\n\nOnce can then add a new user by running\n\n```bash\npython -m mechanical_bull.add_user [--accept] name hostname\n```\n\nThis will then prompt you to add a new did:key to your ActivityPub Actor. This did:key will be used to authenticate mechanical_bull against your server. Once you have added the key, press enter, and mechanical_bull is running. This method of authentication is called Moo-Auth-1 and described [here](https://blog.mymath.rocks/2023-03-15/BIN1_Moo_Authentication_and_Authoriation).\n\nThe configuration is saved in `config.toml`. bovine also supports authentication through private keys and HTTP signatures. For the details on how to configure this, please consult bovine. You can add further automations there.\n\nThen you should be able to run mechanical bull via\n\n```bash\npython -m mechanical_bull.run\n```\n\n## Configuration\n\nFirst by adding `log_file = \"mechanical_bull.log\"` to your `config.toml` you can make mechanical_bull write log entries to a file. Second, the config file has the following format\n\n```toml\nlogfile = \"mechanical_bull.log\"\n\n[cow]\nprivate_key = \"z3u2Yxcowsarethebestcowsarethebestcowsarethebest\"\nhost = \"cows.rocks\"\n\n[cow.handlers]\n\"mechanical_bull.actions.reject_follow_request\" = true\n# \"mechanical_bull.actions.accept_follow_request\" = true\n\"mechanical_bull.actions.log_to_file\" = { filename = \"cow.txt\" }\n```\n\nThe listed handlers are provided by mechanical_bull. They allow to accept / reject follow requests automatically, and the final one logs all traffic on the event source to \"cow.txt\".\n\n## Writing automations\n\nThe examples of `mechanical_bull.actions.accept_follow_request` and `mechanical_bull.actions.log_to_file` should show how to write a new automation. The basic idea is that each file contains a function handle with signature\n\n```python\nasync def handle(client: BovineClient, data: dict, **kwargs):\n return\n```\n\nhere the kwargs are the dict given by the definiton in the handler block, i.e.\n\n```toml\n[user.handlers]\n\"my.package\" = { arg1 = \"value1\", arg2 = \"value2 }\n```\n\n## Contibuting\n\nPlease report bugs, etc. to the [issue tracker](https://codeberg.org/bovine/mechanical_bull/issues). Contributings in the form of pull requests are welcome. You can also contact me on the FediVerse at `@helge@mymath.rocks`.\n\nFinally, I plan a multi-user \"server\" version of this project called __mechanical_herd__. The functionality should be similar, but updating the configuration should not require a restart. One might also think hooking into the redis from [bovine_pubsub](https://codeberg.org/bovine/bovine/src/branch/dev/bovine_pubsub) for this. mechanical_herd will probably be part of the bovine user management interface.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A framework to automate reacting to ActivityStreams events.",
"version": "0.2.6",
"project_urls": {
"Documentation": "https://mechanical-bull.readthedocs.io/en/latest/",
"Homepage": "https://codeberg.org/bovine/mechanical_bull",
"Repository": "https://codeberg.org/bovine/mechanical_bull"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c3f5c9c2fe162ed75b623b605f834dfac5ecb93dd30f34759390bdec2867a5bc",
"md5": "059299948ac19ac83872d2dae2cc6cfc",
"sha256": "032c2bdd380527836e82f93fd72f40cd87ce628db543c9db8b5e4dd67c52f1c8"
},
"downloads": -1,
"filename": "mechanical_bull-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "059299948ac19ac83872d2dae2cc6cfc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 11753,
"upload_time": "2023-10-27T18:03:10",
"upload_time_iso_8601": "2023-10-27T18:03:10.807319Z",
"url": "https://files.pythonhosted.org/packages/c3/f5/c9c2fe162ed75b623b605f834dfac5ecb93dd30f34759390bdec2867a5bc/mechanical_bull-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "66f5bd630db64297a85005839c27fb4e1761b5fcdb923002bc19c1a67f8de611",
"md5": "864e1b24c2a96372d7668391e17e5fc0",
"sha256": "868f4a1c9656f8fab9e7c62620ac98a95af9ca752804e6c0a5a256f450c41733"
},
"downloads": -1,
"filename": "mechanical_bull-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "864e1b24c2a96372d7668391e17e5fc0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 12241,
"upload_time": "2023-10-27T18:03:12",
"upload_time_iso_8601": "2023-10-27T18:03:12.483478Z",
"url": "https://files.pythonhosted.org/packages/66/f5/bd630db64297a85005839c27fb4e1761b5fcdb923002bc19c1a67f8de611/mechanical_bull-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-27 18:03:12",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": true,
"codeberg_user": "bovine",
"codeberg_project": "mechanical_bull",
"lcname": "mechanical-bull"
}
JSON