evennia.locks.lockfuncs

This module provides a set of permission lock functions for use with Evennia’s permissions system.

To call these locks, make sure this module is included in the settings tuple PERMISSION_FUNC_MODULES then define a lock on the form ‘<access_type>:func(args)’ and add it to the object’s lockhandler. Run the access() method of the handler to execute the lock check.

Note that accessing_obj and accessed_obj can be any object type with a lock variable/field, so be careful to not expect a certain object type.

Appendix: MUX locks

Below is a list nicked from the MUX help file on the locks available in standard MUX. Most of these are not relevant to core Evennia since locks in Evennia are considerably more flexible and can be implemented on an individual command/typeclass basis rather than as globally available like the MUX ones. So many of these are not available in basic Evennia, but could all be implemented easily if needed for the individual game.

MUX Name: Affects: Effect:

DefaultLock: Exits: controls who may traverse the exit to

its destination.

Evennia: “traverse:<lockfunc()>”

Rooms: controls whether the account sees the

SUCC or FAIL message for the room following the room description when looking at the room.

Evennia: Custom typeclass

Accounts/Things: controls who may GET the object.

Evennia: “get:<lockfunc()”

EnterLock: Accounts/Things: controls who may ENTER the object

Evennia:

GetFromLock: All but Exits: controls who may gets things from a

given location.

Evennia:

GiveLock: Accounts/Things: controls who may give the object.

Evennia:

LeaveLock: Accounts/Things: controls who may LEAVE the object.

Evennia:

LinkLock: All but Exits: controls who may link to the location

if the location is LINK_OK (for linking exits or setting drop-tos) or ABODE (for setting homes)

Evennia:

MailLock: Accounts: controls who may @mail the account.

Evennia:

OpenLock: All but Exits: controls who may open an exit.

Evennia:

PageLock: Accounts: controls who may page the account.

Evennia: “send:<lockfunc()>”

ParentLock: All: controls who may make @parent links to

the object.

Evennia: Typeclasses and

“puppet:<lockstring()>”

ReceiveLock: Accounts/Things: controls who may give things to the

object.

Evennia:

SpeechLock: All but Exits: controls who may speak in that location

Evennia:

TeloutLock: All but Exits: controls who may teleport out of the

location.

Evennia:

TportLock: Rooms/Things: controls who may teleport there

Evennia:

UseLock: All but Exits: controls who may USE the object, GIVE

the object money and have the PAY attributes run, have their messages heard and possibly acted on by LISTEN and AxHEAR, and invoke $-commands stored on the object.

Evennia: Commands and Cmdsets.

DropLock: All but rooms: controls who may drop that object.

Evennia:

VisibleLock: All: Controls object visibility when the

object is not dark and the looker passes the lock. In DARK locations, the object must also be set LIGHT and the viewer must pass the VisibleLock.

Evennia: Room typeclass with

Dark/light script

evennia.locks.lockfuncs.true(*args, **kwargs)

Always returns True.

evennia.locks.lockfuncs.all(*args, **kwargs)

evennia.locks.lockfuncs.false(*args, **kwargs)

Always returns False

evennia.locks.lockfuncs.none(*args, **kwargs)

evennia.locks.lockfuncs.self(accessing_obj, accessed_obj, *args, **kwargs)

Check if accessing_obj is the same as accessed_obj

Usage:

self()

This can be used to lock specifically only to the same object that the lock is defined on.

evennia.locks.lockfuncs.perm(accessing_obj, accessed_obj, *args, **kwargs)

The basic permission-checker. Ignores case.

Usage:

perm(<permission>)

where <permission> is the permission accessing_obj must have in order to pass the lock.

If the given permission is part of settings.PERMISSION_HIERARCHY, permission is also granted to all ranks higher up in the hierarchy.

If accessing_object is an Object controlled by an Account, the permissions of the Account is used unless the Attribute _quell is set to True on the Object. In this case however, the LOWEST hieararcy-permission of the Account/Object-pair will be used (this is order to avoid Accounts potentially escalating their own permissions by use of a higher-level Object)

evennia.locks.lockfuncs.perm_above(accessing_obj, accessed_obj, *args, **kwargs)

Only allow objects with a permission higher in the permission hierarchy than the one given. If there is no such higher rank, it’s assumed we refer to superuser. If no hierarchy is defined, this function has no meaning and returns False.

evennia.locks.lockfuncs.pperm(accessing_obj, accessed_obj, *args, **kwargs)

The basic permission-checker only for Account objects. Ignores case.

Usage:

pperm(<permission>)

where <permission> is the permission accessing_obj must have in order to pass the lock. If the given permission is part of _PERMISSION_HIERARCHY, permission is also granted to all ranks higher up in the hierarchy.

evennia.locks.lockfuncs.pperm_above(accessing_obj, accessed_obj, *args, **kwargs)

Only allow Account objects with a permission higher in the permission hierarchy than the one given. If there is no such higher rank, it’s assumed we refer to superuser. If no hierarchy is defined, this function has no meaning and returns False.

