
Security News
Deno 2.4 Brings Back deno bundle, Improves Dependency Management and Observability
Deno 2.4 brings back bundling, improves dependency updates and telemetry, and makes the runtime more practical for real-world JavaScript projects.
easy-mongodb-auth-handler
Advanced tools
A user authentication and verification system using MongoDB, supporting email-based verification, password hashing, and reset mechanisms.
pip install easy-mongodb-auth-handler
Make sure you have MongoDB installed and running. You also need access to an SMTP mail server for sending verification and reset codes.
easy_mongodb_auth_handler/
βββ .github/
β βββ workflows/
β βββ linter.yml
β βββ minlinter.yml
β βββ python-package.yml
|ββ dist/
| βββ easy_mongodb_auth_handler-2.1.0-py3-none-any.whl
| βββ easy_mongodb_auth_handler-2.1.0.tar.gz
βββ src/
β βββ .gitignore
β βββ easy_mongodb_auth_handler/
β βββ .gitignore
β βββ __init__.py
β βββ auth.py
β βββ utils.py
β βββ core_db.py
β βββ package_functions/
β βββ __init__.py
β βββ func.py
β βββ message.py
|ββ README.md
|ββ LICENSE
|ββ requirements.txt
|ββ minrequirements.txt
|ββ MANIFEST.in
|ββ setup.py
|ββ .gitignore
|ββ .pylintrc
|ββ .flake8
βββCONTRIBUTING.md
from easy_mongodb_auth_handler import Auth, Utils, CoreDB
auth = Auth(
mongo_uri="mongodb://localhost:27017", # MongoDB URI for your database (Must match the other modules' mongo_uri if using other modules)
db_name="auth", # Database name for user data (Must match the other modules' db_name if using other modules)
mail_info={
"server": "smtp.example.com",
"port": 587,
"username": "your_email@example.com",
"password": "your_email_password"
}, # Optional: Include if using email verification
mail_subject="Verification Code", # Optional: Custom subject for verification codes
mail_body="Your verification code is: {verifcode}", # Optional: Custom email body for verification codes. The text "{verifcode}" is replaced with the verification code. Use HTML or plain text in the template. It is recommended to read the template from a file and pass it here.
blocking=True/False, # Optional: True to enable user blocking
rate_limiting=0, # Optional: Set to 0 to disable rate limiting, or a positive integer to enable rate limiting with that cooldown period in seconds between user requests.
rate_limit_penalty=0, # Optional: Set to 0 to disable rate limiting penalty, or a positive integer to set the penalty in seconds for rate limiting. If rate limiting is enabled, this is the penalty in seconds added to the cooldown period for violating the cooldown. Requires `rate_limiting` to be set to a positive integer.
readable_errors=True/False, # Optional: False to switch to numeric error codes translated in the README.md file
code_length=6, # Optional: Length of the numeric verification code (default is 6 characters).
db_attempts=6, # Optional: Number of attempts to initially connect to MongoDB (default is 6).
db_delay=10, # Optional: Delay in seconds between MongoDB initial connection attempts (default is 10 seconds).
db_timeout=5000, # Optional: Timeout in ms for MongoDB connection (default is 5000 ms).
certs=certifi.where() # Optional: Path to CA bundle for SSL verification (default is certifi's CA bundle)
)
utils = Utils(
mongo_uri="mongodb://localhost:27017", # Must match the Auth module's mongo_uri
db_name="auth", # Must match the Auth module's db_name
attempts=6, # Optional: Number of attempts for initial MongoDB connection (default is 6).
readable_errors=True/False, # Optional: False to switch to numeric error codes translated in the README.md file
delay=10, # Optional: Delay in seconds between MongoDB initial connection attempts (default is 10 seconds).
timeout=5000, # Optional: Timeout in ms for MongoDB connection (default is 5000 ms).
certs=certifi.where() # Optional: Path to CA bundle for SSL verification (default is certifi's CA bundle)
)
coredb = CoreDB(
mongo_uri="mongodb://localhost:27017", # Must match the Auth module's mongo_uri
db_name="auth", # Must match the Auth module's db_name
attempts=6, # Optional: Number of attempts for initial MongoDB connection (default is 6).
readable_errors=True/False, # Optional: False to switch to numeric error codes translated in the README.md file
delay=10, # Optional: Delay in seconds between MongoDB initial connection attempts (default is 10 seconds).
timeout=5000, # Optional: Timeout in ms for MongoDB connection (default is 5000 ms).
certs=certifi.where() # Optional: Path to CA bundle for SSL verification (default is certifi's CA bundle)
)
This code initializes the modules. The Auth module is used for most functions. The Utils module is used for utility functions that are designed for user management, data retrieval, and status checks that are not intended to directly process user input. The CoreDB module is used for direct database interactions, such as manually resetting or deleting the db and collections.
The mail arguments are not required but needed to use verification code functionality.
Each module can be initialized separately if you only need specific functionalities of one or two module(s). Make sure to use the same mongo uri and db name for all modules.
The blocking
argument is optional and defaults to True
. If set to True
, it enables user blocking functionality.
The rate_limiting
argument is optional and defaults to 0
, which disables rate limiting. If configured with x number of seconds, it will refuse more than two requests per email address in that time period (timer reset upon successful or unsuccessful request). rate_limit_penalty can be used to add a stackable cooldown penalty to the timer per user.
The mail subject and body arguments can be customized using your own templates. Be sure to include the {verifcode}
placeholder in the body, as it will be replaced with the actual verification code sent to the user.
Both HTML and plain text formats are supported for the email body. It is recommended to read the email body from a file and pass it to the mail_body
argument.
Both blocking and rate limiting are optional and only affect functions in the Auth module.
The data can be easily accessed externally by connecting to the same mongodb instance, navigating to the database passed to the db_name
argument, and then accessing the users
, blocked
, and limit
collections.
All methods return True or False (unless the method is meant to return data) with additional detailed outcome reports (as in the following format) EXCEPT for the CoreDB methods, which have no returns or returns of data.:
{
"success": True/False,
"message": "specific message or error code"
}
All functions return a dictionary: {"success": True/False, "message": "specific message"}
.
auth.register_user(email, password, custom_data=None, cust_length=None, ignore_rate_limit=False)
email
(str
): User's email address.password
(str
): User's password.custom_data
(any
, optional): Additional user info to store. If None, defaults to an empty dictionary.cust_length
(int
, optional): Length of the verification code. If None, defaults to the module's code_length
setting.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.register_user_no_verif(email, password, custom_data=None, ignore_rate_limit=False)
email
(str
): User's email address.password
(str
): User's password.custom_data
(any
, optional): Additional user info to store. If None, defaults to an empty dictionary.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.register_user_no_pass(email, custom_data=None, cust_length=None, ignore_rate_limit=False)
email
(str
): User's email address.custom_data
(any
, optional): Additional user info to store. If None, defaults to an empty dictionary.cust_length
(int
, optional): Length of the verification code. If None, defaults to the module's code_length
setting.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.verify_user(email, code, ignore_rate_limit=False)
email
(str
): User's email address.code
(str
): Verification code sent to the user.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.authenticate_user(email, password, mfa=False, cust_length=None, ignore_rate_limit=False)
email
(str
): User's email address.password
(str
): User's password.mfa
(bool
, optional): If set to True
, it will send the user a numeric code to their email for multi-factor authentication. Defaults to False
.cust_length
(int
, optional): Length of the verification code for MFA. If None, defaults to the module's code_length
setting.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.verify_mfa_code(email, code, ignore_rate_limit=False)
email
(str
): User's email address.code
(str
): Numeric code sent to the user's email.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.email
(str
): User's email address.cust_length
(int
, optional): Length of the verification code. If None, defaults to the module's code_length
setting.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.reset_password_no_verif(email, old_password, new_password, ignore_rate_limit=False)
email
(str
): User's email address.old_password
(str
): User's current password.new_password
(str
): New password to set.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.verify_reset_code_and_reset_password(email, reset_code, new_password, ignore_rate_limit=False)
email
(str
): User's email address.reset_code
(str
): Code sent to the user's email.new_password
(str
): New password to set.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.change_email_no_verif(email, new_email, password, ignore_rate_limit=False)
email
(str
): User's current email address.new_email
(str
): New email address to set.password
(str
): User's password.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.verify_reset_code_and_change_email(email, reset_code, new_email, password=None, ignore_rate_limit=False)
email
(str
): User's current email address.reset_code
(str
): Reset code sent to the user's email.new_email
(str
): New email address to set.password
(str
, optional): User's password for additional verification.ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.When a user is blocked, they cannot log in or perform any actions that require authentication.
auth.delete_user(email, password, del_from_blocking=True, ignore_rate_limit=False)
del_from_blocking
is True
, also removes from the blocking database.email
(str
): User's email address.password
(str
): User's password.del_from_blocking
(bool
, optional): Also remove from blocking database (default: True).ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.auth.delete_user_with_verif(email, password, code, del_from_blocking=True, ignore_rate_limit=False)
del_from_blocking
is True
, also removes from the blocking database.email
(str
): User's email address.password
(str
): User's password.code
(str
): Verification code sent to the user's email.del_from_blocking
(bool
, optional): Also remove from blocking database (default: True).ignore_rate_limit
(bool
, optional): If set to True
, it will skip the rate limit checking and updating for this request. Defaults to False
.utils.block_user(email)
email
(str
): User's email address.utils.unblock_user(email)
email
(str
): User's email address.utils.is_blocked(email)
email
(str
): User's email address.utils.is_verified(email)
email
(str
): User's email address.utils.time_since_request(email)
email
(str
): User's email address.auth.is_rate_limited(email)
email
(str
): User's email address.auth.update_rate_limit(email)
email
(str
): User's email address.auth.check_and_update_rate_limit(email)
email
(str
): User's email address.Custom user data is a flexible field that can store any type of data. It is stored alongside the normal user data. Store all custom data in a dictionary format for more storage and to use the 2nd and 4th functions in the section below. If the method is meant to return data, it will do so in the following format:
{ "success": True/False, "message": "Custom user data if success OR error code if failure" }
utils.get_cust_usr_data(email)
email
(str
): User's email address.utils.get_some_cust_usr_data(email, field)
email
(str
): User's email address.field
(str
): Dictionary name to retrieve.utils.replace_usr_data(email, custom_data)
email
(str
): User's email address.custom_data
(any
): New custom data to store.utils.update_usr_data(email, field, custom_data)
email
(str
): User's email address.field
(str
): Dictionary name to update.custom_data
(any
): New value for the field.auth.del(self)
utils.del(self)
coredb.del(self)
The CoreDB module provides functions for managing the MongoDB database and its collections. It allows you to create, delete, and reset collections as needed. These functions have no return values, but they will raise exceptions if the operations fail. The necessary collections and database will be created automatically when any of the modules are initialized, so you do not need to call these functions unless you want to reset, delete, or re-create the collections or database.
IT IS RECOMMENDED TO RUN THESE FUNCTIONS IN A TRY EXCEPT BLOCK TO HANDLE ANY EXCEPTIONS. BE CAREFUL when using these functions, as they WILL delete data permanently.
coredb.remove_users_collection()
users
collection from the database.coredb.remove_blocked_collection()
blocked
collection from the database.coredb.remove_limit_collection()
limit
collection from the database.coredb.remove_all_collections()
coredb.create_users_collection()
users
collection in the database.coredb.create_blocked_collection()
blocked
collection in the database.coredb.create_limit_collection()
limit
collection in the database.coredb.create_all_collections()
users
, blocked
, limit
) in the database.coredb.reset_users_collection()
users
collection by deleting the collection and re-creating it.coredb.reset_blocked_collection()
blocked
collection by deleting the collection and re-creating it.coredb.reset_limit_collection()
limit
collection by deleting the collection and re-creating it.coredb.reset_all_collections()
users
, blocked
, limit
) by deleting and re-creating them.coredb.remove_db()
coredb.create_db()
coredb.reset_db()
It is still recommended to run these functions in a try except block to handle any exceptions. These functions dump MongoDB statistics and return the results.
coredb.user_count()
users
collection as int.coredb.db_data_size()
coredb.db_storage_size()
coredb.db_index_size()
coredb.db_raw_stats()
These codes are returned by the functions in the package if readable_errors
is set to False
.
Error codes starting with 2xx indicate success, while those starting with 4xx indicate errors.
3xx codes indicate user status checks. 5xx codes indicate authentication errors.
Numeric Code | User-Friendly Message |
---|---|
200 | Success |
201 | Verification email sent. |
202 | Authentication successful. |
203 | Password reset successful. |
204 | User deleted. |
205 | Custom user data field updated. |
206 | Custom user data changed. |
207 | User unblocked. |
300 | User verified. |
301 | User is not blocked. |
302 | User is not verified. |
400 | Error |
401 | User exceeded rate limits. |
402 | User already exists. |
403 | User is blocked. |
404 | User not found. |
410 | Failed to delete user. |
412 | Field not found. |
417 | Invalid code. |
419 | Failed to delete user. |
420 | User deleted but not from blocked database. |
421 | Failed to delete user from all databases. |
423 | User is not found in blocked database. |
500 | Invalid old password. |
501 | Invalid password. |
502 | Invalid credentials. |
503 | Invalid email format. |
GNU Affero General Public License v3
Lukbrew25
...and all future contributors!
FAQs
A user authentication and verification system using MongoDB.
We found that easy-mongodb-auth-handler demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Β It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.4 brings back bundling, improves dependency updates and telemetry, and makes the runtime more practical for real-world JavaScript projects.
Security News
CVEForecast.org uses machine learning to project a record-breaking surge in vulnerability disclosures in 2025.
Security News
Browserslist-rs now uses static data to reduce binary size by over 1MB, improving memory use and performance for Rust-based frontend tools.