roboherd 0.1.2__py3-none-any.whl

roboherd/cow/test_init.py

@@ -0,0 +1,56 @@
+import pytest
+from unittest.mock import AsyncMock
+
+from . import RoboCow
+from .types import Information
+
+
+@pytest.mark.parametrize(
+    "name,summary,profile,expected",
+    [
+        ("moocow", None, None, True),
+        ("moocow", None, {"id": "123"}, True),
+        ("moocow", None, {"id": "123", "name": "moocow"}, False),
+        ("moocow", None, {"id": "123", "name": "other"}, True),
+        ("moocow", "description", {"id": "123", "name": "moocow"}, True),
+        (
+            "moocow",
+            "description",
+            {"id": "123", "name": "moocow", "summary": "description"},
+            False,
+        ),
+    ],
+)
+def test_needs_update(name, summary, profile, expected):
+    info = Information(
+        handle="testcow",
+        name=name,
+        description=summary,
+    )
+    cow = RoboCow(information=info, profile=profile)
+
+    assert cow.needs_update() == expected
+
+
+def test_cron():
+    info = Information(handle="testcow")
+    cow = RoboCow(information=info)
+
+    @cow.cron("* * * * *")
+    async def test_func():
+        pass
+
+    assert len(cow.cron_entries) == 1
+
+
+async def test_startup():
+    info = Information(handle="testcow")
+    cow = RoboCow(information=info)
+    cow.profile = {"id": "http://host.test/actor/cow"}
+    mock = AsyncMock()
+
+    cow.startup(mock)
+
+    await cow.run_startup(AsyncMock())
+
+    mock.assert_called_once()

roboherd/cow/test_profile.py

@@ -0,0 +1,49 @@
+import pytest
+
+from .types import Information, MetaInformation
+
+from .profile import determine_profile_update
+
+
+@pytest.mark.parametrize(
+    "info_params, profile",
+    [
+        ({}, {"type": "Service"}),
+        ({"name": "name"}, {"type": "Service", "name": "name"}),
+        ({"description": "description"}, {"type": "Service", "summary": "description"}),
+    ],
+)
+def test_determine_profile_update_no_update(info_params, profile):
+    info = Information(**info_params)
+
+    assert determine_profile_update(info, profile) is None
+
+
+def test_determine_profile_update():
+    info = Information(name="name", description="description")
+    profile = {"id": "http://host.test/actor/1"}
+
+    result = determine_profile_update(info, profile)
+
+    assert result == {
+        "actor": "http://host.test/actor/1",
+        "profile": {"type": "Service", "name": "name", "summary": "description"},
+    }
+
+
+def test_determine_profile_update_author():
+    info = Information(meta_information=MetaInformation(author="acct:author@host.test"))
+    profile = {"id": "http://host.test/actor/1", "type": "Service"}
+
+    result = determine_profile_update(info, profile)
+
+    assert result == {
+        "actor": "http://host.test/actor/1",
+        "actions": [
+            {
+                "action": "update_property_value",
+                "key": "Author",
+                "value": "acct:author@host.test",
+            }
+        ],
+    }

roboherd/cow/test_util.py

@@ -0,0 +1,17 @@
+from unittest.mock import AsyncMock
+from almabtrieb.mqtt import MqttConnection
+
+from .util import HandlerInformation, call_handler
+
+
+async def test_call_handler():
+    test_data = {"test": "data"}
+
+    async def func(data: dict):
+        assert data == test_data
+
+    handler_info = HandlerInformation(func=func)
+
+    connection = AsyncMock(MqttConnection)
+
+    await call_handler(handler_info, test_data, connection, "actor_id")

roboherd/cow/types.py

