Skip to main content
Yanked

This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Consider using release 0.3.0 instead.
Reason given by maintainers: This release is being removed due to issues identified after publication. Users are advised to install the latest available version.

outnoise-sdk

Official Python SDK for the Outnoise Developer Platform (formerly Chat X).

from outnoise import Outnoise

client = Outnoise(api_key="YOUR_BOT_TOKEN")
print(client.users.me().username)
client.posts.create(content="Hello from Outnoise SDK!")
  • Package name: outnoise-sdk · import name: outnoise
  • Python 3.8+ · built on httpx · synchronous and asynchronous clients
  • Typed exceptions, automatic pagination, automatic rate-limit handling, mocked-HTTP test suite

Installation

pip install outnoise-sdk

The package is not published yet. Until it is, install it from this folder (see Local development).

Getting started

  1. On Outnoise open the Developer Portal (/developers) and create an application.
  2. In Permissions enable the scopes your code needs (for example identify, posts.read, posts.write).
  3. Either create a bot (Bot tab → copy the bot token) or use OAuth2 (OAuth2 tab → Client ID/Secret, add a redirect URL).
  4. Install the SDK and make a request:
import os
from outnoise import Outnoise

client = Outnoise(api_key=os.environ["OUTNOISE_API_KEY"])      # never hard-code credentials

me = client.users.me()                         # scope: identify
posts = client.posts.list(limit=10)            # scope: posts.read
post = client.posts.create(content="Hello from Outnoise SDK!")   # scope: posts.write
groups = client.groups.list(limit=10)          # scope: groups.read
analytics = client.analytics.overview()        # scope: analytics.read

Responses are dictionaries that also allow attribute access: me.username and me["username"] both work.

Authentication

You pass Sent as Acts as Scopes
api_key="…" (bot token) Authorization: Bot … your application's bot account every scope enabled for the application
access_token="…" (OAuth2) Authorization: Bearer … the user who authorized your app the scopes that user approved
bot  = Outnoise(api_key="onbt_…")
user = Outnoise(access_token="onat_…")

Pass either one, not both. Both can also come from the environment:

Variable Meaning
OUTNOISE_API_KEY bot token
OUTNOISE_ACCESS_TOKEN OAuth2 access token
OUTNOISE_BASE_URL API address, e.g. http://127.0.0.1:8000/api/v1
client = Outnoise()          # reads OUTNOISE_API_KEY / OUTNOISE_ACCESS_TOKEN / OUTNOISE_BASE_URL

Getting an OAuth2 access token

Send the user to https://<your-outnoise-host>/oauth2/authorize?client_id=APP_ID&response_type=code&redirect_uri=…&scope=identify%20posts.read&state=…, then exchange the returned code on your server (the client secret must never reach a browser):

import httpx

tokens = httpx.post("https://<your-outnoise-host>/oauth2/token", data={
    "grant_type": "authorization_code", "code": code, "redirect_uri": "https://example.com/callback",
    "client_id": APP_ID, "client_secret": CLIENT_SECRET,
}).json()

client = Outnoise(access_token=tokens["access_token"])

Access tokens expire after 1 hour; renew with grant_type=refresh_token. Full details: /developers/documentation/authentication.

Available resources

Resource Methods Scope
client.applications me() –
client.users me(), get(username) identify, profile.read
client.posts list(limit, offset, author), iter(...), get(id), create(content, visibility, images, feeling) posts.read, posts.write
client.groups list(limit, offset, mine), iter(...), get(id) groups.read
client.events list(limit, offset, include_past), iter(...) events.read
client.messages list(user, limit, offset), iter(user), send(recipient, content) messages.read, messages.write
client.analytics overview(days=28) analytics.read

Notes: visibility is public, followers, unlisted or private. Bots may only direct-message users who authorized the application or messaged the bot first. Methods raise ValueError for bad arguments before any request is made.

Pagination

List methods return a Page (a normal list with paging info):

page = client.posts.list(limit=10)
print(len(page), page.has_more, page.next_offset)
page2 = client.posts.list(limit=10, offset=page.next_offset)

or iterate over everything — pages are fetched lazily:

for post in client.posts.iter(author="alice", page_size=50, max_items=200):
    print(post.content)

Error handling

from outnoise import (Outnoise, OutnoiseError, AuthenticationError, MissingScopeError, NotFoundError,
                      RateLimitError, APIConnectionError)

try:
    client.posts.create(content="hi")
except MissingScopeError as e:
    print("Enable these scopes:", e.required_scopes)
except AuthenticationError:
    print("Bad, expired or revoked credentials")
except RateLimitError as e:
    print("Slow down, retry in", e.retry_after, "seconds")
