natsio-natscontext

Connect natsio using the connection profiles ("contexts") managed by the nats command-line tool — the same JSON files under ~/.config/nats/context/. This is the Python counterpart of the Go helper orbit.go/natscontext, following ADR-21.

pip install natsio-natscontext

Usage

Create a context with the CLI, then use it from Python:

nats context add staging --server nats://staging:4222 --creds ~/staging.creds
nats context select staging

import natsio.natscontext as natscontext

# Connect using a named context...
async with await natscontext.connect("staging") as nc:
    await nc.publish("greet", b"hi")

# ...or the currently selected context (from `nats context select`).
async with await natscontext.connect() as nc:
    ...

# Overrides are forwarded to natsio.connect and win over the context:
nc = await natscontext.connect("staging", name="my-app", ping_interval=30)

Inspect or reuse a context without connecting:

ctx = natscontext.load("staging")          # -> Context
print(ctx.url, ctx.jetstream_domain)
kwargs = ctx.connect_kwargs()              # dict of natsio.connect(**kwargs)

natscontext.list_contexts()                # ['prod', 'staging', ...]
natscontext.selected_context()             # 'staging' or None

An absolute path is loaded directly instead of by name:

ctx = natscontext.load("/etc/nats/prod.json")

Discovery

Contexts are resolved under $XDG_CONFIG_HOME/nats (falling back to ~/.config/nats):

Path Purpose
nats/context/<name>.json one context per file
nats/context.txt name of the active/selected context

Field mapping

Context field natsio option Notes
url servers split on , into a tuple
user + password user, password
creds credentials ~ and $VAR expanded
nkey nkey_seed the file is read and the seed extracted
token token
cert + key tls SSLContext.load_cert_chain
ca tls SSLContext.load_verify_locations
tls_first tls.handshake_first
inbox_prefix inbox_prefix

Auth precedence mirrors the Go helper: user › creds › nkey › token. natsio does not allow combining mechanisms, so a token set alongside another mechanism is ignored (nats.go would send both).

Parsed but not applied

These fields are read and preserved on the returned Context (so you can use them yourself — e.g. the JetStream domain when creating a JetStream context), but natsio's connection layer has no equivalent and does not apply them:

Context field Context attribute Why not applied
jetstream_domain .jetstream_domain connection-independent; used at the JetStream API layer
jetstream_api_prefix .jetstream_api_prefix JetStream API layer
jetstream_event_prefix .jetstream_event_prefix JetStream API layer
socks_proxy .socks_proxy natsio has no custom-dialer / proxy hook
nsc .nsc would shell out to the nsc binary
user_jwt .user_jwt the Go helper parses but never applies it either
color_scheme .color_scheme CLI cosmetic
description .description metadata
windows_cert_store* .windows_cert_store unsupported — connect_kwargs() raises ContextError

Unrecognised JSON keys are kept in Context.raw and reported by Context.unknown_keys.

Interop with the nats CLI

This package only ever reads context files; it never writes them. Manage contexts with the CLI (nats context add|select|edit|ls|rm). Files written by this library's format are byte-compatible with what the CLI expects.

License

Apache-2.0.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for corruptmane from gravatar.com corruptmane

Credits

Author: Corrupt Mane

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.13

Tags

nats nats.io natscontext nats-cli configuration

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

natsio_natscontext-0.1.0.tar.gz (6.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

natsio_natscontext-0.1.0-py3-none-any.whl (7.7 kB view details)

Uploaded Python 3

File details

Details for the file natsio_natscontext-0.1.0.tar.gz.

File metadata

  • Download URL: natsio_natscontext-0.1.0.tar.gz
  • Upload date:
  • Size: 6.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for natsio_natscontext-0.1.0.tar.gz
Algorithm Hash digest
SHA256 52fbd2ec155b6706eb1c123f73f1498ee2830b61fbe1f667ef28082eeb81041e
MD5 58cd2c5183cf7f716b76ae78aa2d8008
BLAKE2b-256 9cc7eb805a8c7f12db69f7c9b4a95a4f3db6459635fa22840c701f911174b8cb

See more details on using hashes here.

Provenance

The following attestation bundles were made for natsio_natscontext-0.1.0.tar.gz:

Publisher: release-extension.yml on corruptmane/natsio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file natsio_natscontext-0.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for natsio_natscontext-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 54af16ac348761c4b1c2236a09571eb463c76991484494d24b32a60d519e2e20
MD5 d8ef90f4f201863989cc45e1c800c66c
BLAKE2b-256 7c36acafe9b3d64238b10634416ebe92cc82a2f7cf4796837d16a63ef53dd6ad

See more details on using hashes here.

Provenance

The following attestation bundles were made for natsio_natscontext-0.1.0-py3-none-any.whl:

Publisher: release-extension.yml on corruptmane/natsio

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 files

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