Thursday 20 October, 2022

Rolumns

Screenshot of a terminal showing a Markdown table of Near-Earth objects.

Rolumns is a Python package I released in October 2022 to squish data into rows and columns.

It supports flat data, grouped data and user-defined fields, with baked-in renderers for iterable rows of cells (suitable for packages like openpyxl to generate XLSX spreadsheets) and Markdown.

Full documentation is online at rolumns.dev, but let’s run through a quick example!

A Flat Table

Let’s say we want to transform this data into a Markdown table with Name, Email and Address columns:

[
  {
    "name": "Robert Pringles",
    "email": "bob@pringles.pop",
    "address": {
      "planet": "Earth"
    }
  },
  {
    "name": "Daniel Sausage",
    "email": "danny@pringles.pop",
    "address": {
      "planet": "Mars"
    }
  },
  {
    "name": "Charlie Marmalade",
    "email": "charlie@pringles.pop",
    "address": {
      "planet": "Pluto"
    }
  }
]

Here’s a full code sample you can copy-paste to run, with some inline comments to explain what’s happening:

from rolumns import Columns
from rolumns.renderers import MarkdownRenderer

data = [
    {
        "name": "Robert Pringles",
        "email": "bob@pringles.pop",
        "address": {
            "planet": "Earth",
        },
    },
    {
        "name": "Daniel Sausage",
        "email": "danny@pringles.pop",
        "address": {
            "planet": "Mars",
        },
    },
    {
        "name": "Charlie Marmalade",
        "email": "charlie@pringles.pop",
        "address": {
            "planet": "Pluto",
        },
    },
]

# Create a column set.
columns = Columns()

# Add a column called "Name" that reads from the "name" key.
columns.add("Name", "name")

# Add a column called "Email" that reads from the "email"
# key.
columns.add("Email", "email")

# Add a column called "Planet" that reads from the "planet"
# key of the "address" object:
columns.add("Planet", "address.planet")

# Create a Markdown renderer for this column set.
renderer = MarkdownRenderer(columns)

# Render the input data.
print(renderer.render_string(data))

All things going well, you should receive a Markdown table like this:

NameEmailPlanet
Robert Pringlesbob@pringles.popEarth
Daniel Sausagedanny@pringles.popMars
Charlie Marmaladecharlie@pringles.popPluto

If you’d prefer to send the render to an XLSX spreadsheet via a package like openpyxl, just replace MarkdownRenderer with a RowsRenderer:

from openpyxl import Workbook
from openpyxl.styles import Font
from rolumns import Columns
from rolumns.renderers import RowsRenderer

# ...

# Create a row renderer for this column set.
renderer = RowsRenderer(columns)

# Render to an iterable list of rows.
rows = renderer.render(data)

# Create an openpyxl worksheet.
workbook = Workbook()
worksheet = workbook.active

# Append each rendered row to the worksheet.
for row in rows:
    worksheet.append(row)

# Export the workbook.
workbook.save("render.xlsx")
Screenshot of LibreOffice Calc showing a table exported by Rolumns.

More information

I’ve published a decent series of examples in the Rolumns Cook Book which include grouping by lists, objects and dictionaries, converting data types and building dynamic values, and user-defined fields.

I also have a GitHub repository at cariad/rolumns-examples with some examples that hit public APIs to generate interesting tables, like Who’s in Space Right Now? and Which Near-Earth Objects Will Approach Earth This Week?.

Rolumns is released under the MIT Licence and the source code is available at cariad/rolumns.