Added more comments to help exploration through the ev interface.

ev.py

@@ -94,8 +94,8 @@ db_helpentries = HelpEntry.objects
 from src.players.player import Player
 from src.players.models import PlayerDB, PlayerAttribute, PlayerNick
 db_players = PlayerDB.objects
-db_playerattrs = PlayerAttribute.objects
+#db_playerattrs = PlayerAttribute.objects
-db_playernicks = PlayerNick.objects
+#db_playernicks = PlayerNick.objects
 del PlayerDB, PlayerAttribute, PlayerNick
 
 # commands
@@ -135,7 +135,7 @@ from src.locks import lockfuncs
 from src.scripts.scripts import Script
 from src.scripts.models import ScriptDB, ScriptAttribute
 db_scripts = ScriptDB.objects
-db_scriptattrs = ScriptAttribute.objects
+#db_scriptattrs = ScriptAttribute.objects
 del ScriptDB, ScriptAttribute
 
 # comms
@@ -149,9 +149,9 @@ db_externalconnections = ExternalChannelConnection.objects
 from src.objects.objects import Object, Character, Room, Exit
 from src.objects.models import ObjAttribute, Alias, ObjectNick, ObjectDB
 db_objects = ObjectDB.objects
-db_aliases = Alias.objects
+#db_aliases = Alias.objects
-db_objnicks = ObjectNick.objects
+#db_objnicks = ObjectNick.objects
-db_objattrs = ObjAttribute.objects
+#db_objattrs = ObjAttribute.objects
 del ObjAttribute, Alias, ObjectNick, ObjectDB
 
 # server 

src/comms/managers.py

@@ -56,7 +56,24 @@ def to_object(inp, objtype='player'):
 
 class MsgManager(models.Manager):
     """
-    Handle msg database
+    This MsgManager implements methods for searching 
+    and manipulating Messages directly from the database.
+
+    These methods will all return database objects 
+    (or QuerySets) directly.
+
+    A Message represents one unit of communication, be it over a 
+    Channel or via some form of in-game mail system. Like an e-mail,
+    it always has a sender and can have any number of receivers (some
+    of which may be Channels). 
+    
+    Evennia-specific:
+     get_message_by_id
+     get_messages_by_sender
+     get_messages_by_receiver
+     get_messages_by_channel
+     text_search
+     message_search (equivalent to ev.search_messages)
     """
     
     def get_message_by_id(self, idnum):
@@ -202,7 +219,24 @@ class MsgManager(models.Manager):
 
 class ChannelManager(models.Manager):
     """
-    Handle channel database
+    This ChannelManager implements methods for searching 
+    and manipulating Channels directly from the database.
+
+    These methods will all return database objects 
+    (or QuerySets) directly.
+
+    A Channel is an in-game venue for communication. It's 
+    essentially representation of a re-sender: Users sends
+    Messages to the Channel, and the Channel re-sends those
+    messages to all users subscribed to the Channel.
+
+    Evennia-specific:
+    get_all_channels
+    get_channel
+    del_channel
+    get_all_connections
+    channel_search (equivalent to ev.search_channel)
+
     """
 
     def get_all_channels(self):
@@ -281,8 +315,23 @@ class ChannelManager(models.Manager):
 #
 class PlayerChannelConnectionManager(models.Manager):
     """
-    This handles all connections between a player and
+    This PlayerChannelConnectionManager implements methods for searching 
-    a channel. 
+    and manipulating PlayerChannelConnections directly from the database.
+
+    These methods will all return database objects 
+    (or QuerySets) directly.
+
+    A PlayerChannelConnection defines a user's subscription to an in-game
+    channel - deleting the connection object will disconnect the player
+    from the channel.
+
+    Evennia-specific:
+    get_all_player_connections
+    has_connection
+    get_all_connections
+    create_connection
+    break_connection
+
     """
     
     def get_all_player_connections(self, player):
@@ -330,12 +379,26 @@ class PlayerChannelConnectionManager(models.Manager):
 
 class ExternalChannelConnectionManager(models.Manager):
     """
-    This handles all connections between a external and
+    This ExternalChannelConnectionManager implements methods for searching 
-    a channel. 
+    and manipulating HelpEntries directly from the database.
+
+    These methods will all return database objects 
+    (or QuerySets) directly.
+
+    An ExternalChannelConnetion describes the connection between an in-game 
+    channel and some external source, such as an IRC or IMC channel.
+
+    Evennia-specific:
+    get_all_external_connections
+    has_connection
+    get_all_connections
+    create_connection
+    break_connection
+    
     """
     
     def get_all_external_connections(self, external):
