roboherd 0.1.4__tar.gz → 0.1.6__tar.gz

{roboherd-0.1.4 → roboherd-0.1.6}/.woodpecker/test.yml

@@ -13,8 +13,10 @@ steps:
   test_format:
     image: ghcr.io/astral-sh/uv:python3.11-alpine
     commands:
-      - uv run ruff format .
+      - uv run ruff format --check .
       - uv run ruff check .
+    when:
+      - matrix: { extras: "--all-extras" }
   test_pytest:
     image: ghcr.io/astral-sh/uv:python3.11-alpine
     commands:

{roboherd-0.1.4 → roboherd-0.1.6}/CHANGES.md

@@ -1,5 +1,19 @@
 # Changes to roboherd
 
+## 0.1.6 ([Milestone](https://codeberg.org/bovine/roboherd/milestone/10694))
+
+- Comment on python path [roboherd#34](https://codeberg.org/bovine/roboherd/issues/34)
+- Enable direct posting of markdown [roboherd#35](https://codeberg.org/bovine/roboherd/issues/35)
+
+## 0.1.5 ([Milestone](https://codeberg.org/bovine/roboherd/milestone/10581))
+
+- Allow overriding the base_url [roboherd#12](https://codeberg.org/bovine/roboherd/issues/12)
+- Separate out the internal state of a RoboCow
+- If no preferredUsername is set and handle is updated, send Update Service [roboherd#33](https://codeberg.org/bovine/roboherd/issues/33)
+- Add an icon property [roboherd#10](https://codeberg.org/bovine/roboherd/issues/10)
+- Added a logo [roboherd#32](https://codeberg.org/bovine/roboherd/issues/32)
+- Add PublishActivity annotation [roboherd#30](https://codeberg.org/bovine/roboherd/issues/30)
+
 ## 0.1.4 ([Milestone](https://codeberg.org/bovine/roboherd/milestone/10442))
 
 - Type check the project

{roboherd-0.1.4 → roboherd-0.1.6}/PKG-INFO

@@ -1,7 +1,9 @@
 Metadata-Version: 2.4
 Name: roboherd
-Version: 0.1.4
+Version: 0.1.6
 Summary: A Fediverse bot framework
+Project-URL: Documentation, https://bovine.codeberg.page/roboherd/
+Project-URL: Repository, https://codeberg.org/bovine/roboherd
 Requires-Python: >=3.11
 Requires-Dist: aiohttp>=3.11.12
 Requires-Dist: almabtrieb[mqtt]>=0.1.0a1
@@ -14,6 +16,7 @@ Requires-Dist: tomli-w>=1.1.0
 Requires-Dist: watchfiles>=1.0.4
 Provides-Extra: bovine
 Requires-Dist: bovine>=0.5.15; extra == 'bovine'
+Requires-Dist: markdown>=3.7; extra == 'bovine'
 Description-Content-Type: text/markdown
 
 # Roboherd

{roboherd-0.1.4 → roboherd-0.1.6}/docs/index.md

@@ -11,6 +11,19 @@ We will now tour how to write bots with Roboherd. We start with
 a basic bot that does nothing except have a profile. Then we will
 start by adding features.
 
+First, you will need to install roboherd, see [Installation](#installation).
+For our purposes, you can start by running the docker container via
+
+```bash
+docker run --rm -ti -v .:/app helgekr/roboherd
+```
+
+Then you can run roboherd with local files by running
+
+```bash
+python -mroboherd run
+```
+
 ### Basic bot aka how to configure the profile
 
 The configuration file defines the actor by a name and the used python file,
@@ -93,23 +106,55 @@ Setting me as the author and the source code is contained in [meta_information][
 --8<-- "roboherd/examples/meta.py"
 ```
 
-!!! todo
-    How to configure a profile picture [roboherd#10](https://codeberg.org/bovine/roboherd/issues/10)
+By setting to `icon` property of [roboherd.cow.types.Information][], one can
+change the profile picture.
+
+### Config overrides
+
+By running
+
+```toml title="roboherd.toml"
+base_url = "https://dev.bovine.social"
+
+[cow.devnull]
+bot = "roboherd.examples.dev_null:bot"
+handle = "nothingness"
+```
+
+one would instead create a bot with the handle `acct:nothingness@dev.bovine.social`.
+Similarly, one can override the name and the `base_url` to use.
 
 ### Posting on startup
 
+The simplest way to post is to use
+
+```python
+@bot.startup
+async def startup(poster: MarkdownPoster):
+    await poster("__Booo!__ 🐦")
+```
+
+here [MarkdownPoster][roboherd.annotations.bovine.MarkdownPoster] is an annotation.
+Annotations are injected through [FastDepends](https://lancetnik.github.io/FastDepends/). The markdown poster abstracts away the following steps
+
+- Convert markdown to HTML
+- Create a note based with the HTML as content (done below with the object factory)
+- Send the note to the server (done below with publish object)
+
+### Manually posting
+
 By adding
 
 ```python
 @bot.startup
 async def startup(publish_object: PublishObject, object_factory: ObjectFactory):
-    await publish_object(object_factory.note(content="Booo! 🐦").as_public().build())
+    note = object_factory.note(content="Booo! 🐦").as_public().build()
+    await publish_object(note)
 ```
 
 one can post on startup. Here  [PublishObject][roboherd.annotations.PublishObject]
 and [ObjectFactory][roboherd.annotations.bovine.ObjectFactory]
-are annotations that are injected
-through [FastDepends](https://lancetnik.github.io/FastDepends/).
+are annotations.
 
 PublishObject depends on the [simple storage extension of cattle_grid](https://bovine.codeberg.page/cattle_grid/extensions/simple_storage/), whereas
 ObjectFactory injects an [ObjectFactory][bovine.activitystreams.object_factory.ObjectFactory] provided by the [bovine](https://bovine.readthedocs.io/en/latest/) library.
@@ -119,6 +164,11 @@ ObjectFactory injects an [ObjectFactory][bovine.activitystreams.object_factory.O
     --8<-- "roboherd/examples/scarecrow.py"
     ```
 
+!!! hint
+    Similarly to PublishObject, one can use
+    [PublishActivity][roboherd.annotations.PublishActivity]
+    to post activities.
+
 ### Replying to messages
 
 By adding a block such as
@@ -193,14 +243,14 @@ and the appropriate bots, one can run these bots
 by running
 
 ```bash
-roboherd run
+python -mroboherd run
 ```
 
 inside the container. Alternatively, this can be done directly
 by running
 
 ```bash
-docker run --rm -v .:/app helgekr/roboherd roboherd run
+docker run --rm -v .:/app helgekr/roboherd python -mroboherd run
 ```
 
 ### Installing roboherd as a python package
@@ -211,18 +261,24 @@ To install roboherd with [bovine](https://bovine.readthedocs.io/en/latest/) supp
 pip install roboherd[bovine]
 ```
 
-You are then able to run the roboherd command either by
+You are then able to run the roboherd command
 
 ```bash
-roboherd run
+python -mroboherd run
 ```
 
-or
+### The roboherd command
+
+You can also run roboherd by running
 
 ```bash
-python -mroboherd run
+roboherd run
 ```
 
+The difference to `python -mroboherd run` is that with the former,
+the current directory is not added to the python path. It will still
+be used to find the `roboherd.toml` configuration file.
+
 ## Configuration
 
 roboherd has three global configuration variables, e.g.
@@ -322,3 +378,7 @@ version, have a [milestone](https://codeberg.org/bovine/roboherd/milestones)
 matching the new version, and appropriate entries in
 `CHANGES.md`. Then once a pull request with this is merged,
 the rest happens automatically.
+
+## Acknowledgements
+
+Logo via [Lorc](https://game-icons.net/1x1/lorc/bull-horns.html).

{roboherd-0.1.4 → roboherd-0.1.6}/mkdocs.yml

@@ -5,6 +5,8 @@ repo_url: https://codeberg.org/bovine/roboherd/
 repo_name: bovine/roboherd
 theme:
   name: material
+  logo: assets/bull-horns.png
+  favicon: assets/bull-horns.png
   icon:
     repo: fontawesome/brands/git-alt
   palette:

{roboherd-0.1.4 → roboherd-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roboherd"
-version = "0.1.4"
+version = "0.1.6"
 description = "A Fediverse bot framework"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -16,6 +16,10 @@ dependencies = [
     "watchfiles>=1.0.4",
 ]
 
+[project.urls]
+Documentation = "https://bovine.codeberg.page/roboherd/"
+Repository = "https://codeberg.org/bovine/roboherd"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -26,7 +30,7 @@ roboherd = "roboherd.__main__:main"
 
 
 [project.optional-dependencies]
-bovine = ["bovine>=0.5.15"]
+bovine = ["bovine>=0.5.15", "markdown>=3.7"]
 
 [tool.uv]
 dev-dependencies = [

{roboherd-0.1.4 → roboherd-0.1.6}/roboherd/annotations/__init__.py

@@ -1,7 +1,7 @@
 from fast_depends import Depends
-from typing import Annotated, Callable, Awaitable
+from typing import Annotated
 
-from almabtrieb import Almabtrieb
+from .common import PublishObject, PublishActivity  # noqa
 
 
 def get_raw(data: dict) -> dict:
@@ -41,16 +41,3 @@ Activity = Annotated[dict, Depends(get_activity)]
 
 EmbeddedObject = Annotated[dict, Depends(get_embedded_object)]
 """The embedded object in the activity as parsed by muck_out"""
-
-Publisher = Callable[[dict], Awaitable[None]]
-
-
-def construct_publish_object(connection: Almabtrieb, actor_id: str) -> Publisher:
-    async def publish(data: dict):
-        await connection.trigger("publish_object", {"actor": actor_id, "data": data})
-
-    return publish
-
-
-PublishObject = Annotated[Publisher, Depends(construct_publish_object)]
-"""Allows one to publish an object as the actor. Assumes cattle_grid has the extension `simple_object_storage` or equivalent"""

{roboherd-0.1.4 → roboherd-0.1.6}/roboherd/annotations/bovine.py

@@ -1,8 +1,8 @@
 """Test documentation"""
 
-from typing import Annotated
+from typing import Annotated, Awaitable, Callable
 from fast_depends import Depends
-from .common import Profile
+from .common import Profile, PublishObject
 
 try:
     from bovine.activitystreams import factories_for_actor_object
@@ -39,3 +39,29 @@ ActivityFactory = Annotated[BovineActivityFactory, Depends(get_activity_factory)
 
 ObjectFactory = Annotated[BovineObjectFactory, Depends(get_object_factory)]  # type: ignore
 """The object factory of type [bovine.activitystreams.object_factory.ObjectFactory][]"""
+
+
+try:
+    import markdown
+
+    def get_markdown_poster(  # type: ignore
+        object_factory: ObjectFactory, publish_object: PublishObject
+    ):
+        async def publish_markdown(message: str):
+            content = markdown.markdown(message)
+            note = object_factory.note(content=content).as_public().build()  # type: ignore
+            await publish_object(note)
+
+        return publish_markdown
+
+except ImportError:
+
+    def get_markdown_poster() -> None:
+        raise ImportError("bovine not installed")
+
+
+MarkdownPublisher = Callable[[str], Awaitable[None]]
+"""Type of the markdown publisher"""
+
+MarkdownPoster = Annotated[MarkdownPublisher, Depends(get_markdown_poster)]  # type: ignore
+"""A function that takes a markdown string and posts it as the content of a note"""

roboherd-0.1.6/roboherd/annotations/common.py

@@ -0,0 +1,43 @@
+from fast_depends import Depends
+from typing import Annotated, Callable, Awaitable
+
+from almabtrieb import Almabtrieb
+
+
+from roboherd.cow import RoboCow
+
+
+def get_profile(cow: RoboCow) -> dict:
+    if cow.internals.profile is None:
+        raise ValueError("Cow has no profile")
+    return cow.internals.profile
+
+
+Profile = Annotated[dict, Depends(get_profile)]
+"""The profile of the cow"""
+
+
+Publisher = Callable[[dict], Awaitable[None]]
+"""Type returned by the publishing functions"""
+
+
+def construct_publish_object(connection: Almabtrieb, actor_id: str) -> Publisher:
+    async def publish(data: dict):
+        await connection.trigger("publish_object", {"actor": actor_id, "data": data})
+
+    return publish
+
+
+def construct_publish_activity(connection: Almabtrieb, actor_id: str) -> Publisher:
+    async def publish(data: dict):
+        await connection.trigger("publish_activity", {"actor": actor_id, "data": data})
+
+    return publish
+
+
+PublishObject = Annotated[Publisher, Depends(construct_publish_object)]
+"""Allows one to publish an object as the actor. Assumes cattle_grid has the extension `simple_object_storage` or equivalent"""
+
+
+PublishActivity = Annotated[Publisher, Depends(construct_publish_activity)]
+"""Allows one to publish an activity as the actor. Assumes cattle_grid has the extension `simple_object_storage` or equivalent"""

{roboherd-0.1.4 → roboherd-0.1.6}/roboherd/cow/__init__.py

@@ -25,17 +25,8 @@ class CronEntry:
 
 
 @dataclass
-class RoboCow:
-    information: Information = field(
-        metadata=dict(description="Information about the cow")
-    )
-
-    auto_follow: bool = field(
-        default=True,
-        metadata=dict(
-            description="""Whether to automatically accept follow requests"""
-        ),
-    )
+class RoboCowInternals:
+    """Internal data for the cow"""
 
     profile: dict | None = field(
         default=None,
@@ -69,6 +60,27 @@ class RoboCow:
 
     startup_routine: Callable | None = None
 
+    base_url: str | None = field(default=None)
+
+
+@dataclass
+class RoboCow:
+    information: Information = field(
+        metadata=dict(description="Information about the cow")
+    )
+
+    auto_follow: bool = field(
+        default=True,
+        metadata=dict(
+            description="""Whether to automatically accept follow requests"""
+        ),
+    )
+
+    internals: RoboCowInternals = field(
+        default_factory=RoboCowInternals,
+        metadata=dict(description="Internal data for the cow"),
+    )
+
     def action(self, action: str = "*", activity_type: str = "*"):
         """Adds a handler for an event. Use "*" as a wildcard.
 
@@ -90,15 +102,15 @@ class RoboCow:
 
         def inner(func):
             config.func = func
-            self.handlers.add_handler(config, func)
-            self.handler_configuration.append(config)
+            self.internals.handlers.add_handler(config, func)
+            self.internals.handler_configuration.append(config)
             return func
 
         return inner
 
     def cron(self, crontab):
         def inner(func):
-            self.cron_entries.append(CronEntry(crontab, func))
+            self.internals.cron_entries.append(CronEntry(crontab, func))
 
             return func
 
@@ -119,7 +131,7 @@ class RoboCow:
             action="incoming",
             activity_type="*",
         )
-        self.handlers.add_handler(config, func)
+        self.internals.handlers.add_handler(config, func)
         return func
 
     def incoming_create(self, func):
@@ -137,79 +149,57 @@ class RoboCow:
         config = HandlerConfiguration(
             action="incoming", activity_type="Create", func=func
         )
-        self.handler_configuration.append(config)
-        self.handlers.add_handler(config, func)
+        self.internals.handler_configuration.append(config)
+        self.internals.handlers.add_handler(config, func)
         return func
 
     def startup(self, func):
         """Adds a startup routine to be run when the cow is started."""
 
-        self.startup_routine = func
+        self.internals.startup_routine = func
 
     def needs_update(self):
         """Checks if the cow needs to be updated"""
-        if self.profile is None:
+        if self.internals.profile is None:
             return True
 
-        if self.information.name != self.profile.get("name"):
+        if self.information.name != self.internals.profile.get("name"):
             return True
 
-        if self.information.description != self.profile.get("summary"):
+        if self.information.description != self.internals.profile.get("summary"):
             return True
 
         return False
 
-    def update_data(self):
-        """
-        Returns the update_actor message to send to cattle_grid
-
-        ```pycon
-        >>> info = Information(handle="moocow", name="name", description="description")
-        >>> cow = RoboCow(information=info, actor_id="http://host.example/actor/1")
-        >>> cow.update_data()
-        {'actor': 'http://host.example/actor/1',
-            'profile': {'name': 'name',
-                'summary': 'description'},
-            'automaticallyUpdateFollowers': True}
-
-        ```
-        """
-        return {
-            "actor": self.actor_id,
-            "profile": {
-                "name": self.information.name,
-                "summary": self.information.description,
-            },
-            "automaticallyUpdateFollowers": self.auto_follow,
-        }
-
     async def run_startup(self, connection: Almabtrieb):
         """Runs when the cow is birthed"""
 
-        if self.profile is None:
-            if not self.actor_id:
+        if self.internals.profile is None:
+            if not self.internals.actor_id:
                 raise ValueError("Actor ID is not set")
-            result = await connection.fetch(self.actor_id, self.actor_id)
+            result = await connection.fetch(
+                self.internals.actor_id, self.internals.actor_id
+            )
             if not result.data:
                 raise ValueError("Could not retrieve profile")
-            self.profile = result.data
+            self.internals.profile = result.data
 
-        if self.cron_entries:
+        if self.internals.cron_entries:
             frequency = ", ".join(
-                get_description(entry.crontab) for entry in self.cron_entries
+                get_description(entry.crontab) for entry in self.internals.cron_entries
             )
             self.information.frequency = frequency
 
-        update = determine_profile_update(self.information, self.profile)
+        update = determine_profile_update(self.information, self.internals.profile)
 
         if update:
             logger.info("Updating profile for %s", self.information.handle)
 
             await connection.trigger("update_actor", update)
 
-        if self.startup_routine:
-            await inject(self.startup_routine)(
-                cow=self,
-                connection=connection,
-                actor_id=self.actor_id,
-            )
+        if self.internals.startup_routine:
+            await inject(self.internals.startup_routine)(
+                cow=self,  # type:ignore
+                connection=connection,  # type:ignore
+                actor_id=self.internals.actor_id,  # type:ignore
+            )  # type:ignore

roboherd-0.1.6/roboherd/cow/const.py

@@ -0,0 +1,6 @@
+default_icon = {
+    "mediaType": "image/png",
+    "type": "Image",
+    "url": "https://dev.bovine.social/assets/bull-horns.png",
+}
+"""The default icon to be used"""

{roboherd-0.1.4 → roboherd-0.1.6}/roboherd/cow/profile.py

@@ -24,6 +24,9 @@ def profile_part_needs_update(information: Information, profile: dict) -> bool:
     if information.type != profile.get("type"):
         return True
 
+    if information.icon != profile.get("icon"):
+        return True
+
     return False
 
 
@@ -110,6 +113,7 @@ def determine_profile_update(information: Information, profile: dict) -> dict |
             "type": information.type,
             "name": information.name,
             "summary": information.description,
+            "icon": information.icon,
         }
 
     actions = determine_actions(information, profile)

{roboherd-0.1.4 → roboherd-0.1.6}/roboherd/cow/test_init.py

@@ -27,7 +27,8 @@ def test_needs_update(name, summary, profile, expected):
         name=name,
         description=summary,
     )
-    cow = RoboCow(information=info, profile=profile)
+    cow = RoboCow(information=info)
+    cow.internals.profile = profile
 
     assert cow.needs_update() == expected
 
@@ -40,13 +41,13 @@ def test_cron():
     async def test_func():
         pass
 
-    assert len(cow.cron_entries) == 1
+    assert len(cow.internals.cron_entries) == 1
 
 
 async def test_startup():
     info = Information(handle="testcow")
     cow = RoboCow(information=info)
-    cow.profile = {"id": "http://host.test/actor/cow"}
+    cow.internals.profile = {"id": "http://host.test/actor/cow"}
     mock = AsyncMock()
 
     cow.startup(mock)

{roboherd-0.1.4 → roboherd-0.1.6}/roboherd/cow/test_profile.py

@@ -1,7 +1,7 @@
 import pytest
 
 from .types import Information, MetaInformation
-
+from .const import default_icon
 from .profile import determine_profile_update
 
 
@@ -14,6 +14,7 @@ from .profile import determine_profile_update
     ],
 )
 def test_determine_profile_update_no_update(info_params, profile):
+    profile["icon"] = default_icon
     info = Information(**info_params)
 
     assert determine_profile_update(info, profile) is None
@@ -27,13 +28,22 @@ def test_determine_profile_update():
 
     assert result == {
         "actor": "http://host.test/actor/1",
-        "profile": {"type": "Service", "name": "name", "summary": "description"},
+        "profile": {
+            "type": "Service",
+            "name": "name",
+            "summary": "description",
+            "icon": default_icon,
+        },
     }
 
 
 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"}
+    profile = {
+        "id": "http://host.test/actor/1",
+        "type": "Service",
+        "icon": default_icon,
+    }
 
     result = determine_profile_update(info, profile)
 
@@ -47,3 +57,25 @@ def test_determine_profile_update_author():
             }
         ],
     }
+
+
+def test_profile_update_for_new_preferredUsername():
+    info = Information(handle="handle")
+    profile = {
+        "id": "http://host.test/actor/1",
+        "type": "Service",
+        "icon": default_icon,
+    }
+
+    result = determine_profile_update(info, profile)
+
+    assert result == {
+        "actor": "http://host.test/actor/1",
+        "actions": [
+            {
+                "action": "add_identifier",
+                "identifier": "acct:handle@host.test",
+                "primary": True,
+            }
+        ],
+    }

{roboherd-0.1.4 → roboherd-0.1.6}/roboherd/cow/types.py

@@ -1,5 +1,7 @@
 from pydantic import BaseModel, Field
 
+from .const import default_icon
+
 
 class MetaInformation(BaseModel):
     """Meta Information about the bot. This includes
@@ -48,6 +50,11 @@ class Information(BaseModel):
         description="The description of the cow, used as summary of the actor",
     )
 
+    icon: dict = Field(
+        default=default_icon,
+        description="The profile image",
+    )
+
     frequency: str | None = Field(
         default=None,
         examples=["daily"],