auth/__init__.py

"""
addons/source-python/_libs/auth/__init__.py

GENERAL INFO

This module is intended to be the glue between auth providers and auth
customers. This means it will turn specific authentification (auth provider
part) into a streamlined auth model (this api) so user-created scripts have a
common interface for querying access.

The corressponding discussion thread can be found here:
http://www.sourcepython.com/forums/showthread.php?46-Auth-API&p=254#post254

HOW PERMISSIONS/FLAGS/GROUPS ARE SUPPOSED TO WORK

Generally, permissions are all positive, as long the user gets access
somewhere from any auth provider, the permission is granted. The same
is true for groups and flags.

However, if any auth provider puts a deny permission on, the user will
have his permissions or group denied regardless whether anywhere else
this setting is granted.

ABOUT DEFAULTS

I define a few groups by default. Some of them behave in a special way:

root       - this flag and group equals 'all permissions'
admin      - just the default admin flag & group
restricted - all permissions / flags denied


API USAGE - AUTH PROVIDERS

TODO


API USAGE - AUTH CONSUMERS

TODO


API TODO:

Search for TODO -> minor changes
"""

# =============================================================================
# >> IMPORTS
# =============================================================================
# Python Imports

# =====================
# Source Python Imports

# =====================
# Auth imports
from auth.provider import _auth_providers
from auth.consumer import _cache

# =============================================================================
# >> INTERNAL (PRIVATE) CLASSES
# =============================================================================

class _Flags(dict):
    def __missing__(self, key):
        f = Flag(key)
        self[key] = f

        # By default this flag is also added to the deny everything group
        group['restricted'].dflags.append(f)

        return f

class _Groups(dict):
    def __missing__(self, key):
        self[key] = Group(key)
        return self[key]

class _Permissions(dict):
    def __missing__(self, key):
        p = Permission(key)
        self[key] = p

        # This permission is new, so it get's added automatically to the deny
        # everything group as well as the flag
        flag['restricted'].dpermissions.append(p)
        group['restricted'].dpermissions.append(p)

        return p

# =============================================================================
# >> EXTERNAL (PUBLIC) CLASSES
# =============================================================================

class Permission(object):
    """
    The Permission Class.

    The purpose of this class is to present an authenficication object for
    a single permission. It does not include any inherited information, only
    information specific to the permission.

    Attributes:
    name   - Name of the permission
    flags  - List of flag objects
    dflags - List of denied flag objects
    groups - List of groups
    """
    def __init__(self, name):
        self.name = name
        self.flags = []
        self.dflags = []
        self.groups = []


class Flag(object):
    """
    The Flag Class.

    The purpose of this class is to present an authenficication object for
    a single flag. It does not include any inherited information, only
    information specific to the flag.

    Attributes:
    name         - Name of the flags
    permissions  - List of permissions
    dpermissions - List of denied permissions
    """
    def __init__(self, name):
        self.name = name
        self.permissions = []
        self.dpermissions = []

class Group(object):
    """
    The Group Class.

    The purpsoe of this class is to present an authenficication object for
    a single group. It does not include any inherited information, only
    information specific to the group.

    Attributes:
    name         - Name of the permission
    flags        - List of flag objects
    dflags       - List of denied flag objects
    permissions  - List of permissions
    dpermissions - List of denied permissions
    immunity     - Immunity level granted by this group
    """
    def __init__(self, name):
        self.name = name
        self.flags = []
        self.dflags = []
        self.permissions = []
        self.dpermissions = []
        self.immunity = 100

class Player(object):
    """
    The Player Class.

    The purpsoe of this class is to present an authenficication object for
    a single player. It does not include any inherited information, only
    information specific to the player.

    Attributes:
    flags        - List of flag objects
    dflags       - List of denied flag objects
    permissions  - List of permissions
    dpermissions - List of denied permissions
    groups       - List of groups
    immunity     - Immunity level
    """
    def __init__(self):
        self.flags = []
        self.dflags = []
        self.permissions = []
        self.dpermissions = []
        self.groups = []
        self.immunity = 100


class PlayerCached(Player):
    """
    The PlayerCached Class.

    This class inherits from Player, as such, all the Player attributes are
    available. In addition, the following may be used:

    Attributes:
    cflags       - List of combined flags (denied flags removed)
    cpermissions - List of combined permissions (denied permissions removed)
    """
    def __init__(self):
        super(Player, self).__init__()
        # Combined flags & permissions
        self.cflags = []
        self.cpermissions = []

# =============================================================================
# >> FUNCTIONS
# =============================================================================

def Refresh():
    for auth_provider in _auth_providers:
        auth_provider.Refresh()
    _cache._Rebuild()

# =============================================================================
# >> INITIALIZE / STARTUP STUFF
# =============================================================================

flags = _Flags()
permissions = _Permissions()
groups = _Groups()

# Call these once so they get added (also in that order because of dependencies)
groups['restricted']
flags['restricted']
# Manually add the root flags
groups['admin'].flags.append(flags['admin'])
groups['root'].flags.append(flags['root'])