Welcome to Streamlit Authenticator’s documentation!
Script description: This module renders the login, logout, register user, reset password, forgot password, forgot username, and modify user details widgets.
Libraries imported:
json: Handles JSON documents.
time: Implements sleep function.
typing: Implements standard typing notations for Python functions.
streamlit: Framework used to build pure Python web applications.
- class Authenticate(credentials: Dict[str, Any] | str, cookie_name: str = 'some_cookie_name', cookie_key: str = 'some_key', cookie_expiry_days: float = 30.0, validator: Validator | None = None, auto_hash: bool = True, api_key: str | None = None, **kwargs: Dict[str, Any] | None)[source]
This class renders login, logout, register user, reset password, forgot password, forgot username, and modify user details widgets.
- experimental_guest_login(button_name: str = 'Guest login', location: Literal['main', 'sidebar'] = 'main', provider: Literal['google', 'microsoft'] = 'google', oauth2: Dict[str, Any] | None = None, max_concurrent_users: int | None = None, single_session: bool = False, roles: List[str] | None = None, use_container_width: bool = False, callback: Callable | None = None) None[source]
Renders a guest login button.
- Parameters:
button_name (str, default='Guest login') – Display name for the guest login button.
location ({'main', 'sidebar'}, default='main') – Location where the guest login button is rendered.
provider ({'google', 'microsoft'}, default='google') – OAuth2 provider used for authentication.
oauth2 (dict, optional) – Configuration parameters for OAuth2 authentication.
max_concurrent_users (int, optional) – Maximum number of users allowed to log in concurrently.
single_session (bool, default=False) – If True, prevents users from logging into multiple sessions simultaneously.
roles (list of str, optional) – Roles assigned to guest users.
use_container_width (bool, default=False) – If True, the button width matches the container.
callback (Callable, optional) – Function to execute when the button is pressed.
- forgot_password(location: Literal['main', 'sidebar'] = 'main', fields: Dict[str, str] | None = None, captcha: bool = False, send_email: bool = False, two_factor_auth: bool = False, clear_on_submit: bool = False, key: str = 'Forgot password', callback: Callable | None = None) Tuple[str | None, str | None, str | None][source]
Renders a forgot password widget.
- Parameters:
location ({'main', 'sidebar'}, default='main') – Location of the forgot password widget.
fields (dict, optional) – Custom labels for form fields and buttons.
captcha (bool, default=False) – If True, requires captcha validation.
send_email (bool, default=False) – If True, sends the new password to the user’s email.
two_factor_auth (bool, default=False) – If True, enables two-factor authentication.
clear_on_submit (bool, default=False) – If True, clears input fields after form submission.
key (str, default='Forgot password') – Unique key for the widget to prevent duplicate WidgetID errors.
callback (Callable, optional) – Function to be executed after form submission.
- Returns:
Username associated with the forgotten password.
Email associated with the forgotten password.
New plain-text password to be securely transferred to the user.
- Return type:
tuple[str, str, str] or (None, None, None)
- forgot_username(location: Literal['main', 'sidebar'] = 'main', fields: Dict[str, str] | None = None, captcha: bool = False, send_email: bool = False, two_factor_auth: bool = False, clear_on_submit: bool = False, key: str = 'Forgot username', callback: Callable | None = None) Tuple[str | None, str | None][source]
Renders a forgot username widget.
- Parameters:
location ({'main', 'sidebar'}, default='main') – Location of the forgot username widget.
fields (dict, optional) – Custom labels for form fields and buttons.
captcha (bool, default=False) – If True, requires captcha validation.
send_email (bool, default=False) – If True, sends the retrieved username to the user’s email.
two_factor_auth (bool, default=False) – If True, enables two-factor authentication.
clear_on_submit (bool, default=False) – If True, clears input fields after form submission.
key (str, default='Forgot username') – Unique key for the widget to prevent duplicate WidgetID errors.
callback (Callable, optional) – Function to be executed after form submission.
- Returns:
Username associated with the forgotten username.
Email associated with the forgotten username.
- Return type:
tuple[str, str] or (None, str)
- login(location: Literal['main', 'sidebar', 'unrendered'] = 'main', max_concurrent_users: int | None = None, max_login_attempts: int | None = None, fields: Dict[str, str] | None = None, captcha: bool = False, single_session: bool = False, clear_on_submit: bool = False, key: str = 'Login', callback: Callable | None = None) Tuple[str | None, bool | None, str | None] | None[source]
Renders a login widget.
- Parameters:
location ({'main', 'sidebar', 'unrendered'}, default='main') – Location where the login widget is rendered.
max_concurrent_users (int, optional) – Maximum number of users allowed to log in concurrently.
max_login_attempts (int, optional) – Maximum number of failed login attempts allowed.
fields (dict, optional) – Custom labels for form fields and buttons.
captcha (bool, default=False) – If True, requires captcha validation.
single_session (bool, default=False) – If True, prevents users from logging into multiple sessions simultaneously.
clear_on_submit (bool, default=False) – If True, clears input fields after form submission.
key (str, default='Login') – Unique key for the widget to prevent duplicate WidgetID errors.
callback (Callable, optional) – Function to execute when the form is submitted.
- Returns:
If location=’unrendered’, returns (user’s name, authentication status, username).
Otherwise, returns None.
- Return type:
tuple[str, bool, str] or None
- logout(button_name: str = 'Logout', location: Literal['main', 'sidebar', 'unrendered'] = 'main', key: str = 'Logout', use_container_width: bool = False, callback: Callable | None = None) None[source]
Renders a logout button.
- Parameters:
button_name (str, default='Logout') – Display name for the logout button.
location ({'main', 'sidebar', 'unrendered'}, default='main') – Location where the logout button is rendered.
key (str, default='Logout') – Unique key for the widget, useful in multi-page applications.
use_container_width (bool, default=False) – If True, the button width matches the container.
callback (Callable, optional) – Function to execute when the button is pressed.
- register_user(location: Literal['main', 'sidebar'] = 'main', pre_authorized: List[str] | None = None, domains: List[str] | None = None, fields: Dict[str, str] | None = None, captcha: bool = True, roles: List[str] | None = None, merge_username_email: bool = False, password_hint: bool = True, two_factor_auth: bool = False, clear_on_submit: bool = False, key: str = 'Register user', callback: Callable | None = None) Tuple[str | None, str | None, str | None][source]
Renders a register new user widget.
- Parameters:
location ({'main', 'sidebar'}, default='main') – Location where the registration widget is rendered.
pre_authorized (list of str, optional) – List of emails of unregistered users who are authorized to register.
domains (list of str, optional) – List of allowed email domains (e.g., [‘gmail.com’, ‘yahoo.com’]).
fields (dict, optional) – Custom labels for form fields and buttons.
captcha (bool, default=True) – If True, requires captcha validation.
roles (list of str, optional) – User roles for registered users.
merge_username_email (bool, default=False) – If True, uses the email as the username.
password_hint (bool, default=True) – If True, includes a password hint field.
two_factor_auth (bool, default=False) – If True, enables two-factor authentication.
clear_on_submit (bool, default=False) – If True, clears input fields after form submission.
key (str, default='Register user') – Unique key for the widget to prevent duplicate WidgetID errors.
callback (Callable, optional) – Function to execute when the form is submitted.
- Returns:
Email associated with the new user.
Username associated with the new user.
Name associated with the new user.
- Return type:
tuple[str, str, str] or (None, None, None)
- reset_password(username: str, location: Literal['main', 'sidebar'] = 'main', fields: Dict[str, str] | None = None, clear_on_submit: bool = False, key: str = 'Reset password', callback: Callable | None = None) bool | None[source]
Renders a password reset widget.
- Parameters:
username (str) – Username of the user whose password is being reset.
location ({'main', 'sidebar'}, default='main') – Location where the password reset widget is rendered.
fields (dict, optional) – Custom labels for form fields and buttons.
clear_on_submit (bool, default=False) – If True, clears input fields after form submission.
key (str, default='Reset password') – Unique key for the widget to prevent duplicate WidgetID errors.
callback (Callable, optional) – Function to execute when the form is submitted.
- Returns:
True if the password reset was successful.
None if the reset failed or was not attempted.
- Return type:
bool or None
- update_user_details(username: str, location: Literal['main', 'sidebar'] = 'main', fields: Dict[str, str] | None = None, clear_on_submit: bool = False, key: str = 'Update user details', callback: Callable | None = None) bool[source]
Renders an update user details widget.
- Parameters:
username (str) – Username of the user whose details are being updated.
location ({'main', 'sidebar'}, default='main') – Location where the update user details widget is rendered.
fields (dict, optional) – Custom labels for form fields and buttons.
clear_on_submit (bool, default=False) – If True, clears input fields after form submission.
key (str, default='Update user details') – Unique key for the widget to prevent duplicate WidgetID errors.
callback (Callable, optional) – Function to execute when the form is submitted.
- Returns:
True if user details were successfully updated.
None if the update failed or was not attempted.
- Return type:
bool or None
Script description: Handles secure hashing and validation of plain text passwords using bcrypt.
Libraries Imported:
re: Implements regular expressions for pattern matching.
bcrypt: Provides secure password hashing.
typing: Provides standard type hints for Python functions.
- class Hasher[source]
This class provides methods for hashing and verifying passwords.
- classmethod check_pw(password: str, hashed_password: str) bool[source]
Verifies if a plain text password matches a hashed password.
- Parameters:
password (str) – The plain text password.
hashed_password (str) – The hashed password to compare against.
- Returns:
True if the password matches the hash, False otherwise.
- Return type:
bool
- classmethod hash(password: str) str[source]
Hashes a plain text password using bcrypt.
- Parameters:
password (str) – The plain text password.
- Returns:
The securely hashed password.
- Return type:
str
- classmethod hash_list(passwords: List[str]) List[str][source]
Hashes a list of plain text passwords.
- Parameters:
passwords (list of str) – The list of plain text passwords to be hashed.
- Returns:
The list of securely hashed passwords.
- Return type:
list of str
- classmethod hash_passwords(credentials: Dict[str, Dict[str, str]]) Dict[str, Dict[str, str]][source]
Hashes all plain text passwords in a credentials dictionary.
- Parameters:
credentials (dict) – Dictionary containing usernames as keys and user details as values.
- Returns:
The credentials dictionary with all passwords securely hashed.
- Return type:
dict
Script description: This script provides string validations for various user inputs.
Libraries Imported:
re: Implements regular expressions for pattern matching.
- class Validator[source]
This class provides validation methods for usernames, names, emails, and passwords.
- diagnose_password(password: str) str[source]
Diagnoses the validity of the entered password and returns an error message if invalid.
- Parameters:
password (str) – The password to be diagnosed.
- Returns:
Error message listing password requirements that were not met.
- Return type:
str
- validate_email(email: str) bool[source]
Checks the validity of the entered email.
- Parameters:
email (str) – The email to be validated.
- Returns:
True if the email is valid, False otherwise.
- Return type:
bool
- validate_length(variable: str, min_length: int = 0, max_length: int = 254) bool[source]
Checks if a given string is within the specified length range.
- Parameters:
variable (str) – The string to be validated.
min_length (int, default=0) – The minimum required length for the string.
max_length (int, default=254) – The maximum allowed length for the string.
- Returns:
True if the string length is within range, False otherwise.
- Return type:
bool
- validate_name(name: str) bool[source]
Checks the validity of the entered name.
- Parameters:
name (str) – The name to be validated.
- Returns:
True if the name is valid, False otherwise.
- Return type:
bool