doc: audit pass — fix env= bug, params, pagination, missing wrappers, broken examples
- env= -> environment= across all docs (Pydantic silently ignores env=) - Remove __version__ check (doesn't exist in module) - Fix APIClient(debug=True) missing required client_id/secret - Fix post.listremoved usage (takes no postId, just lists removed posts) - Fix JS true/false -> Python True/False in code blocks - Fix parameter names: branchName->branch_slug, username->user_slug, postId->post_id - Add missing lastEvaluatedKey param docs for list jobs - Note post.listpublic as unauthenticated endpoint - Fix pagination examples (LastEvaluatedKey, not ExclusiveStartKey dict) - Remove non-existent headers param from make_request example - Fix branch.listbyname example (takes no name arg) - Add 4 missing wrapper docs: follow, react, trust, votecast - Fix broken internal links (case-sensitive filenames) - Fix <environment>_handle_token template artifact - Add CODE_BUGS.md documenting 4 code bugs found during audit
This commit is contained in:
BarnacleBoy
parent
c8611a7b88
commit
a223bcb27a
9 changed files with 552 additions and 247 deletions
308
documentation.md
308
documentation.md
|
|
@ -1,155 +1,155 @@
|
|||
# Basic usage (without an .env)
|
||||
## Setup
|
||||
Here's a very basic example of setting up:
|
||||
```python
|
||||
import trustcafeapiwrapper
|
||||
|
||||
# Setup the API Client
|
||||
API = trustcafeapiwrapper.APIClient(
|
||||
client_id="YOUR_CLIENT_ID",
|
||||
client_secret="YOUR_CLIENT_SECRET",
|
||||
env="alpha" # alpha | production.
|
||||
debug=False
|
||||
)
|
||||
```
|
||||
or with .env
|
||||
```python
|
||||
import trustcafeapiwrapper, os
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv()
|
||||
API = APIClient(
|
||||
client_id=os.getenv("client_id"),
|
||||
client_secret=os.getenv("client_secret"),
|
||||
env="alpha", # alpha | production.
|
||||
debug=False,
|
||||
)
|
||||
```
|
||||
## Handle token (easy way)
|
||||
|
||||
```python
|
||||
API.handle_token()
|
||||
```
|
||||
## Handling the token yourself
|
||||
|
||||
```python
|
||||
|
||||
def getMyToken():
|
||||
# get the token from your personal store
|
||||
# initially this will be None
|
||||
return token_data
|
||||
|
||||
def saveMyToken():
|
||||
# save your token to your personal store
|
||||
return True
|
||||
|
||||
# Use the old token or None if we haven't logged in ever from here
|
||||
API.set_token(getMyToken())
|
||||
# Get a new one if we don't have one or if the existing one is expired
|
||||
if not API.is_token_valid():
|
||||
saveMyToken(API.sign_in())
|
||||
```
|
||||
|
||||
## Use a wrapper
|
||||
Wrappers make it as simple as possible to perform an action.
|
||||
|
||||
A wrapper will come with a job and a payload ready to be passed to the `wrapped` function.
|
||||
|
||||
eg. Use the `create_post` wrapper
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.post.create_post import create_post
|
||||
|
||||
API.wrapped(create_post(
|
||||
"This is a test post created via the create_post wrapper function.",
|
||||
))
|
||||
```
|
||||
|
||||
|
||||
**_NOTE:_** There are not as many wrappers as jobs because fetching is simpler. More will be added though to make it consistent.
|
||||
|
||||
|
||||
## Make a request via `job`
|
||||
Jobs make the requests to the API. They have the endpoint and path setup already, we just pass the payload. If you want to avoid making your own payload, use a `wrapper`.
|
||||
|
||||
Use the job for getting public posts.
|
||||
|
||||
Now you don't need to worry about which API
|
||||
```python
|
||||
postlist = API.run_job('post.listpublic')
|
||||
print(postlist)
|
||||
'''
|
||||
{
|
||||
"Items": [
|
||||
{
|
||||
...
|
||||
'''
|
||||
```
|
||||
**_NOTE:_** There are aren't the complete set yet created here.
|
||||
|
||||
## Custom Request
|
||||
There should hopefully be a `job` or a `wrapper` that exists for what you need but if not, then this is how you make a request using the core mechanism.
|
||||
|
||||
Use the `make_request` function to make a request from the content API to get posts in the music branch.
|
||||
```python
|
||||
postlist = API.make_request("GET", "content", f"post/ref-subwiki/music")
|
||||
print(postlist)
|
||||
'''
|
||||
{
|
||||
"Items": [
|
||||
{
|
||||
...
|
||||
'''
|
||||
```
|
||||
|
||||
# Jobs
|
||||
## block
|
||||
## branch
|
||||
### `get`
|
||||
### `listbyname`
|
||||
## change
|
||||
## comment
|
||||
### `create`
|
||||
### `listbypostid`
|
||||
## feed
|
||||
## mute
|
||||
## notifcation
|
||||
### `listnotifications`
|
||||
```python
|
||||
API.run_job('notification.listnotifications')
|
||||
```
|
||||
### `markallasread`
|
||||
```python
|
||||
API.run_job('notification.markallasread')
|
||||
```
|
||||
## post
|
||||
### create
|
||||
```python
|
||||
API.run_job('post.create', {
|
||||
"postText": "This is a test post created via the API wrapper.",
|
||||
"parent": {
|
||||
"pk": "maintrunk#maintrunk",
|
||||
"sk": "maintrunk#maintrunk"
|
||||
}
|
||||
})
|
||||
```
|
||||
### get
|
||||
### listall
|
||||
### listbybranch
|
||||
### listbyuserprofile
|
||||
### listpublic
|
||||
### listremoved
|
||||
### update
|
||||
## reaction
|
||||
## trust
|
||||
## userprofile
|
||||
## vote
|
||||
|
||||
|
||||
# Wrappers
|
||||
## post
|
||||
### `create_post`
|
||||
### `update_post`
|
||||
## comment
|
||||
### `create_comment`
|
||||
|
||||
# Basic usage (without an .env)
|
||||
## Setup
|
||||
Here's a very basic example of setting up:
|
||||
```python
|
||||
import trustcafeapiwrapper
|
||||
|
||||
# Setup the API Client
|
||||
API = trustcafeapiwrapper.APIClient(
|
||||
client_id="YOUR_CLIENT_ID",
|
||||
client_secret="YOUR_CLIENT_SECRET",
|
||||
environment="alpha", # alpha | production.
|
||||
debug=False
|
||||
)
|
||||
```
|
||||
or with .env
|
||||
```python
|
||||
import trustcafeapiwrapper, os
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv()
|
||||
API = APIClient(
|
||||
client_id=os.getenv("client_id"),
|
||||
client_secret=os.getenv("client_secret"),
|
||||
environment="alpha", # alpha | production.
|
||||
debug=False,
|
||||
)
|
||||
```
|
||||
## Handle token (easy way)
|
||||
|
||||
```python
|
||||
API.handle_token()
|
||||
```
|
||||
## Handling the token yourself
|
||||
|
||||
```python
|
||||
|
||||
def getMyToken():
|
||||
# get the token from your personal store
|
||||
# initially this will be None
|
||||
return token_data
|
||||
|
||||
def saveMyToken():
|
||||
# save your token to your personal store
|
||||
return True
|
||||
|
||||
# Use the old token or None if we haven't logged in ever from here
|
||||
API.set_token(getMyToken())
|
||||
# Get a new one if we don't have one or if the existing one is expired
|
||||
if not API.is_token_valid():
|
||||
saveMyToken(API.sign_in())
|
||||
```
|
||||
|
||||
## Use a wrapper
|
||||
Wrappers make it as simple as possible to perform an action.
|
||||
|
||||
A wrapper will come with a job and a payload ready to be passed to the `wrapped` function.
|
||||
|
||||
eg. Use the `create_post` wrapper
|
||||
|
||||
```python
|
||||
from trustcafeapiwrapper.wrappers.post.create_post import create_post
|
||||
|
||||
API.wrapped(create_post(
|
||||
"This is a test post created via the create_post wrapper function.",
|
||||
))
|
||||
```
|
||||
|
||||
|
||||
**_NOTE:_** There are not as many wrappers as jobs because fetching is simpler. More will be added though to make it consistent.
|
||||
|
||||
|
||||
## Make a request via `job`
|
||||
Jobs make the requests to the API. They have the endpoint and path setup already, we just pass the payload. If you want to avoid making your own payload, use a `wrapper`.
|
||||
|
||||
Use the job for getting public posts.
|
||||
|
||||
Now you don't need to worry about which API
|
||||
```python
|
||||
postlist = API.run_job('post.listpublic')
|
||||
print(postlist)
|
||||
'''
|
||||
{
|
||||
"Items": [
|
||||
{
|
||||
...
|
||||
'''
|
||||
```
|
||||
**_NOTE:_** There are aren't the complete set yet created here.
|
||||
|
||||
## Custom Request
|
||||
There should hopefully be a `job` or a `wrapper` that exists for what you need but if not, then this is how you make a request using the core mechanism.
|
||||
|
||||
Use the `make_request` function to make a request from the content API to get posts in the music branch.
|
||||
```python
|
||||
postlist = API.make_request("GET", "content", f"post/ref-subwiki/music")
|
||||
print(postlist)
|
||||
'''
|
||||
{
|
||||
"Items": [
|
||||
{
|
||||
...
|
||||
'''
|
||||
```
|
||||
|
||||
# Jobs
|
||||
## block
|
||||
## branch
|
||||
### `get`
|
||||
### `listbyname`
|
||||
## change
|
||||
## comment
|
||||
### `create`
|
||||
### `listbypostid`
|
||||
## feed
|
||||
## mute
|
||||
## notifcation
|
||||
### `listnotifications`
|
||||
```python
|
||||
API.run_job('notification.listnotifications')
|
||||
```
|
||||
### `markallasread`
|
||||
```python
|
||||
API.run_job('notification.markallasread')
|
||||
```
|
||||
## post
|
||||
### create
|
||||
```python
|
||||
API.run_job('post.create', {
|
||||
"postText": "This is a test post created via the API wrapper.",
|
||||
"parent": {
|
||||
"pk": "maintrunk#maintrunk",
|
||||
"sk": "maintrunk#maintrunk"
|
||||
}
|
||||
})
|
||||
```
|
||||
### get
|
||||
### listall
|
||||
### listbybranch
|
||||
### listbyuserprofile
|
||||
### listpublic
|
||||
### listremoved
|
||||
### update
|
||||
## reaction
|
||||
## trust
|
||||
## userprofile
|
||||
## vote
|
||||
|
||||
|
||||
# Wrappers
|
||||
## post
|
||||
### `create_post`
|
||||
### `update_post`
|
||||
## comment
|
||||
### `create_comment`
|
||||
|
||||
# Utils
|
||||
Loading…
Add table
Add a link
Reference in a new issue