# 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.

`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.``superuser`(*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)

  For non-hierarchical permissions, a puppeted object’s account is checked first, followed by the puppet (unless quelled, when only puppet’s access is checked).

`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.``objloctag`(accessing_obj, accessed_obj, *args, **kwargs)
  Usage:

    objloctag(tagkey) objloctag(tagkey, category):

  Only true if accessed_obj.location has the given tag and optional category. If obj has no location, this lockfunc fails.

`evennia.locks.lockfuncs.``is_ooc`(accessing_obj, accessed_obj, *args, **kwargs)
  Usage:

    is_ooc()

  This is normally used to lock a Command, so it can be used only when out of character.

`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.``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.