Inconsistent placement of options

[dmyersturnbull]

Great package! I just wrote a tiny pre-commit hook for it. I'm seeing a couple limitations (I'll open an Issue for each).

Restricted to before the command

-v, --debug, --filename, --platform, and --max-len are only allowed before the command, but e.g. pathvalidate -v validate and pathvalidate validate -v should probably both work.

$ pathvalidate validate -v x
# [...]
Error: No such option: -v

Ironically, any unrecognized value starting with - is treated as an option anyway, and the POSIX standard -- is handled correctly, so there's no advantage to the current behavior:

$ pathvalidate -v validate -x
# [...]
Error: No such option: -x

$ # `--` is skipped:
$ pathvalidate -v validate -- -x
[INFO] -x is a valid path for universal

Restricted to after

--min-len and --no-check-reserved are like this.

$ pathvalidate --min-len 100 validate x
error: unexpected argument '--min-len' found

  tip: a similar argument exists: '--find-links'

Usage: uvx [OPTIONS] [COMMAND]

For more information, try '--help'.

Incidentally, validate --max-len suggests you meant --min-len:

$ pathvalidate validate --max-len 100 x
# [...]
Error: No such option: --max-len Did you mean --min-len?

Fixing this

Click is evidently already treating -- correctly. I haven't used Click directly before, only typer.

[thombashi]

@dmyersturnbull
Hello,
I don't fully understand your problem and how you would like to solve it, but I'll explain the command design.

The options for pathvalidate-cli are specified as follows.

pathvalidate [COMMON OPTIONS] <SUBCOMMAND> [SUBCOMMAND OPTIONS] PATHS...

COMMON OPTIONS: Options common between subcommands
SUBCOMMAND OPTIONS: Subcommand-specific options

For example, --max-len is a COMMON OPTIONS because it can be applied to both validate and sanitize subcommands.
Conversely, --min-len is an option that can only be applied to the validate subcommand.
Even if you pass a minimum length to the sanitize subcommand, the sanitize subcommand cannot process it.
The processing of this option specification is the behavior of click, so I basically cannot change it.

COMMON OPTIONS and SUBCOMMAND OPTIONS can be viewed with --help for each subcommand.

$ pathvalidate --help
Usage: pathvalidate [OPTIONS] COMMAND [ARGS]...

Options:
  --version                     Show the version and exit.
  --debug                       For debug print.
  -q, --quiet                   Suppress execution log messages.
  --filename                    Consider inputs as filenames.
  --max-len, --max-bytes BYTES  Maximum byte counts of file paths. -1: same
                                value as the platform limitation.  [default:
                                -1]
  --platform PLATFORM           Target platform name (case-insensitive). Valid
                                platform specifiers are Linux/Windows/macOS.
                                Valid special values are: auto, universal,
                                POSIX (a) auto: automatically detects the
                                execution platform. (b) universal: platform
                                independent. (c) POSIX: POSIX-compliant
                                platform.  [default: universal]
  -v, --verbose                 Verbosity level  [default: 0]
  -h, --help                    Show this message and exit.

Commands:
  error     Print error reasons.
  sanitize  Sanitize file paths.
  validate  Validate file paths.

$ pathvalidate validate --help
Usage: pathvalidate validate [OPTIONS] [FILEPATHS]...

  Validate file paths.

Options:
  --min-len, --min-bytes BYTES  Minimum byte counts of file paths.  [default:
                                1]
  --no-check-reserved           Check reserved names.
  -h, --help                    Show this message and exit.

  Issue tracker: https://github.com/thombashi/pathvalidate-cli/issues

[dmyersturnbull]

@thombashi The design makes sense to me overall. Two things, though:

--max-len doesn't seem general enough to be global.

Most importantly, it doesn't apply to all subcommands. In fact, this runs without complaint: pathvalidate --max-len 1 error PV1001. †

Personally, I'd simply make --max-len an option for validate and sanitize. The option already means something different for sanitize; its help string should probably explain that it truncates. In contrast, -q and -v always apply. --platform is general enough that it could be either global or subcommand-specific. ‡

Most CLIs allow global options to be placed after the subcommand.

For example:

# `-C`/`--git-dir` works before or after:
git -C /path/to/repo log
git log -C /path/to/repo

# Of course, not this:
git log --version

There's a known solution for Click: pallets/click#108 (comment)

The symmetry of --min-len and --max-len makes pathvalidate-cli's behavior especially confusing.

---

† By the way, --max-len 0 isn't an error, but I'm not sure what it does.

‡ I don't know what --filename does; the description is "Consider inputs as filenames.". Does that mean paths are assumed to be regular files?