paperap.auth module

Authentication classes for Paperless-ngx API.

This module provides authentication classes for interacting with the Paperless-ngx API. It supports token-based authentication and basic username/password authentication.

Classes:

AuthBase: Abstract base class for authentication methods. TokenAuth: Authentication using a Paperless-ngx API token. BasicAuth: Authentication using username and password.

class paperap.auth.AuthBase(**data)[source]

Bases: BaseModel, ABC

Base authentication class for Paperless-ngx API.

This abstract base class defines the interface for all authentication methods. Subclasses must implement methods to provide authentication headers and parameters.

model_config

Pydantic configuration for validation behavior.

Type:

ConfigDict

Parameters:

data (Any)

model_config: ClassVar[ConfigDict] = {'str_strip_whitespace': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

abstractmethod get_auth_headers()[source]

Get authentication headers for API requests.

Returns:

A dictionary of HTTP headers needed for authentication.

Return type:

dict[str, str]

Raises:

NotImplementedError – If not implemented by subclasses.

abstractmethod get_auth_params()[source]

Get authentication parameters for API requests.

Returns:

A dictionary of parameters to include in the request.

Return type:

dict[str, Any]

Raises:

NotImplementedError – If not implemented by subclasses.

class paperap.auth.TokenAuth(**data)[source]

Bases: AuthBase

Authentication using a Paperless-ngx API token.

This class implements token-based authentication for the Paperless-ngx API. The token is included in the Authorization header of each request.

token

The API token from Paperless-ngx.

Type:

str

Examples

>>> auth = TokenAuth(token="abcdef1234567890abcdef1234567890abcdef12")
>>> headers = auth.get_auth_headers()
>>> print(headers)
{'Authorization': 'Token abcdef1234567890abcdef1234567890abcdef12'}
Parameters:

data (Any)

token: Annotated[str, Field(min_length=30, max_length=75, pattern='^[a-zA-Z0-9]+$')]
get_auth_headers()[source]

Get the authorization headers with the token.

Returns:

A dictionary containing the Authorization header with the token.

Return type:

dict[str, str]

get_auth_params()[source]

Get authentication parameters for requests.

For token authentication, no additional parameters are needed.

Returns:

An empty dictionary as token auth uses headers, not parameters.

Return type:

dict[str, Any]

model_config: ClassVar[ConfigDict] = {'str_strip_whitespace': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.auth.BasicAuth(**data)[source]

Bases: AuthBase

Authentication using username and password.

This class implements HTTP Basic Authentication for the Paperless-ngx API. The username and password are passed to the requests library’s auth parameter.

username

The Paperless-ngx username.

Type:

str

password

The Paperless-ngx password.

Type:

str

Examples

>>> auth = BasicAuth(username="admin", password="password123")
>>> params = auth.get_auth_params()
>>> print(params)
{'auth': ('admin', 'password123')}
Parameters:

data (Any)

username: str
password: str
get_auth_headers()[source]

Get headers for basic auth.

Basic auth is handled by the requests library’s auth parameter, so no headers are needed here.

Returns:

An empty dictionary as basic auth uses parameters, not headers.

Return type:

dict[str, str]

get_auth_params()[source]

Get authentication parameters for requests.

Returns:

A dictionary containing the auth parameter with username and password.

Return type:

dict[str, Any]

model_config: ClassVar[ConfigDict] = {'str_strip_whitespace': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].