Pychive

Unofficial Python wrapper for the Pawchive API. This project is not affiliated with, endorsed by, or associated with Pawchive.

Pychive provides a clean, typed, object-oriented interface to Pawchive's REST API — covering creators, posts, comments, announcements, fancards, post flagging, favorites, file-hash search, and app version info.

• Base URL: https://pawchive.pw/api/v1
• Auth: cookie-based (session cookie), passed to the client constructor
• Python: 3.9+
• Dependencies: requests

Documentation

Full documentation — installation, quick start, authentication, configuration, API reference, models, exceptions, error handling, pagination, cookbook, and changelog — lives in docs/index.md.

Installation (local, into a virtualenv)

Pychive uses a standard src/-layout package described by pyproject.toml, so it installs cleanly with pip (which will pull in requests automatically).

1. Clone the repository

git clone https://github.com/NoobToolzz/Pychive.git
cd Pychive

2. Create and activate a virtualenv

python3 -m venv .venv

# activate it
source .venv/bin/activate      # Linux / macOS
# .venv\Scripts\activate       # Windows

3. Install the package

From the project root (where pyproject.toml lives):

# editable install (recommended while developing — picks up edits live)
pip install -e .

# OR a regular install (copies the package into the venv)
pip install .

pip install -e . installs in "editable" mode so changes to files under src/pychive/ are reflected immediately without reinstalling. pip install . builds and installs a copy instead.

Both commands automatically pull in the runtime dependency requests.

4. (Optional) Install dev tooling

pip install -e ".[dev]"

This adds pytest, responses, ruff, and mypy for testing/linting.

5. Verify the install

python -c "import pychive; print(pychive.__version__)"

Expected output: 1.0.0

Updating / reinstalling

pip install -e . --upgrade

Uninstall

pip uninstall pychive

Quick start

from pychive import Pawchive, AuthenticationError, NotFoundError

# Pass the session cookie value. The "session=" prefix is optional,
# and surrounding quotes/spaces are stripped automatically.
with Pawchive("your_session_value_here") as client:
    # Public endpoints (no auth needed)
    creators = client.creators.list_all()
    for c in creators:
        print(c.name, c.service, c.url)

    # Recent posts across all creators (paginated)
    posts = client.posts.list_recent(limit=50, offset=0)
    for p in posts:
        print(p.title, p.published_at)

    # Posts from a specific creator
    fanbox_posts = client.posts.list_from_creator("fanbox", "12345", limit=20)

    # A specific post + its revisions and comments
    post = client.posts.get("fanbox", "12345", "67890")
    revisions = client.posts.list_revisions("fanbox", "12345", "67890")
    comments = client.comments.list("fanbox", "12345", "67890")

    # Creator profile / links / tags / announcements / fancards
    profile = client.creators.get_profile("fanbox", "12345")
    links = client.creators.get_links("fanbox", "12345")
    tags = client.creators.get_tags("fanbox", "12345")
    announcements = client.creators.get_announcements("fanbox", "12345")
    fancards = client.creators.get_fancards("fanbox", "12345")  # fanbox only

    # Authorized endpoints (require a valid session)
    try:
        favs = client.favorites.list()
        client.favorites.add_post("fanbox", "12345", "67890")
        client.favorites.add_creator("fanbox", "12345")
        client.flags.flag("fanbox", "12345", "67890")
        flag_status = client.flags.get_status("fanbox", "12345", "67890")
    except AuthenticationError:
        print("Session is invalid or expired.")

    # File search by hash + app version
    result = client.search.lookup_hash("abcdef1234567890")
    version = client.misc.app_version()

Getting your session cookie

1. Log in to https://pawchive.pw in your browser.
2. Open DevTools → Application (Chrome) / Storage (Firefox) → Cookies.
3. Copy the value of the session cookie.
4. Pass it to Pawchive(...) — either as the bare value or as session=<value>.

You can also load it from an environment variable:

import os
from pychive import Pawchive

session = os.environ["PAWCHIVE_SESSION"]
with Pawchive(session) as client:
    ...

export PAWCHIVE_SESSION="your_session_value_here"

API surface

The Pawchive client exposes endpoint groups as properties:

Multi-id methods accept a string or iterable of ids, return a dict keyed by id, and accept an optional delay keyword to throttle between requests. A bare string is treated as a single id (not character-split).

Constructor options

Pawchive(
    session,            # str: session cookie value (with or without "session=")
    base_url="https://pawchive.pw/api/v1",
    timeout=30,         # per-request timeout (seconds)
    max_retries=3,      # retries on 429 / 5xx
    backoff_base=0.5,   # exponential backoff base (seconds)
)

Error handling

All errors inherit from pychive.PawchiveError. Catch the base class or a specific subclass:

Each HTTP exception carries .status_code and .response (the original requests.Response). RateLimitError also exposes .retry_after.

from pychive import Pawchive, RateLimitError, AuthenticationError, NotFoundError

with Pawchive(session) as client:
    try:
        post = client.posts.get("fanbox", "12345", "67890")
    except NotFoundError:
        print("Post not found.")
    except AuthenticationError:
        print("Session expired.")
    except RateLimitError as e:
        print(f"Rate limited; server suggested waiting {e.retry_after}s")

Retry behavior: the client automatically retries 429, 502, 503, and 504 responses up to max_retries times with exponential backoff. It honors the Retry-After header when present (capped at 60s).

Project layout

Pychive/
├── pyproject.toml          # packaging + tool config
├── README.md
├── AGENTS.md               # compact guide for AI coding sessions
├── docs/                   # full documentation (Markdown)
│   ├── index.md            # entry point + table of contents
│   ├── installation.md
│   ├── quickstart.md
│   ├── authentication.md
│   ├── configuration.md
│   ├── api-reference.md    # every endpoint, method, return type
│   ├── models.md           # every dataclass and its fields
│   ├── exceptions.md
│   ├── error-handling.md
│   ├── pagination.md
│   ├── cookbook.md         # complete examples
│   └── changelog.md
├── tests/                  # pytest test suite (responses for HTTP mocking)
│   ├── conftest.py         # shared fixtures (client with max_retries=0)
│   ├── test_session_parsing.py
│   ├── test_models.py
│   ├── test_validation.py
│   ├── test_endpoints.py
│   ├── test_error_handling.py
│   └── test_client.py
└── src/
    └── pychive/
        ├── __init__.py     # public exports (Pawchive, models, exceptions)
        ├── client.py       # Pawchive — main client class
        ├── http.py         # HttpClient — transport, auth, retry/backoff
        ├── exceptions.py   # exception hierarchy
        ├── models.py       # frozen dataclasses for API responses
        ├── py.typed        # PEP 561 marker (typed package)
        └── endpoints/
            ├── __init__.py
            ├── base.py        # BaseEndpoint
            ├── creators.py    # list_all, profile, links, tags, announcements, fancards
            ├── posts.py       # recent, creator posts, specific post, revisions
            ├── comments.py    # post comments
            ├── flags.py       # flag / flag status
            ├── favorites.py   # list / add / remove posts & creators
            ├── search.py      # hash lookup
            └── misc.py        # app version

Development

source .venv/bin/activate
pip install -e ".[dev]"

# lint
ruff check src
# type-check
mypy src
# tests
pytest

License

MIT