<commit_before>[pyramid_simpleauth][] is a package that implements session based authentication
and role based security for a [Pyramid][] web application.

There are many other auth implementations for Pyramid, including [apex][] and 
[pyramid_signup][] and you can, of course, easily roll your own, for example
following the excellent [pyramid_auth_demo][].  This package aims to be:

* relatively simple, targeting a limited set of features
* extensible, with event hooks and overrideable templates
* performant, with, by default, one sql query per authenticated request

# Usage

Include the package (e.g. in your main application factory) along with a session
factory, `pyramid_tm` and `pyramid_basemodel` in the configuration portion of
your Pyramid app:

    # Configure a session factory, here, we're using `pyramid_beaker`.
    config.include('pyramid_beaker')
    config.set_session_factory(session_factory_from_settings(settings))
    
    # Either include `pyramid_tm` or deal with commiting transactions yourself.
    config.include('pyramid_tm')
    
    # Either include `pyramid_basemodel` and provide an `sqlalchemy.url` in your
    # `.ini` settings, or bind the SQLAlchemy models and scoped `Session` to a
    # database engine yourself.
    config.include('pyramid_basemodel')
    
    # Include the package.
    config.include('pyramid_simpleauth')

Once that's done, the package locks down your application, exposes views at:

* /auth/signup
* /auth/login
* /auth/authenticate (login via AJAX)
* /auth/logout

Adds a `user` property to the current `request`:

    # e.g.: in a view callable
    if request.is_authenticated:
        display = request.user.username

And provides `UserSignedUp`, `UserloggedIn` and `UserLoggedOut` events:

    @subscriber(UserSignedUp)
    def my_event_handler(event):
        request = event.request
        user = event.user
        # e.g.: send confirmation email

# Templates

The signup and login forms inherit from a base layout template.  You can override
this base layout template by writing your own, e.g.:

    # my_package:my_templates/layout.mako
    <!DOCTYPE HTML>
    <html>
      <head>
        <title>${self.subtitle()}</title>
        <link href="my_great.css" rel="stylesheet" type="text/css" />
      </head>
      <body>
        <div class="my-great-markup">
          ${next.body()}
        </duv>
      </body>
    </html>
    
Then in your main app factory / package configuration use, e.g.:

    config.override_asset(to_override='pyramid_simpleauth:templates/layout.mako',
                          override_with='my_package:my_templates/layout.mako')

Or you can override the signup and login templates individually, e.g.:

    config.override_asset(to_override='pyramid_simpleauth:templates/signup.mako',
                          override_with='my_package:my_templates/foo.mako')
    config.override_asset(to_override='pyramid_simpleauth:templates/login.mako',
                          override_with='my_package:my_templates/bar.mako')

# Settings

To change the url path for the authentication views, specify a 
`simpleauth.url_prefix` in your application's `.ini` configuration:

    # defaults to 'auth', resulting in urls that start with `/auth/...`
    simpleauth.url_prefix = 'another'

You can also specify where to redirect to after signup, login and logout.  
These are all configured using *route names*, with the route being provided
the additional traversal information of the user's username.  (This means you
can expose a simple named route, or a hybrid route, as you prefer.  The hybrid
route will attempt traversal on the username.).

To redirect to a different named route after signup / login or logout use:

    simpleauth.after_signup_route = 'another' # defaults to 'users'
    simpleauth.after_login_route = 'another' # defaults to 'index'
    simpleauth.after_logout_route = 'another' # defaults to 'index'

Note that on login, a `next` parameter passed to the login page will take
precedence over the specific route.

By default the app redirects after signup to a route named 'users'.  This is
not exposed by `pyramid_simpleauth` by default but the package does provide a 
`.tree.UserRoot` root factory that looks up `.model.User`s by username and a
default `__acl__` property on the `.model.User` class.  These are entirely
optional: you can choose instead to use a different named route, or expose
a simple named route using, e.g.:

    config.add_route('users', 'some/path')

However, if you want to use the machinery provided, with the baked in security<commit_msg>docs: tried to make the README clearer.<commit_after>[pyramid_simpleauth][] is a package that implements session based authentication
and role based security for a [Pyramid][] web application.

