> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snipp.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

> Official Python wrapper for the Snipp API.

<Card horizontal icon="github" href="https://github.com/snipp-gg/snipp-py">
  snipp-gg/snipp
</Card>

<Card horizontal icon="python" href="https://pypi.org/project/snipp">
  snipp
</Card>

## Installation

```bash theme={null}
pip install snipp
```

Requires Python 3.9 or later. Depends on `requests`.

## Getting Started

```python theme={null}
from snipp import SnippClient

client = SnippClient(api_key="YOUR_API_KEY")

me = client.get_user("@me")
print(me["user"]["username"])
```

## Methods

### `get_user(user_id, include_posts=None, posts_limit=None)`

Fetch a user by ID. Pass `"@me"` for the authenticated user.

| Parameter       | Type           | Description                          |
| --------------- | -------------- | ------------------------------------ |
| `user_id`       | `str`          | User ID or `"@me"`.                  |
| `include_posts` | `bool \| None` | Include the user's public uploads.   |
| `posts_limit`   | `int \| None`  | Number of posts to return (1 to 50). |

```python theme={null}
user = client.get_user("@me", include_posts=True, posts_limit=10)
```

### `get_post(code)`

Fetch a post by its share code.

| Parameter | Type  | Description                 |
| --------- | ----- | --------------------------- |
| `code`    | `str` | The share code of the post. |

```python theme={null}
post = client.get_post("AbCd1234")
print(post["post"]["url"])
```

### `upload(file, privacy="unlisted", title=None, description=None, post_type=None)`

Upload a file. Accepts a file path string, bytes, or a file-like object.

| Parameter     | Type                       | Description                                                                           |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------- |
| `file`        | `str \| bytes \| BinaryIO` | File path, raw bytes, or file object.                                                 |
| `privacy`     | `str`                      | `"public"`, `"unlisted"`, or `"private"`.                                             |
| `title`       | `str \| None`              | Optional post title (max 30 chars).                                                   |
| `description` | `str \| None`              | Optional post description (max 200 chars).                                            |
| `post_type`   | `str \| None`              | `"album"` (default) or `"individual"`. Only applies when uploading two or more files. |

```python theme={null}
result = client.upload("image.png", privacy="unlisted", title="My screenshot")
print(result["url"])
```

### `list_uploads(limit=None)`

List the authenticated user's recent uploads. Defaults to 30. Pass `limit` to control the count (max 1000).

| Argument | Type          | Description                         |
| -------- | ------------- | ----------------------------------- |
| `limit`  | `int \| None` | Maximum uploads to return (1-1000). |

```python theme={null}
uploads = client.list_uploads(limit=100)
```

### `edit_upload(code, title=None, description=None, privacy=None)`

Edit an existing upload's title, description, or privacy.

| Parameter     | Type          | Description                                             |
| ------------- | ------------- | ------------------------------------------------------- |
| `code`        | `str`         | The share code of the upload.                           |
| `title`       | `str \| None` | New title (max 30 chars). Empty string to clear.        |
| `description` | `str \| None` | New description (max 200 chars). Empty string to clear. |
| `privacy`     | `str \| None` | `"public"`, `"unlisted"`, or `"private"`.               |

```python theme={null}
client.edit_upload("AbCd1234", title="New title", privacy="public")
```

### `append_upload(code, files)`

Add one or more files to an existing album post. The post's share code, privacy, title, and description are preserved. Albums cap at 9 files total. Requests that would exceed the cap are rejected. New files inherit the post's privacy. Returned URLs are signed with a 24-hour expiry for private posts.

| Parameter | Type                             | Description                                                                        |
| --------- | -------------------------------- | ---------------------------------------------------------------------------------- |
| `code`    | `str`                            | Share code of the post to append to.                                               |
| `files`   | `list[str \| bytes \| BinaryIO]` | One or more files. Each item may be a file path, raw bytes, or a file-like object. |

```python theme={null}
result = client.append_upload("AbCd1234", ["photo-a.png", "photo-b.png"])
print(result["post"]["fileCount"])
```

### `delete_upload(filename)`

Delete an upload by its filename. On albums, only that file is removed; on single-file posts the entire post is deleted.

```python theme={null}
client.delete_upload("a3f7b2c91d4e8f0612ab34cd56ef7890.png")
```

## Error Handling

All API errors raise a `SnippError` with `status` and `message` attributes.

```python theme={null}
from snipp import SnippClient, SnippError

try:
    client.get_user("nonexistent")
except SnippError as err:
    print(err.status, err.message)
```