active-boxes 0.1.0__tar.gz → 0.2.0__tar.gz

{active_boxes-0.1.0 → active_boxes-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: active-boxes
-Version: 0.1.0
+Version: 0.2.0
 Summary: Tiny ActivityPub framework written in Python, both database and server agnostic.
 License: MIT
 License-File: LICENSE
@@ -14,6 +14,7 @@ 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)
@@ -29,7 +30,7 @@ Description-Content-Type: text/markdown
 
 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** ⚠️
+**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.
 
@@ -44,9 +45,10 @@ The original README can be found in [ORIGINAL-README.md](ORIGINAL-README.md).
 - [x] Created comprehensive modernization plans
 - [x] Modernized codebase to leverage Python 3.10+ features
 - [x] Created comprehensive test suite
-- [~] ActivityPub protocol compliance - Core 11 activities ✅, Extended activities ⚠️
+- [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
 
@@ -62,49 +64,53 @@ The original README can be found in [ORIGINAL-README.md](ORIGINAL-README.md).
 ### Code Quality
 
 - 100% type hinting coverage
-- Comprehensive test suite with ~89% 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 activities)
+- 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 ✅
+### Core Activities [x]
 
 Create, Update, Delete, Follow, Accept, Reject, Add, Remove, Like, Block, Undo, Announce
 
-### Actor Properties ✅
+### Extended Activities [x]
+
+Flag, Move, Join, Leave, View, Listen, Read, Write, Travel, Arrive
+
+### Actor Properties [x]
 
 inbox, outbox, following, followers, preferredUsername, endpoints (sharedInbox)
 
-### Collections ✅
+### Collections [x]
 
 Collection, OrderedCollection, CollectionPage, OrderedCollectionPage
 
-### Security ✅
+### Security [x]
 
 HTTP Signatures (generation/verification), Linked Data Signatures
 
-### Plugin Interface ✅
+### Plugin Interface [x]
 
 `active_boxes.plugin.ActivityPubPlugin` - Protocol defining app responsibilities
 
 ### Missing (Under Development)
 
-- Extended activities: Flag, Move, Join, Leave, View, Listen, Read, Write, Travel, Arrive
 - Per-object Likes/Shares collections
 - Backward pagination in collections
+- Featured collection support
 
 ## Quick Start
 
-**This is an async library** - your plugin should use `asyncio` or any async framework (FastAPI, aiohttp, etc.).
+**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
 
@@ -173,6 +179,8 @@ ap.use_backend(plugin)
 
 ### 3. Create and Send Activities
 
+**Async (Recommended for FastAPI, aiohttp, etc.):**
+
 ```python
 # Create a note
 note = ap.Note(
@@ -188,12 +196,35 @@ create.set_id("https://myapp.example/activity/abc123", "abc123")
 # Get recipients and deliver
 recipients = create.recipients()  # Computed by library
 for inbox in recipients:
-    actor = fetch_actor(create.get_actor().id)
+    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):
@@ -202,6 +233,17 @@ async def inbox_handler(request):
     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
@@ -230,10 +272,29 @@ outbox = ap.OrderedCollection(
     first="https://myapp.example/user/alice/outbox?page=1",
 )
 
-# Library handles parsing remote collections
-items = backend.parse_collection(url="https://example.com/user/bob/outbox")
+# 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 |

{active_boxes-0.1.0 → active_boxes-0.2.0}/README.md

@@ -2,7 +2,7 @@
 
 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** ⚠️
+**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.
 
@@ -17,9 +17,10 @@ The original README can be found in [ORIGINAL-README.md](ORIGINAL-README.md).
 - [x] Created comprehensive modernization plans
 - [x] Modernized codebase to leverage Python 3.10+ features
 - [x] Created comprehensive test suite
-- [~] ActivityPub protocol compliance - Core 11 activities ✅, Extended activities ⚠️
+- [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
 
@@ -35,49 +36,53 @@ The original README can be found in [ORIGINAL-README.md](ORIGINAL-README.md).
 ### Code Quality
 
 - 100% type hinting coverage
-- Comprehensive test suite with ~89% 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 activities)
+- 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 ✅
+### Core Activities [x]
 
 Create, Update, Delete, Follow, Accept, Reject, Add, Remove, Like, Block, Undo, Announce
 
-### Actor Properties ✅
+### Extended Activities [x]
+
+Flag, Move, Join, Leave, View, Listen, Read, Write, Travel, Arrive
+
+### Actor Properties [x]
 
 inbox, outbox, following, followers, preferredUsername, endpoints (sharedInbox)
 
-### Collections ✅
+### Collections [x]
 
 Collection, OrderedCollection, CollectionPage, OrderedCollectionPage
 
-### Security ✅
+### Security [x]
 
 HTTP Signatures (generation/verification), Linked Data Signatures
 
-### Plugin Interface ✅
+### Plugin Interface [x]
 
 `active_boxes.plugin.ActivityPubPlugin` - Protocol defining app responsibilities
 
 ### Missing (Under Development)
 
-- Extended activities: Flag, Move, Join, Leave, View, Listen, Read, Write, Travel, Arrive
 - Per-object Likes/Shares collections
 - Backward pagination in collections
+- Featured collection support
 
 ## Quick Start
 
-**This is an async library** - your plugin should use `asyncio` or any async framework (FastAPI, aiohttp, etc.).
+**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
 
@@ -146,6 +151,8 @@ ap.use_backend(plugin)
 
 ### 3. Create and Send Activities
 
+**Async (Recommended for FastAPI, aiohttp, etc.):**
+
 ```python
 # Create a note
 note = ap.Note(
@@ -161,12 +168,35 @@ create.set_id("https://myapp.example/activity/abc123", "abc123")
 # Get recipients and deliver
 recipients = create.recipients()  # Computed by library
 for inbox in recipients:
-    actor = fetch_actor(create.get_actor().id)
+    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):
@@ -175,6 +205,17 @@ async def inbox_handler(request):
     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
@@ -203,10 +244,29 @@ outbox = ap.OrderedCollection(
     first="https://myapp.example/user/alice/outbox?page=1",
 )
 
-# Library handles parsing remote collections
-items = backend.parse_collection(url="https://example.com/user/bob/outbox")
+# 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 |