docs: fix parameter mismatches and inaccurate documentation
- Fix update_post() wrapper documentation (post_id -> post_text/post_path/post_key) - Fix create_comment() wrapper documentation (added post_slug, post_key parameters) - Add missing wrapper docs for follow(), trust(), votecast(), react() - Fix reaction job parameters (parent_id -> parent_sk, corrected payload structure) - Fix trust job parameters (updated to match actual payload structure) - Fix vote job parameters (voteType -> vote, added parent structure) - Clearly mark Block and Mute jobs as NOT IMPLEMENTED - Fix GitLab URLs to Forgejo (git.jezzahehn.com) - Remove LLM-style language (comprehensive -> full/thorough) - Fix trust listbyusersinit parameter (username -> user_id)
This commit is contained in:
Jezza Hehn
parent
fd1a1566e9
commit
e7cf4f1e09
6 changed files with 320 additions and 95 deletions
287
docs/WRAPPERS.md
287
docs/WRAPPERS.md
|
|
@ -157,8 +157,9 @@ Updates an existing post.
|
|||
from trustcafeapiwrapper.wrappers.post.update_post import update_post
|
||||
|
||||
API.wrapped(update_post(
|
||||
post_id="post-uuid",
|
||||
new_post_text="New post content"
|
||||
post_text="New post content",
|
||||
post_path="my-post-slug", # OR use post_key
|
||||
parent_path="/"
|
||||
))
|
||||
```
|
||||
|
||||
|
|
@ -166,15 +167,19 @@ API.wrapped(update_post(
|
|||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `post_id` | str | **Required** | The post to update (pk/sk) |
|
||||
| `new_post_text` | str | **Required** | The new post content |
|
||||
| Optional fields per the API (e.g., blurLabel, cardUrl, etc.)
|
||||
| `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 |
|
||||
|
||||
**Returns:** dict - Updated post data
|
||||
**Returns:** dict - Job specification for update operation
|
||||
|
||||
**Important:** The post_id parameter should be set to the post's pk/sk. The wrapper internally maps the update parameters to the API's update payload structure.
|
||||
**Important:** You must provide either `post_key` OR both `post_path` and `parent_path`.
|
||||
|
||||
**Example - Update Text:**
|
||||
**Example - Update with Path:**
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.post.update_post import update_post
|
||||
|
|
@ -182,31 +187,33 @@ from trustcafeapiwrapper.wrappers.post.update_post import update_post
|
|||
API.handle_token()
|
||||
|
||||
API.wrapped(update_post(
|
||||
post_id="current-pk-same-as-sk",
|
||||
new_post_text="Updated content here"
|
||||
post_text="Updated content here",
|
||||
post_path="my-post-slug",
|
||||
parent_path="/music"
|
||||
))
|
||||
```
|
||||
|
||||
**Example - Update with Optional Fields:**
|
||||
**Example - Update with Key:**
|
||||
|
||||
```python
|
||||
API.wrapped(update_post(
|
||||
post_id="current-pk-same-as-sk",
|
||||
new_post_text="Updated with new card",
|
||||
card_url="https://example.com/resource"
|
||||
post_text="Updated with key",
|
||||
post_key={"pk": "post#123", "sk": "post#123"}
|
||||
))
|
||||
```
|
||||
|
||||
**Example - Update Blur Label:**
|
||||
**Example - Update with Blur:**
|
||||
|
||||
```python
|
||||
API.wrapped(update_post(
|
||||
post_id="current-pk-same-as-sk",
|
||||
blur_label="sensitive"
|
||||
post_text="Sensitive content",
|
||||
post_path="my-post",
|
||||
parent_path="/",
|
||||
blur_label="nsfw"
|
||||
))
|
||||
```
|
||||
|
||||
See update_post.py for mapping of updated fields to the server payload.
|
||||
See update_post.py for full implementation details.
|
||||
|
||||
## Comment Wrappers
|
||||
|
||||
|
|
@ -217,9 +224,17 @@ 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",
|
||||
parent_path="/"
|
||||
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"
|
||||
))
|
||||
```
|
||||
|
||||
|
|
@ -228,11 +243,17 @@ API.wrapped(create_comment(
|
|||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `comment_text` | str | **Required** | The comment content |
|
||||
| `parent_path` | str | **Required** | Path to the parent post where comment will be created |
|
||||
| `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 |
|
||||
|
||||
**Returns:** dict - Job execution result, contains success information
|
||||
**Returns:** dict - Job specification for create operation
|
||||
|
||||
**Example - Basic Comment:**
|
||||
**Important:** You must provide either `post_key` OR both `parent_path` AND `post_slug`.
|
||||
|
||||
**Example - Using post_key:**
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment
|
||||
|
|
@ -240,30 +261,29 @@ from trustcafeapiwrapper.wrappers.comment.create_comment import create_comment
|
|||
API.handle_token()
|
||||
|
||||
API.wrapped(create_comment(
|
||||
"Great post! I really enjoyed reading it.",
|
||||
parent_path="/"
|
||||
comment_text="Great post! I really enjoyed reading it.",
|
||||
post_key={"pk": "post#abc123", "sk": "post#abc123"}
|
||||
))
|
||||
```
|
||||
|
||||
**Example - Comment on a Post:**
|
||||
**Example - Using parent_path and post_slug:**
|
||||
|
||||
```python
|
||||
# First get the post to find its path
|
||||
post = API.run_job('post.get', "target-post-id")
|
||||
|
||||
# Then create a comment
|
||||
API.wrapped(create_comment(
|
||||
"I agree with your point about this.",
|
||||
parent_path="/music" # Path to the post
|
||||
comment_text="I agree with your point.",
|
||||
parent_path="/userprofile/philosopher-jon",
|
||||
post_slug="my-thoughts-on-truth"
|
||||
))
|
||||
```
|
||||
|
||||
**Example - Collaborative Comment:**
|
||||
**Example - With blur label:**
|
||||
|
||||
```python
|
||||
API.wrapped(create_comment(
|
||||
"Let's work on this together!",
|
||||
parent_path="/current-post"
|
||||
comment_text="Spoiler content warning.",
|
||||
parent_path="/subwiki/movies",
|
||||
post_slug="movie-review",
|
||||
blur_label="spoiler"
|
||||
))
|
||||
```
|
||||
|
||||
|
|
@ -489,6 +509,205 @@ 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue