Clean up CLI namespace

[lukaspie]

Currently, pynxtools installs multiple standalone CLI scripts:

read_nexus → pynxtools.nexus.nexus:main
dataconverter → pynxtools.dataconverter.convert:main_cli
generate_eln → pynxtools.eln_mapper.eln_mapper:get_eln
validate_nexus → pynxtools.dataconverter.validate_file:validate_cli

dataconverter has another set of subcommands (convert (aliassed), generate-template, get-readers).

Each is installed as a separate top-level command. This polluts the global shell namespace and it makes it harder for users to discover functionality. Consistent documentation of usage is also hard. We could change this, i.e., make the whole CLI interface available through one namespace.

Proposal: Consolidate under a single CLI namespace

• Introduce a short, unique top-level CLI command, e.g., pynx ...
• Expose current functionality as subcommands:

  pynx read             # read_nexus
  pynx convert          # dataconverter
  pynx generate-eln     # generate_eln
  pynx validate         # validate_nexus

• Pros:
  • Single entry point for all functionality,
  • Easier to document and discover commands
  • Reduces shell namespace pollution
  • Easier to maintain and extend in the future
• Cons:
  • Slightly longer commands (pynx convert instead of dataconverter)
  • (biggest issue) May break existent implementations, examples, documentation, etc.
    • We could keep old commands as aliases to avoid breaking existing scripts, but: this may require extra effort to maintain backward-compatible aliases (or deprecating them at some point)
    • From semver POV, we are fine as we are (technically) still in beta.

Alternatively, we can keep the separate CLI commands which has the advantage of no breaking changes for existing users, but then we have all the disadvantage (multiple binaries cluttering the namespace, inconsistent naming, etc.).

So, in summary, for discussion:

• Do we want this breaking change?
• If so, what's the best CLI entry point? pynx? (short, recognizable, low risk of collision)
• Should old commands remain available (and for how long) as aliases for backward compatibility?
• Could this be an opportunity to clean up subcommands (e.g., remove generate-template from the dataconverter namespace?)

Opinions @mkuehbach @sherjeelshabih @RubelMozumder @rettigl?

[rettigl]

I did not consider this an issue so far, but given how other cli commands work, this totally makes sense to me. My ssugestion would be to keep old commands for a few releases with clear deprecation note, and remove them eventually, as typically done. This gives people time to adopt.