volkanic
========
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
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
Raw data
{
"_id": null,
"home_page": "https://github.com/frozflame/volkanic",
"name": "volkanic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": null,
"author": "frozflame",
"author_email": "frozflame@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/89/40/a22619c597b52ee022b314e859b44bfdf125ce0f325ae49c4affe52b6a06/volkanic-0.5.3.tar.gz",
"platform": null,
"description": "volkanic\n========\n\nInterface with config files and shell prompts easily and elegantly.\n\nTo install (add `sudo` if necessary)\n\n python3 -m pip install volkanic\n\n\n### GlobalInterface and config file\n\nExample:\n\n`GlobalInterface` is defined in `example/environ.py` as:\n\n```python\nimport volkanic\n\n\nclass GlobalInterface(volkanic.GlobalInterface):\n # you should always define `package_name`\n package_name = 'example'\n```\n\nConfiguration file `config.json5`:\n\n```json5\n{\n \"upstram_prefix\": \"http://127.0.0.1:9100\",\n \"sqlite\": \"/data/local/example/db.sqlite\"\n}\n```\n\nThis `config.json5` is at one of the follow locations:\n- Under your project directory in a development enviornment\n- `~/.example/config.json5`\n- `/etc/example/config.json5`\n- `/example/config.json5`\n\nAccess config:\n\n```\n>>> from example.environ import GlobalInterface \n>>> gi = GlobalInterface() # note that GlobalInterface is a sington class\n>>> print(gi.conf)\n{'upstram_prefix': 'http://127.0.0.1:9100', 'sqlite': '/data/local/example/db.sqlite'}\n```\n\nNote that `GlobalInterface` is a singlon class, which means that \n`GlobalInterface()` will always return the same object:\n```\n>>> GlobalInterface() is GlobalInterface()\nTrue\n```\n\nThe recommended usage of `GlobalInterface()` is to create instanciate it \nat the top each module:\n\n```python\nfrom example.environ import GlobalInterface # noqa\nfrom example.tools import your_funny_tool # noqa\n\ngi = GlobalInterface()\n\n\ndef find_funny_things():\n url = gi.conf['upstram_prefix'] + '/funny-api'\n path = gi.under_package_dir('asset/funny.json')\n # more code here ...\n```\n\n\n-------------------------------------------------------------------------\n### Accessories\n\nList sub-commands\n\n $ volk\n availabe commands:\n - a\n - o\n - runconf\n - where\n\nLocate a Python package directory with `volk where`:\n\n $ volk where requests\n requests\t/usr/local/lib/python3.6/site-packages/requests\n\n\nYou can open a file or URL with default application with `volk o`.\n\nTo open current directory with default file manager (Finder / explorer.exe / ...)\n\n $ volk o .\n\nShow `sys.argv`:\n\n $ volk a \\; \"hello world\" hello python\n 0\t'/usr/local/bin/volk'\n 1\t'a'\n 2\t';'\n 3\t'hello world'\n 4\t'hello'\n 5\t'python'\n\n-------------------------------------------------------------------------\n### Sub-command protocal\n\nSay you have a package named `mypkg`\n\n\n mypkg/\n \u251c\u2500\u2500 MANIFEST.in\n \u251c\u2500\u2500 docs/\n \u251c\u2500\u2500 mypkg/\n \u2502 \u251c\u2500\u2500 __init__.py\n \u2502 \u251c\u2500\u2500 algors.py\n \u2502 \u251c\u2500\u2500 formatters.py\n \u2502 \u251c\u2500\u2500 main.py\n \u2502 \u2514\u2500\u2500 parsers.py\n \u251c\u2500\u2500 requirements.txt\n \u251c\u2500\u2500 setup.py\n \u2514\u2500\u2500 tests/\n\n\nIn one of your functional modules, e.g. `mypkg/mypkg/formatter.py`,\nprovide a entry function which takes exactly 2 arguments:\n\n\n```python\nimport argparse\n\ndef process_file(path):\n # actual code here\n return\n\ndef run(prog=None, args=None):\n desc = 'human readable formatter'\n parser = argparse.ArgumentParser(prog=prog, description=desc)\n add = parser.add_argument\n add('-i', '--input-file', help='path to your input file')\n ns = parser.parse_args(args)\n process_file(ns.input_file)\n```\n\n\nSub-command registry in `mypkg/mypkg/main.py`:\n\n\n```python\nimport volkanic\n\ncommands = {\n \"fmt\": \"mypkg.formatter\",\n \"yml\": \"mypkg.parsers:run_yml_parser\",\n \"ini\": \"mypkg.parsers:run_ini_parser\",\n}\nregistry = volkanic.CommandRegistry(commands)\n```\n\nNote that `mypkg.formatter` is a shorthand for `mypkg.formatter:run`.\n\n\nConfigure top level command in `mypkg/setup.py`:\n\n```python\nfrom setuptools import setup\n\nsetup(\n name=\"mypkg\",\n entry_points={\"console_scripts\": [\"mycmd = mypkg.main:registry\"]},\n # more arguments here\n)\n```\n\n\nInstall package `mypkg` or link with `python3 setup.py develop`.\n\nNow you have command `mycmd`:\n\n $ mycmd\n availabe commands:\n - fmt\n - ini\n - yml\n\nRun with sub-command `fmt`:\n\n $ mycmd fmt -h\n\n",
"bugtrack_url": null,
"license": "GNU General Public License (GPL)",
"summary": "access config and CLI easily and elegantly",
"version": "0.5.3",
"project_urls": {
"Homepage": "https://github.com/frozflame/volkanic"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8940a22619c597b52ee022b314e859b44bfdf125ce0f325ae49c4affe52b6a06",
"md5": "bbfea8504ad1b06e7c110a94022d275c",
"sha256": "4c737f63a6099925239f4b61e387be2171426d1ba38a7bd793846b8f1124b99e"
},
"downloads": -1,
"filename": "volkanic-0.5.3.tar.gz",
"has_sig": false,
"md5_digest": "bbfea8504ad1b06e7c110a94022d275c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 26800,
"upload_time": "2024-06-02T15:08:36",
"upload_time_iso_8601": "2024-06-02T15:08:36.981554Z",
"url": "https://files.pythonhosted.org/packages/89/40/a22619c597b52ee022b314e859b44bfdf125ce0f325ae49c4affe52b6a06/volkanic-0.5.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-02 15:08:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "frozflame",
"github_project": "volkanic",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "json5",
"specs": [
[
">=",
"0.9.5"
]
]
}
],
"lcname": "volkanic"
}
JSON
