Getting Started¶
This guide will walk you through setting up an example CLI project using HelCLI.
Project Layout¶
project-src/
project/
__init__.py
commands/
__init__.py
example-command.py
setup.py
project/__init__.py¶
This is where most of core CLI code will go, we need to instantiate the Class
and run it inside of a function. When we go to reference this with an entry
point in setup.py we’ll need to remember the name we use. We will call it with
the main
function as an example. Our entry point will then be
project:main
.
from helcli import HelCLI
def main():
cli = HelCLI(sub_commands='commands', description='A simple CLI')
cli.run()
Great! Now when project.main() is called it will execute our CLI. Take note that sub_commands is set to ‘commands’ this is the directory relative to our package (project) where our sub-commands for this CLI will go.
project/commands/__init__.py¶
Python requires this file to know that the commands directory is a submodule that we can import from. It’s fine to leave this file blank, it just needs to exist.
project/commands/example-command.py¶
HelCLI will be looking for commands inside of the ‘commands’ directory which we
set above. It will go through every file in this directory when the run
method is called on the HelCLI object and execute setup
. This is where you
should setup any command line arguments you expect for this command. Inside of
the main method is what should happen if someone is actually calling this
command. The arguments you requested above will be passed to main
as a
dictionary you can reference.
For this example let’s have example-command take one argument, name, and have
the command print out ‘Hello name
!’. Note that it uses the
argparse module to set
this up.
def setup(parser, subparsers):
parser_example_command = subparsers.add_parser(
'example-command',
help='Prints "Hello <name>!"')
parser_example_command.add_argument(
'name',
help='The name to say hello to.')
def main(parser_d):
name = parser_d['name'] # retrieved from parser name argument
print 'Hello {}!'.format(name)
setup.py¶
Lastly is our setup file. This syntax isn’t specific to HelCLI, but is included for completeness.
from setuptools import setup, find_packages
setup(name='project',
version=0.0.1,
author='You',
author_email='you@mail.com',
packages=find_packages(),
install_requires=['helcli'],
entry_points={'console_scripts': [
'project = project:main',
]})
Wrapping up¶
Now you may pip install -e ./project-src
and run the project
command to
have a fully functional CLI.