From 284a20cfd9ea51ca2aaf4a98e8526dbfe86fb2a6 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 8 Mar 2015 13:51:53 +0100 Subject: [PATCH] Minor updates --- CODING_STYLE.md | 58 ++++++++++++++++++++++------------------ evennia/utils/evtable.py | 44 +++++++++++++++++------------- 2 files changed, 58 insertions(+), 44 deletions(-) diff --git a/CODING_STYLE.md b/CODING_STYLE.md index 5842413c9d..f9a35ee944 100644 --- a/CODING_STYLE.md +++ b/CODING_STYLE.md @@ -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 diff --git a/evennia/utils/evtable.py b/evennia/utils/evtable.py index 427e7bebdb..c4f39023a0 100644 --- a/evennia/utils/evtable.py +++ b/evennia/utils/evtable.py @@ -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