pylocalauth

Cross-platform local authentication library for Python applications.

---

Documentation: README

Source Code: Repository

---

Add local authentication to your Python applications with ease. pylocalauth provides a simple and secure way to authenticate users using platform-specific methods such as passwords, biometrics, and PINs.

Features

Feature	Status
Cross-platform: Works on Windows, macOS, and Linux. (macOS is still in beta, but it should work reliably)	✅
Multiple authentication methods: Supports password-based, biometric (Windows Hello, Touch ID, etc.), and PIN-based authentication.	✅
Easy integration: Simple API for integrating local authentication into your Python applications.	✅
Secure: Utilizes platform-specific security features to ensure user data is protected.	✅
Lightweight: Minimal dependencies and easy to install.	✅

Windows Example	Linux Example

Installation

You can install pylocalauth via pip:

pip install pylocalauth --upgrade

Usage

Here's a very simple example of how to use pylocalauth to authenticate a user:

from pylocalauth import authenticate # Import the authenticate function for your platform
result = authenticate()
if result:
    print("Authentication successful!")
else:
    print("Authentication failed.")

You can also customize the message displayed during authentication:

from pylocalauth import authenticate
result = authenticate(message="Please authenticate to proceed.")

By default, pylocalauth will raise an AuthUnavailableError if authentication is not available on the current platform. You can disable this behavior by setting the check_availability parameter to False (You should only do this if you plan to handle the unavailability yourself):

from pylocalauth import authenticate, is_available
from pylocalauth.exceptions import AuthError, AuthUnavailableError

# Let it handle availability automatically
try:
    result = authenticate(check_availability=True) # default
    print(f"Authentication successful?: {result}")
except AuthUnavailableError:
    print("Authentication is not available on this platform.")
except AuthError as e:
    print(f"An error occurred: {e}")

# Handle availability yourself
try:
    if not is_available():
        print("Authentication is not available on this platform.")
    else:
        result = authenticate(check_availability=False)
        print(f"Authentication successful?: {result}")
except AuthError as e:
    print(f"An error occurred: {e}")

Contributing

We welcome contributions from the community! If you'd like to contribute, please follow the steps explained in the CONTRIBUTORS file.

Contributions Needed

We are especially looking for help with the following:

• macOS support: Testing, bug reports, and improvements for the macOS backend.
• Documentation & Tests: Examples, API docs, tests (using pytest and pytest-asyncio) and usage guides.
• CI/CD: Enhancements to cross-platform test automation.
• New authentication methods: Suggestions or PRs for additional local authentication backends.
• Issue triage: Help us reproduce and resolve open issues.

If you want to help, please see CONTRIBUTORS and open an issue or pull request!

Development

Setup environment

We use Hatch to manage the development environment and production build. Ensure it's installed on your system.

Run unit tests

You can run all the tests with:

hatch run test

Format the code

Execute the following command to apply isort and black formatting:

hatch run lint

License

This project is licensed under the terms of the Apache 2.0 license. See the LICENSE file for more information.