Updated ReST documentation.

docs/sphinx/source/wiki/ExecutePythonCode.rst

@@ -3,10 +3,10 @@ The ``@py`` command
 
 The ``@py`` command supplied with the default command set of Evennia
 allows you to execute Python commands directly from inside the game. An
-alias to ``@py`` is simply "``!``". *Access to the ``@py`` command
-should be severely restricted only to game admins.* Being able to
-execute arbitrary Python code on the server is not something you should
-entrust to just anybody.
+alias to ``@py`` is simply "``!``\ ". *Access to the ``@py`` command
+should be severely restricted*. This is no joke - being able to execute
+arbitrary Python code on the server is not something you should entrust
+to just anybody.
 
 ::
 
@@ -16,27 +16,24 @@ Available variables
 -------------------
 
 A few local variables are made available when running ``@py``. These
-offer entry into the running system and allows for quick exploration of
-the standard objects.
+offer entry into the running system.
 
 -  **self** / **me** - the calling object (i.e. you)
 -  **here** - the current caller's location
 -  **obj** - a dummy `Object <Objects.html>`_ instance
--  **script** - a dummy `Script <Scripts.html>`_ instance
--  **config** - a dummy ConfigValue instance
--  **ObjectDB** - direct reference to the ObjectDB database class
--  **ScriptDB** - direct reference to the ScriptDB database class
--  **!ConfigValue** - direct reference to the ConfigValue database class
+-  **ev** - Evennia's flat API - through this you can access all of
+   Evennia.
 
 Returning output
 ----------------
 
 This is an example where we import and test one of Evennia's utilities
-found in ``src/utils/utils.py``:
+found in ``src/utils/utils.py``, but also accessible through
+``ev.utils``:
 
 ::
 
-    @py from src.utils import utils; utils.time_format(33333) <<< Done.
+    @py from ev import utils; utils.time_format(33333) <<< Done.
 
 Note that we didn't get any return value, all we where told is that the
 code finished executing without error. This is often the case in more
@@ -46,7 +43,7 @@ system to echo it to us explicitly with ``self.msg()``.
 
 ::
 
-    @py from src.utils import utils; self.msg(utils.time_format(33333)) 09:15 <<< Done.
+    @py from ev import utils; self.msg(utils.time_format(33333)) 09:15 <<< Done.
 
 If you were to use Python's standard ``print``, you will see the result
 in your current ``stdout`` (your terminal by default), *if* you are
@@ -68,31 +65,28 @@ Locating an object is best done using ``self.search()``:
 ``self.search()`` is by far the most used case, but you can also search
 other database tables for other Evennia entities like scripts or
 configuration entities. To do this you can use the generic search
-entries found in ``src.utils.search``.
+entries found in ``ev.search_*``.
 
 ::
 
-    @py from src.utils import search; self.msg(search.scripts("sys_game_time")) <<< [<src.utils.gametime.GameTime object at 0x852be2c>]
+    @py ev.search_script("sys_game_time") <<< [<src.utils.gametime.GameTime object at 0x852be2c>]
 
-You can also use the database model managers directly (accessible
-through the ``objects`` properties of database models). This is a bit
-more flexible since it gives you access to the full range of database
-search methods defined in each manager.
+(Note that since this becomes a simple statement, we don't have to wrap
+it in ``self.msg()`` to get the output). You can also use the database
+model managers directly (accessible through the ``objects`` properties
+of database models or as ``ev.db_*``). This is a bit more flexible since
+it gives you access to the full range of database search methods defined
+in each manager.
 
 ::
 
-    @py ScriptDB.objects.script_search("sys_game_time") <<< [<src.utils.gametime.GameTime object at 0x852be2c>]
+    @py ev.db_scripts.script_search("sys_game_time") <<< [<src.utils.gametime.GameTime object at 0x852be2c>]
 
-(Note that since this second example becomes a simple statement, we
-don't have to wrap it in ``self.msg()`` to get the output). If you want
-to see what is available, the managers are found in the ``manager.py``
-files throughout the ``src`` directory (e.g.
-``src/objects/manager.py``). Through the manager you can also view the
-contents of the database using normal Django query operations:
+The managers are useful for all sorts of database studies.
 
 ::
 
-    @py ConfigValue.objects.all() <<< [<ConfigValue: default_home]>, <ConfigValue:site_name>, ...]
+    @py ev.db_configvalues.all() <<< [<ConfigValue: default_home]>, <ConfigValue:site_name>, ...]
 
 In doing so however, keep in mind the difference between `Typeclasses
 and Database Objects <Typeclasses.html>`_: Using the search commands in
@@ -104,7 +98,7 @@ most situations.
 
 ::
 
-    # this uses Evennia's manager method get_id().  # It returns a Character typeclass instance @py ObjectDB.objects.get_id(1).__class__ <<< Character# this uses the standard Django get() query.  # It returns a django database model instance. @py ObjectDB.objects.get(id=1).__class__ <<< <class 'src.objects.models.ObjectDB'>
+    # this uses Evennia's manager method get_id().  # It returns a Character typeclass instance @py ev.db_objects.get_id(1).__class__ <<< Character# this uses the standard Django get() query.  # It returns a django database model instance. @py ev.db_objects.get(id=1).__class__ <<< <class 'src.objects.models.ObjectDB'>
 
 Running a Python Parser outside the game
 ========================================
@@ -122,12 +116,13 @@ Go to the ``game`` directory and get into a new terminal.
 Your default Python intrepeter will start up, configured to be able to
 work with and import all modules of your Evennia installation. From here
 you can explore the database and test-run individual modules as desired.
-Not only does a fully featured Python interpreter like
+Most of the time you can get by with just the ``ev`` module though. A
+fully featured Python interpreter like
 `iPython <http://ipython.scipy.org/moin/>`_ allow you to work over
-several lines, it also has lots of other editing features, usch as
+several lines, but also has lots of other editing features, usch as
 tab-completion and ``__doc__``-string reading.
 
 ::
 
-    $ python manage.py shellIPython 0.10 -- An enhanced Interactive Python ...In [1]: from src.objects.models import ObjectDB In [2]: ObjectDB.objects.all() Out[3]: [<ObjectDB: Harry>, <ObjectDB: Limbo>, ...]
+    $ python manage.py shellIPython 0.10 -- An enhanced Interactive Python ...In [1]: import ev In [2]: ev.db_objects.all() Out[3]: [<ObjectDB: Harry>, <ObjectDB: Limbo>, ...]