atproto_oauth.scopes

class atproto_oauth.scopes.AccountPermission(attr: str, action: Tuple[str, ...])

Bases: object

Permission for account attribute access.

classmethod from_string(scope: str) → AccountPermission | None

classmethod from_syntax(syntax: ScopeStringSyntax) → AccountPermission | None

matches(attr: str, action: str) → bool

static scope_needed_for(attr: str, action: str) → str

attr: str

action: Tuple[str, ...]

class atproto_oauth.scopes.BlobPermission(accept: Tuple[str, ...])

Bases: object

Permission for blob uploads.

classmethod from_string(scope: str) → BlobPermission | None

classmethod from_syntax(syntax: ScopeStringSyntax) → BlobPermission | None

matches(mime: str) → bool

static scope_needed_for(mime: str) → str

accept: Tuple[str, ...]

class atproto_oauth.scopes.IdentityPermission(attr: str)

Bases: object

Permission for identity operations.

classmethod from_string(scope: str) → IdentityPermission | None

classmethod from_syntax(syntax: ScopeStringSyntax) → IdentityPermission | None

matches(attr: str) → bool

static scope_needed_for(attr: str) → str

attr: str

class atproto_oauth.scopes.IncludeScope(nsid: str, aud: str | None = None)

Bases: object

An include: scope that references a lexicon permission set.

Not a permission itself — it resolves via a lexicon definition to produce RepoPermission and/or RpcPermission instances.

aud: str | None = None

classmethod from_string(scope: str) → IncludeScope | None

classmethod from_syntax(syntax: ScopeStringSyntax) → IncludeScope | None

is_parent_authority_of(other_nsid: str) → bool

Check if other_nsid is in the same namespace authority.

The namespace authority is everything before the last . segment of self.nsid. other_nsid must start with that same prefix.

nsid: str

class atproto_oauth.scopes.RepoPermission(collection: Tuple[str, ...], action: Tuple[str, ...])

Bases: object

Permission for repository record operations.

classmethod from_string(scope: str) → RepoPermission | None

classmethod from_syntax(syntax: ScopeStringSyntax) → RepoPermission | None

matches(collection: str, action: str) → bool

static scope_needed_for(collection: str, action: str) → str

collection: Tuple[str, ...]

action: Tuple[str, ...]

class atproto_oauth.scopes.RpcPermission(aud: str, lxm: Tuple[str, ...])

Bases: object

Permission for RPC (XRPC) method calls.

classmethod from_string(scope: str) → RpcPermission | None

classmethod from_syntax(syntax: ScopeStringSyntax) → RpcPermission | None

matches(lxm: str, aud: str) → bool

static scope_needed_for(lxm: str, aud: str) → str

aud: str

lxm: Tuple[str, ...]

exception atproto_oauth.scopes.ScopeMissingError(scope: str)

Bases: OAuthError

A required scope was not granted.

scope: The missing scope.

class atproto_oauth.scopes.ScopePermissions(scope: str | None = None)

Bases: object

Typed permission checker wrapping a ScopesSet.

Example:

perms = ScopePermissions('atproto repo:com.example.record blob:*/*')
perms.allows_repo(collection='com.example.record', action='create')  # True

allows_account(attr: str, action: str) → bool

allows_blob(mime: str) → bool

allows_identity(attr: str) → bool

allows_repo(collection: str, action: str) → bool

allows_rpc(lxm: str, aud: str) → bool

assert_account(attr: str, action: str) → None

assert_blob(mime: str) → None

assert_identity(attr: str) → None

assert_repo(collection: str, action: str) → None

assert_rpc(lxm: str, aud: str) → None

class atproto_oauth.scopes.ScopePermissionsTransition(scope: str | None = None)

Bases: ScopePermissions

Permission checker with transition scope support.

Transition scopes are legacy grants from the pre-scoped OAuth era:

transition:generic: all repo, all blob, all non-chat.bsky RPC
transition:chat.bsky: all chat.bsky.* RPC methods
transition:email: read access to account email

allows_account(attr: str, action: str) → bool

allows_blob(mime: str) → bool

allows_repo(collection: str, action: str) → bool

allows_rpc(lxm: str, aud: str) → bool

property has_transition_chat_bsky: bool

property has_transition_email: bool

property has_transition_generic: bool

class atproto_oauth.scopes.ScopesSet(scopes: Iterable[str] | None = None)

Bases: object

A set of OAuth scope strings with permission matching.

Example:

scopes = ScopesSet.from_string('atproto repo:com.example.record blob:*/*')
scopes.matches('repo', collection='com.example.record', action='create')  # True
scopes.matches('blob', mime='image/png')  # True

add(scope: str) → None: Add a scope string to the set.

assert_matches(resource: str, **kwargs: Any) → None

Ensure that a scope grants the requested permission.

Raises:: atproto_oauth.exceptions.ScopeMissingError – No scope grants the permission.

discard(scope: str) → None: Remove a scope string if present.

classmethod from_string(scope_string: str | None = None) → ScopesSet: Parse a space-separated scope string.

has(scope: str) → bool: Check if an exact scope string is in the set.

matches(resource: str, **kwargs: Any) → bool

Check if any scope in the set grants the requested permission.

Parameters:

resource – The resource type (repo, blob, rpc, account, identity).
**kwargs – Permission-specific parameters passed to matches().

Returns:

Whether any scope grants the permission.

Return type:

bool

property size: int