There are many other auth implementations for Pyramid, including [apex][] and 
[pyramid_signup][] and you can, of course, easily roll your own, for example
following the excellent [pyramid_auth_demo][].  This package aims to be:

* relatively simple: with a limited feature set
* extensible: with event hooks and overrideable templates
* performant: minimising db queries

# Features

If you install the package and include it in your Pyramid application, it will
lock down your application and expose views at:

* /auth/signup
* /auth/login
* /auth/authenticate (login via AJAX)
* /auth/logout

You get a `user` instance and an `is_authenticated` flag added to the `request`:

    # e.g.: in a view callable
    if request.is_authenticated:
        display = request.user.username

Plus `UserSignedUp`, `UserloggedIn` and `UserLoggedOut` events to subscribe to:

    @subscriber(UserSignedUp)
    def my_event_handler(event):
        request = event.request
        user = event.user
        # e.g.: send confirmation email

# Install

Install using `pip` or `easy_install`, e.g.:

    pip install pyramid_simpleauth

# Configure

Include the package along with a session factory, `pyramid_tm` and `pyramid_basemodel`
in the configuration portion of your Pyramid app:

    # Configure a session factory, here, we're using `pyramid_beaker`.
    config.include('pyramid_beaker')
    config.set_session_factory(session_factory_from_settings(settings))
    
    # Either include `pyramid_tm` or deal with committing transactions yourself.
    config.include('pyramid_tm')
    
    # Either include `pyramid_basemodel` and provide an `sqlalchemy.url` in your
    # `.ini` settings, or bind the SQLAlchemy models and scoped `Session` to a
    # database engine yourself.
    config.include('pyramid_basemodel')
    
    # Include the package.
    config.include('pyramid_simpleauth')

The signup and login forms inherit from a base layout template.  You can override
this base layout template by writing your own, e.g.:

    # my_package:my_templates/layout.mako
    <!DOCTYPE HTML>
    <html>
      <head>
        <title>${self.subtitle()}</title>
        <link href="my_great.css" rel="stylesheet" type="text/css" />
      </head>
      <body>
        <div class="my-great-markup">
          ${next.body()}
        </duv>
      </body>
    </html>
    
Then in your main app factory / package configuration use, e.g.:

    config.override_asset(to_override='pyramid_simpleauth:templates/layout.mako',
                          override_with='my_package:my_templates/layout.mako')

Or you can nuke the signup and login templates directly, e.g.:

    config.override_asset(to_override='pyramid_simpleauth:templates/signup.mako',
                          override_with='my_package:my_templates/foo.mako')
    config.override_asset(to_override='pyramid_simpleauth:templates/login.mako',
                          override_with='my_package:my_templates/bar.mako')

To change the url path for the authentication views, specify a 
`simpleauth.url_prefix` in your application's `.ini` configuration:

    # defaults to 'auth', resulting in urls that start with `/auth/...`
    simpleauth.url_prefix = 'another'

You can also specify where to redirect to after signup, login and logout. These
are all configured using *route names*, with the route being provided the 
additional traversal information of the user's username.  (This means you can 
expose a simple named route, or a hybrid route, as you prefer.  The hybrid route
will attempt traversal on the username).

To redirect to a different named route after signup / login or logout use:

    simpleauth.after_signup_route = 'another' # defaults to 'users'
    simpleauth.after_login_route = 'another' # defaults to 'index'
    simpleauth.after_logout_route = 'another' # defaults to 'index'

Note that on login, a `next` parameter passed to the login page will take
precedence over the specific route.

By default the app redirects after signup to a route named 'users'.  This is
not exposed by `pyramid_simpleauth` by default but the package does provide a 
`.tree.UserRoot` root factory that looks up `.model.User`s by username and a
default `__acl__` property on the `.model.User` class.  These are entirely
optional: you can choose instead to use a different named route, or expose
a simple named route using, e.g.:

    config.add_route('users', 'some/path')

However, if you want to use the machinery provided, with the baked in security
{'fraction_non_alphanumeric': 0.08346830795810388, 'fraction_numerical': 0.0, 'mean_word_length': 3.725510204081633, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4057746', 'n_tokens_mistral': 2706, 'n_tokens_neox': 2620, 'n_words': 998}