Converted a large part of utils/ folder to google code docstrings as per #709.

evennia/utils/create.py

@@ -59,24 +59,35 @@ def create_object(typeclass=None, key=None, location=None,
 
     Create a new in-game object.
 
-    keywords:
-        typeclass - class or python path to a typeclass
-        key - name of the new object. If not set, a name of #dbref will be set.
-        home - obj or #dbref to use as the object's home location
-        permissions - a comma-separated string of permissions
-        locks - one or more lockstrings, separated by semicolons
-        aliases - a list of alternative keys
-        tags - a list of tag keys (using no category)
-        destination - obj or #dbref to use as an Exit's target
+    Kwargs:
+        typeclass (class or str): Class or python path to a typeclass.
+        key (str): Name of the new object. If not set, a name of
+            #dbref will be set.
+        home (Object or str): Obj or #dbref to use as the object's
+            home location.
+        permissions (str): A comma-separated string of permissions.
+        locks (str): one or more lockstrings, separated by semicolons.
+        aliases (list): A list of alternative keys.
+        tags (list): List of tag keys (using no category).
+        destination (Object or str): Obj or #dbref to use as an Exit's
+            target.
+        report_to (Object): The object to return error messages to.
+        nohome (bool): This allows the creation of objects without a
+            default home location; only used when creating the default
+            location itself or during unittests.
+
+    Returns:
+        object (Object): A newly created object of the given typeclass.
+
+    Raises:
+        ObjectDB.DoesNotExist: If trying to create an Object with
+            `location` or `home` that can't be found.
 
-        nohome - this allows the creation of objects without a default home location;
-                 only used when creating the default location itself or during unittests
     """
     global _ObjectDB
     if not _ObjectDB:
         from evennia.objects.models import ObjectDB as _ObjectDB
 
-
     typeclass = typeclass if typeclass else settings.BASE_OBJECT_TYPECLASS
 
     if isinstance(typeclass, basestring):
@@ -120,32 +131,42 @@ object = create_object
 # Script creation
 #
 
-def create_script(typeclass, key=None, obj=None, player=None, locks=None,
+def create_script(typeclass=None, key=None, obj=None, player=None, locks=None,
                   interval=None, start_delay=None, repeats=None,
                   persistent=None, autostart=True, report_to=None):
     """
-    Create a new script. All scripts are a combination
-    of a database object that communicates with the
-    database, and an typeclass that 'decorates' the
-    database object into being different types of scripts.
-    It's behaviour is similar to the game objects except
-    scripts has a time component and are more limited in
-    scope.
+    Create a new script. All scripts are a combination of a database
+    object that communicates with the database, and an typeclass that
+    'decorates' the database object into being different types of
+    scripts.  It's behaviour is similar to the game objects except
+    scripts has a time component and are more limited in scope.
+
+    Kwargs:
+        typeclass (class or str): Class or python path to a typeclass.
+        key (str): Name of the new object. If not set, a name of
+            #dbref will be set.
+        obj (Object): The entity on which this Script sits. If this
+            is `None`, we are creating a "global" script.
+        player (Player): The player on which this Script sits. It is
+            exclusiv to `obj`.
+        locks (str): one or more lockstrings, separated by semicolons.
+        interval (int): The triggering interval for this Script, in
+            seconds. If unset, the Script will not have a timing
+            component.
+        start_delay (bool): If `True`, will wait `interval` seconds
+            before triggering the first time.
+        repeats (int): The number of times to trigger before stopping.
+            If unset, will repeat indefinitely.
+        persistent (bool): If this Script survives a server shutdown
+            or not (all Scripts will survive a reload).
+        autostart (bool): If this Script will start immediately when
+            created or if the `start` method must be called explicitly.
+        report_to (Object): The object to return error messages to.
 
-    Argument 'typeclass' can be either an actual
-    typeclass object or a python path to such an object.
-    Only set key here if you want a unique name for this
-    particular script (set it in config to give
-    same key to all scripts of the same type). Set obj
-    to tie this script to a particular object.
 
     See evennia.scripts.manager for methods to manipulate existing
     scripts in the database.
 
-    report_to is an obtional object to receive error messages.
-              If report_to is not set, an Exception with the
-              error will be raised. If set, this method will
-              return None upon errors.
     """
     global _ScriptDB
     if not _ScriptDB:
@@ -194,10 +215,20 @@ script = create_script
 def create_help_entry(key, entrytext, category="General", locks=None):
     """
     Create a static help entry in the help database. Note that Command
-    help entries are dynamic and directly taken from the __doc__ entries
-    of the command. The database-stored help entries are intended for more
-    general help on the game, more extensive info, in-game setting information
-    and so on.
+    help entries are dynamic and directly taken from the __doc__
+    entries of the command. The database-stored help entries are
+    intended for more general help on the game, more extensive info,
+    in-game setting information and so on.
+
+    Args:
+        key (str): The name of the help entry.
+        entrytext (str): The body of te help entry
+        category (str, optional): The help category of the entry.
+        locks (str, optional): A lockstring to restrict access.
+
+    Returns:
+        help (HelpEntry): A newly created help entry.
+
     """
     global _HelpEntry
     if not _HelpEntry:
@@ -230,24 +261,28 @@ help_entry = create_help_entry
 def create_message(senderobj, message, channels=None,
                    receivers=None, locks=None, header=None):
     """
-    Create a new communication message. Msgs are used for all
-    player-to-player communication, both between individual players
-    and over channels.
-    senderobj - the player sending the message. This must be the actual object.
-    message - text with the message. Eventual headers, titles etc
-              should all be included in this text string. Formatting
-              will be retained.
-    channels - a channel or a list of channels to send to. The channels
-             may be actual channel objects or their unique key strings.
-    receivers - a player to send to, or a list of them. May be Player objects
-               or playernames.
-    locks - lock definition string
-    header - mime-type or other optional information for the message
+    Create a new communication Msg. Msgs represent a unit of
+    database-persistent communication between entites.
+
+    Args:
+        senderobj (Object or Player): The entity sending the Msg.
+        message (str): Text with the message. Eventual headers, titles
+            etc should all be included in this text string. Formatting
+            will be retained.
+        channels (Channel, key or list): A channel or a list of channels to
+            send to. The channels may be actual channel objects or their
+            unique key strings.
+        receivers (Object, Player, str or list): A Player/Object to send
+            to, or a list of them. May be Player objects or playernames.
+        locks (str): Lock definition string.
+        header (str): Mime-type or other optional information for the message
+
+    Notes:
+        The Comm system is created very open-ended, so it's fully possible
+        to let a message both go to several channels and to several
+        receivers at the same time, it's up to the command definitions to
+        limit this as desired.
 
-    The Comm system is created very open-ended, so it's fully possible
-    to let a message both go to several channels and to several receivers
-    at the same time, it's up to the command definitions to limit this as
-    desired.
     """
     global _Msg
     if not _Msg:
@@ -275,16 +310,27 @@ def create_channel(key, aliases=None, desc=None,
                    locks=None, keep_log=True,
                    typeclass=None):
     """
-    Create A communication Channel. A Channel serves as a central
-    hub for distributing Msgs to groups of people without
-    specifying the receivers explicitly. Instead players may
-    'connect' to the channel and follow the flow of messages. By
-    default the channel allows access to all old messages, but
-    this can be turned off with the keep_log switch.
+    Create A communication Channel. A Channel serves as a central hub
+    for distributing Msgs to groups of people without specifying the
+    receivers explicitly. Instead players may 'connect' to the channel
+    and follow the flow of messages. By default the channel allows
+    access to all old messages, but this can be turned off with the
+    keep_log switch.
+
+    Args:
+        key (str): This must be unique.
+
+    Kwargs:
+        aliases (list): List of alternative (likely shorter) keynames.
+        desc (str): A description of the channel, for use in listings.
+        locks (str): Lockstring.
+        keep_log (bool): Log channel throughput.
+        typeclass (str or class): The typeclass of the Channel (not
+            often used).
+
+    Returns:
+        channel (Channel): A newly created channel.
 
-    key - this must be unique.
-    aliases - list of alternative (likely shorter) keynames.
-    locks - lock string definitions
     """
     typeclass = typeclass if typeclass else settings.BASE_CHANNEL_TYPECLASS
 
@@ -322,23 +368,28 @@ def create_player(key, email, password,
     """
     This creates a new player.
 
-    key - the player's name. This should be unique.
-    email - email on valid addr@addr.domain form.
-    password - password in cleartext
-    is_superuser - wether or not this player is to be a superuser
-    locks - lockstring
-    permission - list of permissions
-    report_to - an object with a msg() method to report errors to. If
-                not given, errors will be logged.
+    Args:
+        key (str): The player's name. This should be unique.
+        email (str): Email on valid addr@addr.domain form. This is
+            technically required but if set to `None`, an email of
+            `dummy@dummy.com` will be used as a placeholder.
+        password (str): Password in cleartext.
 
-    Will return the Player-typeclass or None/raise Exception if the
-    Typeclass given failed to load.
+    Kwargs:
+        is_superuser (bool): Wether or not this player is to be a superuser
+        locks (str): Lockstring.
+        permission (list): List of permission strings.
+        report_to (Object): An object with a msg() method to report
+            errors to. If not given, errors will be logged.
 
-    Concerning is_superuser:
-     Usually only the server admin should need to be superuser, all
-     other access levels can be handled with more fine-grained
-     permissions or groups. A superuser bypasses all lock checking
-     operations and is thus not suitable for play-testing the game.
+    Raises:
+        ValueError: If `key` already exists in database.
+
+    Notes:
+        Usually only the server admin should need to be superuser, all
+        other access levels can be handled with more fine-grained
+        permissions or groups. A superuser bypasses all lock checking
+        operations and is thus not suitable for play-testing the game.
 
     """
     global _PlayerDB