From 82a10903d1dddcbc97973f210dd288b8bc77c16f Mon Sep 17 00:00:00 2001 From: Griatch Date: Thu, 29 Mar 2012 19:42:08 +0200 Subject: [PATCH] Added more comments to help exploration through the ev interface. --- ev.py | 12 +++--- src/comms/managers.py | 77 +++++++++++++++++++++++++++++++++++---- src/help/manager.py | 15 +++++++- src/objects/manager.py | 28 +++++++++++--- src/players/manager.py | 30 ++++++++++++--- src/scripts/manager.py | 21 ++++++++++- src/server/manager.py | 14 +++++-- src/typeclasses/models.py | 54 ++++++++++++++++++++++----- 8 files changed, 213 insertions(+), 38 deletions(-) diff --git a/ev.py b/ev.py index d5cabb796b..ab6ebe9145 100644 --- a/ev.py +++ b/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_playernicks = PlayerNick.objects +#db_playerattrs = PlayerAttribute.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_objnicks = ObjectNick.objects -db_objattrs = ObjAttribute.objects +#db_aliases = Alias.objects +#db_objnicks = ObjectNick.objects +#db_objattrs = ObjAttribute.objects del ObjAttribute, Alias, ObjectNick, ObjectDB # server diff --git a/src/comms/managers.py b/src/comms/managers.py index 1404e2c43e..955c172a08 100644 --- a/src/comms/managers.py +++ b/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 - a channel. + This PlayerChannelConnectionManager implements methods for searching + 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 - a channel. + This ExternalChannelConnectionManager implements methods for searching + 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) diff --git a/src/help/manager.py b/src/help/manager.py index 7a3466731f..ff0306fd29 100644 --- a/src/help/manager.py +++ b/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): """ diff --git a/src/objects/manager.py b/src/objects/manager.py index d83bae718e..64c5a6947a 100644 --- a/src/objects/manager.py +++ b/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 - implements search functions specialized for objects of this - type, such as searches based on user, contents or location. + This ObjectManager implementes methods for searching + and manipulating Objects 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_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. """ # diff --git a/src/players/manager.py b/src/players/manager.py index acbb38d01c..8713a950bd 100644 --- a/src/players/manager.py +++ b/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 - to wrap users in general in evennia, and supply some useful - search/statistics methods. + This PlayerManager implements methods for searching + and manipulating Players directly from the database. - Note how ALL these commands return character objects if possible. + 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 + """ def num_total_players(self): """ diff --git a/src/scripts/manager.py b/src/scripts/manager.py index 863a766b48..5ffff0b132 100644 --- a/src/scripts/manager.py +++ b/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): diff --git a/src/server/manager.py b/src/server/manager.py index ffbe32babb..88c196c10a 100644 --- a/src/server/manager.py +++ b/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 - the configvalue database. + This ServerConfigManager implements methods for searching + 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): """ diff --git a/src/typeclasses/models.py b/src/typeclasses/models.py index ee806b665d..def313a972 100644 --- a/src/typeclasses/models.py +++ b/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) - def has(self, nick, nick_type="inputline"): - "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() + return self.NickClass.objects.filter(db_obj=obj) + def has(self, nick, nick_type="inputline", obj=None): + """ + 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() #------------------------------------------------------------