Cleaning some unnecessary whitespace, overall cleanup of various source codes.

CODING_STYLE

@@ -1,7 +1,7 @@
 Evennia Code Style
 ------------------
-All code submitted or committed to the Evennia project needs to follow the
+All code submitted or committed to the Evennia project needs to follow
-guidelines outlined in Python PEP 8, which may be found at:
+the guidelines outlined in Python PEP 8, which may be found at:
 
     http://www.python.org/dev/peps/pep-0008/
 
@@ -10,40 +10,44 @@ A quick list of code style points
  * 4-space indendation, NO TABS!
  * Unix line endings.
  * CamelCase is only used for classes, nothing else.
- * All non-global variable names and all function names are to be lowercase, 
+ * All non-global variable names and all function names are to be
-   words separated by underscores. Variable names should always be more than 
+   lowercase, words separated by underscores. Variable names should
-   two letters long.
+   always be more than two letters long.
  * Module-level global variables (only) are to be in CAPITAL letters.
- * Imports are to be done in this order:
+ * (Evennia-specific): Imports should normally be done in this order:
-   - Python modules (builtins and modules otherwise unrelated to Evennia)
+   - Python modules (builtins and standard library)
-   - Twisted 
+   - Twisted modules
-   - Django
+   - Django modules
    - Evennia src/ modules
    - Evennia game/ modules
+   - Evennia 'ev' API imports
 
 Documentation
 -------------
-Remember that Evennia's source code is intended to be read  - and will be read - by 
+Remember that Evennia's source code is intended to be read - and will
-game admins trying to implement various features. Evennia prides itself with being 
+be read - by game admins trying to implement their game. Evennia
-extensively documented. Modules, functions, classes and class methods should all 
+prides itself with being extensively documented. Modules, functions,
-start with at least one line of docstring summing up the function's purpose. Ideally 
+classes and class methods should all start with at least one line of
-also explain eventual arguments and caveats. Add comments where appropriate. 
+docstring summing up the function's purpose. Ideally also explain
+eventual arguments and caveats. Add comments where appropriate.
 
 Pylint
 ------
