active-boxes 0.0.1.dev2__tar.gz → 0.2.0__tar.gz

{active_boxes-0.0.1.dev2 → active_boxes-0.2.0}/LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2018, Thomas Sileo
-Copyright (c) 2025, Chaiwat Suttipongsakul
+Copyright (c) 2025-2026, Chaiwat Suttipongsakul
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +19,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR PERFORMANCE OF THE
-SOFTWARE.
+SOFTWARE.

active_boxes-0.2.0/PKG-INFO

@@ -0,0 +1,323 @@
+Metadata-Version: 2.4
+Name: active-boxes
+Version: 0.2.0
+Summary: Tiny ActivityPub framework written in Python, both database and server agnostic.
+License: MIT
+License-File: LICENSE
+Author: Chaiwat Suttipongsakul
+Author-email: cwt@bashell.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: aiohttp (>=3.9.0)
+Requires-Dist: bleach (>=6.0.0)
+Requires-Dist: html2text (>=2020.1.16)
+Requires-Dist: markdown (>=3.4.0)
+Requires-Dist: mdx_linkify (>=1.5.0)
+Requires-Dist: pycryptodome (>=3.18.0)
+Requires-Dist: pyld (>=2.0.0)
+Requires-Dist: regex (>=2023.0.0)
+Requires-Dist: requests (>=2.31.0)
+Project-URL: Homepage, https://github.com/cwt/active-boxes
+Description-Content-Type: text/markdown
+
+# Active Boxes (Modernized Little Boxes)
+
+This project is a fork of [Little Boxes](https://github.com/tsileo/little-boxes) that has been modernized and relicensed from ISC to MIT.
+
+**Modernization Complete, ActivityPub Compliance In Progress**
+
+This project has been successfully modernized and updated to current Python packaging standards and Python 3.10+ features. Core ActivityPub functionality is implemented, with federation delivery features under development.
+
+The original README can be found in [ORIGINAL-README.md](ORIGINAL-README.md).
+
+## Current Status
+
+- [x] Migrated from `setup.py` to `pyproject.toml`
+- [x] Moved development dependencies to `pyproject.toml`
+- [x] Switched to Poetry for dependency management and building
+- [x] Updated to require Python 3.10+
+- [x] Created comprehensive modernization plans
+- [x] Modernized codebase to leverage Python 3.10+ features
+- [x] Created comprehensive test suite
+- [x] ActivityPub protocol compliance - Core 11 activities, Extended activities
+- [x] Updated documentation and examples
+- [x] Prepared for stable release
+- [x] **Async-by-default API** with sync wrappers for Flask/Django compatibility
+
+## Modernization Features
+
+### Python 3.10+ Features
+
+- Structural Pattern Matching (match/case statements)
+- Modern Union Types (`X | Y` syntax instead of `Union[X, Y]`)
+- Parenthesized context managers
+- Improved type hinting throughout the codebase
+- Walrus operator usage where appropriate
+- Modern string formatting with f-strings
+
+### Code Quality
+
+- 100% type hinting coverage
+- Comprehensive test suite with ~89% code coverage
+- Modern code formatting with Black
+- Strict linting with Ruff
+- Type checking with MyPy
+
+### Testing
+
+- ActivityPub protocol compliance testing (core + extended activities)
+- Integration tests with mock servers
+- Property-based testing for robustness
+- Security-focused test suite (~89% coverage)
+
+## Implemented ActivityPub Features
+
+### Core Activities [x]
+
+Create, Update, Delete, Follow, Accept, Reject, Add, Remove, Like, Block, Undo, Announce
+
+### Extended Activities [x]
+
+Flag, Move, Join, Leave, View, Listen, Read, Write, Travel, Arrive
+
+### Actor Properties [x]
+
+inbox, outbox, following, followers, preferredUsername, endpoints (sharedInbox)
+
+### Collections [x]
+
+Collection, OrderedCollection, CollectionPage, OrderedCollectionPage
+
+### Security [x]
+
+HTTP Signatures (generation/verification), Linked Data Signatures
+
+### Plugin Interface [x]
+
+`active_boxes.plugin.ActivityPubPlugin` - Protocol defining app responsibilities
+
+### Missing (Under Development)
+
+- Per-object Likes/Shares collections
+- Backward pagination in collections
+- Featured collection support
+
+## Quick Start
+
+**This is an async-first library** - the primary API uses `async`/`await`. Sync wrappers (e.g., `fetch_iri_sync()`) are available for Flask/Django compatibility.
+
+### 1. Implement the Plugin Protocol
+
+```python
+from active_boxes import activitypub as ap
+from active_boxes.plugin import ActivityPubPlugin
+
+class MyAppPlugin(ActivityPubPlugin):
+    BASE_URL = "https://myapp.example"
+
+    # Required: URL generation
+    def base_url(self) -> str:
+        return self.BASE_URL
+
+    def activity_url(self, obj_id: str) -> str:
+        return f"{self.BASE_URL}/activity/{obj_id}"
+
+    def note_url(self, obj_id: str) -> str:
+        return f"{self.BASE_URL}/note/{obj_id}"
+
+    # Required: Deliver activities to remote inboxes
+    async def deliver_activity(
+        self,
+        activity: dict,
+        inbox: str,
+        actor: dict,
+    ) -> bool:
+        signed = self.sign_request(activity, actor)
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(inbox, json=signed)
+        return resp.status_code in (200, 201, 202)
+
+    # Required: Process incoming activities
+    async def receive_activity(
+        self,
+        activity: dict,
+        source_inbox: str | None = None,
+    ) -> bool:
+        if self.is_duplicate(activity["id"]):
+            return False  # Skip duplicate
+        await self.store_activity(activity, source_inbox)
+        await self.process_activity(activity)
+        return True
+
+    # Required: Deduplication
+    def is_duplicate(self, activity_id: str) -> bool:
+        return self.redis.exists(f"activity:{activity_id}")
+
+    # Optional: Add extra recipients for all activities
+    def extra_inboxes(self) -> list[str]:
+        return []  # Or add a shared inbox
+
+    def sign_request(self, activity: dict, actor: dict) -> dict:
+        # Your HTTP signature logic here
+        ...
+```
+
+### 2. Initialize the Backend
+
+```python
+from active_boxes import activitypub as ap
+
+plugin = MyAppPlugin()
+ap.use_backend(plugin)
+```
+
+### 3. Create and Send Activities
+
+**Async (Recommended for FastAPI, aiohttp, etc.):**
+
+```python
+# Create a note
+note = ap.Note(
+    content="Hello, federation!",
+    attributedTo="https://myapp.example/user/alice",
+    to=[ap.AS_PUBLIC],
+)
+
+# Create the activity wrapping the note
+create = note.build_create()
+create.set_id("https://myapp.example/activity/abc123", "abc123")
+
+# Get recipients and deliver
+recipients = create.recipients()  # Computed by library
+for inbox in recipients:
+    actor = await fetch_actor(create.get_actor().id)
+    await plugin.deliver_activity(create.to_dict(), inbox, actor)
+```
+
+**Sync (For Flask, Django sync views):**
+
+```python
+# Create a note
+note = ap.Note(
+    content="Hello, federation!",
+    attributedTo="https://myapp.example/user/alice",
+    to=[ap.AS_PUBLIC],
+)
+
+# Create the activity wrapping the note
+create = note.build_create()
+create.set_id("https://myapp.example/activity/abc123", "abc123")
+
+# Get recipients and deliver (sync wrapper)
+recipients = create.recipients()
+for inbox in recipients:
+    actor = fetch_actor_sync(create.get_actor_sync().id)
+    plugin.deliver_activity(create.to_dict(), inbox, actor)
+```
+
+### 4. Receive Activities
+
+**Async (FastAPI, aiohttp):**
+
+```python
+# In your inbox endpoint handler
+async def inbox_handler(request):
+    activity = await request.json()
+    await plugin.receive_activity(activity, source_inbox=str(request.url))
+    return web.Response(status=202)
+```
+
+**Sync (Flask, Django sync views):**
+
+```python
+# In your Flask route
+@app.post("/inbox")
+def inbox():
+    activity = request.get_json()
+    plugin.receive_activity_sync(activity, source_inbox=request.url)
+    return "", 202
+```
+
+### 5. Working with Actors
+
+```python
+# Create a person actor
+person = ap.Person(
+    id="https://myapp.example/user/alice",
+    inbox="https://myapp.example/user/alice/inbox",
+    outbox="https://myapp.example/user/alice/outbox",
+    followers="https://myapp.example/user/alice/followers",
+    preferredUsername="alice",
+    publicKey={
+        "id": "https://myapp.example/user/alice#main-key",
+        "owner": "https://myapp.example/user/alice",
+        "publicKeyPem": "-----BEGIN PUBLIC KEY-----...",
+    },
+)
+```
+
+### 6. Collection Pagination
+
+```python
+# Build a paginated outbox
+outbox = ap.OrderedCollection(
+    id="https://myapp.example/user/alice/outbox",
+    totalItems=42,
+    first="https://myapp.example/user/alice/outbox?page=1",
+)
+
+# Library handles parsing remote collections (async)
+items = await backend.parse_collection(url="https://example.com/user/bob/outbox")
+
+# Or use sync wrapper
+items = backend.parse_collection_sync(url="https://example.com/user/bob/outbox")
+```
+
+## API Naming Convention
+
+The library uses an **async-first** naming convention:
+
+| Operation | Async (Primary) | Sync Wrapper |
+|-----------|----------------|--------------|
+| Fetch IRI | `fetch_iri()` | `fetch_iri_sync()` |
+| Fetch JSON | `fetch_json()` | `fetch_json_sync()` |
+| Get Actor | `get_actor()` | `get_actor_sync()` |
+| Get Object | `get_object()` | `get_object_sync()` |
+| WebFinger | `webfinger()` | `webfinger_sync()` |
+| Verify Signature | `verify_request()` | `verify_request_sync()` |
+| Parse Collection | `parse_collection()` | `parse_collection_sync()` |
+
+**Guideline:** Use async methods by default. Use `_sync()` variants only when integrating with sync frameworks like Flask or Django sync views.
+
+## Plugin Responsibilities
+
+| What Library Does | What Your App Does |
+|-------------------|-------------------|
+| Activity/Object serialization | HTTP client setup (httpx, aiohttp, etc.) |
+| Computing recipients | Signing outgoing requests (HTTP Signatures) |
+| HTTP Signature generation | Delivering to remote inboxes |
+| HTTP Signature verification | Receiving from remote inboxes |
+| Collection pagination | Storing activities persistently |
+| Activity vocabulary (Create, Follow, etc.) | Deduplication |
+| WebFinger support | Retry/backoff logic |
+
+## Modernization Plans
+
+Detailed planning documents have been created to guide the modernization effort:
+
+- [MODERNIZE_PLAN.md](documents/MODERNIZE_PLAN.md) - Overall modernization strategy
+- [PYTHON_310_MODERNIZATION.md](documents/PYTHON_310_MODERNIZATION.md) - Python 3.10+ feature implementation
+- [TEST_SUITE_IMPROVEMENTS.md](documents/TEST_SUITE_IMPROVEMENTS.md) - Test suite enhancement plans
+- [ACTIVITYPUB_COMPLIANCE.md](documents/ACTIVITYPUB_COMPLIANCE.md) - ActivityPub protocol compliance requirements
+- [IMPLEMENTATION_PLAN.md](documents/IMPLEMENTATION_PLAN.md) - Detailed 8-week implementation timeline
+
+## Original Project
+
+For information about the original project, please refer to [ORIGINAL-README.md](ORIGINAL-README.md).
+

active_boxes-0.2.0/README.md

@@ -0,0 +1,294 @@
+# Active Boxes (Modernized Little Boxes)
+
+This project is a fork of [Little Boxes](https://github.com/tsileo/little-boxes) that has been modernized and relicensed from ISC to MIT.
+
+**Modernization Complete, ActivityPub Compliance In Progress**
+
+This project has been successfully modernized and updated to current Python packaging standards and Python 3.10+ features. Core ActivityPub functionality is implemented, with federation delivery features under development.
+
+The original README can be found in [ORIGINAL-README.md](ORIGINAL-README.md).
+
+## Current Status
+
+- [x] Migrated from `setup.py` to `pyproject.toml`
+- [x] Moved development dependencies to `pyproject.toml`
+- [x] Switched to Poetry for dependency management and building
+- [x] Updated to require Python 3.10+
+- [x] Created comprehensive modernization plans
+- [x] Modernized codebase to leverage Python 3.10+ features
+- [x] Created comprehensive test suite
+- [x] ActivityPub protocol compliance - Core 11 activities, Extended activities
+- [x] Updated documentation and examples
+- [x] Prepared for stable release
+- [x] **Async-by-default API** with sync wrappers for Flask/Django compatibility
+
+## Modernization Features
+
+### Python 3.10+ Features
+
+- Structural Pattern Matching (match/case statements)
+- Modern Union Types (`X | Y` syntax instead of `Union[X, Y]`)
+- Parenthesized context managers
+- Improved type hinting throughout the codebase
+- Walrus operator usage where appropriate
+- Modern string formatting with f-strings
+
+### Code Quality
+
+- 100% type hinting coverage
+- Comprehensive test suite with ~89% code coverage
+- Modern code formatting with Black
+- Strict linting with Ruff
+- Type checking with MyPy
+
+### Testing
+
+- ActivityPub protocol compliance testing (core + extended activities)
+- Integration tests with mock servers
+- Property-based testing for robustness
+- Security-focused test suite (~89% coverage)
+
+## Implemented ActivityPub Features
+
+### Core Activities [x]
+
+Create, Update, Delete, Follow, Accept, Reject, Add, Remove, Like, Block, Undo, Announce
+
+### Extended Activities [x]
+
+Flag, Move, Join, Leave, View, Listen, Read, Write, Travel, Arrive
+
+### Actor Properties [x]
+
+inbox, outbox, following, followers, preferredUsername, endpoints (sharedInbox)
+
+### Collections [x]
+
+Collection, OrderedCollection, CollectionPage, OrderedCollectionPage
+
+### Security [x]
+
+HTTP Signatures (generation/verification), Linked Data Signatures
+
+### Plugin Interface [x]
+
+`active_boxes.plugin.ActivityPubPlugin` - Protocol defining app responsibilities
+
+### Missing (Under Development)
+
+- Per-object Likes/Shares collections
+- Backward pagination in collections
+- Featured collection support
+
+## Quick Start
+
+**This is an async-first library** - the primary API uses `async`/`await`. Sync wrappers (e.g., `fetch_iri_sync()`) are available for Flask/Django compatibility.
+
+### 1. Implement the Plugin Protocol
+
+```python
+from active_boxes import activitypub as ap
+from active_boxes.plugin import ActivityPubPlugin
+
+class MyAppPlugin(ActivityPubPlugin):
+    BASE_URL = "https://myapp.example"
+
+    # Required: URL generation
+    def base_url(self) -> str:
+        return self.BASE_URL
+
+    def activity_url(self, obj_id: str) -> str:
+        return f"{self.BASE_URL}/activity/{obj_id}"
+
+    def note_url(self, obj_id: str) -> str:
+        return f"{self.BASE_URL}/note/{obj_id}"
+
+    # Required: Deliver activities to remote inboxes
+    async def deliver_activity(
+        self,
+        activity: dict,
+        inbox: str,
+        actor: dict,
+    ) -> bool:
+        signed = self.sign_request(activity, actor)
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(inbox, json=signed)
+        return resp.status_code in (200, 201, 202)
+
+    # Required: Process incoming activities
+    async def receive_activity(
+        self,
+        activity: dict,
+        source_inbox: str | None = None,
+    ) -> bool:
+        if self.is_duplicate(activity["id"]):
+            return False  # Skip duplicate
+        await self.store_activity(activity, source_inbox)
+        await self.process_activity(activity)
+        return True
+
+    # Required: Deduplication
+    def is_duplicate(self, activity_id: str) -> bool:
+        return self.redis.exists(f"activity:{activity_id}")
+
+    # Optional: Add extra recipients for all activities
+    def extra_inboxes(self) -> list[str]:
+        return []  # Or add a shared inbox
+
+    def sign_request(self, activity: dict, actor: dict) -> dict:
+        # Your HTTP signature logic here
+        ...
+```
+
+### 2. Initialize the Backend
+
+```python
+from active_boxes import activitypub as ap
+
+plugin = MyAppPlugin()
+ap.use_backend(plugin)
+```
+
+### 3. Create and Send Activities
+
+**Async (Recommended for FastAPI, aiohttp, etc.):**
+
+```python
+# Create a note
+note = ap.Note(
+    content="Hello, federation!",
+    attributedTo="https://myapp.example/user/alice",
+    to=[ap.AS_PUBLIC],
+)
+
+# Create the activity wrapping the note
+create = note.build_create()
+create.set_id("https://myapp.example/activity/abc123", "abc123")
+
+# Get recipients and deliver
+recipients = create.recipients()  # Computed by library
+for inbox in recipients:
+    actor = await fetch_actor(create.get_actor().id)
+    await plugin.deliver_activity(create.to_dict(), inbox, actor)
+```
+
+**Sync (For Flask, Django sync views):**
+
+```python
+# Create a note
+note = ap.Note(
+    content="Hello, federation!",
+    attributedTo="https://myapp.example/user/alice",
+    to=[ap.AS_PUBLIC],
+)
+
+# Create the activity wrapping the note
+create = note.build_create()
+create.set_id("https://myapp.example/activity/abc123", "abc123")
+
+# Get recipients and deliver (sync wrapper)
+recipients = create.recipients()
+for inbox in recipients:
+    actor = fetch_actor_sync(create.get_actor_sync().id)
+    plugin.deliver_activity(create.to_dict(), inbox, actor)
+```
+
+### 4. Receive Activities
+
+**Async (FastAPI, aiohttp):**
+
+```python
+# In your inbox endpoint handler
+async def inbox_handler(request):
+    activity = await request.json()
+    await plugin.receive_activity(activity, source_inbox=str(request.url))
+    return web.Response(status=202)
+```
+
+**Sync (Flask, Django sync views):**
+
+```python
+# In your Flask route
+@app.post("/inbox")
+def inbox():
+    activity = request.get_json()
+    plugin.receive_activity_sync(activity, source_inbox=request.url)
+    return "", 202
+```
+
+### 5. Working with Actors
+
+```python
+# Create a person actor
+person = ap.Person(
+    id="https://myapp.example/user/alice",
+    inbox="https://myapp.example/user/alice/inbox",
+    outbox="https://myapp.example/user/alice/outbox",
+    followers="https://myapp.example/user/alice/followers",
+    preferredUsername="alice",
+    publicKey={
+        "id": "https://myapp.example/user/alice#main-key",
+        "owner": "https://myapp.example/user/alice",
+        "publicKeyPem": "-----BEGIN PUBLIC KEY-----...",
+    },
+)
+```
+
+### 6. Collection Pagination
+
+```python
+# Build a paginated outbox
+outbox = ap.OrderedCollection(
+    id="https://myapp.example/user/alice/outbox",
+    totalItems=42,
+    first="https://myapp.example/user/alice/outbox?page=1",
+)
+
+# Library handles parsing remote collections (async)
+items = await backend.parse_collection(url="https://example.com/user/bob/outbox")
+
+# Or use sync wrapper
+items = backend.parse_collection_sync(url="https://example.com/user/bob/outbox")
+```
+
+## API Naming Convention
+
+The library uses an **async-first** naming convention:
+
+| Operation | Async (Primary) | Sync Wrapper |
+|-----------|----------------|--------------|
+| Fetch IRI | `fetch_iri()` | `fetch_iri_sync()` |
+| Fetch JSON | `fetch_json()` | `fetch_json_sync()` |
+| Get Actor | `get_actor()` | `get_actor_sync()` |
+| Get Object | `get_object()` | `get_object_sync()` |
+| WebFinger | `webfinger()` | `webfinger_sync()` |
+| Verify Signature | `verify_request()` | `verify_request_sync()` |
+| Parse Collection | `parse_collection()` | `parse_collection_sync()` |
+
+**Guideline:** Use async methods by default. Use `_sync()` variants only when integrating with sync frameworks like Flask or Django sync views.
+
+## Plugin Responsibilities
+
+| What Library Does | What Your App Does |
+|-------------------|-------------------|
+| Activity/Object serialization | HTTP client setup (httpx, aiohttp, etc.) |
+| Computing recipients | Signing outgoing requests (HTTP Signatures) |
+| HTTP Signature generation | Delivering to remote inboxes |
+| HTTP Signature verification | Receiving from remote inboxes |
+| Collection pagination | Storing activities persistently |
+| Activity vocabulary (Create, Follow, etc.) | Deduplication |
+| WebFinger support | Retry/backoff logic |
+
+## Modernization Plans
+
+Detailed planning documents have been created to guide the modernization effort:
+
+- [MODERNIZE_PLAN.md](documents/MODERNIZE_PLAN.md) - Overall modernization strategy
+- [PYTHON_310_MODERNIZATION.md](documents/PYTHON_310_MODERNIZATION.md) - Python 3.10+ feature implementation
+- [TEST_SUITE_IMPROVEMENTS.md](documents/TEST_SUITE_IMPROVEMENTS.md) - Test suite enhancement plans
+- [ACTIVITYPUB_COMPLIANCE.md](documents/ACTIVITYPUB_COMPLIANCE.md) - ActivityPub protocol compliance requirements
+- [IMPLEMENTATION_PLAN.md](documents/IMPLEMENTATION_PLAN.md) - Detailed 8-week implementation timeline
+
+## Original Project
+
+For information about the original project, please refer to [ORIGINAL-README.md](ORIGINAL-README.md).

{active_boxes-0.0.1.dev2 → active_boxes-0.2.0}/active_boxes/__version__.py

@@ -2,7 +2,7 @@ try:
     import importlib.metadata as importlib_metadata
 except ImportError:
     # Python < 3.8
-    import importlib_metadata
+    import importlib_metadata  # type: ignore[no-redef,import-not-found]
 
 try:
     __version__ = importlib_metadata.version("active-boxes")