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
- On Outnoise open the Developer Portal (
/developers) and create an application. - In Permissions enable the scopes your code needs (for example
identify,posts.read,posts.write). - Either create a bot (Bot tab → copy the bot token) or use OAuth2 (OAuth2 tab → Client ID/Secret, add a redirect URL).
- 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
429responses after theRetry-Afterdelay (also forPOST, because a rate-limited request was not processed); - retries
GETrequests 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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| outnoise-1.0.0.tar.gz | 18.9 kB | Without provenance | Details for outnoise-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| outnoise-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for outnoise-1.0.0-py3-none-any.whl |
Total release size: 33.4 kB
Release files / outnoise-1.0.0.tar.gz
| Download URL | outnoise-1.0.0.tar.gz |
|---|---|
| Size | 18.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d700c99d83de9e9960578f2187b6539681d16804566a9d59c4e5a983b30b5212
|
|
BLAKE2b-256 checksum How to use checksums |
21f050adc7c61ec0184f04ab789550a6d36b1a4ccece56ce2d6a30a6dd4380e8
|
| 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.0-py3-none-any.whl
| Download URL | outnoise-1.0.0-py3-none-any.whl |
|---|---|
| Size | 14.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
91feeb1c7659f86ff2b25f3b4f0a6e5a151285a23457470e53bda5bde659bbb7
|
|
BLAKE2b-256 checksum How to use checksums |
08be96dce9eebeb9491589ffc5d93352a48fe95b4001cf2baa3c563fe84f5fc6
|
| 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.0
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.