{"id":19090153,"url":"https://github.com/destrangis/pgusers","last_synced_at":"2026-03-04T01:11:58.845Z","repository":{"id":56899660,"uuid":"478329167","full_name":"destrangis/pgusers","owner":"destrangis","description":"User authentication and session management based on PostgreSQL","archived":false,"fork":false,"pushed_at":"2024-07-07T20:55:16.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-09T21:36:07.924Z","etag":null,"topics":["authentication","database","postgresql","python","session","session-management"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/destrangis.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-05T23:09:46.000Z","updated_at":"2024-07-07T20:55:19.000Z","dependencies_parsed_at":"2022-08-21T01:50:31.350Z","dependency_job_id":null,"html_url":"https://github.com/destrangis/pgusers","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/destrangis%2Fpgusers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/destrangis%2Fpgusers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/destrangis%2Fpgusers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/destrangis%2Fpgusers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/destrangis","download_url":"https://codeload.github.com/destrangis/pgusers/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240952857,"owners_count":19884017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","database","postgresql","python","session","session-management"],"created_at":"2024-11-09T03:02:18.224Z","updated_at":"2026-03-04T01:11:58.833Z","avatar_url":"https://github.com/destrangis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"=======\npgusers\n=======\n\nUser authentication and session management based on PostgreSQL\n\nInstallation\n------------\n\nJust download it from PYPI using pip::\n\n    pip install pgusers\n\nUsage\n-----\n\n``UserSpace(**kwargs)``\n~~~~~~~~~~~~~~~~~~~~~~~\nInitialises the UserSpace, creating a database connection if it doesn't exist. The arguments in ``kwargs``\ncan be any of the `arguments for a PostgreSQL connection`_, some of the most common are the following:\n\n.. _arguments for a PostgreSQL connection: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS\n\n+------------+-------------------+--------------------------------------------------------------+\n| Parameter  | Env Variable      | Meaning                                                      |\n+============+===================+==============================================================+\n| dbname     | PGUSERS_USERSPACE | The userspace name, i.e. database containing the userspace   |\n+------------+-------------------+--------------------------------------------------------------+\n| user       | PGUSERS_ADMIN     | The admin user for the userspace                             |\n+------------+-------------------+--------------------------------------------------------------+\n| password   | PGUSERS_PASSWORD  | The password for the admin user                              |\n+------------+-------------------+--------------------------------------------------------------+\n| host       | PGUSERS_HOST      | The hostname (PostgreSQL server) where the userspace resides |\n+------------+-------------------+--------------------------------------------------------------+\n| port       | PGUSERS_PORT      | The PorstgreSQL server port if not the usual 5432            |\n+------------+-------------------+--------------------------------------------------------------+\n\nFor any of the above parameters, the corresponding environment variable can be specified in its place.\n\nIn addition to the above environment variables, PGUSERS_CONNECTION_STRING can be defined as well, with the format\nspecified in `PostgreSQL Connection Strings`_.\n\n.. _PostgreSQL Connection Strings: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING\n\n.. important::\n   When initialising a UserSpace object either `dbname` must be specified in `kwargs`, or the `PGUSERS_USERSPACE`\n   environment variable must be set, even if already specified in the connection string.\n\nThe parameters specified in `kwargs` take precedence over the Environment Variables, which, in turn,\ntake precedence over parameters in the Connection String.\n\nRepeated connections to the same userspace return the same object.\n\nThe following are the methods available to ``UserSpace`` instances.\n\n``create_user(self, username, password, email, admin=False, extra_data=None)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nCreates a new user. Returns a numeric userid for the user created.\n\n:username:\n  The username to be created, if there is already a record with that username, a ``BadCallError`` exception is raised.\n:password:\n  The user's password in cleartext.\n:email:\n  Email for notifications or password recovery. ``BadCallError`` is raised if the email exists in the database.\n:admin:\n  A boolean value indicating whether the user is an administrator.\n:extra_data:\n  Any data that will be attached to the record. This can be anything that can be serialised using the ``pickle``  module from the standard library.\n\n\n``validate_user(self, username, password, extra_data=None)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nValidates (or logs in) a user. Returns a tuple with a string\ncontaining a session key, a boolean value indicating whether the user is\nan admin, and the numeric userid. If the user was not found, the returned\ntuple would be ``(\"\", False, None)``\n\n:username:\n  The username to be authenticated.\n:password:\n  The password in clear text.\n:extra_data:\n  Optional data that will be attached to the session. This can be anything that can be serialised using the ``pickle`` module from the standard library.\n\n\n``delete_user(self, username=None, userid=None)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nDelete a user given either its username or userid. Either username or userid\nmust be specified. Returns ``OK`` if deleted, ``NOT_FOUND`` if not found.\n\n:username:\n    The username.\n:userid:\n  The numeric userid.\n\n``change_password(self, userid, newpassword, oldpassword=None)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nChange a user's password. Returns either ``OK``, ``NOT_FOUND`` or ``REJECTED``\nThrows BadCallError if neither username or userid are specified.\n\n:userid:\n  The numeric user id, as returned by ``create_user()``\n:newpassword:\n  The new password, in cleartext.\n:oldpassword:\n  The current password, in cleartext. If specified, oldpassword is checked against the current password and the call will fail if they don't match. If ``oldpassword`` is not specified, the password will be changed unconditionally.\n\n``check_key(self, key)``\n~~~~~~~~~~~~~~~~~~~~~~~~\nReset the session timeout. Resets the key's Time To Live to the default value.\nReturns a tuple of the form *(rc, username, userid, extra_data)* where rc\ncan be either ``OK``, ``NOT_FOUND`` or ``EXPIRED``. If ``NOT_FOUND`` or ``EXPIRED``, username\nand userid will be ``None``.\n\n:key:\n  The session key as returned by ``validate_user()``\n\n``set_session_TTL(self, secs)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nSets the TTL for all sessions. All new sessions or checked sessions will\nbe set to this new TTL value.\n\n:secs:\n  The number of seconds of Time To Live. The default TTL for a session is currently 864000 seconds, or 10 days. This might change in future releases.\n\n\n``find_user(self, username=None, email=None, userid=None)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nFind a user given either its username, its email or its userid. At least\none of those must be supplied.\n\nThis method\ndoes not validate the user or any session. It is used to retrieve information\nabout a user in the database.\n\nReturns a dictionary with fields ``userid``, ``username``, ``email``, ``admin``,\nand ``extra_data``. ``None`` if the user was not found.\n\n:username:\n  The username.\n:email:\n  The email.\n:userid:\n  The numeric userid.\n\n``modify_user(self, userid, username=None, email=None, extra_data=None)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nModify user data. Returns ``OK`` if successful ``NOT_FOUND`` if not.\n\n:userid:\n  The user id as returned by ``create_user()``\n:username:\n  The new username to change, if specified.\n:email:\n  The new email to change, if specified.\n:extra_data:\n  The new extra_data to change, if specified.\n\n``is_admin(self, userid)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~\nChecks whether the user is admin. Returns ``True`` if it is, ``False`` if not.\n\n:userid:\n  The user id as returned by ``create_user()``\n\n``set_admin(self, userid, admin=True)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nGrant or revoke admin privileges to the user. To revoke, call with admin set to ``False``\n\n:userid:\n  The user id as returned by ``create_user()``\n:admin:\n  If set to ``True`` or not specified, mark the user as administrator. If set to ``False``, revokes administrator rights.\n\n``all_users(self)``\n~~~~~~~~~~~~~~~~~~~\nGenerator yielding (userid, username, email, admin) tuples for all users\nin the userspace.\n\n``list_sessions(self, uid, expired=False)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nGenerator yielding all sessions for a user or for all users (i.e. all sessions) if uid is 0. If\nexpired is set to ``True``, yield only the sessions that have expired.\nYields tuples of the form ``(username, key, expiration)``\n\n:userid:\n  The user id as returned by ``create_user()``, or 0 to return all sessions.\n:expired:\n  Boolean indicating whether the method should only return expired sessions.\n\n``kill_sessions(self, uid, expired=False)``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nKill the sessions for a user or for all users (i.e. all sessions) if uid is 0. If\nexpired is set to ``True``, kill only the sessions that have expired. *Killing* a\nsession removes it from the database, efectively invalidating it.\n\n\n:userid:\n  The user id as returned by ``create_user()``, or 0 to kill all sessions.\n:expired:\n  Boolean indicating whether the method should only kill the expired sessions.\n\nLicense\n-------\nThis software is licensed under the terms of the **MIT license**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdestrangis%2Fpgusers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdestrangis%2Fpgusers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdestrangis%2Fpgusers/lists"}