clasp


Nameclasp JSON
Version 1.1.2 PyPI version JSON
download
home_pagehttps://bitbucket.org/stephenwasilewski/clasp
Summaryclasp is tools for command line and subprocess script development
upload_time2020-10-10 07:58:32
maintainer
docs_urlNone
authorStephen Wasilewski
requires_python>=3.6
licenseMozilla Public License 2.0 (MPL 2.0)
keywords clasp
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            About
-----
Clasp (command line and subprocess) extends click (https://palletsprojects.com/p/click/)
and provides a library of functions that aid in the development of command line 
tools that require frequent calls to system exectubles.  A particular structure
program [options] command arguments [options] has been implemented for click that
sets up an easy way to read and write config files and group commands under common
programs to allow for organized development of suites of command line tools.

https://clasp.readthedocs.io/


Installation
------------

::

    pip install clasp


Usage
-----

a command line program has the following structure::

    """template file."""

    import clasp.click as click
    import clasp.click_ext as clk



    @click.group()
    @clk.shared_decs(clk.main_decs)
    def main(ctx, config, outconfig, configalias, inputalias):
        """template file for script development."""
        clk.get_config(ctx, config, outconfig, configalias, inputalias)


    @main.command('XXX')
    @click.argument('arg1')
    @click.option('--opts','-opts', is_flag=True,
                  help="check parsed options")
    @click.option('--debug', is_flag=True,
                  help="show traceback on exceptions")
    @click.pass_context
    def XXX(ctx, arg1, **kwargs):
        """
        docstring with full help text for command
        """
        if kwargs['opts']:
            kwargs['opts'] = False
            clk.echo_args(arg1,**kwargs)
        else:
            try:
                ##########
                #code body
                ##########
            except click.Abort:
                raise
            except Exception as ex:
                clk.print_except(ex, kwargs['debug'])
        return 'XXX', kwargs, ctx


    @main.resultcallback()
    @click.pass_context
    def printconfig(ctx, opts, **kwargs):
        """callback to save config file"""
        try:
            clk.tmp_clean(opts[2])
        except Exception:
            pass
        if kwargs['outconfig']:
            clk.print_config(ctx, opts, kwargs['outconfig'], kwargs['config'],
                             kwargs['configalias'])

to make an entry point in setup::

    entry_points={"console_scripts":'program=package.program:main'}


and then to execute::

    program XXX arg1 [options]

to enable autocomple for options::

    _PROGRAM_COMPLETE=source program > bash_complete.sh
    # put this in .bash_profile (with path)
    source bash_complete.sh


scripting
~~~~~~~~~

see script_tools documentation for helpful functions matching parsed args
to functions, calling subprocesses, and parallel processing using ipyparallel
locally and via ssh.

Callbacks
---------

in addition to the powerful option parsing provided by click a number of 
callbacks are part of clasp which help with commonly used argument parsing

File input
~~~~~~~~~~

file inputs can be given with wildcard expansion (in quotes so that the callback handles)
using glob plus the following:

    * [abc] (one of a, b, or c) 
    * [!abc] (none of a, b or c)
    * '-' (hyphen) collect the stdin into a temporary file (clasp_tmp*)
    * ~ expands user

The file input callbacks are:

    * parse_file_list: returns list of files (raise error if file not found)
    * is_file: check if a single path exists (prompts for user input if file not found)
    * are_files: recursively calls parse_file_list and prompts on error
    * is_file_iter: use when multiple=True
    * are_files_iter: use when mulitple=True
    * are_files_or_str: tries to parse as files, then tries split_float, then split_int, then returns string
    * are_files_or_str_iter: use when mulitple=True

String parsing
~~~~~~~~~~~~~~

    * split_str: split with shlex.split
    * split_str_iter: use when multiple=True
    * color_inp: return alphastring, split on whitespace, convert floats and parse tuples on ,

Number parsing
~~~~~~~~~~~~~~

    * tup_int: parses integer tuples from comma/space seperated string
    * tup_float: parses float tuples from comma/space seperated string
    * split_float: splits list of floats and extends ranges based on : notation
    * split_int: splits list of ints and extends ranges based on : notation

Documentation
-------------

Click and sphinx_click make help and documentation super easy, but there are
a few conflicts in formatting docstrings both for --help and for sphinx.
clasp.sphinx_click_ext attempts to resolve these conflicts and does some sorting of options
and help display based on the script template shown above.  To use with sphinx
add 'clasp.sphinx_click_ext' to extensions in your conf.py


Source Code
-----------

* clasp: https://bitbucket.org/stephenwasilewski/clasp

Licence
-------

| Copyright (c) 2018 Stephen Wasilewski
| This Source Code Form is subject to the terms of the Mozilla Public
| License, v. 2.0. If a copy of the MPL was not distributed with this
| file, You can obtain one at http://mozilla.org/MPL/2.0/.




            

Raw data

            {
    "_id": null,
    "home_page": "https://bitbucket.org/stephenwasilewski/clasp",
    "name": "clasp",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "",
    "keywords": "clasp",
    "author": "Stephen Wasilewski",
    "author_email": "stephanwaz@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/28/ea/fc287ae8b0f4ccee93e4cfcf156e0b1e6b38d628843083c70cdba97987ce/clasp-1.1.2.tar.gz",
    "platform": "",
    "description": "About\n-----\nClasp (command line and subprocess) extends click (https://palletsprojects.com/p/click/)\nand provides a library of functions that aid in the development of command line \ntools that require frequent calls to system exectubles.  A particular structure\nprogram [options] command arguments [options] has been implemented for click that\nsets up an easy way to read and write config files and group commands under common\nprograms to allow for organized development of suites of command line tools.\n\nhttps://clasp.readthedocs.io/\n\n\nInstallation\n------------\n\n::\n\n    pip install clasp\n\n\nUsage\n-----\n\na command line program has the following structure::\n\n    \"\"\"template file.\"\"\"\n\n    import clasp.click as click\n    import clasp.click_ext as clk\n\n\n\n    @click.group()\n    @clk.shared_decs(clk.main_decs)\n    def main(ctx, config, outconfig, configalias, inputalias):\n        \"\"\"template file for script development.\"\"\"\n        clk.get_config(ctx, config, outconfig, configalias, inputalias)\n\n\n    @main.command('XXX')\n    @click.argument('arg1')\n    @click.option('--opts','-opts', is_flag=True,\n                  help=\"check parsed options\")\n    @click.option('--debug', is_flag=True,\n                  help=\"show traceback on exceptions\")\n    @click.pass_context\n    def XXX(ctx, arg1, **kwargs):\n        \"\"\"\n        docstring with full help text for command\n        \"\"\"\n        if kwargs['opts']:\n            kwargs['opts'] = False\n            clk.echo_args(arg1,**kwargs)\n        else:\n            try:\n                ##########\n                #code body\n                ##########\n            except click.Abort:\n                raise\n            except Exception as ex:\n                clk.print_except(ex, kwargs['debug'])\n        return 'XXX', kwargs, ctx\n\n\n    @main.resultcallback()\n    @click.pass_context\n    def printconfig(ctx, opts, **kwargs):\n        \"\"\"callback to save config file\"\"\"\n        try:\n            clk.tmp_clean(opts[2])\n        except Exception:\n            pass\n        if kwargs['outconfig']:\n            clk.print_config(ctx, opts, kwargs['outconfig'], kwargs['config'],\n                             kwargs['configalias'])\n\nto make an entry point in setup::\n\n    entry_points={\"console_scripts\":'program=package.program:main'}\n\n\nand then to execute::\n\n    program XXX arg1 [options]\n\nto enable autocomple for options::\n\n    _PROGRAM_COMPLETE=source program > bash_complete.sh\n    # put this in .bash_profile (with path)\n    source bash_complete.sh\n\n\nscripting\n~~~~~~~~~\n\nsee script_tools documentation for helpful functions matching parsed args\nto functions, calling subprocesses, and parallel processing using ipyparallel\nlocally and via ssh.\n\nCallbacks\n---------\n\nin addition to the powerful option parsing provided by click a number of \ncallbacks are part of clasp which help with commonly used argument parsing\n\nFile input\n~~~~~~~~~~\n\nfile inputs can be given with wildcard expansion (in quotes so that the callback handles)\nusing glob plus the following:\n\n    * [abc] (one of a, b, or c) \n    * [!abc] (none of a, b or c)\n    * '-' (hyphen) collect the stdin into a temporary file (clasp_tmp*)\n    * ~ expands user\n\nThe file input callbacks are:\n\n    * parse_file_list: returns list of files (raise error if file not found)\n    * is_file: check if a single path exists (prompts for user input if file not found)\n    * are_files: recursively calls parse_file_list and prompts on error\n    * is_file_iter: use when multiple=True\n    * are_files_iter: use when mulitple=True\n    * are_files_or_str: tries to parse as files, then tries split_float, then split_int, then returns string\n    * are_files_or_str_iter: use when mulitple=True\n\nString parsing\n~~~~~~~~~~~~~~\n\n    * split_str: split with shlex.split\n    * split_str_iter: use when multiple=True\n    * color_inp: return alphastring, split on whitespace, convert floats and parse tuples on ,\n\nNumber parsing\n~~~~~~~~~~~~~~\n\n    * tup_int: parses integer tuples from comma/space seperated string\n    * tup_float: parses float tuples from comma/space seperated string\n    * split_float: splits list of floats and extends ranges based on : notation\n    * split_int: splits list of ints and extends ranges based on : notation\n\nDocumentation\n-------------\n\nClick and sphinx_click make help and documentation super easy, but there are\na few conflicts in formatting docstrings both for --help and for sphinx.\nclasp.sphinx_click_ext attempts to resolve these conflicts and does some sorting of options\nand help display based on the script template shown above.  To use with sphinx\nadd 'clasp.sphinx_click_ext' to extensions in your conf.py\n\n\nSource Code\n-----------\n\n* clasp: https://bitbucket.org/stephenwasilewski/clasp\n\nLicence\n-------\n\n| Copyright (c) 2018 Stephen Wasilewski\n| This Source Code Form is subject to the terms of the Mozilla Public\n| License, v. 2.0. If a copy of the MPL was not distributed with this\n| file, You can obtain one at http://mozilla.org/MPL/2.0/.\n\n\n\n",
    "bugtrack_url": null,
    "license": "Mozilla Public License 2.0 (MPL 2.0)",
    "summary": "clasp is  tools for command line and subprocess script development",
    "version": "1.1.2",
    "split_keywords": [
        "clasp"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "0d643c4adf84d6ff7b16c6135b6b6b58",
                "sha256": "16cc9645b7528989e138210743e3699120b9a3163638d29136e73b0867075c7c"
            },
            "downloads": -1,
            "filename": "clasp-1.1.2-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0d643c4adf84d6ff7b16c6135b6b6b58",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": ">=3.6",
            "size": 28257,
            "upload_time": "2020-10-10T07:58:30",
            "upload_time_iso_8601": "2020-10-10T07:58:30.956358Z",
            "url": "https://files.pythonhosted.org/packages/09/6f/0edbbdc715e82710a5b835bec0b97ed4d507ae8fd62ec96a48ab4c6ccb4d/clasp-1.1.2-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "ed76d801ca03157ba592f0c0ef8e121f",
                "sha256": "bbfed1e0299e99acee58dc8e8b9e849c8e08edfb2af41e5de496b2f3510440a1"
            },
            "downloads": -1,
            "filename": "clasp-1.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "ed76d801ca03157ba592f0c0ef8e121f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 32159,
            "upload_time": "2020-10-10T07:58:32",
            "upload_time_iso_8601": "2020-10-10T07:58:32.201855Z",
            "url": "https://files.pythonhosted.org/packages/28/ea/fc287ae8b0f4ccee93e4cfcf156e0b1e6b38d628843083c70cdba97987ce/clasp-1.1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-10-10 07:58:32",
    "github": false,
    "gitlab": false,
    "bitbucket": true,
    "bitbucket_user": null,
    "bitbucket_project": "stephenwasilewski",
    "lcname": "clasp"
}
        
Elapsed time: 0.17382s