-        "Get all connections that the given external."
+        "Get all connections that the given as external."
         external = to_object(external, objtype='external')
         return self.filter(db_external_key=external)
 

src/help/manager.py

@@ -6,7 +6,20 @@ from src.utils import logger, utils
 
 class HelpEntryManager(models.Manager):
     """
-    This implements different ways to search for help entries.
+    This HelpEntryManager implements methods for searching 
+    and manipulating HelpEntries directly from the database.
+
+    These methods will all return database objects 
+    (or QuerySets) directly.
+
+    Evennia-specific:
+    find_topicmatch
+    find_apropos
+    find_topicsuggestions
+    find_topics_with_category
+    all_to_category
+    search_help (equivalent to ev.search_helpentry)
+
     """
     def find_topicmatch(self, topicstr, exact=False):
         """

src/objects/manager.py

@@ -16,12 +16,30 @@ AT_MULTIMATCH_INPUT = utils.mod_import(*settings.SEARCH_AT_MULTIMATCH_INPUT.rspl
 
 class ObjectManager(TypedObjectManager):
     """
-    This is the main ObjectManager for all in-game objects. It
+    This ObjectManager implementes methods for searching
-    implements search functions specialized for objects of this
+    and manipulating Objects directly from the database. 
-    type, such as searches based on user, contents or location. 
+
+    Evennia-specific search methods (will return Typeclasses or
+    lists of Typeclasses, whereas Django-general methods will return
+    Querysets or database objects). 
+
+    dbref (converter)
+    dbref_search
+    get_dbref_range
+    object_totals
+    typeclass_search
+    get_object_with_user
+    get_object_with_player
+    get_objs_with_key_and_typeclass
+    get_objs_with_attr
+    get_objs_with_attr_match
+    get_objs_with_db_property
+    get_objs_with_db_property_match
+    get_objs_with_key_or_alias
+    get_contents
+    object_search (interface to many of the above methods, equivalent to ev.search_object)
+    copy_object
 
-    See src.dbobjects.TypedObjectManager for more general
-    search methods. 
     """
     
     #

src/players/manager.py

@@ -3,6 +3,7 @@ The managers for the custom Player object and permissions.
 """
 
 import datetime 
+from functools import update_wrapper
 from django.db import models
 from django.contrib.auth.models import User
 from src.typeclasses.managers import returns_typeclass_list, returns_typeclass, TypedObjectManager
@@ -43,7 +44,7 @@ def returns_player_list(method):
                 else:
                     logger.log_trace("No connection User<->Player, maybe database was partially reset?")                
         return players
-    return func 
+    return update_wrapper(func, method) 
 
 def returns_player(method):
     """
@@ -57,15 +58,32 @@ def returns_player(method):
             return match[0]
         else:
             return None 
-    return func
+    return update_wrapper(func, method)
 
 class PlayerManager(TypedObjectManager):
     """
-    Custom manager for the player profile model. We use this
+    This PlayerManager implements methods for searching 
-    to wrap users in general in evennia, and supply some useful
+    and manipulating Players directly from the database.
-    search/statistics methods. 
+
+    Evennia-specific search methods (will return Characters if
+    possible or a Typeclass/list of Typeclassed objects, whereas
+    Django-general methods will return Querysets or database objects):
+    
+    dbref (converter)
+    dbref_search
+    get_dbref_range
+    object_totals
+    typeclass_search
+    num_total_players
+    get_connected_players
+    get_recently_created_players
+    get_recently_connected_players
+    get_player_from_email
+    get_player_from_uid
+    get_player_from_name
+    player_search (equivalent to ev.search_player)
+    swap_character
     
-    Note how ALL these commands return character objects if possible. 
     """
     def num_total_players(self):
         """

src/scripts/manager.py

@@ -9,7 +9,26 @@ VALIDATE_ITERATION = 0
 
 class ScriptManager(TypedObjectManager):
     """
-    ScriptManager get methods
+    This Scriptmanager implements methods for searching 
+    and manipulating Scripts directly from the database.
+
+    Evennia-specific search methods (will return Typeclasses or
+    lists of Typeclasses, whereas Django-general methods will return
+    Querysets or database objects). 
+    
+    dbref (converter)
+    dbref_search
+    get_dbref_range
+    object_totals
+    typeclass_search
+    get_all_scripts_on_obj
+    get_all_scripts
+    delete_script
+    remove_non_persistent
+    validate
+    script_search (equivalent to ev.search_script)
+    copy_script
+
     """
     @returns_typeclass_list
     def get_all_scripts_on_obj(self, obj, key=None):

