diff --git a/evennia/contrib/email_login.py b/evennia/contrib/email_login.py index 0a581ad82f..6cd319dae6 100644 --- a/evennia/contrib/email_login.py +++ b/evennia/contrib/email_login.py @@ -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 + connect 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\" + create \"playername\" 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. diff --git a/evennia/contrib/extended_room.py b/evennia/contrib/extended_room.py index 076e8fb1f5..6ba177a190 100644 --- a/evennia/contrib/extended_room.py +++ b/evennia/contrib/extended_room.py @@ -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 ... -. By default there are four timeslots per day - morning, +during that particular time of day. The tags looks like ` ... +`. 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 " command it +command cannot find an object match for a `look ` 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 ... of the + Filter so that only time markers `...` 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 " - the look command should defer to this + add new objects. For this to work, we require a custom `look` command that + allows for `look ` - 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] [ =] @detail[/del] [ = ] - Switches for @desc: - spring - set description for in current room + Switches for `@desc`: + spring - set description for 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: - In the darkness, the forest looks foreboding.. 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. + ``` + In the darkness, the forest looks foreboding.. + ``` + + 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. """ diff --git a/evennia/contrib/lineeditor.py b/evennia/contrib/lineeditor.py index 75fc9859a2..6a4884c97c 100644 --- a/evennia/contrib/lineeditor.py +++ b/evennia/contrib/lineeditor.py @@ -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 : - 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 :. + 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 / + @editor / This will start Evennia's powerful line editor to edit an Attribute. The editor has a host of commands on its own. Use :h diff --git a/evennia/game_template/commands/command.py b/evennia/game_template/commands/command.py index 42e7788867..e53686a79a 100644 --- a/evennia/game_template/commands/command.py +++ b/evennia/game_template/commands/command.py @@ -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 diff --git a/evennia/game_template/commands/default_cmdsets.py b/evennia/game_template/commands/default_cmdsets.py index e9c125decb..e46330c56f 100644 --- a/evennia/game_template/commands/default_cmdsets.py +++ b/evennia/game_template/commands/default_cmdsets.py @@ -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() diff --git a/evennia/game_template/typeclasses/exits.py b/evennia/game_template/typeclasses/exits.py index 212ca970a5..bb48b1cc06 100644 --- a/evennia/game_template/typeclasses/exits.py +++ b/evennia/game_template/typeclasses/exits.py @@ -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 diff --git a/evennia/game_template/world/batch_cmds.ev b/evennia/game_template/world/batch_cmds.ev index 1513e66964..3bd0c21c5d 100644 --- a/evennia/game_template/world/batch_cmds.ev +++ b/evennia/game_template/world/batch_cmds.ev @@ -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. # diff --git a/evennia/game_template/world/prototypes.py b/evennia/game_template/world/prototypes.py index 85f750fd53..58280deace 100644 --- a/evennia/game_template/world/prototypes.py +++ b/evennia/game_template/world/prototypes.py @@ -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_ - value of a nattribute (the "ndb_" part is ignored) + ndb_ - 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. """