Metadata-Version: 2.1
Name: vulcano
Version: 0.5.3
Summary: Vulcano
Home-page: https://github.com/dgarana/vulcano
Author: David Garaña
License: UNKNOWN
Description: Vulcano
        =======
        |PyPI version| |Code style: black| |Build Status| |codecov|
        |readthedocs| |Downloads|
        
        
        Please, help us to continue improving, become a `patreon <https://www.patreon.com/dgarana>`__
        
        
        What is Vulcano?
        ----------------
        
        Vulcano is a framework for creating command line utils.
        
        Built on top of
        `prompt\_toolkit <https://github.com/prompt-toolkit/python-prompt-toolkit>`__,
        it helps you to create human-friendly modern command line utils.
        
        It's simplicity makes it suitable in a lot of scenarios where you just
        want to run already-created functions in a REPL/ARGS mode.
        
        .. figure:: https://github.com/dgarana/vulcano/raw/master/docs/_static/repl_demo.gif?raw=true
           :alt: REPL Demo gif video
        
        .. note:: Important notes
           Due some design changes we are working on, we recommend you to
           avoid using this framework on a production environment.
           We're still looking forward having a more idiomatic module name
           convention. If you're happy with the current state, just use it ;)
        
        Key features
        ------------
        
        -  *Autocomplete*: Vulcano will inspect all the functions you register,
           and will create a list of autocomplete with your command name and
           it's arguments.
        -  *Help*: It will create help based on your functions docstrings or the
           help provided during the registration process.
        -  *History*: Use up & down arrows to select a command from your
           history.
        -  *Register modules*: It can register all the functions inside a module
           just by calling the register module function. It will help you to
           prevent modifying the source module.
        -  *Lexer*: Of course, we use lexer with pygments to colorize your
           command line ;)
        -  *Concatenated commands*: You want to execute more than one command at
           once from the command line arguments? Just use the "and".
           ``python your_script.py my_func arg=\"something\˝ and my_func_2 arg=\"another thing here\"``
           , such hacker!
        -  *Context*: If you want to communicate different functions between
           them, you can use the VulcanoApp.context (it's just a dictionary
           where you store and read data).
        -  *Command templating*: You can use whatever is on the context to
           format your command and generate it with data from the context.
        -  *Autosuggestion*: Whenever you enter a command that doesn't exists, you'll get
           the most similar command name. This improves the user experience. You could define
           your own function to determine which command you should use.
        
        .. code:: python
        
            >> niu
            Command niu not found
            Did you mean: "new"?
            >>
        
        -  *Inspect commands source code*: With vulcano, you can inspect a
           command sourcecode by just typing ``?`` at the end of the command.
           For example: ``>> bye?`` it will print this function source with
           syntax highlight.
        
        .. code:: python
        
           >> bye?
           @app.command
           def bye(name="User"):
               """ Say goodbye to someone """
               return "Bye {}!".format(name)
           >>
        
        Installation
        ------------
        
        Vulcano is automatically delivered through TravisCI, which means that we
        usually keep the pip package up to date, this will help you to install
        the vulcano latest version by just executing the:
        ``pip install vulcano``
        
        But in case you're looking for installing a non-delivered version or
        just a custom branch, you can install it by cloning the repository and
        executing the: ``python setup.py install``
        
        Lets keep things simple.
        
        Learn by example
        ----------------
        
        The repository usually holds a simple sample ready to execute which
        brings an example of almost all the features.
        
        In case you don't want to clone it, you can copy paste it:
        
        .. code:: python
        
            from __future__ import print_function
            import random
            from vulcano.app import VulcanoApp
            from vulcano.app.lexer import MonokaiTheme
        
        
            app = VulcanoApp()
        
            @app.command("hi", "Salute people given form parameter")
            def salute_method_here(name, title="Mr."):
                """Salute to someone
        
                :param str name: Name of who you want to say hi!
                :param str title: Title of this person
                """
                print("Hi! {} {} :) Glad to see you.".format(title, name))
        
        
            def has_context_name():
                """Function to hide a command from command line
        
                This function is to prevent showing help and autocomplete for commands that need the name
                to be set up on the context.
                """
                return 'name' in app.context
        
        
            @app.command
            def i_am(name):
                """Set your name
        
                :param str name: Your name goes here!
                """
                app.context['name'] = name
        
        
            @app.command(show_if=has_context_name)
            def whoami():
                """Returns your name from the context
        
                This is only shown where you've set your name
                """
                return app.context['name']
        
        
            @app.command
            def bye(name="User"):
                """ Say goodbye to someone """
                return "Bye {}!".format(name)
        
        
            @app.command
            def sum_numbers(*args):
                """ Sums all numbers passed as parameters """
                return sum(args)
        
        
            @app.command
            def multiply(number1, number2):
                """ Just multiply two numbers """
                return number1 * number2
        
        
            @app.command
            def reverse_word(word):
                """ Reverse a word """
                return word[::-1]
        
        
            @app.command
            def random_upper_word(word):
                """ Returns the word with random upper letters """
                return "".join(random.choice([letter.upper(), letter]) for letter in word)
        
        
            if __name__ == '__main__':
                app.run(theme=MonokaiTheme)
        
        
        
        This will create next commands: - hi - bye - i\_am - whoami -
        sum\_numbers - multiply - reverse\_word - random\_upper\_word
        
        Those commands can ``return`` data that will be printed (if there's
        something) and the result will be stored inside the context under the
        ``last_result`` node. This helps you to be able to use it on the command
        line templating.
        
        You can execute from ``repl`` mode:
        
        .. figure:: https://github.com/dgarana/vulcano/raw/master/docs/_static/repl_demo.gif?raw=true
           :alt: REPL Demo gif video
        
        .. code:: bash
        
            $ python simple_example.py
            >> reverse_word "Hello Baby! This is awesome"
            emosewa si sihT !ybaB olleH
            >> random_upper_word "{last_result}"
            EMosEWa si SiHT !ybAB OlLEH
            >> exit
        
        And also can be executed from ``args`` mode:
        
        .. figure:: https://github.com/dgarana/vulcano/raw/master/docs/_static/args_demo.gif?raw=true
           :alt: REPL Demo gif video
        
        .. code:: bash
        
            $ python simple_example.py reverse_word \"Hello Baby! This is awesome\" and random_upper_word \"{last_result}\"
            emosewa si sihT !ybaB olleH
            EMOSEWa Si siHT !YbAB olLeH
        
        Nice, right?
        
        Contribute
        ----------
        
        If you have an idea, you want to help improving something ... or
        whatever you think you can help, you're welcome.
        
        All the pull requests will be checked (and also the bugs you report).
        
        
        .. |PyPI version| image:: https://badge.fury.io/py/vulcano.svg
           :target: https://badge.fury.io/py/vulcano
        .. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
           :target: https://github.com/ambv/black
        .. |Build Status| image:: https://travis-ci.org/dgarana/vulcano.svg?branch=master
           :target: https://travis-ci.org/dgarana/vulcano
        .. |codecov| image:: https://codecov.io/gh/dgarana/vulcano/branch/master/graph/badge.svg
           :target: https://codecov.io/gh/dgarana/vulcano
        .. |readthedocs| image:: https://readthedocs.org/projects/vulcano/badge/?version=latest
           :target: https://vulcano.readthedocs.org
        .. |Downloads| image:: https://pepy.tech/badge/vulcano
           :target: https://pepy.tech/project/vulcano
        
Keywords: console development cli repl
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
