UserController - applebiter/gnatwriter GitHub Wiki

User controller encapsulates user management functionality.

One could use Noveler to build a desktop application and never need to touch the UserController class, or one could build a multi-user application for the desktop or Web and then the methods herein might be useful.

By default, a system user (noveler) is created in the database when the database schema is created, during installation. Other users can be created, and an authentication system can be made using existing code. Authorization has not yet been implemented, for the most part. By default, every database call - whether a read or a write operation - requires or includes the current user's id, and every record in the database includes that information. In other words, there are no methods in any of the other controllers whereby a user might fetch any other user's records, by accident or otherwise, if Noveler's current user is set to the correct user each time. Sharing or administration/moderation will require further development, if that is desired. This controller needs to be protected and it will be up to the developer to decide how that should be accomplished.

create_user()

create_user(username: str, password: str, email: str) -> User

Takes a username, password, and email. Returns a new User.

register_user()

register_user(
    username: str, password: str, repassword: str, email: str,
    reemail: str
) -> User

Takes a username, password, and email value. The password and email must be submitted twice to ensure no typos on the user's part. The idea is that this will keep someone from being unable to actually log in because they accidentally typed something wrong.

activate_user()

activate_user(user_id: int) -> Type[User]

This method simply takes a User id and activates the User, and then returns the updated User. When a User is created using the register_user() method, the account is not yet activated. The idea here is that a self-registering user from the Web might be prevented from providing a bogus email address and still successfully logging onto the system. How this is implemented is up to the developer, but the standard has been to generate a code on the server side, and then send that code to the email address provided by the newly registered user. Also, a narrow window of time is usually allowed within which the user must open their email and click the link provided in it. The website should have an endpoint for this function, where a user can redeem their special code and have their account activated. PLEASE NOTE that none of that is implemented in this method.

deactivate_user()

deactivate_user(user_id: int) -> Type[User]

Takes a User id and deactivates the specified account. Returns the updated User.

login()

login(username: str, password: str) -> Type[User]

Takes a username and password and returns the associated User if the matching account is found and activated. This method raises an Exception if the User is not found, and a value error if either the password is invalid or the User account is not activated.

change_password()

change_password(user_id: int, old_password: str, new_password, repassword: str) -> User

Takes a User id, the user's current password, and the new password typed twice to ensure no typos are present.

delete_user()

delete_user(user_id: int) -> bool

Takes a User id and returns True if the User is successfully deleted. PLEASE NOTE that the User is the most complex object in the database because it contains all other object types within itself as subordinate objects. All records in all database tables associated with the User will be deleted. ALSO NOTE that this application generates JSON and plain text documents as files on the hard drive, but I haven't included any service to clean that up, yet. @TODO

get_user_by_id()

get_user_by_id(user_id: int) -> Type[User] | None

Takes a User id and returns the specified User if found, None otherwise.

get_user_by_uuid()

get_user_by_uuid(user_uuid: str) -> Type[User] | None

Takes a 36-character long UUID and returns the associated User if found, None otherwise.

get_user_by_username()

get_user_by_username(username: str) -> Type[User] | None

Takes a username and returns the matching User if found, None otherwise.

get_user_by_email()

get_user_by_email(email: str) -> Type[User] | None

Takes a user email and returns the matching User if found, None otherwise.

get_user_count()

get_user_count() -> int

Returns an integer describing how many Users are in the database.

get_all_users()

get_all_users() -> List[Type[User]]

Returns a list containing all Users in the database.

get_all_users_page()

get_all_users_page(page: int, per_page: int) -> List[Type[User]]

Takes a page number and an integer describing how many Users to return per page of results. Returns a list containing the specified page of Users.

search_users()

search_users(search: str) -> List[Type[User]]

Takes a search term and searches in username and email fields for matches. Returns a list containing all matching Users, if any.