AtmosphereClient

atmosphere.AtmosphereClient(base_url=None, *, _client=None)

ATProto client wrapper for atdata operations.

This class wraps the atproto SDK client and provides higher-level methods for working with atdata records (schemas, datasets, lenses).

Examples

>>> client = AtmosphereClient()
>>> client.login("alice.bsky.social", "app-password")
>>> print(client.did)
'did:plc:...'

Note

The password should be an app-specific password, not your main account password. Create app passwords in your Bluesky account settings.

Attributes

Name	Description
did	Get the DID of the authenticated user.
handle	Get the handle of the authenticated user.
is_authenticated	Check if the client has a valid session.

Methods

Name	Description
create_record	Create a record in the user’s repository.
delete_record	Delete a record.
export_session	Export the current session for later reuse.
get_blob	Download a blob from a PDS.
get_blob_url	Get the direct URL for fetching a blob.
get_record	Fetch a record by AT URI.
list_datasets	List dataset records.
list_lenses	List lens records.
list_records	List records in a collection.
list_schemas	List schema records.
login	Authenticate with the ATProto PDS.
login_with_session	Authenticate using an exported session string.
put_record	Create or update a record at a specific key.
upload_blob	Upload binary data as a blob to the PDS.

create_record

atmosphere.AtmosphereClient.create_record(
    collection,
    record,
    *,
    rkey=None,
    validate=False,
)

Create a record in the user’s repository.

Parameters

Name	Type	Description	Default
collection	str	The NSID of the record collection (e.g., ‘ac.foundation.dataset.sampleSchema’).	required
record	dict	The record data. Must include a ‘$type’ field.	required
rkey	Optional[str]	Optional explicit record key. If not provided, a TID is generated.	None
validate	bool	Whether to validate against the Lexicon schema. Set to False for custom lexicons that the PDS doesn’t know about.	False

Returns

Name	Type	Description
	AtUri	The AT URI of the created record.

Raises

Name	Type	Description
	ValueError	If not authenticated.
	atproto.exceptions.AtProtocolError	If record creation fails.

delete_record

atmosphere.AtmosphereClient.delete_record(uri, *, swap_commit=None)

Delete a record.

Parameters

Name	Type	Description	Default
uri	str | AtUri	The AT URI of the record to delete.	required
swap_commit	Optional[str]	Optional CID for compare-and-swap delete.	None

Raises

Name	Type	Description
	ValueError	If not authenticated.
	atproto.exceptions.AtProtocolError	If deletion fails.

export_session

atmosphere.AtmosphereClient.export_session()

Export the current session for later reuse.

Returns

Name	Type	Description
	str	Session string that can be passed to login_with_session().

Raises

Name	Type	Description
	ValueError	If not authenticated.

get_blob

atmosphere.AtmosphereClient.get_blob(did, cid)

Download a blob from a PDS.

This resolves the PDS endpoint from the DID document and fetches the blob directly from the PDS.

Parameters

Name	Type	Description	Default
did	str	The DID of the repository containing the blob.	required
cid	str	The CID of the blob.	required

Returns

Name	Type	Description
	bytes	The blob data as bytes.

Raises

Name	Type	Description
	ValueError	If PDS endpoint cannot be resolved.
	requests.HTTPError	If blob fetch fails.

get_blob_url

atmosphere.AtmosphereClient.get_blob_url(did, cid)

Get the direct URL for fetching a blob.

This is useful for passing to WebDataset or other HTTP clients.

Parameters

Name	Type	Description	Default
did	str	The DID of the repository containing the blob.	required
cid	str	The CID of the blob.	required

Returns

Name	Type	Description
	str	The full URL for fetching the blob.

Raises

Name	Type	Description
	ValueError	If PDS endpoint cannot be resolved.

get_record

atmosphere.AtmosphereClient.get_record(uri)

Fetch a record by AT URI.

Parameters

Name	Type	Description	Default
uri	str | AtUri	The AT URI of the record.	required

