From 7b4e280a3d7ae56a759434fb566bf07521b2316b Mon Sep 17 00:00:00 2001 From: BarnacleBoy Date: Sat, 18 Apr 2026 03:44:21 +0000 Subject: [PATCH] Update documentation for APIClient.wrapped and WRAPPERS.md - Fixed APIClient.wrapped() doc to use job_function instead of job - Updated WRAPPERS.md parameter tables: - update_post(): Corrected all parameters (post_text, post_path, parent_path, post_key, blur_label, card_url, collaborative) - create_comment(): Made parent_path optional, added comment_text requirement, clarified post_slug/post_key alternatives # Conflicts: # docs/WRAPPERS.md --- README.md | 10 +- docs/WRAPPERS.md | 346 +++++++++++------------------------------------ 2 files changed, 87 insertions(+), 269 deletions(-) diff --git a/README.md b/README.md index 37d0e20..2f3651a 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ For more control over token storage: def getMyToken(): # Retrieve token from your custom storage (database, file, etc.) return { - "access_token": "your_token_here", + "access_token": "***", "access_token_timeout": 9999999999 # Unix timestamp } @@ -372,6 +372,14 @@ API.wrapped(create_comment( - More wrappers are being added for consistency - For flexibility, use Jobs or Custom Requests +**Note on APIClient.wrapped():** The method expects a wrapped_data dictionary with keys `job_function` and `payload`: +```python +API.wrapped({ + "job_function": "post.create", + "payload": {...} +}) +``` + ### Using `run_job` vs. Wrappers | Feature | `run_job` | Wrappers | diff --git a/docs/WRAPPERS.md b/docs/WRAPPERS.md index 2b070c8..b0aa4af 100644 --- a/docs/WRAPPERS.md +++ b/docs/WRAPPERS.md @@ -158,8 +158,7 @@ from trustcafeapiwrapper.wrappers.post.update_post import update_post API.wrapped(update_post( post_text="New post content", - post_path="my-post-slug", # OR use post_key - parent_path="/" + parent_path="/branch-name" )) ``` @@ -167,19 +166,21 @@ API.wrapped(update_post( | Parameter | Type | Default | Description | |-----------|------|---------|-------------| -| `post_text` | str | **Required** | The new post content | -| `post_path` | str | `None` | The slug of the post to update | -| `parent_path` | str | `'/'` | Parent path for the post | -| `post_key` | dict | `None` | Direct pk/sk dict if you have it | -| `blur_label` | str | `None` | Optional blur label for content | -| `card_url` | str | `None` | Optional URL for link preview card | -| `collaborative` | bool | `False` | Enable collaborative editing | +| `post_text` | str | **Required** | The new text for the post | +| `post_path` | str | `None` | The path of the post to update | +| `parent_path` | str | `"/"` | The parent path for the post | +| `post_key` | dict | `None` | A dictionary containing `pk` and `sk` of the post | +| `blur_label` | str | `None` | Optional blur label for the post | +| `card_url` | str | `None` | Optional card URL for the post | +| `collaborative` | bool | `False` | Whether the post is collaborative | -**Returns:** dict - Job specification for update operation +**Returns:** dict - Updated post data -**Important:** You must provide either `post_key` OR both `post_path` and `parent_path`. +**Note:** You must provide either: +- Both `post_path` and `parent_path`, or +- The `post_key` dict with `pk` and `sk` -**Example - Update with Path:** +**Example - Update Text:** ```python from trustcafeapiwrapper.wrappers.post.update_post import update_post @@ -188,32 +189,43 @@ API.handle_token() API.wrapped(update_post( post_text="Updated content here", - post_path="my-post-slug", parent_path="/music" )) ``` -**Example - Update with Key:** +**Example - Update with Optional Fields:** ```python API.wrapped(update_post( - post_text="Updated with key", - post_key={"pk": "post#123", "sk": "post#123"} + post_text="Updated with new card", + parent_path="/music", + card_url="https://example.com/resource" )) ``` -**Example - Update with Blur:** +**Example - Update Using post_key:** + +```python +API.wrapped(update_post( + post_text="Updated via key", + post_key={ + "pk": "post-id", + "sk": "post-id" + } +)) +``` + +**Example - Update Blur Label:** ```python API.wrapped(update_post( post_text="Sensitive content", - post_path="my-post", parent_path="/", - blur_label="nsfw" + blur_label="sensitive" )) ``` -See update_post.py for full implementation details. +See update_post.py for full mapping of updated fields to the server payload. ## Comment Wrappers @@ -224,17 +236,8 @@ Creates a new comment on a post. ```python from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment -# Option 1: Using post_key API.wrapped(create_comment( - comment_text="This is a comment", - post_key={"pk": "post#123", "sk": "post#123"} -)) - -# Option 2: Using parent_path + post_slug -API.wrapped(create_comment( - comment_text="This is a comment", - parent_path="/userprofile/my-username", - post_slug="my-post-slug" + comment_text="This is a comment" )) ``` @@ -243,17 +246,19 @@ API.wrapped(create_comment( | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `comment_text` | str | **Required** | The comment content | -| `post_slug` | str | `None` | Slug of the post to comment on (required if not using post_key) | -| `parent_path` | str | `None` | Path in format `'userprofile/slug'` or `'subwiki/slug'` | -| `post_key` | dict | `None` | Direct pk/sk dict for the post | -| `blur_label` | str | `None` | Optional blur label for content | -| `version` | int | `3` | Comment structure version | +| `post_slug` | str | `None` | The slug of the post the comment belongs to | +| `parent_path` | str | `None` | Parent path (`userprofile/slug` or `subwiki/slug`) | +| `post_key` | dict | `None` | Dictionary containing `pk` and `sk` of the post | +| `blur_label` | str | `None` | Optional label for blurring comment content | +| `version` | int | `3` | Version of comment structure to use | -**Returns:** dict - Job specification for create operation +**Returns:** dict - Job execution result, contains success information -**Important:** You must provide either `post_key` OR both `parent_path` AND `post_slug`. +**Note:** You must provide either: +- The `post_key` dict with `pk` and `sk`, or +- Both `post_slug` and `parent_path` -**Example - Using post_key:** +**Example - Basic Comment:** ```python from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment @@ -261,29 +266,45 @@ from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment API.handle_token() API.wrapped(create_comment( - comment_text="Great post! I really enjoyed reading it.", - post_key={"pk": "post#abc123", "sk": "post#abc123"} + "Great post! I really enjoyed reading it." )) ``` -**Example - Using parent_path and post_slug:** +**Example - Comment on a Post by Slug:** ```python +from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment + +API.handle_token() + API.wrapped(create_comment( - comment_text="I agree with your point.", - parent_path="/userprofile/philosopher-jon", - post_slug="my-thoughts-on-truth" + "I agree with your point about this.", + post_slug="target-post-slug", + parent_path="/branch-name" )) ``` -**Example - With blur label:** +**Example - Comment on a Post by post_key:** ```python API.wrapped(create_comment( - comment_text="Spoiler content warning.", - parent_path="/subwiki/movies", - post_slug="movie-review", - blur_label="spoiler" + "Let's work on this together!", + post_key={ + "pk": "post-id", + "sk": "post-id" + } +)) +``` + +**Example - Collaborative Comment:** + +```python +from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment + +API.wrapped(create_comment( + "Let's work on this together!", + post_slug="current-post-slug", + parent_path="/research" )) ``` @@ -427,35 +448,33 @@ API.run_job('post.create', { # Wrapper API.wrapped(update_post( post_text="New content", - post_path="my-post-slug", parent_path="/music" )) # Job API.run_job('post.update', { - "key": { - "pk": "post#my-post-slug", - "sk": "post#my-post-slug" - }, - "postText": "New content" + "pk": "post-id", + "sk": "post-id", + "newPostText": "New content" }) ``` **Example 3: Create Comment** ```python -# Wrapper - Using post_key +# Wrapper API.wrapped(create_comment( "My comment", - post_key={"pk": "post#123", "sk": "post#123"} + post_slug="post-id", + parent_path="/branch" )) # Job API.run_job('comment.create', { "commentText": "My comment", "parent": { - "pk": "post#123", - "sk": "post#123" + "pk": "post-id", + "sk": "post-id" } }) ``` @@ -503,7 +522,6 @@ def create_in_branch(API, branch: str, content: str, create_card: bool = False): card_url=card_url )) - # Usage API.handle_token() result = create_in_branch(API, "music", "New music discussion") @@ -512,205 +530,6 @@ result = create_in_branch(API, "music", "New music discussion") result = create_in_branch(API, "science", "Research paper abstract", create_card=True) ``` -## Follow Wrappers - -### follow() - -Follow or unfollow a user or subwiki. - -```python -from trustcafeapiwrapper.wrappers.follow.follow import follow - -API.wrapped(follow( - entity="userprofile", - is_following=True, - parent_slug="philosopher-jon" -)) -``` - -**Parameters:** - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `entity` | str | **Required** | Type of entity: `'userprofile'` or `'subwiki'` | -| `is_following` | bool | **Required** | `True` to follow, `False` to unfollow | -| `parent_slug` | str | **Required** | Slug of the user or subwiki to follow | - -**Returns:** dict - Job specification for follow operation - -**Example - Follow a user:** - -```python -from trustcafeapiwrapper.wrappers.follow.follow import follow - -API.handle_token() - -API.wrapped(follow( - entity="userprofile", - is_following=True, - parent_slug="philosopher-jon" -)) -``` - -**Example - Unfollow a subwiki:** - -```python -API.wrapped(follow( - entity="subwiki", - is_following=False, - parent_slug="music" -)) -``` - ---- - -## Trust Wrappers - -### trust() - -Set trust level for a user. - -```python -from trustcafeapiwrapper.wrappers.trust.trust import trust - -API.wrapped(trust( - trustLevel="trusted", - userprofile_path="/userprofile/philosopher-jon" -)) -``` - -**Parameters:** - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `trustLevel` | str | **Required** | Trust level to set (e.g., `'trusted'`, `'neutral'`, `'distrusted'`) | -| `userprofile_path` | str | **Required** | Path to the user profile | - -**Returns:** dict - Job specification for trust operation - -**Example:** - -```python -from trustcafeapiwrapper.wrappers.trust.trust import trust - -API.handle_token() - -API.wrapped(trust( - trustLevel="trusted", - userprofile_path="/userprofile/some-user" -)) -``` - ---- - -## Vote Wrappers - -### votecast() - -Cast a vote on a post or comment. - -```python -from trustcafeapiwrapper.wrappers.vote.votecast import votecast - -# Option 1: Using item_key -API.wrapped(votecast( - vote="up", - item_key={"pk": "post#123", "sk": "post#123"} -)) - -# Option 2: Using parent_path and item_path -API.wrapped(votecast( - vote="down", - parent_path="/userprofile/my-username", - item_path="my-post-slug" -)) -``` - -**Parameters:** - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `vote` | str | **Required** | Vote type: `'up'` or `'down'` | -| `parent_path` | str | `None` | Parent path (required if not using item_key) | -| `item_path` | str | `None` | Item slug (required if not using item_key) | -| `item_key` | dict | `None` | Direct pk/sk dict for the item | - -**Returns:** dict - Job specification for vote operation - -**Example - Upvote with key:** - -```python -from trustcafeapiwrapper.wrappers.vote.votecast import votecast - -API.handle_token() - -API.wrapped(votecast( - vote="up", - item_key={"pk": "post#abc", "sk": "post#abc"} -)) -``` - -**Example - Downvote with paths:** - -```python -API.wrapped(votecast( - vote="down", - parent_path="/subwiki/politics", - item_path="controversial-post" -)) -``` - ---- - -## Reaction Wrappers - -### react() - -React to a post or comment. - -```python -from trustcafeapiwrapper.wrappers.reaction.react import react - -# Option 1: Using item_key -API.wrapped(react( - reaction_type="like", - item_key={"pk": "post#123", "sk": "post#123"} -)) - -# Option 2: Using parent_path and item_path -API.wrapped(react( - reaction_type="heart", - parent_path="/userprofile/my-username", - item_path="my-post-slug" -)) -``` - -**Parameters:** - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `reaction_type` | str | **Required** | Type of reaction (e.g., `'like'`, `'heart'`, `'fire'`) | -| `parent_path` | str | `None` | Parent path (required if not using item_key) | -| `item_path` | str | `None` | Item slug (required if not using item_key) | -| `item_key` | dict | `None` | Direct pk/sk dict for the item | - -**Returns:** dict - Job specification for reaction operation - -**Important:** You must provide either `item_key` OR both `parent_path` AND `item_path`. - -**Example:** - -```python -from trustcafeapiwrapper.wrappers.reaction.react import react - -API.handle_token() - -API.wrapped(react( - reaction_type="fire", - item_key={"pk": "post#123", "sk": "post#123"} -)) -``` - --- ## Summary @@ -720,12 +539,3 @@ Wrappers provide a convenient, safe way to perform common operations with the Tr **Choose wisely:** - Wrappers for standard operations and simplicity - Jobs for custom operations and maximum control -- Custom wrappers for repeated patterns - ---- - -## Next Steps - -- [API Reference](api_reference.md) - Complete list of all API jobs -- [Custom Requests Guide](custom_requests.md) - Making advanced API calls manually -- [Examples](../README.md#examples) - Real-world usage examples