Explain pipx run with more examples

[wpyoga]

• [x ] I have added an entry to docs/changelog.md

Summary of changes

• README: added more examples (using mpremote and esptool) for pip run
• README: added section for ambiguous arguments

I had trouble trying to run esptool, which has multiple commands in it. I thought there was a missing feature or something (didn't read the whole README before installing pipx). With this change, it will be much easier to search for a solution if someone else runs into a similar issue.

The other addition (section for ambiguous arguments) seem like a minor change that doesn't warrant another pull request. Please CMIIW though.

Thanks!

[chrysle]

Have you tried running these apps without the filetype ending?

[wpyoga]

Yes, and it doesn't work. The project esptool provides executables with .py ending:

$ pipx run --spec esptool esptool
'esptool' executable script not found in package 'esptool'.
Available executable scripts:
    esp_rfc2217_server.py - usage: 'pipx run --spec esptool esp_rfc2217_server.py [arguments?]'
    espefuse.py - usage: 'pipx run --spec esptool espefuse.py [arguments?]'
    espsecure.py - usage: 'pipx run --spec esptool espsecure.py [arguments?]'
    esptool.py - usage: 'pipx run --spec esptool esptool.py [arguments?]'

I suppose this is different from package to package. There are projects that provide executables without the .py ending:

$ pipx run --spec pymodbus[repl] pymodbus.simulator 
2023-06-26 09:35:23,311 INFO  logging:96 Start simulator
2023-06-26 09:35:23,430 INFO  logging:96 Modbus server started
Executing <Task pending name='Task-1' coro=<run_main() running at /home/william/.local/pipx/.cache/8d7f1cb8ac876e4/lib/python3.11/site-packages/pymodbus/server/simulator/main.py:116> wait_for=<_GatheringFuture pending cb=[Task.task_wakeup()] created at /usr/lib/python3.11/asyncio/tasks.py:699> cb=[_run_until_complete_cb() at /usr/lib/python3.11/asyncio/base_events.py:180] created at /usr/lib/python3.11/asyncio/runners.py:100> took 0.119 seconds
2023-06-26 09:35:23,431 INFO  logging:96 HTTP server started
2023-06-26 09:35:23,431 INFO  logging:96 Server(TCP) listening.

Now that I think about it, it seems to be a good example to add into the README. The package requirement has a [repl] suffix, which pulls in dependencies for a REPL, in this instance.

[uranusjr]

Can we add some more text in the document to explain this? i.e. list out what scripts esptool provides so people not familiar with this particular package understand the exact situation.

[wpyoga]

Alright, I've added more detailed explanation in my latest commit.

[uranusjr]

Awesome