{"id":22336519,"url":"https://github.com/querateam/django-qsessions","last_synced_at":"2025-04-12T00:13:48.842Z","repository":{"id":43288477,"uuid":"118227377","full_name":"QueraTeam/django-qsessions","owner":"QueraTeam","description":"Extended session backends for Django (Sessions store IP, User Agent, and foreign key to User)","archived":false,"fork":false,"pushed_at":"2025-02-23T11:07:45.000Z","size":156,"stargazers_count":161,"open_issues_count":2,"forks_count":15,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-12T00:13:42.756Z","etag":null,"topics":["cache","django","python","session","session-management","sessions"],"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/QueraTeam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-20T09:09:56.000Z","updated_at":"2025-04-09T13:36:05.000Z","dependencies_parsed_at":"2022-08-12T10:21:55.128Z","dependency_job_id":"54e75903-9665-4b5b-9909-9a246b70057d","html_url":"https://github.com/QueraTeam/django-qsessions","commit_stats":{"total_commits":125,"total_committers":8,"mean_commits":15.625,"dds":"0.29600000000000004","last_synced_commit":"ecfd7327ebe32483746704b59fca72f05be07284"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QueraTeam%2Fdjango-qsessions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QueraTeam%2Fdjango-qsessions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QueraTeam%2Fdjango-qsessions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QueraTeam%2Fdjango-qsessions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QueraTeam","download_url":"https://codeload.github.com/QueraTeam/django-qsessions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248497820,"owners_count":21113984,"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":["cache","django","python","session","session-management","sessions"],"created_at":"2024-12-04T06:07:00.398Z","updated_at":"2025-04-12T00:13:48.787Z","avatar_url":"https://github.com/QueraTeam.png","language":"Python","readme":"# Django QSessions\n\n[![pypi](https://img.shields.io/pypi/v/django-qsessions.svg)](https://pypi.python.org/pypi/django-qsessions/)\n[![tests ci](https://github.com/QueraTeam/django-qsessions/workflows/tests/badge.svg)](https://github.com/QueraTeam/django-qsessions/actions)\n[![coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/quera-org/24a6d63ff9d29d9be5399169f8199ca0/raw/pytest-coverage__main.json)](https://github.com/QueraTeam/django-qsessions/actions)\n[![MIT](https://img.shields.io/github/license/QueraTeam/django-qsessions.svg)](https://github.com/QueraTeam/django-qsessions/blob/master/LICENSE.txt)\n[![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n**django-qsessions** offers two extended session backends for Django.\nThey extend Django's `db` and `cached_db` backends (and `Session` model)\nwith following extra features:\n\n- Sessions have a foreign key to User\n- Sessions store IP and User Agent\n\nThese features help you implement \"Session Management\" and show a list\nof active sessions to the user. You can display IP, location and user\nagent for each session and add an option to revoke sessions.\n\n## Comparison\n\nHere is a brief comparison between Django's session backends (db, cache,\ncached_db), and django-qsessions.\n\n\u003ctable\u003e\n  \u003cthead\u003e\n  \u003ctr\u003e\n    \u003cth rowspan=\"2\"\u003e\u003c/th\u003e\n    \u003cth colspan=\"3\"\u003edjango\u003c/th\u003e\n    \u003cth colspan=\"2\"\u003eqsessions\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003cth\u003ecache\u003c/th\u003e\n    \u003cth\u003edb\u003c/th\u003e\n    \u003cth\u003ecached_db\u003c/th\u003e\n    \u003cth\u003edb\u003c/th\u003e\n    \u003cth\u003ecached_db\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctd\u003ePerformance\u003c/td\u003e\n    \u003ctd\u003e✔✔\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003ePersistence\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eForeign Key to User\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eStore IP and User Agent\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n    \u003ctd\u003e✔\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n## Compatibility\n\n- Python: **3.9**, **3.10**, **3.11**, **3.12**, **3.13**\n- Django: **4.2**, **5.0**, **5.1**\n\n## Installation\n\nIf your system is in production and there are active sessions using\nanother session backend, you need to migrate them manually. We have no\nmigration script.\n\n1.  If you want to use the `cached_db` backend, make sure you've\n    [configured your\n    cache](https://docs.djangoproject.com/en/dev/topics/cache/). If you\n    have multiple caches defined in `CACHES`, Django will use the\n    default cache. To use another cache, set `SESSION_CACHE_ALIAS` to\n    the name of that cache.\n\n2.  Install the latest version from PyPI:\n\n    ```sh\n    pip install django-qsessions\n    ```\n\n3.  In settings:\n\n    - In `INSTALLED_APPS` replace `'django.contrib.sessions'` with\n      `'qsessions'`.\n    - In `MIDDLEWARE` or `MIDDLEWARE_CLASSES` replace\n      `'django.contrib.sessions.middleware.SessionMiddleware'` with\n      `'qsessions.middleware.SessionMiddleware'`.\n    - Set `SESSION_ENGINE` to:\n      - `'qsessions.backends.cached_db'` if you want to use\n        `cached_db` backend.\n      - `'qsessions.backends.db'` if you want to use `db` backend.\n\n4.  Run migrations to create `qsessions.models.Session` model.\n\n    ```sh\n    python manage.py migrate qsessions\n    ```\n\nTo enable location detection using GeoIP2 (optional):\n\n5.  Install `geoip2` package:\n\n    ```sh\n    pip install geoip2\n    ```\n\n6.  Set `GEOIP_PATH` to a directory for storing GeoIP2 database.\n\n7.  Run the following command to download latest GeoIP2 database. You\n    can add this command to a cron job to update GeoIP2 DB\n    automatically. Due to [Maxmind license\n    changes](https://blog.maxmind.com/2019/12/18/significant-changes-to-accessing-and-using-geolite2-databases/)\n    you will need to acquire and use a license key for downloading the\n    databases. You can pass the key on the command line, or in the\n    `MAXMIND_LICENSE_KEY` environment variable.\n\n    ```sh\n    python manage.py download_geoip_db -k mykey\n    ```\n\n## Usage\n\ndjango-qsessions has a custom `Session` model with following extra\nfields: `user`, `user_agent`, `created_at`, `updated_at`, `ip`.\n\nGet a user's sessions:\n\n```python\nuser.session_set.filter(expire_date__gt=timezone.now())\n```\n\nDelete a session:\n\n```python\n# Deletes the session from both the database and the cache.\nsession.delete()\n```\n\nLogout a user:\n\n```python\nuser.session_set.all().delete()\n```\n\nGet session creation time (user login time):\n\n```python\n\u003e\u003e\u003e session.created_at\ndatetime.datetime(2018, 6, 12, 17, 9, 17, 443909, tzinfo=\u003cUTC\u003e)\n```\n\nGet IP and user agent:\n\n```python\n\u003e\u003e\u003e session.ip\n'127.0.0.1'\n\u003e\u003e\u003e session.user_agent\n'Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Mobile Safari/537.36'\n```\n\nGet user device (parsed user-agent string):\n\n```python\n\u003e\u003e\u003e session.device\n'K / Android 10 / Chrome Mobile 118.0.0.0'\n\u003e\u003e\u003e session.device_info.device\nDevice(family='K', brand='Generic_Android', model='K')\n\u003e\u003e\u003e session.device_info.os\nOS(family='Android', major='10', minor=None, patch=None, patch_minor=None)\n\u003e\u003e\u003e session.device_info.user_agent\nUserAgent(family='Chrome Mobile', major='118', minor='0', patch='0', patch_minor='0')\n```\n\n\nAnd if you have configured GeoIP2,\nyou can get location info using `.location` and `.location_info`:\n\n```python\n\u003e\u003e\u003e session.location\n'Tehran, Iran'\n\n\u003e\u003e\u003e session.location_info\n{'city': 'Tehran', 'continent_code': 'AS', 'continent_name': 'Asia', 'country_code': 'IR', 'country_name': 'Iran', 'time_zone': 'Asia/Tehran', ...}\n```\n\nAdmin page:\n\n![image](https://user-images.githubusercontent.com/2115303/41525284-b0b258b0-72f5-11e8-87f1-8770e0094f4c.png)\n\n### Caveats\n\n- `session.updated_at` is not the session's exact last activity. It's\n  updated each time the session object is saved in DB. (e.g. when user\n  logs in, or when ip, user agent, or session data changes)\n- The IP address is directly read from `request.META[\"REMOTE_ADDR\"]`.\n  If you are using a reverse proxy,\n  you should configure it\n  to pass the real IP address in the `REMOTE_ADDR` header.\n  You can also write a custom middleware\n  to set `REMOTE_ADDR` from the value of other headers\n  (`X-Forwarded-For`, `X-Real-IP`, ...)\n  in a safe way suitable for your environment.\n  More info: [Why Django removed SetRemoteAddrFromForwardedFor](https://docs.djangoproject.com/en/5.2/releases/1.1/#removed-setremoteaddrfromforwardedfor-middleware).\n\n## Development\n\n- Create and activate a python virtualenv.\n- Install development dependencies in your virtualenv with `pip install -e '.[dev]'`\n- Install pre-commit hooks with `pre-commit install`\n- Run tests with coverage:\n  - `py.test --cov`\n\n## TODO\n\n- Write better documentation.\n  - Explain how it works (in summary)\n  - Add more details to existing documentation.\n- Write more tests\n- Performance benchmark (and compare with Django's `cached_db`)\n\nContributions are welcome!\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquerateam%2Fdjango-qsessions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquerateam%2Fdjango-qsessions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquerateam%2Fdjango-qsessions/lists"}