-The program 'pylint' (http://www.logilab.org/857) is a useful tool for checking
+The program 'pylint' (http://www.logilab.org/857) is a useful tool for
-your Python code for errors. It will also check how well your code adheres to 
+checking your Python code for errors. It will also check how well your
-the PEP 8 guidelines (such as lack of docstrings) and tells you what can be improved.
+code adheres to the PEP 8 guidelines (such as lack of docstrings) and
+tells you what can be improved.
 
-Since pylint cannot catch dynamically created variables used in commands and 
+Since pylint cannot catch dynamically created variables used in
-elsewhere in Evennia, one needs to reduce some checks to avoid false errors and
+commands and elsewhere in Evennia, one needs to reduce some checks to
-warnings. For best results, run pylint like this: 
+avoid false errors and warnings. For best results, run pylint like
+this:
 
  > pylint --disable=E1101,E0102,F0401,W0232,R0903 filename.py
 
-To avoid entering the options every time, you can auto-create a pylintrc file by 
+To avoid entering the options every time, you can auto-create a
-using the option --generate-rcfile. You need to dump this output into a 
+pylintrc file by using the option --generate-rcfile. You need to dump
-file .pylintrc, for example like this (linux):
+this output into a file .pylintrc, for example like this (linux):
 
  > pylint --disable=E1101,E0102,F0401,W0232,R0903 --generate-rcfile > ~/.pylintrc
 
@@ -53,7 +57,7 @@ From now on you can then just run
 
 Ask Questions!
 --------------
-If any of the rules outlined in PEP 8 or in the sections above doesn't make sense, please
+If any of the rules outlined in PEP 8 or in the sections above doesn't
-don't hesitate to ask on the Evennia mailing list at http://evennia.com.
+make sense, please don't hesitate to ask on the Evennia mailing list
-Keeping our code style uniform makes this project much easier for a wider group
+at http://evennia.com.  Keeping our code style uniform makes this
-of people to participate in.
+project much easier for a wider group of people to participate in.

INSTALL

@@ -12,14 +12,15 @@ Installation
 
 * Make sure you have/install the prerequsites with minimum versions
   listed on http://code.google.com/p/evennia/wiki/GettingStarted:
+
     - python
     - django
     - twisted + PIL
     - mercurial
-    - django-south (optional)
+    - django-south (optional, but highly recommended)
 
-* Go to a directory on your harddrive where you want the "evennia" 
+* Go to a directory on your harddrive where you want the 'evennia'
-  directory to be created.
+  directory to be created, for example mud/.
 
     $ cd mud/
 
@@ -46,11 +47,11 @@ Installation
 Starting Evennia
 ----------------
 
-    $ python evennia.py -i start 
+* Start the server with
-  or 
-    $ python evennia.py
 
-  for a menu of launch options.
+    $ python evennia.py -i start
+
+  or run without arguments for a menu of launch options.
   See http://code.google.com/p/evennia/wiki/StartStopReload for more info.
 
 * Start up your MUD client of choice and point it to your server and port 4000.
@@ -59,8 +60,14 @@ Starting Evennia
 * Alternatively, you can find the web interface and webclient by
   pointing your web browser to http://localhost:8000.
 
-* Login with the email address and password you provided to the syncdb script.
+* Login with the email address and password you provided when setting up the server.
-  Welcome to Evennia! 
 
-See also "Getting Started" on www.evennia.com for more verbose instructions and
+
-the documentation wiki for further help.
+Welcome to Evennia!
+-------------------
+
+* See www.evennia.com for more information and help with how to
+  proceed from here.
+
+* For questions, see the discussion group or the chat. Report bugs or
+  request features via the Issue Tracker.

README

@@ -9,31 +9,17 @@
 About Evennia
 -------------
 
-Evennia is a MUD/MUX/MU* server that aims to provide a functional
+Evennia is a MUD/MUX/MU* development system and server that aims to
-bare-bones base for developers. Some of our main features are: 
+provide a functional bare-bones codebase for developers. Some of our main
+features are:
 
-* Coded and extended using normal Python modules.
+ * Coded and extended using normal Python modules.
-* Extensive web integration due to our use of Django. 
+ * Reload code without players logging off
-* Runs its own Twisted webserver. Comes with game website and ajax web-browser mud client. 
+ * Database handling and network connectivity are abstracted away
-* Extensive current and potential connectivity and protocol-support through Twisted.
+ * Extensive web integration due to our use of Django.
-* Extremely easy-to-manipulate SQL database back-end via Django 
+ * Server runs game website and ajax web-browser mud client out of the box.
-  (djangoproject.com)
+ * Supports a slew of different connection protocols with Twisted.
-* Powerful an extremely extendable bare-bones base system 
+ * Extremely extendable to almost any sort of text-based multiplayer game
-
-The Django framework has database abstraction abilities that give us
-many features free, such as:
-
-* The codebase will run transparently on MySQL, SQLite, or Postgres
-* At the time of this document's writing, our SQL-backed application here
-  contains 0 lines of SQL. Django's database abstraction layer is absolutely
-  simple yet very powerful.
-* For any model we outline for the server's use, we have the ability to
-  more or less automatically generate a web-based admin interface for it with
-  two lines of code. This lets you Create, Update, or Delete entries, as well
-  limit permissions for those abilities.
-* On the web-based side of things, features such as automatic form validation,
-  abstraction of sessions and cookies, and access to whatever game data you
-  desire are all attractive.  
 
 See the INSTALL file for help on setting up and running Evennia.
 
@@ -41,6 +27,18 @@ See the INSTALL file for help on setting up and running Evennia.
 Current Status
 --------------
 
+March 2012:
+Evennia's API has changed and simplified slightly in that the
+base-modules where removed from game/gamesrc. Instead admins are
+encouraged to explicitly create new modules under game/gamesrc/ when
+they want to implement their game - gamesrc/ is empty by default
+except for the example folders that contain template files to use for
+this purpose. We also added the ev.py file, implementing a new, flat
+API.  Work is ongoing to add support for mud-specific telnet
+extensions, notably the MSDP and GMCP out-of-band extensions.  On the
+community side, evennia's dev blog was started and linked on planet
+Mud-dev aggregator.
+
 Nov 2011:
 After creating several different proof-of-concept game systems (in
 contrib and privately) as well testing lots of things to make sure the
@@ -116,49 +114,49 @@ Directory structure
 -------------------
 evennia
  |
- |_______src
+ |       ev.py
- |        |___(engine-related dirs)
+ |_______game (start the server, settings)
- |        
- |_______game (start the server)
  |        |___gamesrc
  |              |___(game-related dirs)
- | 
+ |_______src
+ |        |___(engine-related dirs)
+ | |
  |_______contrib
  |
  |_______docs
  |
  |_______locales
 
-The two main directories you will spend most of your time in
+ev.py is the API file. It contains easy shortcuts to most
-are src/ and game/ (probably mostly game/). 
+of Evennia's functionality. Import ev into a python interpreter
+(like ipython) and explore what's available.
 
-Basically src/ contains everything related to 
+The game/ folder is where you develop your game. The root
-running the gritty stuff behind the scenes. Unless you are an
+of this directory contains the settings file and the executables
-Evennia developer you should normally make sure never to edit 
+to start the server. Under game/gamesrc you will create the
-things in src/, since this is where we push new revisions that
+modules that will define your game.
-may overwrite your changes when you update. You will however 
-need to have a good feeling for the resources supplied by 
-the functions in src, since accessing them correctly is the key 
-to making your dream game come true. 
 
-If src/ is the Evennia developer's domain, the game/ directory 
+src/ contains the Evennia library. As a normal user you should
-on the other hand contains YOUR game. This is where you will 
+not edit anything in this folder - you will run into mercurial
-define and extend the commands, objects and systems of Evennia
+conflicts as we update things from our end. If you see code
-to make your dream game. game/ contains the main server settings
+you like (such as that of a default command), copy&paste it
-and the actual evennia executable to start things. game/gamesrc/
+into a new module in game/gamesrc/ instead. If you find that
-holds all the templates for creating objects in your virtual world. 
+src/ doesn't support a functionality you need, issue a Feature
+request or a bug report appropriately.
+If you do add functionality or fix bugs in src yourself, please
+consider contributing it to Evennia main to help us improve!
 
 contrib/ contains optional code snippets. These are potentially useful
-but deemed to be too game-specific to be part of the server itself.
+but are deemed to be too game-specific to be part of the server itself.
 Modules in contrib are not used unless you yourself decide to import
 and use them.
 
 docs/ contain offline versions of the documentation, you can use
 python-sphinx to convert the raw data to nice-looking output for
-printing etc. The online wiki is otherwise first to be updated.  
+printing etc. The online wiki is however the most updated version
+of the documentation.
 
 locales/ holds translations of the server strings to other languages
 than English.
 
-With this little first orientation, you should head into the online 
+Enjoy!
-Evennia wiki documentation to get going with the codebase. 

src/commands/command.py

@@ -86,8 +86,18 @@ class Command(object):
     cmd.obj - the object on which this command is defined. If a default command,
                  this is usually the same as caller.
 
-    (Note that this initial string is also used by the system to create the help
+    The following class properties can/should be defined on your child class:
-    entry for the command, so it's a good idea to format it similar to this one)
+
+    key - identifier for command (e.g. "look")
+    aliases - (optional) list of aliases (e.g. ["l", "loo"])
+    locks - lock string (default is "cmd:all()")
+    help_category - how to organize this help entry in help system (default is "General")
+    auto_help - defaults to True. Allows for turning off auto-help generation
+    arg_regex - (optional) raw string regex defining how the argument part of the command should look
+                in order to match for this command (e.g. must it be a space between cmdname and arg?)
+
+    (Note that if auto_help is on, this initial string is also used by the system
+    to create the help entry for the command, so it's a good idea to format it similar to this one)
     """
     # Tie our metaclass, for some convenience cleanup
     __metaclass__ = CommandMeta

src/objects/manager.py

@@ -203,13 +203,22 @@ class ObjectManager(TypedObjectManager):
         is looked for. The Character is returned, not the Player. Use player_search
         to find Player objects. Always returns a list.
 
+        Arguments:
         ostring: (string) The string to compare names against.
                   Can be a dbref. If name is appended by *, a player is searched for.
-        caller: (Object) The object performing the search.
+        caller: (Object) The optional object performing the search.
-        global_search: Search all objects, not just the current location/inventory
+        global_search (bool). Defaults to False. If a caller is defined, search will
-        attribute_name: (string) Which attribute to search in each object.
+                  be restricted to the contents of caller.location unless global_search
-                                 If None, the default 'key' attribute is used.        
+                  is True. If no caller is given (or the caller has no location), a
-        location: If None, character.location will be used. 
+                  global search is assumed automatically.
+        attribute_name: (string) Which object attribute to match ostring against. If not
+                  set, the "key" and "aliases" properties are searched in order.
+        location (Object): If set, this location's contents will be used to limit the search instead
+                  of the callers. global_search will override this argument
+
+        Returns:
+        A list of matching objects (or a list with one unique match)
+
         """
         ostring = to_unicode(ostring, force_string=True)
 

src/typeclasses/managers.py

@@ -152,4 +152,3 @@ class TypedObjectManager(idmapper.manager.SharedMemoryManager):
             typeclass = "%s.%s" % (cls.__module__, cls.__name__)
         o_query = self.filter(db_typeclass_path__exact=typeclass)
         return o_query
-

src/typeclasses/typeclass.py

@@ -45,9 +45,6 @@ class MetaTypeClass(type):
         mcs.typename = mcs.__name__
         mcs.path = "%s.%s" % (mcs.__module__, mcs.__name__)
 
-
-
-        
     def __str__(cls):
         return "%s" % cls.__name__