Checking devices should have a clear command

[cool-RR]

trafficstars

python -m sounddevice is used to see the list of devices. I think that's a bit awkward, because the command is not descriptive. I know that it's the only command that sounddevice needs to offer, but I do think it'll be more elegant as something like python -m sounddevice list_devices.

[mgeier]

That's already implemented!

You can also use something like:

python3 -m sounddevice gimme_my_devices --and-hurry-up-please

Therefore, supporting a special command (like list_devices) explicitly doesn't make too much sense, or does it?

What should happen if a unsupported command is used? What if no command is used?

[cool-RR]

Yeah, I'd understand the resistance to this issue, it might be OCD on my part.

The issue is that once you support calling python -m sounddevice to show the list of devices, it becomes difficult to change it in the future because of backward compatibility. You might want to change it in the future to support more commands, or for example --version to get the versions of both sounddevice and portaudio. So changing it as soon as possible is beneficial.

To your questions:

What should happen if a unsupported command is used?

An error message, same as if you tried an unsupported command on any other CLI tool:

$ pip floof                   
ERROR: unknown command "floof"

What if no command is used?

Showing the list of commands would be reasonable, like pip does.

I'd understand if you'd close this issue.

[mgeier]

The issue is that once you support calling python -m sounddevice to show the list of devices, it becomes difficult to change it in the future because of backward compatibility.

That is true, but now it would be too late anyway. This functionality has been there since the initial commit, now slightly more than 5 years ago.

I knew that it was a risk not to use sub-commands, but I was willing to take it.

You might want to change it in the future to support more commands, or for example --version to get the versions of both sounddevice and portaudio.

That's a good idea.

But why not just print the version information unconditionally every time, before or after the device list?

I'm not considering the actual text content of the output to be part of the API, so I would feel free to add some text any time. This is meant for human consumption, I don't think adding some version information would hurt. On the contrary, it might be very helpful information for debugging.

If we just add version information to the output, we don't need any additional command line options (at least for now).

Alternatively, we could just check for --version and make a separate version output, I don't see any conflict with the current behavior.

What if no command is used?

Showing the list of commands would be reasonable, like pip does.

I think this would be annoying, since we would have at most two options. So why not show everything immediately?

It sure makes sense with pip to have sub-commands, because it actually has several sub-commands.

To give a counter-example, this module doesn't have sub-commands (but it takes some optional arguments):

python3 -m http.server

We could of course make a sub-module like sounddevice.devicelist which could be used like this:

python3 -m sounddevice.devicelist

... but I don't think this is actually an improvement in ergonomics and I don't think it would be worth the implementation effort (re-structuring the module/package).

I'd understand if you'd close this issue.

I'm very much open to suggestions like this.

I've mentioned my concerns and some counter-suggestions, probably we can find some middle ground?

[cool-RR]

Hmm, this issue is small enough that I don't see the point in a compromise. If you're happy with the current situation that's fine, if you'd like to change it that's fine too.

[mgeier]

I really don't see any reason for artificially creating an obstacle for users by requiring an explicit sub-command (especially since there will be only a single sub-command in the foreseeable future).

I would be fine with optional sub-commands (or flags), though, if there is need for them.

I do like your idea of providing version information (be it in addition to the device list or separately).

And I'm open for further suggestions!