except NotFoundError:
    ...
except APIConnectionError:
    print("Could not reach Outnoise")
except OutnoiseError as e:      # catches everything from this package
    print(e)                    # e.g. "[400 content_too_long] Content too long (max 2500 characters)."
Exception When
ConfigurationError missing/conflicting credentials, bad base_url
APIConnectionError / APITimeoutError network failure / timeout
InvalidRequestError (400) the API rejected the request
AuthenticationError (401) invalid, expired or revoked token
PermissionDeniedError (403), MissingScopeError not allowed / missing scope
NotFoundError (404) unknown or invisible resource
RateLimitError (429) rate limit exceeded (.retry_after)
ServerError (5xx) server problem

Every API error has .status_code, .code, .message, .body and .headers.

Rate limits and retries

The API limits each token (reads 120/min, writes 30/min, messages 20/min). The SDK automatically:

  • retries 429 responses after the Retry-After delay (also for POST, because a rate-limited request was not processed);
  • retries GET requests on connection errors, timeouts and 502/503/504 with exponential backoff.

Control it with Outnoise(max_retries=2, max_retry_wait=30); max_retries=0 turns retrying off. If the server asks for a longer wait than max_retry_wait, RateLimitError is raised immediately.

Async usage

import asyncio
from outnoise import AsyncOutnoise

async def main():
    async with AsyncOutnoise(api_key="YOUR_BOT_TOKEN") as client:
        me = await client.users.me()
        post = await client.posts.create(content="Hello from async!")
        async for p in client.posts.iter(max_items=100):
            print(p.content)

asyncio.run(main())

AsyncOutnoise has the same resources and options; every call is awaited and iter() is used with async for.

Configuration

client = Outnoise(
    api_key="…",
    base_url="http://127.0.0.1:8000/api/v1",   # custom API address (local testing, staging)
    timeout=30,                                # seconds
    max_retries=2,
)

The built-in default address is the beta deployment (https://beta-chatx.hostmybotprojects.net/api/v1). Change DEFAULT_BASE_URL in src/outnoise/_base.py, or pass base_url / OUTNOISE_BASE_URL, when you use another host. You can also hand over your own httpx.Client / httpx.AsyncClient with http_client= (proxies, custom transports).

Local development

Install in editable mode — no PyPI needed:

cd outnoise-sdk
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Test it against your local Outnoise backend (use a test account/application, never production credentials):

from outnoise import Outnoise
client = Outnoise(api_key="TEST_KEY", base_url="http://127.0.0.1:8000/api/v1")
print(client.users.me())

(python app.py in the Outnoise project serves on port 3002 by default, so the local URL is usually http://127.0.0.1:3002/api/v1.)

Testing

pytest

The suite uses httpx.MockTransport, so it needs no network and no credentials. It covers authentication, request building, invalid credentials, API errors, pagination, rate limits, custom base URLs, every resource method and the async client. tests/test_live_backend.py is an optional integration test that is skipped unless OUTNOISE_TEST_BASE_URL and OUTNOISE_TEST_API_KEY point at a local test backend.

Security

  • Keep bot tokens and client secrets in environment variables or a secrets manager — never in source control, browsers or mobile apps.
  • Resetting a token or secret in the Developer Portal invalidates the old one immediately.
  • Credentials are never included in exception messages or repr() output.

Metadata

Release files for outnoise 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for outnoise 1.0.1
File Size Uploaded Provenance Actions
outnoise-1.0.1.tar.gz 18.9 kB Without provenance Details for outnoise-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for outnoise 1.0.1
File Interpreter ABI Platform Actions
outnoise-1.0.1-py3-none-any.whl Python 3 none any Details for outnoise-1.0.1-py3-none-any.whl

Total release size: 33.4 kB

Release files / outnoise-1.0.1.tar.gz

Download URL outnoise-1.0.1.tar.gz
Size 18.9 kB
Tags Source
SHA-256 checksum
How to use checksums
853876dc55085933550d1bfeba7d1bf723624f319f5ed4498ff41f8a16011dc7
BLAKE2b-256 checksum
How to use checksums
14544aa2afea9e53578dcae6af826fda6296ac96e61b4249e8f9a9be7ce341b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.13

Release files / outnoise-1.0.1-py3-none-any.whl

Download URL outnoise-1.0.1-py3-none-any.whl
Size 14.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
42bfc8064f4a896cc8cbfcbd7ac5b4c5e9fd3a059897d70675e3dd8e985d8d5d
BLAKE2b-256 checksum
How to use checksums
fe4275dbd811701fd6b14f46bbecea6deed17aa5876d6b9365ca8a33d0ecade8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.13

Security for outnoise 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page