Flask-Login


NameFlask-Login JSON
Version 0.6.3 PyPI version JSON
download
home_pagehttps://github.com/maxcountryman/flask-login
SummaryUser authentication and session management for Flask.
upload_time2023-10-30 14:53:21
maintainerMax Countryman
docs_urlhttps://pythonhosted.org/Flask-Login/
authorMatthew Frazier
requires_python>=3.7
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Flask-Login

![Tests](https://github.com/maxcountryman/flask-login/workflows/Tests/badge.svg)
[![coverage](https://coveralls.io/repos/maxcountryman/flask-login/badge.svg?branch=main&service=github)](https://coveralls.io/github/maxcountryman/flask-login?branch=main)
[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)

Flask-Login provides user session management for Flask. It handles the common
tasks of logging in, logging out, and remembering your users' sessions over
extended periods of time.

Flask-Login is not bound to any particular database system or permissions
model. The only requirement is that your user objects implement a few methods,
and that you provide a callback to the extension capable of loading users from
their ID.

## Installation

Install the extension with pip:

```sh
$ pip install flask-login
```

## Usage

Once installed, the Flask-Login is easy to use. Let's walk through setting up
a basic application. Also please note that this is a very basic guide: we will
be taking shortcuts here that you should never take in a real application.

To begin we'll set up a Flask app:

```python
import flask

app = flask.Flask(__name__)
app.secret_key = 'super secret string'  # Change this!
```

Flask-Login works via a login manager. To kick things off, we'll set up the
login manager by instantiating it and telling it about our Flask app:

```python
import flask_login

login_manager = flask_login.LoginManager()

login_manager.init_app(app)
```

To keep things simple we're going to use a dictionary to represent a database
of users. In a real application, this would be an actual persistence layer.
However it's important to point out this is a feature of Flask-Login: it
doesn't care how your data is stored so long as you tell it how to retrieve it!

```python
# Our mock database.
users = {'foo@bar.tld': {'password': 'secret'}}
```

We also need to tell Flask-Login how to load a user from a Flask request and
from its session. To do this we need to define our user object, a
`user_loader` callback, and a `request_loader` callback.

```python
class User(flask_login.UserMixin):
    pass


@login_manager.user_loader
def user_loader(email):
    if email not in users:
        return

    user = User()
    user.id = email
    return user


@login_manager.request_loader
def request_loader(request):
    email = request.form.get('email')
    if email not in users:
        return

    user = User()
    user.id = email
    return user
```

Now we're ready to define our views. We can start with a login view, which will
populate the session with authentication bits. After that we can define a view
that requires authentication.

```python
@app.route('/login', methods=['GET', 'POST'])
def login():
    if flask.request.method == 'GET':
        return '''
               <form action='login' method='POST'>
                <input type='text' name='email' id='email' placeholder='email'/>
                <input type='password' name='password' id='password' placeholder='password'/>
                <input type='submit' name='submit'/>
               </form>
               '''

    email = flask.request.form['email']
    if email in users and flask.request.form['password'] == users[email]['password']:
        user = User()
        user.id = email
        flask_login.login_user(user)
        return flask.redirect(flask.url_for('protected'))

    return 'Bad login'


@app.route('/protected')
@flask_login.login_required
def protected():
    return 'Logged in as: ' + flask_login.current_user.id
```

Finally we can define a view to clear the session and log users out:

```python
@app.route('/logout')
def logout():
    flask_login.logout_user()
    return 'Logged out'
```

We now have a basic working application that makes use of session-based
authentication. To round things off, we should provide a callback for login
failures:

```python
@login_manager.unauthorized_handler
def unauthorized_handler():
    return 'Unauthorized', 401
```

Documentation for Flask-Login is available on [ReadTheDocs](https://flask-login.readthedocs.io/en/latest/).
For complete understanding of available configuration, please refer to the [source code](https://github.com/maxcountryman/flask-login).


## Contributing

We welcome contributions! If you would like to hack on Flask-Login, please
follow these steps:

1. Fork this repository
2. Make your changes
3. Install the dev requirements with `pip install -r requirements/dev.txt`
4. Submit a pull request after running `tox` (ensure it does not error!)

Please give us adequate time to review your submission. Thanks!

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/maxcountryman/flask-login",
    "name": "Flask-Login",
    "maintainer": "Max Countryman",
    "docs_url": "https://pythonhosted.org/Flask-Login/",
    "requires_python": ">=3.7",
    "maintainer_email": "",
    "keywords": "",
    "author": "Matthew Frazier",
    "author_email": "leafstormrush@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/c3/6e/2f4e13e373bb49e68c02c51ceadd22d172715a06716f9299d9df01b6ddb2/Flask-Login-0.6.3.tar.gz",
    "platform": null,
    "description": "# Flask-Login\n\n![Tests](https://github.com/maxcountryman/flask-login/workflows/Tests/badge.svg)\n[![coverage](https://coveralls.io/repos/maxcountryman/flask-login/badge.svg?branch=main&service=github)](https://coveralls.io/github/maxcountryman/flask-login?branch=main)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)\n\nFlask-Login provides user session management for Flask. It handles the common\ntasks of logging in, logging out, and remembering your users' sessions over\nextended periods of time.\n\nFlask-Login is not bound to any particular database system or permissions\nmodel. The only requirement is that your user objects implement a few methods,\nand that you provide a callback to the extension capable of loading users from\ntheir ID.\n\n## Installation\n\nInstall the extension with pip:\n\n```sh\n$ pip install flask-login\n```\n\n## Usage\n\nOnce installed, the Flask-Login is easy to use. Let's walk through setting up\na basic application. Also please note that this is a very basic guide: we will\nbe taking shortcuts here that you should never take in a real application.\n\nTo begin we'll set up a Flask app:\n\n```python\nimport flask\n\napp = flask.Flask(__name__)\napp.secret_key = 'super secret string'  # Change this!\n```\n\nFlask-Login works via a login manager. To kick things off, we'll set up the\nlogin manager by instantiating it and telling it about our Flask app:\n\n```python\nimport flask_login\n\nlogin_manager = flask_login.LoginManager()\n\nlogin_manager.init_app(app)\n```\n\nTo keep things simple we're going to use a dictionary to represent a database\nof users. In a real application, this would be an actual persistence layer.\nHowever it's important to point out this is a feature of Flask-Login: it\ndoesn't care how your data is stored so long as you tell it how to retrieve it!\n\n```python\n# Our mock database.\nusers = {'foo@bar.tld': {'password': 'secret'}}\n```\n\nWe also need to tell Flask-Login how to load a user from a Flask request and\nfrom its session. To do this we need to define our user object, a\n`user_loader` callback, and a `request_loader` callback.\n\n```python\nclass User(flask_login.UserMixin):\n    pass\n\n\n@login_manager.user_loader\ndef user_loader(email):\n    if email not in users:\n        return\n\n    user = User()\n    user.id = email\n    return user\n\n\n@login_manager.request_loader\ndef request_loader(request):\n    email = request.form.get('email')\n    if email not in users:\n        return\n\n    user = User()\n    user.id = email\n    return user\n```\n\nNow we're ready to define our views. We can start with a login view, which will\npopulate the session with authentication bits. After that we can define a view\nthat requires authentication.\n\n```python\n@app.route('/login', methods=['GET', 'POST'])\ndef login():\n    if flask.request.method == 'GET':\n        return '''\n               <form action='login' method='POST'>\n                <input type='text' name='email' id='email' placeholder='email'/>\n                <input type='password' name='password' id='password' placeholder='password'/>\n                <input type='submit' name='submit'/>\n               </form>\n               '''\n\n    email = flask.request.form['email']\n    if email in users and flask.request.form['password'] == users[email]['password']:\n        user = User()\n        user.id = email\n        flask_login.login_user(user)\n        return flask.redirect(flask.url_for('protected'))\n\n    return 'Bad login'\n\n\n@app.route('/protected')\n@flask_login.login_required\ndef protected():\n    return 'Logged in as: ' + flask_login.current_user.id\n```\n\nFinally we can define a view to clear the session and log users out:\n\n```python\n@app.route('/logout')\ndef logout():\n    flask_login.logout_user()\n    return 'Logged out'\n```\n\nWe now have a basic working application that makes use of session-based\nauthentication. To round things off, we should provide a callback for login\nfailures:\n\n```python\n@login_manager.unauthorized_handler\ndef unauthorized_handler():\n    return 'Unauthorized', 401\n```\n\nDocumentation for Flask-Login is available on [ReadTheDocs](https://flask-login.readthedocs.io/en/latest/).\nFor complete understanding of available configuration, please refer to the [source code](https://github.com/maxcountryman/flask-login).\n\n\n## Contributing\n\nWe welcome contributions! If you would like to hack on Flask-Login, please\nfollow these steps:\n\n1. Fork this repository\n2. Make your changes\n3. Install the dev requirements with `pip install -r requirements/dev.txt`\n4. Submit a pull request after running `tox` (ensure it does not error!)\n\nPlease give us adequate time to review your submission. Thanks!\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "User authentication and session management for Flask.",
    "version": "0.6.3",
    "project_urls": {
        "Changes": "https://github.com/maxcountryman/flask-login/blob/main/CHANGES.md",
        "Documentation": "https://flask-login.readthedocs.io/",
        "Homepage": "https://github.com/maxcountryman/flask-login",
        "Issue Tracker": "https://github.com/maxcountryman/flask-login/issues",
        "Source Code": "https://github.com/maxcountryman/flask-login"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "59f567e9cc5c2036f58115f9fe0f00d203cf6780c3ff8ae0e705e7a9d9e8ff9e",
                "md5": "7a765091d853ee6284648f3a61bc6902",
                "sha256": "849b25b82a436bf830a054e74214074af59097171562ab10bfa999e6b78aae5d"
            },
            "downloads": -1,
            "filename": "Flask_Login-0.6.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "7a765091d853ee6284648f3a61bc6902",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 17303,
            "upload_time": "2023-10-30T14:53:19",
            "upload_time_iso_8601": "2023-10-30T14:53:19.636262Z",
            "url": "https://files.pythonhosted.org/packages/59/f5/67e9cc5c2036f58115f9fe0f00d203cf6780c3ff8ae0e705e7a9d9e8ff9e/Flask_Login-0.6.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "c36e2f4e13e373bb49e68c02c51ceadd22d172715a06716f9299d9df01b6ddb2",
                "md5": "689564b8b7f3782f0db382b7aa85bbc2",
                "sha256": "5e23d14a607ef12806c699590b89d0f0e0d67baeec599d75947bf9c147330333"
            },
            "downloads": -1,
            "filename": "Flask-Login-0.6.3.tar.gz",
            "has_sig": false,
            "md5_digest": "689564b8b7f3782f0db382b7aa85bbc2",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 48834,
            "upload_time": "2023-10-30T14:53:21",
            "upload_time_iso_8601": "2023-10-30T14:53:21.151690Z",
            "url": "https://files.pythonhosted.org/packages/c3/6e/2f4e13e373bb49e68c02c51ceadd22d172715a06716f9299d9df01b6ddb2/Flask-Login-0.6.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-10-30 14:53:21",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "maxcountryman",
    "github_project": "flask-login",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "flask-login"
}
        
Elapsed time: 0.29214s