https://github.com/frozflame/volkanic
Interface with config files and shell prompts easily and elegantly.
https://github.com/frozflame/volkanic
python subcommand
Last synced: about 1 month ago
JSON representation
Interface with config files and shell prompts easily and elegantly.
- Host: GitHub
- URL: https://github.com/frozflame/volkanic
- Owner: frozflame
- License: gpl-3.0
- Created: 2018-11-02T02:29:08.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2025-10-02T08:03:07.000Z (6 months ago)
- Last Synced: 2025-12-18T18:36:19.816Z (3 months ago)
- Topics: python, subcommand
- Language: Python
- Homepage: https://pypi.org/project/volkanic/
- Size: 144 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
volkanic
========
Interface with config files and shell prompts easily and elegantly.
To install (add `sudo` if necessary)
python3 -m pip install volkanic
Python version requirement (plan)
0.5.0 Python 3.5+
0.6.0 Python 3.6+
0.7.0 Python 3.7+
0.8.0 Python 3.8+
0.9.0 Python 3.9+
### GlobalInterface and config file
Example:
`GlobalInterface` is defined in `example/environ.py` as:
```python
import volkanic
class GlobalInterface(volkanic.GlobalInterface):
# you should always define `package_name`
package_name = 'example'
```
Configuration file `config.json5`:
```json5
{
"upstram_prefix": "http://127.0.0.1:9100",
"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': 'http://127.0.0.1:9100', '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()
True
```
The recommended usage of `GlobalInterface()` is to create instanciate it
at the top each module:
```python
from example.environ import GlobalInterface # noqa
from example.tools 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 ...
```
-------------------------------------------------------------------------
### Accessories
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`
mypkg/
├── MANIFEST.in
├── docs/
├── mypkg/
│ ├── __init__.py
│ ├── algors.py
│ ├── formatters.py
│ ├── main.py
│ └── parsers.py
├── requirements.txt
├── setup.py
└── tests/
In one of your functional modules, e.g. `mypkg/mypkg/formatter.py`,
provide a entry function which takes exactly 2 arguments:
```python
import argparse
def process_file(path):
# actual code here
return
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)
process_file(ns.input_file)
```
Sub-command registry in `mypkg/mypkg/main.py`:
```python
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/setup.py`:
```python
from setuptools import setup
setup(
name="mypkg",
entry_points={"console_scripts": ["mycmd = mypkg.main:registry"]},
# more arguments here
)
```
Install package `mypkg` or link with `python3 setup.py develop`.
Now you have command `mycmd`:
$ mycmd
availabe commands:
- fmt
- ini
- yml
Run with sub-command `fmt`:
$ mycmd fmt -h