Metadata-Version: 2.4
Name: easy_mongodb_auth_handler
Version: 1.0.5
Summary: A user authentication and verification system using MongoDB.
Home-page: https://github.com/lukbrew25/easy_mongodb_auth_handler/
Author: Lukbrew25
License: AGPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pymongo>=4.6.3
Requires-Dist: bcrypt>=4.0.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# easy_mongodb_auth_handler

A user authentication and verification system using MongoDB, supporting email-based verification, password hashing, and reset mechanisms.

## Installation

```
pip install easy-mongodb-auth-handler
```

## Setup

Make sure you have MongoDB installed and running. You also need access to an SMTP mail server for sending verification and reset codes.

## Project Structure

```
easy_mongodb_auth_handler/
├── setup.py
├── src/
│   └── easy_mongodb_auth_handler/
│       ├── __init__.py
│       ├── auth.py
│       └── utils.py
```

## Features

- User registration with and without email verification
- Email format validation
- Secure password hashing with bcrypt
- User login/authentication
- Password reset via email verification
- MongoDB-based user data persistence

## Usage

```
from easy_mongodb_auth_handler import Auth

auth = Auth(
    mongo_uri="mongodb://localhost:27017",
    db_name="mydb",
    mail_info={
        mail_server="smtp.example.com",
        mail_port=587,
        mail_username="your_email@example.com",
        mail_password="your_email_password"
    }, # Optional: Include if using email verification
    blocking=True/False  # Optional: True to enable user blocking
)
```
This code initializes the package. The mail arguments are not required, but needed to use verification code functionality. All methods return True or False with additional detailed outcome reports.

## Function Reference - auth.example_func(args)

All functions return a dictionary: `{"success": True/False, "message": "specific message"}`.

### User Registration & Verification

- `register_user(email, password, custom_data=False)`
  - Registers a user and sends a verification code via email. `custom_data` can be any additional user info.

- `register_user_no_verif(email, password, custom_data=False)`
  - Registers a user without email verification. `custom_data` is optional.

- `verify_user(email, code)`
  - Verifies a user by checking the provided verification code.

### Authentication

- `authenticate_user(email, password)`
  - Authenticates a user. Requires the user to be verified.

### Password Management

- `reset_password_no_verif(email, old_password, new_password)`
  - Resets the user's password after verifying the old password. No email code required.

- `generate_reset_code(email)`
  - Generates and emails a password reset code to the user.

- `verify_reset_code_and_reset_password(email, reset_code, new_password)`
  - Verifies a password reset code and resets the user's password.

### User Deletion & Blocking

- `delete_user(email, password, del_from_blocking=True)`
  - Deletes a user from the database if credentials match. If `del_from_blocking` is `True`, also removes from the blocking database.

- `block_user(email)`
  - Blocks a user by setting their status to "blocked".

- `unblock_user(email)`
  - Unblocks a user.

### Custom User Data

- `get_cust_usr_data(email)`
  - Retrieves all custom user data for the user.

- `get_some_cust_usr_data(email, field)`
  - Retrieves a specific field from the user's custom data.

- `replace_usr_data(email, custom_data)`
  - Replaces the user's custom data with new data.

- `update_usr_data(email, field, custom_data)`
  - Updates a specific field in the user's custom data.

## Requirements

- Python >= 3.8
- pymongo >= 4.0.0
- bcrypt >= 4.0.0

## License

GNU Affero General Public License v3

## Author

Lukbrew25

...and all future contributors!