@@ -0,0 +1,58 @@
+from pydantic import BaseModel, Field
+
+
+class MetaInformation(BaseModel):
+    """Meta Information about the bot. This includes
+    information such as the author and the source repository"""
+
+    source: str | None = Field(
+        None,
+        examples=["https://forge.example/repo"],
+        description="The source repository",
+    )
+
+    author: str | None = Field(
+        None,
+        examples=["acct:author@domain.example"],
+        description="The author, often a Fediverse handle",
+    )
+
+
+class Information(BaseModel):
+    """Information about the cow"""
+
+    type: str = Field(
+        "Service", examples=["Service"], description="ActivityPub type of the actor."
+    )
+
+    handle: str | None = Field(
+        None,
+        examples=["moocow"],
+        description="Used as the handle in `acct:handle@domain.example`",
+    )
+
+    name: str | None = Field(
+        None,
+        examples=["The mooing cow 🐮"],
+        description="The display name of the cow",
+    )
+
+    description: str | None = Field(
+        None,
+        examples=[
+            "I'm a cow that moos.",
+            """<p>An example bot to illustrate Roboherd</p><p>For more information on RoboHerd, see <a href="https://codeberg.org/bovine/roboherd">its repository</a>.</p>""",
+        ],
+        description="The description of the cow, used as summary of the actor",
+    )
+
+    frequency: str | None = Field(
+        None,
+        examples=["daily"],
+        description="Frequency of posting. Is set automatically if cron expressions are used.",
+    )
+
+    meta_information: MetaInformation = Field(
+        MetaInformation(),
+        description="Meta information about the cow, such as the source repository",
+    )

roboherd/cow/util.py

@@ -0,0 +1,23 @@
+from fast_depends import inject
+
+from dataclasses import dataclass
+from typing import Callable, Dict, Awaitable
+
+from almabtrieb import Almabtrieb
+
+
+@dataclass
+class HandlerInformation:
+    func: Callable[[Dict], Awaitable[None]]
+
+
+async def call_handler(
+    handler_info: HandlerInformation,
+    data: dict,
+    connection: Almabtrieb,
+    actor_id: str,
+    cow=None,
+):
+    return await inject(handler_info.func)(
+        data=data, connection=connection, actor_id=actor_id, cow=cow
+    )

roboherd/examples/dev_null.py

@@ -0,0 +1,13 @@
+from roboherd.cow import RoboCow
+from roboherd.cow.types import Information
+
+from .meta import meta_information
+
+bot = RoboCow(
+    information=Information(
+        name="/dev/null",
+        description="""I don't do anything.""",
+        handle="devnull",
+        meta_information=meta_information,
+    )
+)

roboherd/examples/json_echo.py

@@ -0,0 +1,56 @@
+import json
+
+from roboherd.cow import RoboCow
+from roboherd.annotations import RawData, PublishObject
+from roboherd.annotations.bovine import ObjectFactory
+
+from roboherd.cow.types import Information
+from .meta import meta_information
+
+bot = RoboCow(
+    information=Information(
+        handle="jsonecho",
+        name="JSON Echo {}",
+        description="""<p>I'm a silly bot that replies to
+you with the JSON as received through a HTTP
+post request by 
+<a href="https://codeberg.org/helge/cattle_grid">cattle_grid</a>.</p>
+    
+    """,
+        meta_information=meta_information,
+    )
+)
+
+
+def reply_content(raw: dict) -> str:
+    """Formats and escapes the JSON data:
+
+    ```pycon
+    >>> reply_content({"html": "<b>bold</b>"})
+    '<pre><code>{\\n  "html": "&lt;b&gt;bold&lt;/b&gt;"\\n}</code></re>'
+
+    ```
+    """
+    json_formatted = (
+        json.dumps(raw, indent=2)
+        .replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+    )
+    return f"<pre><code>{json_formatted}</code></re>"
+
+
+@bot.incoming_create
+async def create(
+    raw: RawData, publish_object: PublishObject, object_factory: ObjectFactory
+):
+    note = (
+        object_factory.reply(
+            raw.get("object"),
+            content=reply_content(raw),
+        )
+        .as_public()
+        .build()
+    )
+
+    await publish_object(note)

