Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-16 21:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

More docstring

Browse source 
8 more files docstringed. A bit from everywere...
This commit is contained in:
tajmone 2015-03-09 18:34:56 +01:00 • committed by Griatch
parent 5256f4b7ad
commit a25ead9626
8 changed files with 154 additions and 145 deletions
Download patch file Download diff file Expand all files Collapse all files

22
evennia/contrib/email_login.py
View file

@ -4,7 +4,7 @@ Email-based login system
Evennia contrib - Griatch 2012
This is a variant of the login system that requires a email-adress
This is a variant of the login system that requires an email-address
instead of a username to login.
This used to be the default Evennia login before replacing it with a
@ -14,16 +14,18 @@ on it. The email is not strictly needed internally, nor is any
confirmation email sent out anyway).
Install is simple:
Installation is simple:
To your settings file, add/edit the line:
```python
CMDSET_UNLOGGEDIN = "contrib.email-login.UnloggedinCmdSet"
```
That's it. Reload the server and try to log in to see it.
The initial login "graphic" will still not mention email addresses
after this change. The login splash screen is taken from strings in
after this change. The login splashscreen is taken from strings in
the module given by settings.CONNECTION_SCREEN_MODULE.
"""
@ -60,7 +62,7 @@ class CmdUnconnectedConnect(MuxCommand):
Connect to the game.
Usage (at login screen):
connect <email> <password>
connect <email> <password>
Use the create command to first create an account before logging in.
"""
@ -71,8 +73,8 @@ class CmdUnconnectedConnect(MuxCommand):
def func(self):
"""
Uses the Django admin api. Note that unlogged-in commands
have a unique position in that their func() receives
a session object instead of a source_object like all
have a unique position in that their `func()` receives
a session object instead of a `source_object` like all
other types of logged-in commands (this is because
there is no object yet before the player has logged in)
"""
@ -120,7 +122,7 @@ class CmdUnconnectedCreate(MuxCommand):
Create a new account.
Usage (at login screen):
create \"playername\" <email> <password>
create \"playername\" <email> <password>
This creates a new player account.
@ -133,7 +135,7 @@ class CmdUnconnectedCreate(MuxCommand):
"""
The parser must handle the multiple-word player
name enclosed in quotes:
connect "Long name with many words" my@myserv.com mypassw
connect "Long name with many words" my@myserv.com mypassw
"""
super(CmdUnconnectedCreate, self).parse()
@ -261,7 +263,7 @@ its and @/./+/-/_ only.") # this echoes the restrictions made by django's auth m
class CmdUnconnectedQuit(MuxCommand):
"""
We maintain a different version of the quit command
We maintain a different version of the `quit` command
here for unconnected players for the sake of simplicity. The logged in
version is a bit more complicated.
"""
@ -278,7 +280,7 @@ class CmdUnconnectedQuit(MuxCommand):
class CmdUnconnectedLook(MuxCommand):
"""
This is an unconnected version of the look command for simplicity.
This is an unconnected version of the `look` command for simplicity.
This is called by the server and kicks everything in gear.
All it does is display the connect screen.

71
evennia/contrib/extended_room.py
View file

@ -4,7 +4,7 @@ Extended Room
Evennia Contribution - Griatch 2012
This is an extended Room typeclass for Evennia. It is supported
by an extended Look command and an extended @desc command, also
by an extended `Look` command and an extended `@desc` command, also
in this module.
@ -13,17 +13,17 @@ Features:
1) Time-changing description slots
This allows to change the full description text the room shows
depending on larger time variations. Four seasons - spring, summer,
autumn and winter are used by default). The season is calculated
depending on larger time variations. Four seasons (spring, summer,
autumn and winter) are used by default. The season is calculated
on-demand (no Script or timer needed) and updates the full text block.
There is also a general description which is used as fallback if
one or more of the seasonal descriptions are not set when their
time comes.
An updated @desc command allows for setting seasonal descriptions.
An updated `@desc` command allows for setting seasonal descriptions.
The room uses the evennia.utils.gametime.GameTime global script. This is
The room uses the `evennia.utils.gametime.GameTime` global script. This is
started by default, but if you have deactivated it, you need to
supply your own time keeping mechanism.
@ -32,20 +32,20 @@ supply your own time keeping mechanism.
Within each seasonal (or general) description text, you can also embed
time-of-day dependent sections. Text inside such a tag will only show
during that particular time of day. The tags looks like <timeslot> ...
</timeslot>. By default there are four timeslots per day - morning,
during that particular time of day. The tags looks like `<timeslot> ...
</timeslot>`. By default there are four timeslots per day - morning,
afternoon, evening and night.
3) Details
The Extended Room can be "detailed" with special keywords. This makes
use of a special Look command. Details are "virtual" targets to look
use of a special `Look` command. Details are "virtual" targets to look
at, without there having to be a database object created for it. The
Details are simply stored in a dictionary on the room and if the look
command cannot find an object match for a "look <target>" command it
command cannot find an object match for a `look <target>` command it
will also look through the available details at the current location
if applicable. An extended @desc command is used to set details.
if applicable. An extended `@desc` command is used to set details.
4) Extra commands
@ -53,17 +53,17 @@ if applicable. An extended @desc command is used to set details.
CmdExtendedLook - look command supporting room details
CmdExtendedDesc - @desc command allowing to add seasonal descs and details,
as well as listing them
CmdGameTime - A simple "time" command, displaying the current
CmdGameTime - A simple `time` command, displaying the current
time and season.
Installation/testing:
1) Add CmdExtendedLook, CmdExtendedDesc and CmdGameTime to the default cmdset
(see wiki how to do this).
2) @dig a room of type contrib.extended_room.ExtendedRoom (or make it the
1) Add `CmdExtendedLook`, `CmdExtendedDesc` and `CmdGameTime` to the default `cmdset`
(see Wiki for how to do this).
2) `@dig` a room of type `contrib.extended_room.ExtendedRoom` (or make it the
default room type)
3) Use @desc and @detail to customize the room, then play around!
3) Use `@desc` and `@detail` to customize the room, then play around!
"""
@ -102,7 +102,7 @@ DAY_BOUNDARIES = (0, 6 / 24.0, 12 / 24.0, 18 / 24.0)
class ExtendedRoom(DefaultRoom):
"""
This room implements a more advanced look functionality depending on
This room implements a more advanced `look` functionality depending on
time. It also allows for "details", together with a slightly modified
look command.
"""
@ -126,7 +126,7 @@ class ExtendedRoom(DefaultRoom):
def get_time_and_season(self):
"""
Calculate the current time and season ids
Calculate the current time and season ids.
"""
# get the current time as parts of year and parts of day
# returns a tuple (years,months,weeks,days,hours,minutes,sec)
@ -158,7 +158,7 @@ class ExtendedRoom(DefaultRoom):
def replace_timeslots(self, raw_desc, curr_time):
"""
Filter so that only time markers <timeslot>...</timeslot> of the
Filter so that only time markers `<timeslot>...</timeslot>` of the
correct timeslot remains in the description.
"""
if raw_desc:
@ -173,8 +173,8 @@ class ExtendedRoom(DefaultRoom):
"""
This will attempt to match a "detail" to look for in the room. A detail
is a way to offer more things to look at in a room without having to
add new objects. For this to work, we require a custom look command that
allows for "look <detail>" - the look command should defer to this
add new objects. For this to work, we require a custom `look` command that
allows for `look <detail>` - the look command should defer to this
method on the current location (if it exists) before giving up on
finding the target.
@ -298,36 +298,39 @@ class CmdExtendedLook(default_cmds.CmdLook):
class CmdExtendedDesc(default_cmds.CmdDesc):
"""
@desc - describe an object or room
`@desc` - describe an object or room.
Usage:
@desc[/switch] [<obj> =] <description>
@detail[/del] [<key> = <description>]
Switches for @desc:
spring - set description for <season> in current room
Switches for `@desc`:
spring - set description for <season> in current room.
summer
autumn
winter
Switch for @detail:
del - delete a named detail
Switch for `@detail`:
del - delete a named detail.
Sets the "desc" attribute on an object. If an object is not given,
describe the current room.
The alias @detail allows to assign a "detail" (a non-object
target for the look command) to the current room (only).
The alias `@detail` allows to assign a "detail" (a non-object
target for the `look` command) to the current room (only).
You can also embed special time markers in your room description, like this:
<night>In the darkness, the forest looks foreboding.</night>. Text
marked this way will only display when the server is truly at the given
time slot. The available times
are night, morning, afternoon and evening.
Note that @detail, seasons and time-of-day slots only works on rooms in this
version of the @desc command.
```
<night>In the darkness, the forest looks foreboding.</night>.
```
Text marked this way will only display when the server is truly at the given
timeslot. The available times are night, morning, afternoon and evening.
Note that `@detail`, seasons and time-of-day slots only works on rooms in this
version of the `@desc` command.
"""
aliases = ["@describe", "@detail"]
@ -434,7 +437,7 @@ class CmdGameTime(default_cmds.MuxCommand):
Check the game time
Usage:
time
time
Shows the current in-game time and season.
"""

