Extending the CLI¶
Developers can create their own ‘subcommands’ for the pydicom
command,
by adding entry points to their package’s setup.py file, specifying a callback
function to register the subcommand and its arguments.
If you wanted to create two subcommands, ‘command1’ and ‘command2’, your setup.py file should include something like:
from setuptools import setup
if __name__ == '__main__':
setup(
name="yourpackage",
# various setup options...,
entry_points = {
"pydicom_subcommands": [
"command1 = yourpackage.command1module.add_subparser",
"command2 = yourpackage.command2module.add_subparser"
]
}
)
The "pydicom_subcommands"
is a literal string; this must not be
changed or pydicom will not find your subcommand.
The add_subparser
function name could be changed if you wish, but usually
would be used by convention, and is assumed in the following examples.
In the module you have specified, create the add_subparser
function,
which takes a single argument subparsers
, and a do_command
function,
which will take the call when you subcommand is actually used at the command
line:
from pydicom.cli.main import filespec_help, filespec_parser
def add_subparser(subparsers):
# Register the sub-parser
subparser = subparsers.add_parser(
"subcommandname",
description="Summary of your subcommand"
)
subparser.add_argument(
"filespec",
help=filespec_help,
type=filespec_parser
)
subparser.add_argument(
...
)
subparser.set_defaults(func=do_command)
And define your command function:
def do_command(args):
for ds, element_val in args.filespec:
if args.yourarg:
# Do something...
# work with the dataset ds or element as needed...
The pydicom
command uses Python’s
argparse library to
process commands.
The above code snippets show adding the filespec
argument, and processing
the resulting dataset-element_value pairs in the do_command()
function. This is
recommended if you wish to use the filespec as was seen in the pydicom show command
and pydicom codify command sections. If not, you can just create a normal
arg with the type set to argparse.FileType
to open files yourself.
The above has been shown in relation to a different package than pydicom;
however, if you think your command has general use, please consider contributing
it to pydicom: in that case, change the entry points in the pydicom
setup.py
script, and add a module under pydicom.cli
and create a
pull request.