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

Cleaned up Coding and style guides, improved contribs

Browse source
This commit is contained in:
Griatch 2022-11-25 19:47:32 +01:00
parent ce2d001e35
commit a77d568709
30 changed files with 1135 additions and 1360 deletions
Download patch file Download diff file Expand all files Collapse all files

86
docs/source/Coding/Debugging.md
View file

@ -1,12 +1,8 @@
# Debugging
Sometimes, an error is not trivial to resolve. A few simple `print` statements is not enough to find the cause of the issue. The traceback is not informative or even non-existing.
Sometimes, an error is not trivial to resolve. A few simple `print` statements is not enough to find
the cause of the issue. Running a *debugger* can then be very helpful and save a lot of time.
Debugging
means running Evennia under control of a special *debugger* program. This allows you to stop the
action at a given point, view the current state and step forward through the program to see how its
logic works.
Running a *debugger* can then be very helpful and save a lot of time. Debugging means running Evennia under control of a special *debugger* program. This allows you to stop the action at a given point, view the current state and step forward through the program to see how its logic works.
Evennia natively supports these debuggers:
@ -24,11 +20,8 @@ To run Evennia with the debugger, follow these steps:
```python
from evennia import set_trace;set_trace()
```
2. (Re-)start Evennia in interactive (foreground) mode with `evennia istart`. This is important -
without this step the debugger will not start correctly - it will start in this interactive
terminal.
3. Perform the steps that will trigger the line where you added the `set_trace()` call. The debugger
will start in the terminal from which Evennia was interactively started.
2. (Re-)start Evennia in interactive (foreground) mode with `evennia istart`. This is important - without this step the debugger will not start correctly - it will start in this interactive terminal.
3. Perform the steps that will trigger the line where you added the `set_trace()` call. The debugger will start in the terminal from which Evennia was interactively started.
The `evennia.set_trace` function takes the following arguments:
@ -37,8 +30,7 @@ The `evennia.set_trace` function takes the following arguments:
evennia.set_trace(debugger='auto', term_size=(140, 40))
```
Here, `debugger` is one of `pdb`, `pudb` or `auto`. If `auto`, use `pudb` if available, otherwise
use `pdb`. The `term_size` tuple sets the viewport size for `pudb` only (it's ignored by `pdb`).
Here, `debugger` is one of `pdb`, `pudb` or `auto`. If `auto`, use `pudb` if available, otherwise use `pdb`. The `term_size` tuple sets the viewport size for `pudb` only (it's ignored by `pdb`).
## A simple example using pdb
@ -71,9 +63,7 @@ class CmdTest(Command):
```
If you type `test` in your game, everything will freeze. You won't get any feedback from the game,
and you won't be able to enter any command (nor anyone else). It's because the debugger has started
in your console, and you will find it here. Below is an example with `pdb`.
If you type `test` in your game, everything will freeze. You won't get any feedback from the game, and you won't be able to enter any command (nor anyone else). It's because the debugger has started in your console, and you will find it here. Below is an example with `pdb`.
```
...
@ -83,13 +73,11 @@ in your console, and you will find it here. Below is an example with `pdb`.
```
`pdb` notes where it has stopped execution and, what line is about to be executed (in our case, `obj
= self.search(self.args)`), and ask what you would like to do.
`pdb` notes where it has stopped execution and, what line is about to be executed (in our case, `obj = self.search(self.args)`), and ask what you would like to do.
### Listing surrounding lines of code
When you have the `pdb` prompt `(Pdb)`, you can type in different commands to explore the code. The
first one you should know is `list` (you can type `l` for short):
When you have the `pdb` prompt `(Pdb)`, you can type in different commands to explore the code. The first one you should know is `list` (you can type `l` for short):
```
(Pdb) l
@ -107,18 +95,13 @@ first one you should know is `list` (you can type `l` for short):
(Pdb)
```
Okay, this didn't do anything spectacular, but when you become more confident with `pdb` and find
yourself in lots of different files, you sometimes need to see what's around in code. Notice that
there is a little arrow (`->`) before the line that is about to be executed.
Okay, this didn't do anything spectacular, but when you become more confident with `pdb` and find yourself in lots of different files, you sometimes need to see what's around in code. Notice that there is a little arrow (`->`) before the line that is about to be executed.
This is important: **about to be**, not **has just been**. You need to tell `pdb` to go on (we'll
soon see how).
This is important: **about to be**, not **has just been**. You need to tell `pdb` to go on (we'll soon see how).
### Examining variables
`pdb` allows you to examine variables (or really, to run any Python instruction). It is very useful
to know the values of variables at a specific line. To see a variable, just type its name (as if
you were in the Python interpreter:
`pdb` allows you to examine variables (or really, to run any Python instruction). It is very useful to know the values of variables at a specific line. To see a variable, just type its name (as if you were in the Python interpreter:
```
(Pdb) self
@ -158,9 +141,7 @@ AttributeError: "'CmdTest' object has no attribute 'search'"
(Pdb)
```
`Pdb` is complaining that you try to call the `search` method on a command... whereas there's no
`search` method on commands. The character executing the command is in `self.caller`, so we might
change our line:
`Pdb` is complaining that you try to call the `search` method on a command... whereas there's no `search` method on commands. The character executing the command is in `self.caller`, so we might change our line:
```python
obj = self.caller.search(self.args)
@ -168,19 +149,14 @@ obj = self.caller.search(self.args)
### Letting the program run
`pdb` is waiting to execute the same instruction... it provoked an error but it's ready to try
again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a
command. To tell `pdb` to terminate and keep on running the program, use the `continue` (or `c`)
command:
`pdb` is waiting to execute the same instruction... it provoked an error but it's ready to try again, just in case. We have fixed it in theory, but we need to reload, so we need to enter a command. To tell `pdb` to terminate and keep on running the program, use the `continue` (or `c`) command:
```
(Pdb) c
...
```
You see an error being caught, that's the error we have fixed... or hope to have. Let's reload the
game and try again. You need to run `evennia istart` again and then run `test` to get into the
command again.
You see an error being caught, that's the error we have fixed... or hope to have. Let's reload the game and try again. You need to run `evennia istart` again and then run `test` to get into the command again.
```
> .../mygame/commands/command.py(79)func()
@ -218,12 +194,11 @@ fix that bug too, it would be better):
...
```
Notice that you'll have an error in the game this time. Let's try with a valid parameter. I have
another character, `barkeep`, in this room:
Notice that you'll have an error in the game this time. Let's try with a valid parameter. I have another character, `barkeep`, in this room:
```test barkeep```
And again, the command freezes, and we have the debugger opened in the console.
And again, the command freezes, and we have the debugger opened in the console.
Let's execute this line right away:
@ -248,32 +223,16 @@ TypeError: 'get_display_name() takes exactly 2 arguments (1 given)'
(Pdb)
```
As an exercise, fix this error, reload and run the debugger again. Nothing better than some
experimenting!
As an exercise, fix this error, reload and run the debugger again. Nothing better than some experimenting!
Your debugging will often follow the same strategy:
1. Receive an error you don't understand.
2. Put a breaking point **BEFORE** the error occurs.
3. Run the code again and see the debugger open.
4. Run the program line by line,examining variables, checking the logic of instructions.
5. Continue and try again, each step a bit further toward the truth and the working feature.
### Stepping through a function
`n` is useful, but it will avoid stepping inside of functions if it can. But most of the time, when
we have an error we don't understand, it's because we use functions or methods in a way that wasn't
intended by the developer of the API. Perhaps using wrong arguments, or calling the function in a
situation that would cause a bug. When we have a line in the debugger that calls a function or
method, we can "step" to examine it further. For instance, in the previous example, when `pdb` was
about to execute `obj = self.caller.search(self.args)`, we may want to see what happens inside of
the `search` method.
To do so, use the `step` (or `s`) command. This command will show you the definition of the
function/method and you can then use `n` as before to see it line-by-line. In our little example,
stepping through a function or method isn't that useful, but when you have an impressive set of
commands, functions and so on, it might really be handy to examine some feature and make sure they
operate as planned.
3. Run `evennia istart`
4. Run the code again and see the debugger open.
5. Run the program line by line, examining variables, checking the logic of instructions.
6. Continue and try again, each step a bit further toward the truth and the working feature.
## Cheat-sheet of pdb/pudb commands
@ -292,5 +251,4 @@ this directly). |
| `<RETURN>` | Repeat the last command (don't type `n` repeatedly, just type it once and then press
`<RETURN>` to repeat it). |
If you want to learn more about debugging with Pdb, you will find an [interesting tutorial on that
topic here](https://pymotw.com/3/pdb/).
If you want to learn more about debugging with Pdb, you will find an [interesting tutorial on that topic here](https://pymotw.com/3/pdb/).