roboherd/examples/meta.py

@@ -0,0 +1,5 @@
+from roboherd.cow.types import MetaInformation
+
+meta_information = MetaInformation(
+    author="acct:helge@mymath.rocks", source="https://codeberg.org/bovine/roboherd"
+)

roboherd/examples/moocow.py

@@ -0,0 +1,39 @@
+import logging
+
+from roboherd.cow import RoboCow
+from roboherd.annotations import EmbeddedObject, PublishObject
+from roboherd.cow.types import Information
+from .meta import meta_information
+
+logger = logging.getLogger(__name__)
+
+moocow = RoboCow(
+    information=Information(
+        handle="moocow",
+        name="The mooing cow 🐮",
+        description="""I'm a cow that likes to moo.
+
+I also serve as an example for the RoboHerd python tool.
+See <a href="https://codeberg.org/helge/roboherd">codeberg.org</a>.""",
+        meta_information=meta_information,
+    )
+)
+
+
+@moocow.incoming_create
+async def on_incoming_create(obj: EmbeddedObject, publisher: PublishObject):
+    recipient = obj.get("attributedTo")
+
+    logger.info("Replying to %s", recipient)
+
+    obj = {
+        "@context": "https://www.w3.org/ns/activitystreams",
+        "type": "Note",
+        "attributedTo": moocow.actor_id,
+        "to": [recipient],
+        "cc": ["https://www.w3.org/ns/activitystreams#Public"],
+        "content": "moo",
+        "inReplyTo": obj.get("id"),
+    }
+
+    await publisher(obj)

roboherd/examples/number.py

@@ -0,0 +1,72 @@
+import random
+from urllib.parse import urlparse
+
+from almabtrieb import Almabtrieb
+
+from roboherd.cow import RoboCow
+from roboherd.annotations import PublishObject
+from roboherd.annotations.bovine import ObjectFactory
+from roboherd.cow.types import Information
+from .meta import meta_information
+
+
+def hostname(actor_id):
+    return urlparse(actor_id).netloc
+
+
+bot = RoboCow(
+    information=Information(
+        handle="even",
+        description="""<p>I'm a bot by Helge. I post a random number every hour. When posting an even number, I change my Fediverse handle to even. When posting an odd one, I use odd.</p>
+
+<p>I also update my name. I'm not sure how you should display my handle with your Fediverse application. Please write a FEP explaining it.</p>""",
+        meta_information=meta_information,
+    )
+)
+
+
+@bot.startup
+async def startup(connection: Almabtrieb, actor_id: str):
+    await connection.trigger(
+        "update_actor",
+        {
+            "actor": actor_id,
+            "actions": [
+                {
+                    "action": "add_identifier",
+                    "identifier": f"acct:odd@{hostname(actor_id)}",
+                    "primary": False,
+                }
+            ],
+        },
+    )
+
+
+@bot.cron("* * * * *")
+async def post_number(
+    connection: Almabtrieb,
+    publisher: PublishObject,
+    factory: ObjectFactory,
+    actor_id: str,
+):
+    number = random.randint(0, 1000)
+
+    note = factory.note(content=f"Number: {number}").as_public().build()
+    await publisher(note)
+
+    handle = "even" if number % 2 == 0 else "odd"
+
+    await connection.trigger(
+        "update_actor",
+        {
+            "actor": actor_id,
+            "actions": [
+                {
+                    "action": "update_identifier",
+                    "identifier": f"acct:{handle}@{hostname(actor_id)}",
+                    "primary": True,
+                }
+            ],
+            "profile": {"name": f"Posted an {handle} number"},
+        },
+    )

roboherd/examples/rooster.py

