basicauth library

Common errors

• TypeError: cannot unpack non-iterable NoneType object

  cause Attempting to directly unpack the return value of `basicauth.decode()` when it returns `None` for an invalid or missing Basic Auth header.
  fix Always check if the result of `basicauth.decode()` is not `None` before attempting to unpack it. Use `if basicauth.decode(header): username, password = basicauth.decode(header)`.

• TypeError: decode() missing 1 required positional argument: 'auth_header'

  cause Calling `basicauth.decode()` or `basicauth.verify()` without providing the required `auth_header` string argument.
  fix Ensure you pass a string representing the HTTP 'Authorization' header (e.g., `basicauth.decode(request.headers.get('Authorization', ''))`).

• Basic authentication is not working in my Flask/Django/FastAPI application.

  cause Misunderstanding the scope of the `basicauth` library. It only decodes the header; it doesn't automatically implement the full authentication flow within a web framework (e.g., checking credentials against a database, creating sessions, or middleware).
  fix Use `basicauth` to get `username` and `password` from the incoming request's 'Authorization' header. Then, implement your own application logic to verify these credentials against your user store (database, file, etc.) and handle authenticated state within your framework's request handling pipeline.

Warnings

• gotcha The `basicauth.decode()` function returns `None` if the provided `auth_header` is malformed, not a 'Basic' type header, or cannot be base64 decoded and split. It does not raise an exception in these cases.
  Fix: Always check if the result of `basicauth.decode()` is not `None` before attempting to unpack or use the returned username and password. Example: `result = basicauth.decode(header); if result: username, password = result`.
• gotcha This library is intentionally simplistic. It only handles the decoding and basic verification of HTTP Basic Auth headers. It does not provide functionality for user management, password hashing, session management, token expiry, or integration with web frameworks.
  Fix: Use `basicauth` to obtain the username and password, then implement your application's specific logic for user lookup, password verification (e.g., using `bcrypt` or `argon2`), and session management within your web framework's request handlers.
• breaking The library is stable at version 1.0.0. While no breaking changes are known or anticipated for minor versions, be aware that any future major version increment (e.g., to 2.0.0) could introduce API changes.
  Fix: Always pin your dependency version (e.g., `basicauth==1.0.0`) and review the changelog if upgrading to a new major version.

Install

• pip install basicauth Install `basicauth`

Imports

• decode

  import basicauth
  username, password = basicauth.decode(auth_header)

  The primary function to decode a Basic Auth header.
• verify

  import basicauth
  is_valid = basicauth.verify(auth_header, expected_username, expected_password)

  A utility function to verify a Basic Auth header against known credentials.

Quickstart

This quickstart demonstrates how to use `basicauth.decode` to extract username and password from an 'Authorization' header, and `basicauth.verify` to check credentials. It highlights handling `None` returns for invalid headers.

import basicauth

# Example Authorization header
auth_header_valid = 'Basic Zm9vOmJhcg==' # 'foo:bar'
auth_header_invalid = 'Bearer eyJh...' # Not Basic Auth
auth_header_malformed = 'Basic not_base64'

# --- Decoding a Basic Auth header ---
# Returns (username, password) or None
username, password = basicauth.decode(auth_header_valid)
if username and password:
    print(f"Decoded (valid): Username='{username}', Password='{password}'")
else:
    print(f"Failed to decode (valid): {username=}, {password=}")

username_invalid, password_invalid = basicauth.decode(auth_header_invalid)
if username_invalid is None:
    print(f"Decoded (invalid type, correctly None): {username_invalid=}, {password_invalid=}")

username_malformed, password_malformed = basicauth.decode(auth_header_malformed)
if username_malformed is None:
    print(f"Decoded (malformed, correctly None): {username_malformed=}, {password_malformed=}")

# --- Verifying a Basic Auth header ---
# Returns True or False
is_valid_auth = basicauth.verify(auth_header_valid, 'foo', 'bar')
print(f"Verification (correct credentials): {is_valid_auth}")

is_invalid_auth = basicauth.verify(auth_header_valid, 'wrong', 'credentials')
print(f"Verification (incorrect credentials): {is_invalid_auth}")

is_invalid_format = basicauth.verify(auth_header_invalid, 'foo', 'bar')
print(f"Verification (wrong header format): {is_invalid_format}")