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
This commit is contained in:
BarnacleBoy
parent
2de47079ab
commit
7b4e280a3d
2 changed files with 87 additions and 269 deletions
10
README.md
10
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 |
|
||||
|
|
|
|||
346
docs/WRAPPERS.md
346
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue