Skip to main content

access config and CLI easily and elegantly

Project description


Interface with config files and shell prompts easily and elegantly.

To install (add sudo if necessary)

python3 -m pip install volkanic

GlobalInterface and config file


GlobalInterface is defined in example/ as:

import volkanic

class GlobalInterface(volkanic.GlobalInterface):
    # you should always define `package_name`
    package_name = 'example'

Configuration file config.json5:

    "upstram_prefix": "",
    "sqlite": "/data/local/example/db.sqlite"

This config.json5 is at one of the follow locations:

  • Under your project directory in a development enviornment
  • ~/.example/config.json5
  • /etc/example/config.json5
  • /example/config.json5

Access config:

>>> from example.environ import GlobalInterface 
>>> gi = GlobalInterface()  # note that GlobalInterface is a sington class
>>> print(gi.conf)
{'upstram_prefix': '', 'sqlite': '/data/local/example/db.sqlite'}

Note that GlobalInterface is a singlon class, which means that GlobalInterface() will always return the same object:

>>> GlobalInterface() is GlobalInterface()

The recommended usage of GlobalInterface() is to create instanciate it at the top each module:

from example.environ import GlobalInterface  # noqa
from import your_funny_tool  # noqa

gi = GlobalInterface()

def find_funny_things():
    url = gi.conf['upstram_prefix'] + '/funny-api'
    path = gi.under_package_dir('asset/funny.json')
    # more code here ...


List sub-commands

$ volk
availabe commands:
- a
- o
- runconf
- where

Locate a Python package directory with volk where:

$ volk where requests
requests	/usr/local/lib/python3.6/site-packages/requests

You can open a file or URL with default application with volk o.

To open current directory with default file manager (Finder / explorer.exe / ...)

$ volk o .

Show sys.argv:

$ volk a \; "hello world" hello python
0	'/usr/local/bin/volk'
1	'a'
2	';'
3	'hello world'
4	'hello'
5	'python'

Sub-command protocal

Say you have a package named mypkg

├── docs/
├── mypkg/
│    ├──
│    ├──
│    ├──
│    ├──
│    └──
├── requirements.txt
└── tests/

In one of your functional modules, e.g. mypkg/mypkg/, provide a entry function which takes exactly 2 arguments:

import argparse

def process_file(path):
    # actual code here

def run(prog=None, args=None):
    desc = 'human readable formatter'
    parser = argparse.ArgumentParser(prog=prog, description=desc)
    add = parser.add_argument
    add('-i', '--input-file', help='path to your input file')
    ns = parser.parse_args(args)

Sub-command registry in mypkg/mypkg/

import volkanic

commands = {
    "fmt": "mypkg.formatter",
    "yml": "mypkg.parsers:run_yml_parser",
    "ini": "mypkg.parsers:run_ini_parser",
registry = volkanic.CommandRegistry(commands)

Note that mypkg.formatter is a shorthand for mypkg.formatter:run.

Configure top level command in mypkg/

from setuptools import setup

    entry_points={"console_scripts": ["mycmd = mypkg.main:registry"]},
    # more arguments here

Install package mypkg or link with python3 develop.

Now you have command mycmd:

$ mycmd
availabe commands:
- fmt
- ini
- yml

Run with sub-command fmt:

$ mycmd fmt -h

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

volkanic-0.4.2.tar.gz (26.7 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