Returns

Name	Type	Description
	dict	The record data as a dictionary.

Raises

Name	Type	Description
	atproto.exceptions.AtProtocolError	If record not found.

list_datasets

atmosphere.AtmosphereClient.list_datasets(repo=None, limit=100)

List dataset records.

Parameters

Name	Type	Description	Default
repo	Optional[str]	The DID to query. Defaults to authenticated user.	None
limit	int	Maximum number to return.	100

Returns

Name	Type	Description
	list[dict]	List of dataset records.

list_lenses

atmosphere.AtmosphereClient.list_lenses(repo=None, limit=100)

List lens records.

Parameters

Name	Type	Description	Default
repo	Optional[str]	The DID to query. Defaults to authenticated user.	None
limit	int	Maximum number to return.	100

Returns

Name	Type	Description
	list[dict]	List of lens records.

list_records

atmosphere.AtmosphereClient.list_records(
    collection,
    *,
    repo=None,
    limit=100,
    cursor=None,
)

List records in a collection.

Parameters

Name	Type	Description	Default
collection	str	The NSID of the record collection.	required
repo	Optional[str]	The DID of the repository to query. Defaults to the authenticated user’s repository.	None
limit	int	Maximum number of records to return (default 100).	100
cursor	Optional[str]	Pagination cursor from a previous call.	None

Returns

Name	Type	Description
	list[dict]	A tuple of (records, next_cursor). The cursor is None if there
	Optional[str]	are no more records.

Raises

Name	Type	Description
	ValueError	If repo is None and not authenticated.

list_schemas

atmosphere.AtmosphereClient.list_schemas(repo=None, limit=100)

List schema records.

Parameters

Name	Type	Description	Default
repo	Optional[str]	The DID to query. Defaults to authenticated user.	None
limit	int	Maximum number to return.	100

Returns

Name	Type	Description
	list[dict]	List of schema records.

login

atmosphere.AtmosphereClient.login(handle, password)

Authenticate with the ATProto PDS.

Parameters

Name	Type	Description	Default
handle	str	Your Bluesky handle (e.g., ‘alice.bsky.social’).	required
password	str	App-specific password (not your main password).	required

Raises

Name	Type	Description
	atproto.exceptions.AtProtocolError	If authentication fails.

login_with_session

atmosphere.AtmosphereClient.login_with_session(session_string)

Authenticate using an exported session string.

This allows reusing a session without re-authenticating, which helps avoid rate limits on session creation.

Parameters

Name	Type	Description	Default
session_string	str	Session string from export_session().	required

put_record

atmosphere.AtmosphereClient.put_record(
    collection,
    rkey,
    record,
    *,
    validate=False,
    swap_commit=None,
)

Create or update a record at a specific key.

Parameters

Name	Type	Description	Default
collection	str	The NSID of the record collection.	required
rkey	str	The record key.	required
record	dict	The record data. Must include a ‘$type’ field.	required
validate	bool	Whether to validate against the Lexicon schema.	False
swap_commit	Optional[str]	Optional CID for compare-and-swap update.	None

Returns

Name	Type	Description
	AtUri	The AT URI of the record.

Raises

Name	Type	Description
	ValueError	If not authenticated.
	atproto.exceptions.AtProtocolError	If operation fails.

upload_blob

atmosphere.AtmosphereClient.upload_blob(
    data,
    mime_type='application/octet-stream',
)

Upload binary data as a blob to the PDS.

Parameters

Name	Type	Description	Default
data	bytes	Binary data to upload.	required
mime_type	str	MIME type of the data (for reference, not enforced by PDS).	'application/octet-stream'

Returns

Name	Type	Description
	dict	A blob reference dict with keys: ‘$type’, ‘ref’, ‘mimeType’, ‘size’.
	dict	This can be embedded directly in record fields.

Raises

Name	Type	Description
	ValueError	If not authenticated.
	atproto.exceptions.AtProtocolError	If upload fails.