60
evennia/contrib/lineeditor.py
View file

@ -9,17 +9,17 @@ in-game. The editor mimics the command mechanisms of the VI editor as
far as possible.
Features of the editor:
undo/redo
edit/replace on any line of the buffer
search&replace text anywhere in buffer
formatting of buffer, or selection, to certain width + indentations
allow to echo the input or not depending on your client.
undo/redo.
edit/replace on any line of the buffer.
search&replace text anywhere in buffer.
formatting of buffer, or selection, to certain width + indentations.
allow to echo the input or not, depending on your client.
Whereas the editor is intended to be called from other commands that
requires more elaborate text editing of data, there is also a
stand-alone editor command for editing Attributes at the end of this
module. To use it just import and add it to your default cmdset.
module. To use it just import and add it to your default `cmdset`.
"""
@ -49,13 +49,13 @@ class CmdEditorBase(Command):
Handles pre-parsing
Editor commands are on the form
:cmd [li] [w] [txt]
:cmd [li] [w] [txt]
Where all arguments are optional.
li - line number (int), starting from 1. This could also
be a range given as <l>:<l>
w - word(s) (string), could be encased in quotes.
txt - extra text (string), could be encased in quotes
li - line number (int), starting from 1. This could also
be a range given as <l>:<l>.
w - word(s) (string), could be encased in quotes.
txt - extra text (string), could be encased in quotes.
"""
linebuffer = []
@ -152,7 +152,9 @@ class CmdLineInput(CmdEditorBase):
aliases = [CMD_NOINPUT]
def func(self):
"Adds the line without any formatting changes."
"""
Adds the line without any formatting changes.
"""
# add a line of text
if not self.editor.buffer:
buf = self.args
@ -406,23 +408,23 @@ class LineEditor(object):
quitfunc=None, quitfunc_args=None,
key=""):
"""
caller - who is using the editor
caller - who is using the editor.
loadfunc - this will be called as func(*loadfunc_args) when the
loadfunc - this will be called as `func(*loadfunc_args)` when the
editor is first started, e.g. for pre-loading text into it.
loadfunc_args - optional tuple of arguments to supply to loadfunc.
savefunc - this will be called as func(*savefunc_args) when the
loadfunc_args - optional tuple of arguments to supply to `loadfunc`.
savefunc - this will be called as `func(*savefunc_args)` when the
save-command is given and is used to actually determine
where/how result is saved. It should return True if save
where/how result is saved. It should return `True` if save
was successful and also handle any feedback to the user.
savefunc_args - optional tuple of arguments to supply to savefunc.
quitfunc - this will optionally e called as func(*quitfunc_args) when
the editor is exited. If defined, it should handle all
wanted feedback to the user.
quitfunc_args - optional tuple of arguments to supply to quitfunc.
savefunc_args - optional tuple of arguments to supply to `savefunc`.
quitfunc - this will optionally be called as `func(*quitfunc_args)`
when the editor is exited. If defined, it should handle
all wanted feedback to the user.
quitfunc_args - optional tuple of arguments to supply to `quitfunc`.
key = an optional key for naming this session (such as which attribute
is being edited)
is being edited).
"""
self.key = key
self.caller = caller
@ -492,7 +494,9 @@ class LineEditor(object):
self.unsaved = True
def quit(self):
"Cleanly exit the editor."
"""
Cleanly exit the editor.
"""
if self.quitfunc:
# call quit function hook if available
try:
@ -508,7 +512,7 @@ class LineEditor(object):
def save_buffer(self):
"""
Saves the content of the buffer. The 'quitting' argument is a bool
Saves the content of the buffer. The 'quitting' argument is a bool
indicating whether or not the editor intends to exit after saving.
"""
if self.unsaved:
@ -549,7 +553,7 @@ class LineEditor(object):
"""
This displays the line editor buffer, or selected parts of it.
If buf is set and is not the full buffer, offset should define
If `buf` is set and is not the full buffer, `offset` should define
the starting line number, to get the linenum display right.
"""
if buf == None:
@ -626,10 +630,10 @@ class LineEditor(object):
class CmdEditor(Command):
"""
start editor
Start editor
Usage:
@editor <obj>/<attr>
@editor <obj>/<attr>
This will start Evennia's powerful line editor to edit an
Attribute. The editor has a host of commands on its own. Use :h

70
evennia/game_template/commands/command.py
View file

@ -13,9 +13,9 @@ class Command(BaseCommand):
"""
Inherit from this if you want to create your own
command styles. Note that Evennia's default commands
use MuxCommand instead (next in this module)
use MuxCommand instead (next in this module).
Note that the class's __doc__ string (this text) is
Note that the class's `__doc__` string (this text) is
used by Evennia to create the automatic help entry for
the command, so make sure to document consistently here.
@ -38,15 +38,15 @@ class Command(BaseCommand):
def at_pre_cmd(self):
"""
This hook is called before self.parse() on all commands
This hook is called before `self.parse()` on all commands.
"""
pass
def parse(self):
"""
This method is called by the cmdhandler once the command name
This method is called by the `cmdhandler` once the command name
has been identified. It creates a new set of member variables
that can be later accessed from self.func() (see below)
that can be later accessed from `self.func()` (see below).
The following variables are available to us:
# class variables:
@ -56,72 +56,72 @@ class Command(BaseCommand):
self.locks - lock string for this command ("cmd:all()")
self.help_category - overall category of command ("General")
# added at run-time by cmdhandler:
# added at run-time by `cmdhandler`:
self.caller - the object calling this command
self.cmdstring - the actual command name used to call this
(this allows you to know which alias was used,
for example)
self.args - the raw input; everything following self.cmdstring.
self.cmdset - the cmdset from which this command was picked. Not
often used (useful for commands like 'help' or to
list all available commands etc)
self.args - the raw input; everything following `self.cmdstring`.
self.cmdset - the `cmdset` from which this command was picked. Not
often used (useful for commands like `help` or to
list all available commands etc).
self.obj - the object on which this command was defined. It is often
the same as self.caller.
the same as `self.caller`.
"""
pass
def func(self):
"""
This is the hook function that actually does all the work. It is called
by the cmdhandler right after self.parser() finishes, and so has access
to all the variables defined therein.
by the `cmdhandler` right after `self.parser()` finishes, and so has access
to all the variables defined therein.
"""
self.caller.msg("Command called!")
def at_post_cmd(self):
"""
This hook is called after self.func().
This hook is called after `self.func()`.
"""
pass
class MuxCommand(default_cmds.MuxCommand):
"""
This sets up the basis for a Evennia's 'MUX-like' command
style. The idea is that most other Mux-related commands should
This sets up the basis for Evennia's 'MUX-like' command style.
The idea is that most other Mux-related commands should
just inherit from this and don't have to implement parsing of
their own unless they do something particularly advanced.
A MUXCommand command understands the following possible syntax:
name[ with several words][/switch[/switch..]] arg1[,arg2,...] [[=|,] arg[,..]]
name[ with several words][/switch[/switch..]] arg1[,arg2,...] [[=|,] arg[,..]]
The 'name[ with several words]' part is already dealt with by the
cmdhandler at this point, and stored in self.cmdname. The rest is stored
in self.args.
The `name[ with several words]` part is already dealt with by the
`cmdhandler` at this point, and stored in `self.cmdname`. The rest is stored
in `self.args`.
The MuxCommand parser breaks self.args into its constituents and stores them
The MuxCommand parser breaks `self.args` into its constituents and stores them
in the following variables:
self.switches = optional list of /switches (without the /)
self.raw = This is the raw argument input, including switches
self.args = This is re-defined to be everything *except* the switches
self.lhs = Everything to the left of = (lhs:'left-hand side'). If
no = is found, this is identical to self.args.
self.rhs: Everything to the right of = (rhs:'right-hand side').
If no '=' is found, this is None.
self.lhslist - self.lhs split into a list by comma
self.rhslist - list of self.rhs split into a list by comma
self.arglist = list of space-separated args (including '=' if it exists)
self.switches = optional list of /switches (without the /).
self.raw = This is the raw argument input, including switches.
self.args = This is re-defined to be everything *except* the switches.
self.lhs = Everything to the left of `=` (lhs:'left-hand side'). If
no `=` is found, this is identical to `self.args`.
self.rhs: Everything to the right of `=` (rhs:'right-hand side').
If no `=` is found, this is `None`.
self.lhslist - `self.lhs` split into a list by comma.
self.rhslist - list of `self.rhs` split into a list by comma.
self.arglist = list of space-separated args (including `=` if it exists).
All args and list members are stripped of excess whitespace around the
strings, but case is preserved.
"""
All args and list members are stripped of excess whitespace around the
strings, but case is preserved.
"""
def func(self):
"""
This is the hook function that actually does all the work. It is called
by the cmdhandler right after self.parser() finishes, and so has access
by the `cmdhandler` right after `self.parser()` finishes, and so has access
to all the variables defined therein.
"""
# this can be removed in your child class, it's just

20
evennia/game_template/commands/default_cmdsets.py
View file

@ -6,11 +6,11 @@ can be part of any number of cmdsets and cmdsets can be added/removed
and merged onto entities at runtime.
To create new commands to populate the cmdset, see
commands/command.py.
`commands/command.py`.
This module wrap the default command sets of Evennia; overload them
This module wraps the default command sets of Evennia; overloads them
to add/remove commands from the default lineup. You can create your
own cmdsets by inheriting from them or directly from evennia.CmdSet.
own cmdsets by inheriting from them or directly from `evennia.CmdSet`.
"""
@ -18,9 +18,9 @@ from evennia import default_cmds
class CharacterCmdSet(default_cmds.CharacterCmdSet):
"""
The CharacterCmdSet contains general in-game commands like look,
get etc available on in-game Character objects. It is merged with
the PlayerCmdSet when a Player puppets a Character.
The `CharacterCmdSet` contains general in-game commands like `look`,
`get`, etc available on in-game Character objects. It is merged with
the `PlayerCmdSet` when a Player puppets a Character.
"""
key = "DefaultCharacter"
@ -37,9 +37,9 @@ class CharacterCmdSet(default_cmds.CharacterCmdSet):
class PlayerCmdSet(default_cmds.PlayerCmdSet):
"""
This is the cmdset available to the Player at all times. It is
combined with the CharacterCmdSet when the Player puppets a
combined with the `CharacterCmdSet` when the Player puppets a
Character. It holds game-account-specific commands, channel
commands etc.
commands, etc.
"""
key = "DefaultPlayer"
@ -56,7 +56,7 @@ class PlayerCmdSet(default_cmds.PlayerCmdSet):
class UnloggedinCmdSet(default_cmds.UnloggedinCmdSet):
"""
Command set available to the Session before being logged in. This
holds commands like creating a new account, logging in etc.
holds commands like creating a new account, logging in, etc.
"""
key = "DefaultUnloggedin"
@ -82,7 +82,7 @@ class SessionCmdSet(default_cmds.SessionCmdSet):
This is the only method defined in a cmdset, called during
its creation. It should populate the set with command instances.
As and example we just add the empty base Command object.
As and example we just add the empty base `Command` object.
It prints some info.
"""
super(SessionCmdSet, self).at_cmdset_creation()

20
evennia/game_template/typeclasses/exits.py
View file

@ -11,24 +11,24 @@ from evennia import DefaultExit
class Exit(DefaultExit):
"""
Exits are connectors between rooms. Exits are normal Objects except
they defines the 'destination' property. It also does work in the
they defines the `destination` property. It also does work in the
following methods:
basetype_setup() - sets default exit locks (to change, use at_object_creation instead)
basetype_setup() - sets default exit locks (to change, use `at_object_creation` instead).
at_cmdset_get(**kwargs) - this is called when the cmdset is accessed and should
rebuild the Exit cmdset along with a command matching the name
of the Exit object. Conventionally, a kwarg 'force_init'
of the Exit object. Conventionally, a kwarg `force_init`
should force a rebuild of the cmdset, this is triggered
by the @alias command when aliases are changed.
by the `@alias` command when aliases are changed.
at_failed_traverse() - gives a default error message ("You cannot
go there") if exit traversal fails and an
attribute err_traverse is not defined.
attribute `err_traverse` is not defined.
Relevant hooks to overload (compared to other types of Objects):
at_before_traverse(traveller) - called just before traversing
at_after_traverse(traveller, source_loc) - called just after traversing
at_failed_traverse(traveller) - called if traversal failed for some reason. Will
not be called if the attribute 'err_traverse' is
defined, in which case that will simply be echoed.
at_before_traverse(traveller) - called just before traversing.
at_after_traverse(traveller, source_loc) - called just after traversing.
at_failed_traverse(traveller) - called if traversal failed for some reason. Will
not be called if the attribute `err_traverse` is
defined, in which case that will simply be echoed.
"""
pass

8
evennia/game_template/world/batch_cmds.ev
View file

@ -14,13 +14,13 @@
# - every command must be separated by at least one line of comment.
#
# All supplied commands are given as normal, on their own line
# and accepts arguments in any format up until the first next
# comment line begins. Extra whitespace is removed; an empty
# and accept arguments in any format up until the first next
# comment line begins. Extra whitespace is removed; an empty
# line in a command definition translates into a newline.
#
# See evennia/contrib/tutorial_examples/batch_cmds.ev for
# See `evennia/contrib/tutorial_examples/batch_cmds.ev` for
# an example of a batch-command code. See also the batch-code
# system for loading python-code in this way.
# system for loading python-code this way.
#

28
evennia/game_template/world/prototypes.py
View file

@ -2,7 +2,7 @@
Prototypes
A prototype is a simple way to create individualized instances of a
given Typeclass. For example, you might have a Sword typeclass that
given `Typeclass`. For example, you might have a Sword typeclass that
implements everything a Sword would need to do. The only difference
between different individual Swords would be their key, description
and some Attributes. The Prototype system allows to create a range of
@ -12,27 +12,27 @@ Sabres and all Broadswords some common properties). Note that bigger
variations, such as custom commands or functionality belong in a
hierarchy of typeclasses instead.
Example prototypes are read by the @spawn command but is also easily
available to use from code via evennia.spawn or evennia.utils.spawner.
Example prototypes are read by the `@spawn` command but is also easily
available to use from code via `evennia.spawn` or `evennia.utils.spawner`.
Each prototype should be a dictionary. Use the same name as the
variable to refer to other prototypes.
Possible keywords are:
prototype - string pointing to parent prototype of this structure
key - string, the main object identifier
typeclass - string, if not set, will use settings.BASE_OBJECT_TYPECLASS
location - this should be a valid object or #dbref
home - valid object or #dbref
destination - only valid for exits (object or dbref)
prototype - string pointing to parent prototype of this structure.
key - string, the main object identifier.
typeclass - string, if not set, will use `settings.BASE_OBJECT_TYPECLASS`.
location - this should be a valid object or #dbref.
home - valid object or #dbref.
destination - only valid for exits (object or dbref).
permissions - string or list of permission strings
locks - a lock-string
aliases - string or list of strings
permissions - string or list of permission strings.
locks - a lock-string.
aliases - string or list of strings.
ndb_<name> - value of a nattribute (the "ndb_" part is ignored)
ndb_<name> - value of a nattribute (the "ndb_" part is ignored).
any other keywords are interpreted as Attributes and their values.
See the @spawn command and evennia.utils.spawner for more info.
See the `@spawn` command and `evennia.utils.spawner` for more info.
"""