repoze.what SQL source adapters

Overview

This document explains the SQL source adapters provided by the plugin.

The classes and functions mentioned below are imported into the repoze.what.plugins.sql namespace, so you can also import them from there.

SQL adapters

class repoze.what.plugins.sql.adapters.SqlGroupsAdapter(group_class, user_class, dbsession)

The SQL group source adapter.

To use this adapter, you must also define your users in a SQLAlchemy or Elixir-managed table with the relevant one-to-many (or many-to-many) relationship defined with group_class.

On the other hand, unless stated otherwise, it will also assume the following naming conventions in both classes; to replace any of those default values, you should use the translations dictionary of the relevant class accordingly:

• In group_class, the attribute that contains the group name is group_name (e.g., Group.group_name).
• In group_class, the attribute that contains the members of such a group is users (e.g., Group.users).
• In user_class, the attribute that contains the user’s name is user_name (e.g., User.user_name).
• In user_class, the attribute that contains the groups to which a user belongs is groups (e.g., User.groups).

Example #1, without special naming conventions:

# ...
from repoze.what.plugins.sql import SqlGroupsAdapter
from my_model import User, Group, DBSession

groups = SqlGroupsAdapter(Group, User, DBSession)

# ...

Example #2, with special naming conventions:

# ...
from repoze.what.plugins.sql import SqlGroupsAdapter
from my_model import Member, Team, DBSession

groups = SqlGroupsAdapter(Team, Member, DBSession)

# Replacing the default attributes, if necessary:

# We have "Team.team_name" instead of "Team.group_name":
groups.translations['section_name'] = 'team_name'
# We have "Team.members" instead of "Team.users":
groups.translations['items'] = 'members'
# We have "Member.username" instead of "Member.user_name":
groups.translations['item_name'] = 'username'
# We have "Member.teams" instead of "Member.groups":
groups.translations['sections'] = 'teams'

# ...

Changed in version 1.0.1: The groups to which a user belongs can be set dynamically by using a property called “groups” on user_class. The result must be a set made up of group_class_ instances. To use a different property name, you’d also need to set the translation for “sections” (see above).

__init__(group_class, user_class, dbsession)

Create an SQL groups source adapter.

Parameters:

• group_class – The class that manages the groups.
• user_class – The class that manages the users.
• dbsession – The SQLALchemy/Elixir session to be used.

class repoze.what.plugins.sql.adapters.SqlPermissionsAdapter(permission_class, group_class, dbsession)

The SQL permission source adapter.

To use this adapter, you must also define your groups in a SQLAlchemy or Elixir-managed table with the relevant one-to-many (or many-to-many) relationship defined with permission_class.

On the other hand, unless stated otherwise, it will also assume the following naming conventions in both classes; to replace any of those default values, you should use the translations dictionary of the relevant class accordingly:

• In permission_class, the attribute that contains the permission name is permission_name (e.g., Permission.permission_name).
• In permission_class, the attribute that contains the groups that are granted such a permission is groups (e.g., Permission.groups).
• In group_class, the attribute that contains the group name is group_name (e.g., Group.group_name).
• In group_class, the attribute that contains the permissions granted to that group is permissions (e.g., Group.permissions).

Example #1, without special naming conventions:

# ...
from repoze.what.plugins.sql import SqlPermissionsAdapter
from my_model import Group, Permission, DBSession

groups = SqlPermissionsAdapter(Permission, Group, DBSession)

# ...

Example #2, with special naming conventions:

# ...
from repoze.what.plugins.sql import SqlPermissionsAdapter
from my_model import Team, Permission, DBSession

permissions = SqlPermissionsAdapter(Permission, Team, DBSession)

# Replacing the default attributes, if necessary:

# We have "Permission.perm_name" instead of "Permission.permission_name":
permissions.translations['section_name'] = 'perm_name'
# We have "Permission.teams" instead of "Permission.groups":
permissions.translations['items'] = 'teams'
# We have "Team.team_name" instead of "Team.group_name":
permissions.translations['item_name'] = 'team_name'
# We have "Team.perms" instead of "Team.permissions":
permissions.translations['sections'] = 'perms'

# ...

Changed in version 1.0.1: The permissions granted to a group can be set dynamically by using a property called “permissions” on group_class. The result must be a set made up of permission_class_ instances. To use a different property name, you’d also need to set the translation for “sections” (see above).

__init__(permission_class, group_class, dbsession)

Create an SQL permissions source adapter.

Parameters:

• permission_class – The class that manages the permissions.
• group_class – The class that manages the groups.
• dbsession – The SQLALchemy/Elixir session to be used.

Utilities

repoze.what.plugins.sql.adapters.configure_sql_adapters(user_class, group_class, permission_class, session, group_translations={}, permission_translations={})

Configure and return group and permission adapters that share the same model.

Parameters:

• user_class – The class that manages the users.
• group_class – The class that manages the groups.
• user_class – The class that manages the permissions.
• dbsession – The SQLALchemy/Elixir session to be used.
• group_translations – The dictionary of translations for the group.
• permission_translations – The dictionary of translations for the permissions.

Returns:

The group and permission adapters, configured.

Return type:

dict

For this function to work, user_class and group_class must have the relevant one-to-many (or many-to-many) relationship; likewise, group_class and permission_class must have the relevant one-to-many (or many-to-many) relationship.

Example:

# ...
from repoze.what.plugins.sql import configure_sql_adapters
from my_model import User, Group, Permission, DBSession

adapters = configure_sql_adapters(User, Group, Permission, DBSession)
groups = adapters['group']
permissions = adapters['permission']

# ...