table-format

Format Python code (list of lists) as a fixed width table.

Motivation and usage

You've got some tests or other code like this:

def test_the_table():
    assert generate_the_table() == [
        ['Date', 'Description', 'Amount', 'Balance'],
        ['2021-04-06', 'Account opened', 0, 0],
        ['2021-04-07', 'Cash deposit at 123 Main St, Newtown', 1000, 1000],
        ['2021-04-08', 'ACME anvils', -300, 700],
    ]

Or maybe even worse like this:

assert generate_the_table() == [
    [
        "Date",
        "Description",
        "Amount",
        "Balance",
    ],
    [
        "2021-04-06",
        "Account opened",
        0,
        0,
    ],
    [
        "2021-04-07",
        "Cash deposit at 123 Main St, Newtown",
        1000,
        1000,
    ],
    [
        "2021-04-08",
        "ACME anvils",
        -300,
        700,
    ],
]

Wouldn't it be nice to have readable tests with columns all lined up?

    [
        ['Date',       'Description',                          'Amount', 'Balance'],
        ['2021-04-06', 'Account opened',                       0,        0        ],
        ['2021-04-07', 'Cash deposit at 123 Main St, Newtown', 1000,     1000     ],
        ['2021-04-08', 'ACME anvils',                          -300,     700      ],
    ]

To reformat, copy the whole list of lists to the clipboard, then pipe to table-format --guess-indent:

on Linux you can use xsel or xclip
on MacOS you can use pbpaste
on Windows Powershell you can use Get-Clipboard

Linux example:

$ xsel | table-format --guess-indent

The output should be ready to paste back into your editor. You might do better with some editor integration — see the tips below.

Options

Pass the --help flag to show all options:

$ table-format --help

⬇️ Installation

The most recent release can be installed from PyPI with:

$ pip install table-format

You can also use pipx to install it more conveniently in an isolated environment:

$ pipx install table-format

See CHANGES for changelog.

The most recent code and data can be installed directly from GitHub with:

$ pip install git+https://github.com/spookylukey/table-format.git

To install in development mode, use the following:

$ git clone git+https://github.com/spookylukey/table-format.git
$ cd table-format
$ pip install -e .

Other tips

Tuples

It also supports having lists of tuples as well as lists of lists, and this will be preserved.

Black

Black will revert code formatted like this. But you can use # fmt: off and # fmt: on commands to stop black reformatting these blocks.

To format quotes more similarly to Black style, use --quote-style=double (this won’t be exactly the same as Black, it just switches to double quotes instead of single).

Flake8

Flake8 might complain about:

E202 - whitespace before ]
E241 - multiple spaces after comma
E501 - line too long

The simplest solution is to silence those flake8 errors globally in your config, especially if you are using a formatter like Black which will enforce those same rules for you automatically.

Otherwise, you can silence the errors on a per-line basis using noqa:E202,E241,E501, which you can automatically add to the end of each line like this:

$ table-format --add-noqa=E202,E241,E501

Other noqa items and other end of line comments will be preserved.

Emacs

With default keybindings, doing C-u M-| table-format --guess-indent ENTER will replace the current region with the formatted version from table-format.

You can wrap it up in a nice function like this:

(defun align-python-table ()
  (interactive)
  (shell-command-on-region
   ;; beginning and end of region
   (region-beginning)
   (region-end)
   ;; command and parameters
   "table-format --guess-indent"
   ;; output buffer
   (current-buffer)
   ;; replace?
   t
   ;; name of the error buffer
   "*Table-Format Error Buffer*"
   ;; show error buffer?
   t))

Other editors

Contributions of instructions to make this easy to use in other editors are very welcome!

⚖️ License

The code in this package is licensed under the MIT License.

🙏 Contributing

Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See CONTRIBUTING.rst for more information on getting involved.

🛠️ Development

The final section of the README is you for if you want to get involved by making a code contribution.

❓ Testing

After cloning the repository, install dev requirements:

pip install -r requirements-dev.txt

And run pytest:

pytest

To test across all environments:

$ tox

Additionally, these tests are automatically re-run with each commit in a GitHub Action.

🍪 Cookiecutter Acknowledgement

This package was created with @audreyfeldroy's cookiecutter package using @cthoyt's cookiecutter-snekpack template.

spookylukey / table-format