Client

BhoonidhiClient is the entry point to the SDK. It holds the portal session and exposes each command group as a namespace: client.archive, client.query, client.cart.

from bhoonidhi_downloader.sdk import BhoonidhiClient

client = BhoonidhiClient()
client.login("my-username", "my-password")

Some accounts also require a 6-digit email OTP after the password — see Log in in the SDK guide for both the interactive (otp_prompt) and non-interactive (otp=) forms.

BhoonidhiClient

BhoonidhiClient(session: SessionSchema | None = None)

A logged-in (or about-to-log-in) handle on the Bhoonidhi portal.

The session is cached in memory. Pass an existing SessionSchema to reuse one, or leave it out and the saved session at ~/.bhoonidhi/session is picked up the first time it's needed.

Methods:

Name	Description
login	Authenticate and remember the session.
logout	Forget the session, in memory and on disk.
whoami	Return the logged-in username, or None. Mirrors bhd auth whoami.
status	Return the saved session and whether its token still validates.
refresh	Renew the current token without re-entering the password.
require_account	Return the held session, or raise if there's no usable token.

Attributes:

Name	Type	Description
is_authenticated		True when a session with a token is held.
account		The active session record, loaded from disk on first use if unset.

is_authenticated property

is_authenticated

True when a session with a token is held.

account property

account

The active session record, loaded from disk on first use if unset.

login

login(
    username: str,
    password: str,
    save: bool = True,
    *,
    otp: str | None = None,
    otp_prompt: Callable[[str], str] | None = None,
) -> SessionSchema

Authenticate and remember the session.

Mirrors bhd auth login. The password is used only for this call and never stored on the client. When the portal mails an email OTP instead of a JWT, pass otp or otp_prompt — see :meth:AuthManager.login for how the retry works. Raises a :class:~bhoonidhi_downloader.exceptions.BhoonidhiError if the credentials are rejected or every OTP attempt fails.

logout

logout() -> bool

Forget the session, in memory and on disk.

Mirrors bhd auth logout. Returns True if a saved session was removed, False if there was nothing to remove.

whoami

whoami() -> str | None

Return the logged-in username, or None. Mirrors bhd auth whoami.

status

status() -> (
    tuple[
        bhoonidhi_downloader.schemas.session.SessionSchema,
        bool,
    ]
    | None
)

Return the saved session and whether its token still validates.

Mirrors bhd auth status. Returns None when there's no session to check.

refresh

refresh() -> (
    bhoonidhi_downloader.schemas.session.SessionSchema
    | None
)

Renew the current token without re-entering the password.

Mirrors bhd auth refresh. Updates the held session on success. Returns None when there's no session to refresh, and raises a :class:~bhoonidhi_downloader.exceptions.BhoonidhiError if the portal rejects the refresh.

require_account

require_account() -> SessionSchema

Return the held session, or raise if there's no usable token.

The single authentication gate the namespaces call before any portal action, so the "not logged in" behaviour and message live in one place.

Raises:

Type	Description
BhoonidhiAuthError	if no session with a token is held.