@@ -0,0 +1,22 @@
+from roboherd.cow import RoboCow
+from roboherd.cow.types import Information
+
+from roboherd.annotations import PublishObject
+from roboherd.annotations.bovine import ObjectFactory
+
+from .meta import meta_information
+
+bot = RoboCow(
+    information=Information(
+        handle="rooster",
+        name="The crowing rooster 🐓",
+        meta_information=meta_information,
+    )
+)
+
+
+@bot.cron("42 * * * *")
+async def crow(publisher: PublishObject, object_factory: ObjectFactory):
+    await publisher(
+        object_factory.note(content="cock-a-doodle-doo").as_public().build()
+    )

roboherd/examples/scarecrow.py

@@ -0,0 +1,21 @@
+from roboherd.cow import RoboCow
+from roboherd.cow.types import Information
+
+from roboherd.annotations import PublishObject
+from roboherd.annotations.bovine import ObjectFactory
+
+from .meta import meta_information
+
+bot = RoboCow(
+    information=Information(
+        name="The scare crow 👩‍🌾",
+        description="""On startup I scare crows""",
+        handle="scarecrow",
+        meta_information=meta_information,
+    )
+)
+
+
+@bot.startup
+async def startup(publish_object: PublishObject, object_factory: ObjectFactory):
+    await publish_object(object_factory.note(content="Booo! 🐦").as_public().build())

roboherd/herd/__init__.py

@@ -0,0 +1,94 @@
+import asyncio
+import logging
+
+from typing import List, Tuple
+from dataclasses import dataclass, field
+
+from roboherd.cow import RoboCow, CronEntry
+from almabtrieb import Almabtrieb
+
+from .manager import HerdManager
+from .scheduler import HerdScheduler
+from .processor import HerdProcessor
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RoboHerd:
+    name: str = "RoboHerd"
+    base_url: str = "http://abel"
+
+    manager: HerdManager = field(default_factory=HerdManager)
+    cows: List[RoboCow] = field(default_factory=list)
+
+    async def run(self, connection: Almabtrieb):
+        async with connection:
+            self.validate(connection)
+            await self.startup(connection)
+            await self.process(connection)
+
+    async def startup(self, connection: Almabtrieb):
+        self.cows = self.manager.existing_cows(connection.information.actors)
+
+        cows_to_create = self.manager.cows_to_create(connection.information.actors)
+
+        for cow_config in cows_to_create:
+            logger.info("Creating cow with name %s", cow_config.name)
+            cow = cow_config.load()
+            result = await connection.create_actor(
+                name=f"{self.manager.prefix}{cow_config.name}",
+                base_url=self.base_url,
+                preferred_username=cow.information.handle,
+                profile={"type": "Service"},
+                automatically_accept_followers=True,
+            )
+            cow.actor_id = result.get("id")
+
+            self.cows.append(cow)
+
+        for cow in self.cows:
+            await cow.run_startup(connection)
+
+    async def process(self, connection: Almabtrieb):
+        async with asyncio.TaskGroup() as tg:
+            logger.info("Starting processing tasks")
+
+            processor = HerdProcessor(connection, self.incoming_handlers())
+            processor.create_tasks(tg)
+
+            scheduler = HerdScheduler(self.cron_entries(), connection)
+            scheduler.create_task(tg)
+
+    def introduce(self, cow: RoboCow):
+        self.manager.add_to_herd(cow)
+
+    def validate(self, connection):
+        result = connection.information
+
+        logger.info("Got base urls: %s", ",".join(result.base_urls))
+
+        if self.base_url not in result.base_urls:
+            logger.error(
+                "Configure base url %s not in base urls %s of server",
+                self.base_url,
+                ", ".join(result.base_urls),
+            )
+            raise ValueError("Incorrectly configured base url")
+
+    def cron_entries(self) -> List[Tuple[RoboCow, CronEntry]]:
+        """Returns the cron entries of all cows"""
+
+        result = []
+        for cow in self.cows:
+            for cron_entry in cow.cron_entries:
+                result.append((cow, cron_entry))
+
+        return result
+
+    def incoming_handlers(self) -> List[RoboCow]:
+        result = []
+        for cow in self.cows:
+            if cow.handlers.has_handlers:
+                result.append(cow)
+        return result

