Merge pull request #83 from angerson/patch-1

Add executable and shebang examples

README.rst

@@ -75,6 +75,7 @@ Usage
 - as runtime dependency context manager
 - as interactive interpreter in dependency context
 - as module launcher (akin to `python -m`)
+- as a shell shebang (``#!/usr/bin/env -S pip-run --``), to create single-file Python tools
 
 Invoke ``pip-run`` from the command-line using the console entry
 script (simply ``pip-run``) or using the module executable (
@@ -128,6 +129,14 @@ executable modules and packages via
 .. image:: docs/cowsay.svg
    :alt: cowsay example animation
 
+Module Executable Runner
+------------------------
+
+Some package tools, like `ranger <https://github.com/ranger/ranger>`_, are
+invoked with a unique executable instead of a module. ``pip-run`` can
+run an executable from a package if it is prependend by a ``!``::
+
+    $ pip-run ranger-fm -- '!ranger'
 
 Command Runner
 --------------
@@ -215,6 +224,38 @@ declaring any parameters to pip::
 
 The format for requirements must follow `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_.
 
+Single-script Tools and Shebang Support
+---------------------------------------
+
+Combined with in-script dependencies, ``pip-run`` can be used
+as a shebang on Unix platforms to create fully self-contained
+scripts that install and run their own dependencies, as long
+as ``pip-run`` is installed on the system ``PATH``.
+
+.. code-block:: shell
+
+    #!/usr/bin/env -S pip-run --
+    __requires__ = ['requests', 'beautifulsoup4', 'cowsay']
+    import requests
+    from bs4 import BeautifulSoup as BS
+    import cowsay
+    res = requests.get('https://python.org')
+    b = BS(res.text, 'html.parser')
+    cowsay.dragon(b.find("div", class_="introduction").get_text())
+
+Executing this script, when saved as ``myscript``, is equivalent to ``pip-run -- myscript``.
+``-S`` and ``--`` ensure that extension-less scripts (like ``myscript`` rather than ``myscript.py``)
+will be correctly identified as a script (rather than as a dependency), so don't forget them.
+
+By default, ``pip-run`` will re-install dependencies every time a script runs.
+This silently adds a variable amount of startup time depending on how many dependencies
+there are (use ``pip-run -v -- myscript`` to see the list). A script may cache those
+installs via `Environment Persistence <#Environment-Persistence>`_ by setting
+``PIP_RUN_MODE=persist``::
+
+    #!/usr/bin/env -S PIP_RUN_MODE=persist pip-run --
+    ...
+
 Other Script Directives
 -----------------------