Command line: Top level nixio command with subcommands for command line scripts

[achilleas-k]

Package defines a single command line interface nixio which calls the appropriate script in nixio/cmd/ based on subcommand.

Each subcommand implements a create_subcmd_parsers() function that receives the parent parser and adds its own parsing subcommands and options.

The main() function of each subcommand receives the top level parsed 'args' object and uses it as it did previously.

Old subcommand main() flow:

1. Define parser
2. Define subparsers
3. Parse args
4. Use args to call functions and pass args.

New top-level command main() flow:

1. Define top level parser
2. Define subcommand names
3. Pass subcommand parser to each subcommand create_subcommand_parsers()
   3.1 Each subcommand defines its subparser
4. Parse args
5. Use args to call subcommand and pass args to subcommand main()
   5.1 Subcommand main() uses args to call appropriate function and validate options.

Here's the output of the `--help` for level for easier review and clarity (note that line length is terminal width dependent and is adjusted automatically by argparse):

$ nixio --help

usage: nixio [-h] {explore,validate,upgrade} ...

Command line interface for nixio tools

optional arguments:
  -h, --help            show this help message and exit

commands:
  {explore,validate,upgrade}
    explore             Search for information within NIX file(s). Use the
                        "file" command for general information about the
                        file(s). The verbose flag can be used to get more
                        detailed information about the file structure.
                        Multiple -v options increase the verbosity. (e.g.
                        'nixio explore file nix_file -vvv' for most detailed
                        output). The "metadata" (mdata) and "data" commands
                        provide further options for finding and viewing data
                        and metadata information. With the "dump" subcommand
                        data can be dumped to file (up to 3D data). The "plot"
                        command is only available if the nixworks package is
                        installed (https://github.com/G-node/nixworks). NOTE:
                        This tool is under active development. Please use the
                        github issue tracker
                        (https://github.com/G-node/nixpy/issues) for bug
                        reports and feature requests.
    validate            Validate NIX files for missing or inconsistent objects
                        and annotations.
    upgrade             Upgrade NIX files to newest file format version.

$ nixio explore --help

usage: nixio explore [-h] {file,data,dump,metadata,mdata} ...

optional arguments:
  -h, --help            show this help message and exit

commands:
  nixio explore functionality is split into sub-commands for file, metadata,
  and data exploration. For help on the commands type e.g.: 'nixio explore
  file --help'.

  {file,data,dump,metadata,mdata}
                        Sub commands for working on data and metadata
    file                Display basic file info
    data                Search and display information about data entities
    dump                Dump stored data to stdout
    metadata (mdata)    Filter and display metadata

$ nixio explore file --help

usage: nixio explore file [-h] [-v] [-s [SUFFIX]] file [file ...]

Quick display of file information such as creation date, file size and
structure etc.

positional arguments:
  file                  Path to file (at least one)

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbosity       increase output verbosity, use -v, -vv, -vvv for more
                        verbose output
  -s [SUFFIX], --suffix [SUFFIX]
                        The file suffix used for nix data files (default:
                        nix).

$ nixio explore data --help

usage: nixio explore data [-h] [-p PATTERN] [-c] [-fm] [-s [SUFFIX]]
                          file [file ...]

Display information about data entities such as DataArrays, Tags, or
MultiTags.

positional arguments:
  file                  Path to file (at least one)

optional arguments:
  -h, --help            show this help message and exit
  -p PATTERN, --pattern PATTERN
                        A string pattern that is parsed to find the data
                        entity.
  -c, --case_sensitive  matching of entitiy names and types is case sensitive,
                        by default the case is ignored
  -fm, --full_match     names and types must be full matches, bey default a
                        partial match is sufficient
  -s [SUFFIX], --suffix [SUFFIX]
                        The file suffix used for nix data files (default:
                        nix).

$ nixio explore mdata --help

usage: nixio explore metadata [-h] [-p PATTERN] [-d DEPTH] [-c] [-fm]
                              [-s [SUFFIX]]
                              file [file ...]

Search for metadata items or display metadata (sub)trees.

positional arguments:
  file                  Path to file (at least one)

optional arguments:
  -h, --help            show this help message and exit
  -p PATTERN, --pattern PATTERN
                        Pattern(s) with which to look for sections and
                        properties. The pattern can be either 1) type_or_name:
                        First looks for a section matching in type or name or
                        a property with matching name. 2)
                        type_or_name/prop_name: first looks for a matching
                        section and within those for matching properties.
                        Patterns are applied case-insensitive and can be
                        partial matches. You can provide multiple patterns by
                        calling the command like: `nixio-explore metadata -p
                        "subject" -p "species" file1.nix file2.nix`
  -d DEPTH, --depth DEPTH
                        maximum depth of metadata tree output, default is -1,
                        full depth
  -c, --case_sensitive  matching of entitiy names and types is case sensitive,
                        by default the case is ignored
  -fm, --full_match     names and types must be full matches, bey default a
                        partial match is sufficient
  -s [SUFFIX], --suffix [SUFFIX]
                        The file suffix used for nix data files (default:
                        nix).

$ nixio explore dump --help

usage: nixio explore dump [-h] [-p PATTERN] [-o OUTFILE] [-c] [-fm]
                          [-s [SUFFIX]]
                          file [file ...]

Dump data to stdout. This command can process up to 3D data. The data dump
contains dimension information as well as the stored data. To write the data
to text file use e.g. 'nixio-explore dump path_to_nix_file -p "name or type of
data entity" > data.dump' or provide the "--outfile" argument.

positional arguments:
  file                  Path to file (at least one)

optional arguments:
  -h, --help            show this help message and exit
  -p PATTERN, --pattern PATTERN
                        A string pattern that is parsed to find the data
                        entity.
  -o OUTFILE, --outfile OUTFILE
                        Name of a file into which the data should be dumped.
                        If not given data will be dumped to stdout.
  -c, --case_sensitive  matching of entitiy names and types is case sensitive,
                        by default the case is ignored
  -fm, --full_match     names and types must be full matches, bey default a
                        partial match is sufficient
  -s [SUFFIX], --suffix [SUFFIX]
                        The file suffix used for nix data files (default:
                        nix).

$ nixio validate --help

usage: nixio validate [-h] file [file ...]

positional arguments:
  file        path to file to validate (at least one)

optional arguments:
  -h, --help  show this help message and exit

$ nixio upgrade --help

usage: nixio upgrade [-h] [-f] file [file ...]

positional arguments:
  file         path to file to upgrade (at least one)

optional arguments:
  -h, --help   show this help message and exit
  -f, --force  overwrite existing files without prompting

[lgtm-com]

This pull request introduces 3 alerts when merging ac2bf0d into cc207ce - view on LGTM.com

new alerts:

• 3 for Unused import

[jgrewe]

nice! Found a few tiny things and if you don't mind fixing a typo in line 591 in explore.py for me ("by default")

[jgrewe]

I guess this should now be ... like: 'nixio explore metadata -p ... '

[jgrewe]

maybe change to: "Dump data to file or stdout. "

[jgrewe]

the example command should now be: nixio explore dump ...

[achilleas-k]

Thanks for catching these. Fixed.