ogu-api 0.6.0

Async Python wrapper for the OGUsers (oguser.com) forum.

ogu-api

An async Python wrapper for the OGUsers forum.

Wraps the public-facing pages and forms; login, profile lookup, reputation, credits, private messages, feed, threads, notifications, member search, account control panel, with a typed, async-first client.

Full documentation: https://ogu-api.readthedocs.io.

Install

pip install ogu-api

Requires Python 3.11+.

Quick start

import asyncio

from ogu_api import OGUClient


async def main() -> None:
    async with OGUClient() as client:
        await client.session.login('username', 'password')

        user = await client.users.get_by_username('forgivenforget')
        print(user.username, user.credits, user.reputation, user.vouches)


asyncio.run(main())

Resources

Resource	What it covers
client.session	login page, login, logout
client.users	profile lookup by username or uid; returns UserProfile (id, username, reputation, vouches, credits)
client.usercp	notepad, signature, options, profile, change username/password/email
client.reputation	reputation page, send reputation
client.credits	donate page, stats page, send credits, parse recently-sent transactions
client.messages	PM inbox, conversation, compose, send, tracking, delete
client.notifications	notifications page, alerts, mark alerts read
client.feed	explore feed, home feed, thread-id extraction
client.threads	view thread, view forum, reply, create thread
client.search	full-text search form + post
client.members	member list, top, statistics, team, groups, vouches, awards, reputation history

Inbox & PMs

inbox = await client.messages.inbox()

for m in inbox.messages:
    print(m.username, m.message)

await client.messages.send(to = 'recipient', message = 'hello')

Inbox is a dataclass with messages: tuple[Message, ...], conversation_ids: tuple[str, ...], and my_post_key.

Every state-changing call in the SDK auto-fetches its own my_post_key and form hidden fields when you don't pass them. To skip the extra round-trip, pass them explicitly:

await client.messages.send(
    to = 'recipient',
    message = 'hello',
    my_post_key = inbox.my_post_key,
)

Read the feed

for thread in await client.feed.explore():
    print(thread.title, thread.link, thread.tid)

for thread in await client.feed.home():
    print(thread.title, thread.tid)

feed.explore() and feed.home() return list[ThreadSummary] with title, link, and tid (numeric, or None for slug-rewritten URLs that don't carry one). For raw HTML access, use get_explore() / get_home().

Reply to a thread

await client.threads.reply(tid, message = 'great post')

Persist a session

ogu-api doesn't store credentials. After login, the session lives on the client's cookie jar — serialize it however you like:

cookies = {cookie.name: cookie.value for cookie in client.cookies}

To resume a session, pre-seed the cookies on a fresh client:

client = OGUClient()

for name, value in cookies.items():
    client.cookies.set(name, value)

Configuration

client = OGUClient(
    proxy = 'user:pass@host:8080',
    timeout_seconds = 30.0,
    max_retries = 3,
    retry_backoff_seconds = 0.5,
    client_identifier = 'chrome131',
)

Proxy strings accept user:pass@host:port, host:port:user:pass, or plain host:port and are normalized to http://... for the underlying tls_client session.

Errors

from ogu_api import OGUNotFoundError, OGURateLimitError

try:
    await client.users.get_by_username('does-not-exist')

except OGUNotFoundError as E:
    print('not found:', E.url)

except OGURateLimitError as E:
    print('rate limited, retry after', E.retry_after_seconds)

Full hierarchy:

• OGUError
  • OGUAPIError — OGUAuthenticationError, OGUAuthorizationError, OGUNotFoundError, OGUValidationError, OGURateLimitError, OGUServerError
  • OGUNetworkError — OGUTimeoutError
  • OGUParseError, OGUSessionError, OGULoginError, OGUReputationError, OGUCreditsError

Captcha

Sending credits requires an hCaptcha token. ogu-api doesn't ship a solver — pass a pre-solved token in:

await client.credits.send(
    username = 'recipient',
    amount = 100,
    captcha_token = solved_token,
)

Features

• Async-first — every request is async, backed by tls_client on a worker thread for Cloudflare-friendly TLS fingerprints
• Typed — from __future__ import annotations everywhere, py.typed marker, dataclass models for parsed payloads
• Resource-oriented — calls grouped under client.session, client.users, client.messages, etc.
• Typed errors — full exception hierarchy mapped from HTTP status codes
• Retries — exponential backoff on 429 and 5xx, honors Retry-After
• Proxies — string-form proxies auto-normalized

License

MIT