evennia.locks.lockfuncs.dbref(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

dbref(3)

This lock type checks if the checking object has a particular dbref. Note that this only works for checking objects that are stored in the database (e.g. not for commands)

evennia.locks.lockfuncs.pdbref(accessing_obj, accessed_obj, *args, **kwargs)

Same as dbref, but making sure accessing_obj is an account.

evennia.locks.lockfuncs.id(accessing_obj, accessed_obj, *args, **kwargs)

Alias to dbref

evennia.locks.lockfuncs.pid(accessing_obj, accessed_obj, *args, **kwargs)

Alias to dbref, for Accounts

evennia.locks.lockfuncs.attr(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

attr(attrname) attr(attrname, value) attr(attrname, value, compare=type)

where compare’s type is one of (eq,gt,lt,ge,le,ne) and signifies how the value should be compared with one on accessing_obj (so compare=gt means the accessing_obj must have a value greater than the one given).

Searches attributes and properties stored on the accessing_obj. if accessing_obj has a property “obj”, then this is used as accessing_obj (this makes this usable for Commands too)

The first form works like a flag - if the attribute/property exists on the object, the value is checked for True/False. The second form also requires that the value of the attribute/property matches. Note that all retrieved values will be converted to strings before doing the comparison.

evennia.locks.lockfuncs.objattr(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

objattr(attrname) objattr(attrname, value) objattr(attrname, value, compare=type)

Works like attr, except it looks for an attribute on accessed_obj instead.

evennia.locks.lockfuncs.locattr(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

locattr(attrname) locattr(attrname, value) locattr(attrname, value, compare=type)

Works like attr, except it looks for an attribute on accessing_obj.location, if such an entity exists.

if accessing_obj has a property “.obj” (such as is the case for a Command), then accessing_obj.obj.location is used instead.

evennia.locks.lockfuncs.objlocattr(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

locattr(attrname) locattr(attrname, value) locattr(attrname, value, compare=type)

Works like attr, except it looks for an attribute on accessed_obj.location, if such an entity exists.

if accessed_obj has a property “.obj” (such as is the case for a Command), then accessing_obj.obj.location is used instead.

evennia.locks.lockfuncs.attr_eq(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

attr_gt(attrname, 54)

evennia.locks.lockfuncs.attr_gt(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

attr_gt(attrname, 54)

Only true if access_obj’s attribute > the value given.

evennia.locks.lockfuncs.attr_ge(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

attr_gt(attrname, 54)

Only true if access_obj’s attribute >= the value given.

evennia.locks.lockfuncs.attr_lt(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

attr_gt(attrname, 54)

Only true if access_obj’s attribute < the value given.

evennia.locks.lockfuncs.attr_le(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

attr_gt(attrname, 54)

Only true if access_obj’s attribute <= the value given.

evennia.locks.lockfuncs.attr_ne(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

attr_gt(attrname, 54)

Only true if access_obj’s attribute != the value given.

evennia.locks.lockfuncs.tag(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

tag(tagkey) tag(tagkey, category)

Only true if accessing_obj has the specified tag and optional category. If accessing_obj has the “.obj” property (such as is the case for a command), then accessing_obj.obj is used instead.

evennia.locks.lockfuncs.objtag(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

objtag(tagkey) objtag(tagkey, category)

Only true if accessed_obj has the specified tag and optional category.

evennia.locks.lockfuncs.inside(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

inside()

True if accessing_obj is ‘inside’ accessing_obj. Note that this only checks one level down. So if if the lock is on a room, you will pass but not your inventory (since their location is you, not the locked object). If you want also nested objects to pass the lock, use the insiderecursive lockfunc.

evennia.locks.lockfuncs.inside_rec(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

inside_rec()

True if accessing_obj is inside the accessed obj, at up to 10 levels of recursion (so if this lock is on a room, then an object inside a box in your inventory will also pass the lock).

evennia.locks.lockfuncs.holds(accessing_obj, accessed_obj, *args, **kwargs)

Usage:

holds() checks if accessed_obj or accessed_obj.obj

is held by accessing_obj

holds(key/dbref) checks if accessing_obj holds an object

with given key/dbref

holds(attrname, value) checks if accessing_obj holds an

object with the given attrname and value

This is passed if accessed_obj is carried by accessing_obj (that is, accessed_obj.location == accessing_obj), or if accessing_obj itself holds an object matching the given key.

evennia.locks.lockfuncs.superuser(*args, **kwargs)

Only accepts an accesing_obj that is superuser (e.g. user #1)

Since a superuser would not ever reach this check (superusers bypass the lock entirely), any user who gets this far cannot be a superuser, hence we just return False. :)

evennia.locks.lockfuncs.has_account(accessing_obj, accessed_obj, *args, **kwargs)

Only returns true if accessing_obj has_account is true, that is, this is an account-controlled object. It fails on actual accounts!

This is a useful lock for traverse-locking Exits to restrain NPC mobiles from moving outside their areas.

evennia.locks.lockfuncs.serversetting(accessing_obj, accessed_obj, *args, **kwargs)

Only returns true if the Evennia settings exists, alternatively has a certain value.

Usage:

serversetting(IRC_ENABLED) serversetting(BASE_SCRIPT_PATH, [‘types’])

A given True/False or integers will be converted properly. Note that everything will enter this function as strings, so they have to be unpacked to their real value. We only support basic properties.