diff --git a/README.md b/README.md index 1683135..8c67023 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ # szurubooru-client SzurubooruClient is a wrapper around the excellently-documented Szurubooru API, -including type-safe (if not API-safe) Query and Sort tokens. +including type-safe (if not API-safe) Query and Sort tokens. Includes a Python wrapper. -## Creating a new client +## From Rust -### Basic authentication +### Creating a new client + +#### Basic authentication Please keep in mind that this is not the preferred method of authentication. Tokens are far superior. @@ -15,7 +17,7 @@ let client = SzurubooruClient::new_with_basic_auth("http://localhost:5001", "myu "mypassword", true).unwrap(); ``` -### Token authentication +#### Token authentication The far superior and more secure means of authentication ```rust @@ -23,4 +25,110 @@ use szurubooru_client::SzurubooruClient; let client = SzurubooruClient::new_with_token("http://localhost:5001", "myuser", "sz-123456", true).unwrap(); ``` -For all other methods for making the requests, see the documentation. +For all other methods for making the requests, see the [documentation](https://docs.rs/szurubooru-client/latest). + +## From Python + +Install the client using `pip install szurubooru-client` + +```python +from szurubooru_client import * +from szurubooru_client.tokens import * +from szurubooru_client.models import * +``` + +### Creating a client + + +```python +client = SzurubooruSyncClient("http://localhost:9802", username="integration_user", + password="integration_password", allow_insecure=True) +``` + +### Creating a new tag + + +```python +foo_tag = client.create_tag("foo", category="default", description="The foo tag") +assert foo_tag.names == ["foo"] +``` + +### Returning only a subset of fields + + +```python +# Omit the "description" field +tags = client.list_tags(fields=["version", "names", "category"]) +assert tags.results[0].description is None +``` + +### Uploading from a file path + + +```python +folly1 = client.create_post(file_path="../folly1.jpg", + tags=["maine_coon", "cat", "folly1"], + safety=PostSafety.Safe) +``` + +### Searching for an existing post using an image + + +```python +folly1_search = client.post_for_image("../folly1.jpg") +assert folly1_search is not None +``` + +### Querying by an anonymous tag + + +```python +cat_posts = client.list_posts(query=[anonymous_token("cat")]) +``` + +### Querying by a named tag + + +```python +mc_posts = client.list_posts(query=[named_token(PostNamedToken.Tag, "maine_coon")]) +``` + +### Pagination + + +```python +posts = client.list_posts(limit=1) +assert posts.total == 4 +assert len(posts.results) == 1 + +posts2 = client.list_posts(limit=1, offset=1) +assert posts.results != posts2.results +``` + +### Commenting on a post + + +```python +cat_results = client.list_posts([anonymous_token("cat")]) +post_id = cat_results.results[0].id + +comment = client.create_comment("Excellent cat!", post_id) +``` + +### Getting all comments for a post + + +```python +comment_list = client.list_comments([named_token(CommentNamedToken.Post, post_id)]) +assert len(comment_list.results) != 0 +``` + +### Downloading an image to a local path + + +```python +cat_results = client.list_posts([anonymous_token("cat")]) +post_id = cat_results.results[0].id + +client.download_image_to_path(post_id, "/tmp/cat.jpg") +```