Skip to main content

pulzr

Python client for the Pulzar API. Python 3.9+, two dependencies (httpx and tenacity).

Full documentation: https://app.pulzr.net/docs

Install

pip install pulzr

pip install "pulzr[mqtt]" adds paho-mqtt, for pulzr.mqtt.Session (https://app.pulzr.net/docs/mqtt).

From a checkout of pulzar-net/pulzr-sdk:

pip install ./python

Quickstart

Create a key at Developers > API keys in the console (/api-keys). The key belongs to one org; org= is only needed with a person's token that has several.

import pulzr

client = pulzr.Client(api_key="pzk_...")  # or set PULZR_API_KEY

for device in client.readings.latest("temperature"):
    value = device["readings"]["temperature"]
    unit = device["units"]["temperature"]
    print(f'{device["name"]:<24} {value} {unit}  at {device["readingTimes"]["temperature"]}')

series = client.readings.series("temperature", since="now-24h", group_by="device")

Readings are canonical: the same quantity and unit whatever the vendor's codec calls the field. client.quantities.list() is the catalog.

Streaming events

with client.events.stream(types=["device.offline", "gateway.offline"]) as stream:
    for event in stream:
        print(event["type"], event["subject"], event["createdAt"])

A dropped connection, or the server closing the stream (it does after an hour), is reopened from the last position, so nothing is skipped or repeated. An org may hold 5 streams open per server; past that the open is refused with a 429 and retried after its Retry-After. To survive a restart, store stream.cursor and pass it back as last_event_id=. Without one the stream starts at the end of the log.

To read the log instead: client.events.iter(after=cursor) pages forward until caught up; client.events.list(before="now") is the newest page.

Verifying webhooks

Verify the raw body bytes, before parsing them.

import pulzr
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = "whsec_..."  # shown once, when the webhook is created

@app.post("/pulzr")
def receive():
    try:
        event = pulzr.webhooks.construct_event(
            SECRET, request.get_data(), request.headers.get("Parkeze-Signature"))
    except pulzr.SignatureVerificationError:
        abort(400)
    # Delivery is at least once: deduplicate on event["id"].
    handle(event)
    return "", 204

During a secret rotation both secrets sign each delivery for 24 hours; pass both while you redeploy: construct_event([new, old], body, header). pulzr.webhooks.verify_signature(...) returns a bool instead of raising.

Devices

client.devices.list()                                   # every device that has reported
client.devices.readings("a84041000181c061", since="now-7d")
client.devices.downlinks.enqueue("a84041000181c061", f_port=10, data=b"\x01")
client.devices.provision("a84041000181c061", app_key="...", device_profile="...")

Agents

thread = client.agents.threads.create()
stream = client.agents.send(thread["id"], "Which gateways went offline today?")
for event in stream:
    if isinstance(event, pulzr.TextEvent):
        print(event.delta, end="")
    elif isinstance(event, pulzr.ApprovalRequiredEvent):
        ...  # decide with client.agents.approve(event.run_id, decisions)

The run belongs to the server: closing the stream stops listening, not the run. client.agents.cancel(run_id) stops it.

Errors

Every failure raises a subclass of pulzr.PulzrError with status, message, details and the response body:

Status Class
400, 422 ValidationError
401 AuthenticationError
403 PermissionDeniedError (missing scope or not an org admin)
404 NotFoundError
409 ConflictError; a quota refusal sets resource and limit
429 RateLimitError
5xx ServerError
no response APIConnectionError

GET, PUT and DELETE are retried on 429, 5xx and connection errors (max_retries=2, exponential backoff, Retry-After honoured). POST and PATCH are never retried: one that timed out may already have queued the downlink or registered the device.

Anything not wrapped

client.request("GET", "/api/v1/data/devices/a84041000181c061/events")

Command line

The package installs pulzr, built on this client:

pulzr login                      # prompts for the key; stored 0600, never printed
pulzr devices list
pulzr events tail --types device.offline
pulzr api --list                 # every operation in the server's spec
pulzr api getDevice --param devEui=a84041000181c061

Table on a terminal, JSON when piped (-o json|table). Exit 0 ok, 1 API error, 2 usage error. Full reference: https://app.pulzr.net/docs/cli

Tests

cd python && PYTHONPATH=src python -m unittest discover -s tests

Metadata

Release files for pulzr 0.1.0

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

Source distribution (sdist)

Source distribution for pulzr 0.1.0
File Size Uploaded Provenance Actions
pulzr-0.1.0.tar.gz 70.3 kB With provenance Details for pulzr-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 132.3 kB

Release files / pulzr-0.1.0.tar.gz

Download URL pulzr-0.1.0.tar.gz
Size 70.3 kB
Tags Source
SHA-256 checksum
How to use checksums
53eacdda3859482af103be22e99e5a7ef648b3f1810c04737043eb919797c8da
BLAKE2b-256 checksum
How to use checksums
ecda2d0063ef1ed5fc962e7bdef2a5956dc74d70aa4b296469ad6a85b0566eb7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pulzr-0.1.0-py3-none-any.whl

Download URL pulzr-0.1.0-py3-none-any.whl
Size 61.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e9573dc05471f2f424e77d8ee201061962a4ecc09f86cec9c497e7d7ad1fb0bf
BLAKE2b-256 checksum
How to use checksums
5b1384f4b9a2cb71ee4e6a535c970bbcb04f20b078e17272ee6b8efb32f82637
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for pulzr 0.1.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pulzr-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

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

0.1.0 This release

2 release files Full 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