Skip to main content

Extensible data structure traversal in the command line

Project description


lens is a command line tool for easy traversal and pretty printing fo data structures from the terminal. It is extensible.

Uses the great Pygments library.

It should work on both Python 2 and 3, but was developed with Python 3 in mind.


The package is yet registered to PyPI. That means you should be able to install it with pip. lens was already taken, so we used lens-cli.

pip install lens-cli


Calling lens -h will print this message:

usage: lens [-h] [--input INPUT] [--format FORMAT]
            [--no-highlight NO_HIGHLIGHT]
            [key [key ...]]

Extensible data structure traversal from the command line

positional arguments:
  key                   the keys to traverse

optional arguments:
  -h, --help            show this help message and exit
  --input INPUT, -i INPUT
                        the input file (defaults to the standard input)
  --format FORMAT, -f FORMAT
                        the data format to consume (defaults to json)
  --no-highlight NO_HIGHLIGHT, -n NO_HIGHLIGHT
                        prevent syntax highlighting

This should be relatively straightforward. Let's go through a few examples:

# just calling lens will print everything, syntax-highlighted
$ curl -s | lens
  "args": {}, 
  "headers": {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", 
    "Accept-Encoding": "gzip, deflate, br", 
    "Accept-Language": "de,en-US;q=0.7,en;q=0.3", 
    "Dnt": "1", 
    "Host": "", 
    "Referer": "", 
    "Upgrade-Insecure-Requests": "1", 
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:50.0) Gecko/20100101 Firefox/50.0"
  "origin": "", 
  "url": ""

# suppose we only want to see the "Host" header
$ curl -s | lens header Host

# or use xml
$ curl -s | lens -f=xml
    title="Sample Slide Show"
    date="Date of publication"
    author="Yours Truly"
    <slide type="all">
      <title>Wake up to WonderWidgets!</title>
    <slide type="all">
        <item>Why <em>WonderWidgets</em> are great</item>
        <item>Who <em>buys</em> WonderWidgets</item>

# suppose we want to only get the title of the second slide
$ curl -s | lens -f=xml slide 1 title

We can also read from files by providing an -i option. lens also discovers if its output is redirected to a file, in which case no syntax highlighting will be applied (the same can be achieved through the --no-highlighting/-n option).


You can write your own parsers/traversers - admittedly, parsers is not a great name, but for now we stick with it.

They should inherit from LensParser in lens.parsers.base, and at least implement the method treat(self, inpt, keys), where inpt is the input string and keys are the keys to traverse. It should return the traversed data structure as a string.

Optionally, the parser can specify a Pygments lexer by exposing the static attribute lexer, if highlighting is applicable. It will work without one, though.

The plugins can be third party pip modules, in which case they should follow the naming scheme lens-{format-name} and export the parser under the name Parser.

An example of a plugin can be found in the bson parser repository.

That is all you need to know!

Have fun!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lens-cli-0.1.4.tar.gz (5.0 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page