docs: Adding missing rest pages to mercurial.

docs/sphinx/source/wiki/evAPI.rst

@@ -0,0 +1,105 @@
+\`ev\` - Evennia's flat API
+===========================
+
+Evennia consists of many components, some of which interact in rather
+complex ways. One such example is the Typeclass system which is
+implemented across four different folders in ``src/``. This is for
+efficiency reasons and to avoid code duplication, but it means that it
+can be a bit of a hurdle to understand just what connects to what and
+which properties are actually available/inherited on a particular game
+entity you want to use.
+
+Evennia's ``ev`` API (Application Programming Interface) tries to help
+with this. ``ev.py`` sits in evennia's root directory which means you
+can import it from your code simply with ``import ev``. The ``ev``
+module basically implements shortcuts to the innards of ``src/``. The
+goal is to give a very "flat" structure (as opposed to a deeply nested
+one). Not only is this a Python recommendation, it also makes it much
+easier to see what you have.
+
+Exploring \`ev\`
+----------------
+
+To check out evennia interactively, it's recommended you use a more
+advanced Python interpreter, like `ipython <http://ipython.org/>`_. With
+ipython you can easily read module headers and help texts as well as
+list possible completions.
+
+Start a python interactive shell, then get ``ev``:
+
+::
+
+     import ev
+
+In ipython we can now do for example ``ev?`` to read the API's help
+text. Using eg. ``ev.Object?`` will read the documentation for the
+``Object`` typeclass. Use ``??`` to see source code. Tab on ``ev.`` to
+see what ``ev`` contains.
+
+Some highlights
+---------------
+
+-  ``Object, Player, Script, Room, Character, Exit`` - direct links to
+   the most common base classes in Evennia.
+-  ``search_*`` - shortcuts to the search functions in
+   ``src.utils.search``, such as ``search_object()`` or
+   ``search_script()``
+-  ``create_*`` - are convenient links to all object-creation functions.
+   Note that all Typeclassed objects *must* be created with methods such
+   as these (or their parents in ``src.utils.create``) to make
+   Typeclasses work.
+-  ``managers`` - this is a container object that groups shortcuts to
+   initiated versions of Evennia's django *managers*. So
+   ``managers.objects`` is in fact equivalent to ``ObjectDB.objects``
+   and you can do ``managers.objects.all()`` to get a list of all
+   database objects. The managers allows to explore the database in
+   various ways. To use, do ``from ev import manager`` and access the
+   desired manager on the imported ``managers`` object.
+-  default\_cmds - this is a container on ``ev`` that groups all default
+   commands and command sets under itself. Do
+   ``from ev import default_cmds`` and you can then access any default
+   command from the imported ``default_cmds`` object.
+-  ``utils, logger, gametime, ansi`` are various utilities. Especially
+   utils contains many useful functions described
+   `here <CodingUtils.html>`_.
+-  ``syscmdkeys`` is a container that holds all the system-command keys
+   needed to define system commands. Similar to the ``managers``
+   container, you import this and can then access the keys on the
+   imported ``syscmdkeys`` object.
+
+To remember when importing from \`ev\`
+--------------------------------------
+
+Properties on ``ev`` are *not* modules in their own right. They are just
+shortcut properties stored in the ``ev.py`` module. That means that you
+cannot use dot-notation to ``import`` nested module-names over ``ev``.
+The rule of thumb is that you cannot use ``import`` for more than one
+level down. Hence you can do
+
+::
+
+     import ev
+     print ev.default_cmds.CmdLook
+
+or import one level down
+
+::
+
+     from ev import default_cmds
+     print default_cmds.CmdLook
+
+but you *cannot* import two levels down
+
+::
+
+     from ev.default_cmds import CmdLook # error!
+
+This will give you an ``ImportError`` telling you that the module
+``default_cmds`` cannot be found. This is not so strange -
+``default_cmds`` is just a variable name in the ``ev.py`` module, it
+does not exist outside of it.
+
+As long as you keep this in mind, you should be fine. If you really want
+full control over which level of package you import you can always
+bypass ``ev`` and import directly from ``src/``. If so, look at
+``ev.py`` to see where it imports from.