roboherd/herd/builder.py

@@ -0,0 +1,21 @@
+from roboherd.cow import RoboCow
+from roboherd.examples.moocow import moocow  # noqa
+
+
+def create_actor_message_for_cow(cow: RoboCow, base_url):
+    """
+    ```pycon
+    >>> create_actor_message_for_cow(moocow, "http://domain.example/")
+    {'baseUrl': 'http://domain.example/',
+        'preferredUsername': 'moocow',
+        'automaticallyAcceptFollowers': True,
+        'profile': {'type': 'Service'}}
+
+    ```
+    """
+    return {
+        "baseUrl": base_url,
+        "preferredUsername": cow.information.handle,
+        "automaticallyAcceptFollowers": cow.auto_follow,
+        "profile": {"type": "Service"},
+    }

roboherd/herd/manager/__init__.py

@@ -0,0 +1,46 @@
+import logging
+
+from typing import List
+from dataclasses import dataclass, field
+
+from almabtrieb.model import ActorInformation
+
+from roboherd.cow import RoboCow
+
+from .config import HerdConfig, CowConfig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HerdManager:
+    prefix: str = "bot:"
+    herd_config: HerdConfig = field(default_factory=HerdConfig)
+
+    @staticmethod
+    def from_settings(settings):
+        return HerdManager(herd_config=HerdConfig.from_settings(settings))
+
+    def existing_cows(self, actors: List[ActorInformation]) -> List[RoboCow]:
+        existing_cows = []
+
+        for info in actors:
+            if info.name.startswith(self.prefix):
+                cow_name = info.name.removeprefix(self.prefix)
+                cow_config = self.herd_config.for_name(cow_name)
+                if cow_config:
+                    cow = cow_config.load()
+                    cow.actor_id = info.id
+                    existing_cows.append(cow)
+
+        return existing_cows
+
+    def cows_to_create(self, existing_actors: list[ActorInformation]) -> set[CowConfig]:
+        existing_names = {
+            actor.name.removeprefix(self.prefix)
+            for actor in existing_actors
+            if actor.name.startswith(self.prefix)
+        }
+        names_to_create = self.herd_config.names - existing_names
+
+        return {self.herd_config.for_name(name) for name in names_to_create}

roboherd/herd/manager/config.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass, field
+
+from roboherd.cow import RoboCow
+from roboherd.util import load_cow
+
+
+@dataclass
+class CowConfig:
+    name: str = field(metadata={"description": "Name of the cow, must be unique"})
+    module: str
+    attribute: str
+
+    @staticmethod
+    def from_name_and_dict(name, cow: dict) -> "CowConfig":
+        module, attribute = cow["bot"].split(":")
+
+        return CowConfig(
+            name=name,
+            module=module,
+            attribute=attribute,
+        )
+
+    def load(self) -> RoboCow:
+        return load_cow(self.module, self.attribute)
+
+    def __hash__(self):
+        return hash(self.name)
+
+
+@dataclass
+class HerdConfig:
+    cows: list[CowConfig] = field(default_factory=list)
+
+    def for_name(self, name: str) -> CowConfig | None:
+        for cow in self.cows:
+            if cow.name == name:
+                return cow
+        return None
+
+    @property
+    def names(self) -> set[str]:
+        return {cow.name for cow in self.cows}
+
+    @staticmethod
+    def from_settings(settings):
+        cows = [
+            CowConfig.from_name_and_dict(name, config)
+            for name, config in settings.cow.items()
+        ]
+
+        return HerdConfig(cows=cows)
+
+    def load_herd(self) -> list[RoboCow]:
+        return [cow.load() for cow in self.cows]