-
Notifications
You must be signed in to change notification settings - Fork 0
API v1
Create a wrapper for a given wiki and API version:
from scuttle import scuttle
API_KEY = "eyJ0eXAiOiJKV1QiLC(...)" # Personal Access Token
wiki = scuttle('en', API_KEY, 1)The wiki here is 'en' and the API version is 1.
If you don't know the domain of your wiki:
print(scuttle(None, API_KEY, 1).wikis())Find your wiki in the list.
v1 of the API is tightly-scoped and you may have to make multiple requests in order to find the information you need.
For example, if you wanted to get the most recently-uploaded file from the page to which the user Croquembouche's most recent revision was applied:
wiki = scuttle('en', API_KEY, 1)
user_id = wiki.wikidotuser("Croquembouche")['wd_user_id']
revisions = wiki.wikidotuser_revisions(user_id, limit=1, direction='desc')
page_id = revisions[0]['page_id']
file_url = wiki.page_files(page_id)[0]['path']Some of SCUTTLE's methods are paginated. This means that each request returns only some of the data you need, and in order to get all the data, you will need to make a series of requests. From the API's wiki, these endpoints are the ones using the POST method.
Paginated methods offer the following keyword arguments:
-
limit: the number of items to be returned per page. Int between 1 and 100, default 20 -
offset: the number of items to skip. Int, default 0 -
direction: the direction that results should be ordered in, typically chronologically. Str of either"asc"or"desc", default"asc"
Paginated methods return more information than their non-paginated counterparts. For example, the non-paginated thread posts endpoint (<Wrapper>.thread_posts(thread_id)) returns an unsorted list of posts in a thread with only their IDs and the ID of their parent posts. However, the paginated method returns an ordered list containing much more information, including the content of the posts. Imagine it like a book - the non-paginated method is the index of the book, telling you where to look to find information; the paginated method is the rest of the book, with page after page of detailed information.
Paginated methods in this wrapper are denoted by the verbose attribute. Paginated versions of methods can be accessed by calling verbose (e.g. <Wrapper>.thread_posts.verbose(thread_id)). For example:
page_id = wiki.page_by_slug("main")['id']
first_20_revisions = wiki.page_revisions.verbose(page_id, limit=20)
first_revision = first_20_revisions[0]Note that some paginated methods do not have a non-paginated counterpart (e.g. POST /forum/{id}/since/{timestamp}). These methods will raise an error if you try to use their non-paginated method - always use the paginated method instead (<Wrapper>.forum_threads_since.verbose(forum_id, timestamp)).
To iterate through all pages of a paginated method, you could write a loop that increments the offset parameter by the limit and then makes the new request. Or, you could let the wrapper do that work for you.
A call to <Wrapper>.verbose with the method you'd like to iterate and any arguments will return a generator that iterates over all pages of the paginated method. For example:
thread_posts_generator = wiki.verbose(wiki.thread_posts, thread_id, limit=20)
for posts in generator:
print(len(posts)) # 20Note that even though we're going to be iterating over the paginated version of the method, <Wrapper>.verbose has been called with the non-paginated version (<Wrapper>.thread_posts). This is to save space and avoid having to write "verbose" twice.
Also note that the length of the returned 'page' will be equal to the specified limit, until you reach the end of the data. The final 'page' will likely contain fewer elements than the limit.
Create a new <Wrapper> instance:
from scuttle import scuttle
wiki = scuttle(domain, API_KEY, 1)Create a generator to iterate over a paginated method:
<Wrapper>.verbose(method: Callable, *args, **kwargs)List all wikis known to SCUTTLE:
<Wrapper>.wikis()Get information about <Wrapper>'s wiki:
<Wrapper>.wiki()Get a list of pages on the wiki:
<Wrapper>.pages()Get a list of pages that have been created since a UNIX timestamp (can be paginated):
<Wrapper>.pages_since(since: int)Get information about a page by its SCUTTLE ID:
<Wrapper>.page_by_id(page_id: int)Get information about a page by its URL slug (a.k.a 'fullname'):
<Wrapper>.page_by_slug(page_slug: str)Get a list of revisions that have been applied to a page (can be paginated):
<Wrapper>.page_revisions(page_id: int)Get a list of votes on a page:
<Wrapper>.page_votes(page_id)Get a list of tags on a page:
<Wrapper>.page_tags(page_id)Get a list of files on a page:
<Wrapper>.page_files(page_id)Get information about a revision:
<Wrapper>.revision(revision_id)Get the content of a revision:
<Wrapper>.full_revision(revision_id)Get a list of forums:
<Wrapper>.forums()Get information about a forum:
<Wrapper>.forum(forum_id)Get a list of threads in a forum:
<Wrapper>.forum_threads(forum_id)Get a list of threads that have been created since a UNIX timestamp (paginated version only):
<Wrapper>.forum_threads_since(forum_id, since)Get information about a single thread:
<Wrapper>.thread(thread_id)Get a list of posts in a thread (can be paginated):
<Wrapper>.thread_posts(thread_id)Get a list of posts in a thread that have been created since a UNIX timestamp (paginated version only):
<Wrapper>.thread_posts_since(thread_id, since)TEXT
<Wrapper>.post(post_id)TEXT
<Wrapper>.post_children(post_id)TEXT
<Wrapper>.post_parent(post_id)TEXT
<Wrapper>.wikidotuser(user_id: int)TEXT
<Wrapper>.wikidotuser_name(wikidot_username: str)TEXT
<Wrapper>.wikidotuser_avatar(wikidot_user_id: int)TEXT (can be paginated):
<Wrapper>.wikidotuser_pages(wikidot_user_id: int)TEXT (can be paginated):
<Wrapper>.wikidotuser_posts(wikidot_user_id: int)TEXT (can be paginated):
<Wrapper>.wikidotuser_revisions(wikidot_user_id: int)TEXT
<Wrapper>.wikidotuser_votes(wikidot_user_id: int)TEXT
<Wrapper>.tags(self)TEXT
<Wrapper>.tag_pages(tag: str)TEXT (paginated version only):
<Wrapper>.tags_pages(tags: Union[List[int], List[str]], operator: str = 'and')