mirror of
https://github.com/evennia/evennia.git
synced 2026-03-21 15:26:30 +01:00
Minor updates
This commit is contained in:
Griatch
parent
c982f7bf80
commit
284a20cfd9
2 changed files with 58 additions and 44 deletions
|
|
@ -5,7 +5,7 @@ follow the guidelines outlined in [Python PEP 8][pep8]. Keeping the code style
|
|||
uniform makes it much easier for people to collaborate and read the
|
||||
code.
|
||||
|
||||
A good way to check if your code follows PEP8 is to use the [PEP8 tool][pep8tool]
|
||||
A good way to check if your code follows PEP8 is to use the [PEP8 tool][pep8tool]
|
||||
on your sources.
|
||||
|
||||
## A quick list of code style points
|
||||
|
|
@ -24,7 +24,7 @@ on your sources.
|
|||
- Evennia src/ modules
|
||||
- Evennia game/ modules
|
||||
- Evennia 'ev' API imports
|
||||
* All modules, classes, functions and modules should have doc
|
||||
* All modules, classes, functions and modules should have doc
|
||||
strings formatted as described below
|
||||
|
||||
## Doc strings
|
||||
|
|
@ -32,11 +32,11 @@ on your sources.
|
|||
All modules, classes, functions and methods should have docstrings
|
||||
formatted with [Google style][googlestyle] -inspired indents, using
|
||||
[Markdown][githubmarkdown] formatting where needed. Evennia's `api2md`
|
||||
parser will use this to create pretty API documentation.
|
||||
parser will use this to create pretty API documentation.
|
||||
|
||||
> Note that far from all sources are currently formatted using the
|
||||
> consistent style listed here. This is something that is being
|
||||
> worked on and any help to convert existing docs are appreciated.
|
||||
> worked on and any help to convert existing docs are appreciated.
|
||||
> We also don't support all forms of the google style syntax, going
|
||||
> for a limited and more restricted set for consistency.
|
||||
|
||||
|
|
@ -46,28 +46,34 @@ Modules should all start with at least a few lines of docstring at
|
|||
their top describing the contents and purpose of the module.
|
||||
Sectioning should not be used - the auto-api will create this
|
||||
automatically. Otherwise markdown should be used as needed to format
|
||||
the text.
|
||||
the text.
|
||||
|
||||
Example of module docstring (top of file):
|
||||
|
||||
```python
|
||||
"""
|
||||
This module handles the creation of `Objects` that
|
||||
This module handles the creation of `Objects` that
|
||||
are useful in the game ...
|
||||
|
||||
"""
|
||||
```
|
||||
|
||||
Code examples should use [multi-line syntax highlighting][markdown-hilight] to mark
|
||||
multi-line code blocks, using the "python" identifier. Just indenting
|
||||
code blocks (common in markdown) will not produce the desired look.
|
||||
Code examples should use [multi-line syntax highlighting][markdown-hilight]
|
||||
to mark multi-line code blocks, using the "python" identifier. Just
|
||||
indenting code blocks (common in markdown) will not produce the
|
||||
desired look.
|
||||
|
||||
When using any code tags (inline or blocks) it's recommended that you
|
||||
don't let the code extend wider than about 70 characters or it will
|
||||
need to be scrolled horisontally in the wiki (this does not affect any
|
||||
other text, only code).
|
||||
|
||||
### Class docstrings
|
||||
|
||||
The root class docstring should describe the over-arcing use of the
|
||||
class. It should usually not describe the exact call sequence nor list
|
||||
important methods, this tends to be hard to keep updated as the API
|
||||
develops.
|
||||
develops.
|
||||
|
||||
Example of class docstring:
|
||||
|
||||
|
|
@ -102,8 +108,8 @@ def funcname(a, b, c, d=False):
|
|||
|
||||
Raises:
|
||||
failed (RuntimeException): If there is a critical error,
|
||||
this is raised.
|
||||
io error (IOError): This is only raised if there is a
|
||||
this is raised.
|
||||
io error (IOError): This is only raised if there is a
|
||||
problem with the database.
|
||||
|
||||
Notes:
|
||||
|
|
@ -113,27 +119,27 @@ def funcname(a, b, c, d=False):
|
|||
"""
|
||||
```
|
||||
|
||||
- If you are describing a class method, the `self` argument should not
|
||||
be included among the documented arguments.
|
||||
- If you are describing a class method, the `self` argument should not
|
||||
be included among the documented arguments.
|
||||
- The text before the argument blocks is free-form. It should
|
||||
decsribe the function/method briefly.
|
||||
- The argument blocks supported by `api2md` are
|
||||
- `Args:`, `Returns` and `Raises` should be followed by a line break. nted
|
||||
an extra 4 spaces (only).
|
||||
- `argname (type):` is used for positional arguments
|
||||
decsribe the function/method briefly.
|
||||
- The argument blocks supported by `api2md` are
|
||||
- `Args:`, `Returns` and `Raises` should be followed by a line break. nted
|
||||
an extra 4 spaces (only).
|
||||
- `argname (type):` is used for positional arguments
|
||||
- `argname (type, optional):` is used for keyword arguments
|
||||
- `raise intention (exception type):` is used to describe exceptions
|
||||
raised from the function or method.
|
||||
raised from the function or method.
|
||||
- All the above should appear on a new line with a 4-space indent relative their
|
||||
block header (as per PEP8). If extending over more than one line, the
|
||||
subsequent lines should be indented another 4 spaces (only).
|
||||
block header (as per PEP8). If extending over more than one line, the
|
||||
subsequent lines should be indented another 4 spaces (only).
|
||||
- The text inside the parenthesis is free-form so you can put
|
||||
anything that makes sense in there (such as `Object` or `list
|
||||
or str`).
|
||||
or str`).
|
||||
- The describing text should start with a capital letter and end
|
||||
with a full stop (`.`).
|
||||
- `Notes:` starts freeform blocks of text and hsould always appear last.
|
||||
The `Notes:` header should
|
||||
- `Notes:` starts freeform blocks of text and hsould always appear last.
|
||||
The `Notes:` header should
|
||||
be followed by a line break and a 4-space indent. The rest of the text
|
||||
is free-form.
|
||||
|
||||
|
|
@ -142,7 +148,7 @@ def funcname(a, b, c, d=False):
|
|||
|
||||
If any of the rules outlined in PEP 8 or in the sections above doesn't
|
||||
make sense, please don't hesitate to ask on the Evennia mailing list
|
||||
or in the chat.
|
||||
or in the chat.
|
||||
|
||||
|
||||
[pep8]: http://www.python.org/dev/peps/pep-0008
|
||||
|
|
|
|||
|
|
@ -1,23 +1,25 @@
|
|||
"""
|
||||
This is an advanced ASCII table creator. It was inspired by
|
||||
[prettytable](https://code.google.com/p/prettytable/) but shares no
|
||||
code.
|
||||
|
||||
EvTable
|
||||
|
||||
This is an advanced ASCII table creator. It was inspired
|
||||
by prettytable but shares no code.
|
||||
|
||||
Note: to test ANSI colors on the command line you need to
|
||||
call the printed table in a unicode() call, like print unicode(table).
|
||||
This is due to a bug in the python interpreter and print.
|
||||
> Note: to test ANSI colors on the command line you need to call the
|
||||
printed table in a unicode() call, like print unicode(table). This is
|
||||
due to a bug in the python interpreter and print.
|
||||
|
||||
Example usage:
|
||||
|
||||
table = EvTable("Heading1", "Heading2", table=[[1,2,3],[4,5,6],[7,8,9]], border="cells")
|
||||
table.add_column("This is long data", "This is even longer data")
|
||||
table.add_row("This is a single row")
|
||||
print table
|
||||
```python
|
||||
table = EvTable("Heading1", "Heading2",
|
||||
table=[[1,2,3],[4,5,6],[7,8,9]], border="cells")
|
||||
table.add_column("This is long data", "This is even longer data")
|
||||
table.add_row("This is a single row")
|
||||
print table
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
```python
|
||||
+----------------------+----------+---+--------------------------+
|
||||
| Heading1 | Heading2 | | |
|
||||
+~~~~~~~~~~~~~~~~~~~~~~+~~~~~~~~~~+~~~+~~~~~~~~~~~~~~~~~~~~~~~~~~+
|
||||
|
|
@ -29,18 +31,20 @@ Result:
|
|||
+----------------------+----------+---+--------------------------+
|
||||
| This is a single row | | | |
|
||||
+----------------------+----------+---+--------------------------+
|
||||
```
|
||||
|
||||
As seen, the table will automatically expand with empty cells to make
|
||||
the table symmetric.
|
||||
the table symmetric. Tables can be restricted to a given width:
|
||||
|
||||
Tables can be restricted to a given width.
|
||||
|
||||
table.reformat(width=50, align="l")
|
||||
```python
|
||||
table.reformat(width=50, align="l")
|
||||
```
|
||||
|
||||
(We could just have added these keywords to the table creation call)
|
||||
|
||||
This yields the following result:
|
||||
|
||||
```python
|
||||
+-----------+------------+-----------+-----------+
|
||||
| Heading1 | Heading2 | | |
|
||||
+~~~~~~~~~~~+~~~~~~~~~~~~+~~~~~~~~~~~+~~~~~~~~~~~+
|
||||
|
|
@ -58,6 +62,7 @@ This yields the following result:
|
|||
| single | | | |
|
||||
| row | | | |
|
||||
+-----------+------------+-----------+-----------+
|
||||
```
|
||||
|
||||
Table-columns can be individually formatted. Note that if an
|
||||
individual column is set with a specific width, table auto-balancing
|
||||
|
|
@ -66,6 +71,8 @@ wide, so be careful mixing fixed-width columns with auto- balancing).
|
|||
Here we change the width and alignment of the column at index 3
|
||||
(Python starts from 0):
|
||||
|
||||
```python
|
||||
|
||||
table.reformat_column(3, width=30, align="r")
|
||||
print table
|
||||
|
||||
|
|
@ -83,6 +90,7 @@ print table
|
|||
| single | | | | |
|
||||
| row | | | | |
|
||||
+-----------+-------+-----+-----------------------------+---------+
|
||||
```
|
||||
|
||||
When adding new rows/columns their data can have its own alignments
|
||||
(left/center/right, top/center/bottom).
|
||||
|
|
@ -91,8 +99,8 @@ If the height is restricted, cells will be restricted from expanding
|
|||
vertically. This will lead to text contents being cropped. Each cell
|
||||
can only shrink to a minimum width and height of 1.
|
||||
|
||||
EvTable is intended to be used with ANSIString for supporting
|
||||
ANSI-coloured string types.
|
||||
`EvTable` is intended to be used with [ANSIString](evennia.utils.ansi#ansistring)
|
||||
for supporting ANSI-coloured string types.
|
||||
|
||||
When a cell is auto-wrapped across multiple lines, ANSI-reset
|
||||
sequences will be put at the end of each wrapped line. This means that
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue