6. Overview of the Evennia library

API

API stands for Application Programming Interface, a description for how to access the resources of a program or library.

There are several good ways to explore the Evennia library.

• This documentation contains the Evennia-API docs, generated automatically from sources. Try clicking through to a few entries - once you get deep enough you’ll see full descriptions of each component along with their documentation. You can also click [source] to see the full Python source code for each thing.

• There are separate doc pages for each component if you want more detailed explanations.

• You can browse the evennia repository on github. This is exactly what you can download from us.

• Finally, you can clone the evennia repo to your own computer and read the sources. This is necessary if you want to really understand what’s going on, or help with Evennia’s development. See the extended install instructions if you want to do this.

6.1. Where is it?

If Evennia is installed, you can import from it simply with

import evennia
from evennia import some_module
from evennia.some_module.other_module import SomeClass

and so on.

If you installed Evennia with pip install, the library folder will be installed deep inside your Python installation; you are better off looking at it on github. If you cloned it, you should have an evennia folder to look into.

You’ll find this being the outermost structure:

evennia/
    bin/
    CHANGELOG.md
    ...
    ...
    docs/
    evennia/

This outer layer is for Evennia’s installation and package distribution. That internal folder evennia/evennia/ is the actual library, the thing covered by the API auto-docs and what you get when you do import evennia.

The evennia/docs/ folder contains the sources for this documentation. See contributing to the docs if you want to learn more about how this works.

This is the structure of the Evennia library:

• evennia

  • __init__.py - The “flat API” of Evennia resides here.

  • settings_default.py - Root settings of Evennia. Copy settings from here to mygame/server/settings.py file.

  • commands/ - The command parser and handler.

    • default/ - The default commands and cmdsets.

  • comms/ - Systems for communicating in-game.

  • contrib/ - Optional plugins too game-specific for core Evennia.

  • game_template/ - Copied to become the “game directory” when using evennia --init.

  • help/ - Handles the storage and creation of help entries.

  • locale/ - Language files (i18n).

  • locks/ - Lock system for restricting access to in-game entities.

  • objects/ - In-game entities (all types of items and Characters).

  • prototypes/ - Object Prototype/spawning system and OLC menu

  • accounts/ - Out-of-game Session-controlled entities (accounts, bots etc)

  • scripts/ - Out-of-game entities equivalence to Objects, also with timer support.

  • server/ - Core server code and Session handling.

    • portal/ - Portal proxy and connection protocols.

  • typeclasses/ - Abstract classes for the typeclass storage and database system.

  • utils/ - Various miscellaneous useful coding resources.

  • web/ - Web resources and webserver. Partly copied into game directory on initialization.

init.py

The __init__.py file is a special Python filename used to represent a Python ‘package’. When you import evennia on its own, you import this file. When you do evennia.foo Python will first look for a property .foo in __init__.py and then for a module or folder of that name in the same location.

While all the actual Evennia code is found in the various folders, the __init__.py represents the entire package evennia. It contains “shortcuts” to code that is actually located elsewhere. Most of these shortcuts are listed if you scroll down a bit on the Evennia-API page.

6.2. An example of exploring the library

In the previous lesson we took a brief look at mygame/typeclasses/objects as an example of a Python module. Let’s open it again.

"""
module docstring
"""
from evennia import DefaultObject

class Object(DefaultObject):
    """
    class docstring
    """
    pass

We have the Object class, which inherits from DefaultObject. Near the top of the module is this line:

from evennia import DefaultObject

We want to figure out just what this DefaultObject offers. Since this is imported directly from evennia, we are actually importing from evennia/__init__.py.

Look at Line 160 of evennia/__init__.py and you’ll find this line:

from .objects.objects import DefaultObject

Relative and absolute imports

The first full-stop in from .objects.objects ... means that we are importing from the current location. This is called a relative import. By comparison, from evennia.objects.objects is an absolute import. In this particular case, the two would give the same result.

You can also look at the right section of the API frontpage and click through to the code that way.

The fact that DefaultObject is imported into __init__.py here is what makes it possible to also import it as from evennia import DefaultObject even though the code for the class is not actually here.

So to find the code for DefaultObject we need to look in evennia/objects/objects.py. Here’s how to look it up in the docs:

1. Open the API frontpage

2. Locate the link to evennia.objects.objects and click on it.

3. You are now in the python module. Scroll down (or search in your web browser) to find the DefaultObject class.

4. You can now read what this does and what methods are on it. If you want to see the full source, click the [source] link next to it.

6.3. Conclusions

This is an important lesson. It teaches you how to find information for yourself. Knowing how to follow the class inheritance tree and navigate to things you need is a big part in learning a new library like Evennia.

Next we’ll start to make use of what we have learned so far and combine it with the building blocks provided by Evennia.