src/server/manager.py

@@ -5,10 +5,18 @@ from django.db import models
 
 class ServerConfigManager(models.Manager):
     """
-    This gives some access methods to search and edit
+    This ServerConfigManager implements methods for searching 
-    the configvalue database. 
+    and manipulating ServerConfigs directly from the database.
+
+    These methods will all return database objects 
+    (or QuerySets) directly.
+
+    ServerConfigs are used to store certain persistent settings for the 
+    server at run-time.
+
+    Evennia-specific:
+    conf 
 
-    If no match is found, return default. 
     """
     def conf(self, key=None, value=None, delete=False, default=None):
         """

src/typeclasses/models.py

@@ -52,6 +52,8 @@ DA = object.__delattr__
 PLOADS = pickle.loads
 PDUMPS = pickle.dumps 
 
+# Property Cache mechanism.
+
 def get_cache(obj, name):
     "On-model Cache handler."
     try:
@@ -588,11 +590,32 @@ class TypeNickHandler(object):
     NickClass = TypeNick 
 
     def __init__(self, obj):
-        "Setup"
+        """
+        This handler allows for accessing and setting nicks -
+        on-the-fly replacements for various text input passing through
+        this object (most often a Character)
+
+        The default nick types used by Evennia are: 
+
+        inputline (default) - match against all input
+        player - match against player searches
+        obj - match against object searches 
+        channel - used to store own names for channels
+
+        You can define other nicktypes by using the add() method of
+        this handler and set nick_type to whatever you want. It's then
+        up to you to somehow make use of this nick_type in your game
+        (such as for a "recog" system).
+
+        """
         self.obj = obj
 
     def add(self, nick, realname, nick_type="inputline"):
-        "We want to assign a new nick"
+        """
+        Assign a new nick for realname. 
+          nick_types used by Evennia are 
+            'inputline', 'player', 'obj' and 'channel'
+        """
         if not nick or not nick.strip():
             return 
         nick = nick.strip()        
@@ -606,25 +629,38 @@ class TypeNickHandler(object):
             new_nick = self.NickClass(db_nick=nick, db_real=real, db_type=nick_type, db_obj=self.obj)
             new_nick.save()                
     def delete(self, nick, nick_type="inputline"):        
-        "Removes a nick"
+        "Removes a previously stored nick"
         nick = nick.strip()        
         query = self.NickClass.objects.filter(db_obj=self.obj, db_nick__iexact=nick, db_type__iexact=nick_type)        
         if query.count():
             # remove the found nick(s)
             query.delete()           
-    def get(self, nick=None, nick_type="inputline"):
+    def get(self, nick=None, nick_type="inputline", obj=None):
+        """Retrieves a given nick (with a specified nick_type) on an object. If no nick is given, returns a list
+        of all nicks on the object, or the empty list. 
+        Defaults to searching the current object."""
+        if not obj:
+            # defaults to the current object
+            obj = self.obj
         if nick:
-            query = self.NickClass.objects.filter(db_obj=self.obj, db_nick__iexact=nick, db_type__iexact=nick_type)        
+            query = self.NickClass.objects.filter(db_obj=obj, db_nick__iexact=nick, db_type__iexact=nick_type)        
             query = query.values_list("db_real", flat=True)
             if query.count():
                 return query[0]
             else:
                 return nick
         else:
-            return self.NickClass.objects.filter(db_obj=self.obj)
+            return self.NickClass.objects.filter(db_obj=obj)
-    def has(self, nick, nick_type="inputline"):
+    def has(self, nick, nick_type="inputline", obj=None):
-        "Returns true/false if this nick is defined or not"
+        """
-        return self.NickClass.objects.filter(db_obj=self.obj, db_nick__iexact=nick, db_type__iexact=nick_type).count()
+        Returns true/false if this nick and nick_type is defined on the given
+        object or not. If no obj is given, default to the current object the 
+        handler is defined on. 
+
+        """
+        if not obj:
+            obj = self.obj
+        return self.NickClass.objects.filter(db_obj=obj, db_nick__iexact=nick, db_type__iexact=nick_type).count()
 
 
 #------------------------------------------------------------