docs: def includeme(config):
      """Include pyramid_multiauth into a pyramid configurator.
  
      This function provides a hook for pyramid to include the default settings
      for auth via pyramid_multiauth.  Activate it like so:
  
          config.include("pyramid_multiauth")
  
      This will pull the list of registered authn policies from the deployment
      settings, and configure and install each policy in order.  The policies to
      use can be specified in one of two ways:
  
          * as the name of a module to be included.
          * as the name of a callable along with a set of parameters.
  
      Here's an example suite of settings:
  
          multiauth.policies = ipauth1 ipauth2 pyramid_browserid
  
          multiauth.policy.ipauth1.use = pyramid_ipauth.IPAuthentictionPolicy
          multiauth.policy.ipauth1.ipaddrs = 123.123.0.0/16
          multiauth.policy.ipauth1.userid = local1
  
          multiauth.policy.ipauth2.use = pyramid_ipauth.IPAuthentictionPolicy
          multiauth.policy.ipauth2.ipaddrs = 124.124.0.0/16
          multiauth.policy.ipauth2.userid = local2
  
      This will configure a MultiAuthenticationPolicy with three policy objects.
      The first two will be IPAuthenticationPolicy objects created by passing
      in the specified keyword arguments.  The third will be a BrowserID
      authentication policy just like you would get from executing:
  
          config.include("pyramid_browserid")
  
      As a side-effect, the configuration will also get the additional views
      that pyramid_browserid sets up by default.
  
      The *group finder function* and the *authorization policy* are also read
      from configuration if specified:
  
          multiauth.authorization_policy = mypyramidapp.acl.Custom
          multiauth.groupfinder  = mypyramidapp.acl.groupfinder
      """
      # Grab the pyramid-wide settings, to look for any auth config.
      settings = config.get_settings()
      # Hook up a default AuthorizationPolicy.
      # Get the authorization policy from config if present.
      # Default ACLAuthorizationPolicy is usually what you want.
      authz_class = settings.get("multiauth.authorization_policy",
                                 "pyramid.authorization.ACLAuthorizationPolicy")
      authz_policy = config.maybe_dotted(authz_class)()
      # If the app configures one explicitly then this will get overridden.
      # In autocommit mode this needs to be done before setting the authn policy.
      config.set_authorization_policy(authz_policy)
      # Get the groupfinder from config if present.
      groupfinder = settings.get("multiauth.groupfinder", None)
      groupfinder = config.maybe_dotted(groupfinder)
      # Look for callable policy definitions.
      # Suck them all out at once and store them in a dict for later use.
      policy_definitions = get_policy_definitions(settings)
      # Read and process the list of policies to load.
      # We build up a list of callables which can be executed at config commit
      # time to obtain the final list of policies.
      # Yeah, it's complicated.  But we want to be able to inherit any default
      # views or other config added by the sub-policies when they're included.
      # Process policies in reverse order so that things at the front of the
      # list can override things at the back of the list.
      policy_factories = []
      policy_names = settings.get("multiauth.policies", "").split()
      for policy_name in reversed(policy_names):
          if policy_name in policy_definitions:
              # It's a policy defined using a callable.
              # Just append it straight to the list.
              definition = policy_definitions[policy_name]
              factory = config.maybe_dotted(definition.pop("use"))
              policy_factories.append((factory, policy_name, definition))
          else:
              # It's a module to be directly included.
              try:
                  factory = policy_factory_from_module(config, policy_name)
              except ImportError:
                  err = "pyramid_multiauth: policy %r has no settings "\
                        "and is not importable" % (policy_name,)
                  raise ValueError(err)
              policy_factories.append((factory, policy_name, {}))
      # OK.  We now have a list of callbacks which need to be called at
      # commit time, and will return the policies in reverse order.
      # Register a special action to pull them into our list of policies.
      policies = []
  
      def grab_policies():
          for factory, name, kwds in policy_factories:
              policy = factory(**kwds)
              if policy:
                  policy._pyramid_multiauth_name = name
                  if not policies or policy is not policies[0]:
                      # Remember, they're being processed in reverse order.
                      # So each new policy needs to go at the front.
                      policies.insert(0, policy)
  
      config.action(None, grab_policies, order=PHASE2_CONFIG)
      authn_policy = MultiAuthenticationPolicy(policies, groupfinder)
      config.set_authentication_policy(authn_policy)