---
id: python-squarelet
version: "0.4.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# python-squarelet — Python library that handles token authentication for MuckRock and DocumentCloud

License: permissive · Maintenance: active · Downloads: 240.1K/mo

## What it is and what it does

python-squarelet is a Python client library that wraps the Squarelet authentication system used by MuckRock and DocumentCloud. It handles the complexity of token-based authentication, automatic token refresh, rate limiting, and request retry logic so you don't have to manage these concerns manually. The library provides a simple SquareletClient class that you initialize with credentials and a base API URI, then use to make HTTP requests (GET, POST, PUT, DELETE, etc.) to MuckRock or DocumentCloud APIs.

The package is designed for developers who need to programmatically interact with MuckRock Requests or DocumentCloud through their APIs. It abstracts away authentication token management, applies rate limiting automatically to respect API quotas, and includes built-in retry logic for transient failures. The library also provides custom exception classes for different error scenarios (API errors, credential issues, missing resources), making error handling more explicit in your code.

Use it for:

- Automate document retrieval and metadata queries from DocumentCloud using Python scripts.
- Build applications that submit and track FOIA requests through MuckRock's API programmatically.
- Create batch processing pipelines that interact with MuckRock or DocumentCloud without managing authentication tokens manually.
- Integrate MuckRock or DocumentCloud data into data analysis workflows or reporting systems.
- Develop bots or scheduled tasks that monitor or update resources in MuckRock or DocumentCloud systems.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Python client library for authenticating with and making API requests to MuckRock and DocumentCloud services, handling token management, rate limiting, and automatic retries.

Yes. The package is actively maintained, has low install friction, carries no known vulnerabilities, and is licensed permissively. Install it if you need to programmatically access MuckRock or DocumentCloud APIs—it eliminates boilerplate around authentication, token refresh, and rate limiting. The narrow scope (specific to Squarelet-based services) means it's only useful if you're targeting those particular APIs.

## Install

pip install python-squarelet
uv add python-squarelet
poetry add python-squarelet

## Installing python-squarelet

Before you install: Low friction installation as a pure Python wheel. Active maintenance with a release on 2026-08-14 and last commit the same day. Three lightweight runtime dependencies (ratelimit, requests, urllib3) are all widely-used and stable.

License in practice: Licensed under MIT (permissive), so you can use, modify, and distribute the package freely with minimal restrictions.

Quickstart:

pip install python-squarelet

from squarelet import SquareletClient
import os

username = os.environ["SQ_USERNAME"]
password = os.environ["SQ_PASSWORD"]
client = SquareletClient(base_uri="https://api.www.documentcloud.org/api/", username=username, password=password)
response = client.request("get", "users/me/")
print(response.text)

Requires Python 3.8 or later (capped at 3.12). Credentials must be provided via environment variables or constructor parameters.

Verify before relying:

- Whether rate limiting configuration is customizable beyond the automatic application mentioned in the description.
- Whether the package handles token refresh transparently across concurrent requests or only sequentially.
- Performance characteristics and typical latency overhead from the rate limiting and retry logic.

## Package facts

- License: not declared (permissive)
- Python support: capped_below_current
- Install friction: low
- Maintenance: active
- Downloads: 240.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

muckrock api client, documentcloud authentication, squarelet token auth, muckrock python wrapper, api client with rate limiting, token refresh automation, http client with retries, api-client, authentication, muckrock

[View on SkillFed](https://skillfed.io/packages/python-squarelet) · [View on PyPI](https://pypi.org/project/python-squarelet/)