Commits

Vinay Sajip  committed 460bee7

Updated documentation.

  • Participants
  • Parent commits 2439ba8

Comments (0)

Files changed (4)

       implemented validation of .rst descriptions, which is not done in
       distlib.
 
+- scripts
+
+    - Changed the interface for script generation options: the ``make`` and
+      ``make_multiple`` methods of ``ScriptMaker`` now take an optional
+      ``options`` dictionary.
+
 - util
 
     - Added extract_by_key() to copy selected keys from one dict to another.

File docs/internals.rst

   the launcher should be a Windows application rather than a console
   application, for GUI-based scripts which shouldn't show a console window.
 
-  The above specification (apart from the flags) is used by ``setuptools``
-  for the 'console_scripts' feature.  See :ref:`flag-formats` for more
-  information about flags.
+  The above specification is used by ``setuptools`` for the 'console_scripts'
+  feature.  See :ref:`flag-formats` for more information about flags.
+
+  .. note:: Both ``setuptools`` and :pep:`426` interpret flags as a single
+     value, which represents an extra (a set of optional dependencies needed
+     for optional features of a distribution).
 
   It seems sensible for this method to return a list of absolute paths of
   files that were installed (or would have been installed, but for the
   [a,,b]
   [a=,b,c]
 
+.. note:: Both ``setuptools`` and :pep:`426` restrict flag formats to a single
+   value, without an ``=``. This value represents an extra (a set of optional
+   dependencies needed for optional features of a distribution).
 
 .. _version-api:
 

File docs/reference.rst

       :type add_launchers: bool
       :param dry_run: If true, don't actually install scripts - just pretend to.
 
-   .. method:: make(specification)
+   .. method:: make(specification, options=None)
 
       Make a script in the target directory.
 
 
                                   name = some_package.some_module:some_callable [flags]
 
-                              where the *flags* part is optional. The only flag
-                              currently in use is ``'gui'``, which indicates on
-                              Windows that a Windows executable launcher
-                              (rather than a launcher which is a console
-                              application) should be used. (This only applies if
-                              ``add_launchers`` is true.)
+                              where the *flags* part is optional.
 
                               When this form is passed, a Python stub script
                               is created with the appropriate shebang line and
                               :ref:`flag-formats`.
 
       :type specification: str
+      :param options: If specified, a dictionary of options used to control
+                      script creation. Currently, only the key ``gui`` is
+                      checked: this should be a ``bool`` which, if ``True``,
+                      indicates that the script is a windowed application.
+                      This distinction is only drawn on Windows if
+                      ``add_launchers`` is ``True``, and results in a windowed
+                      native launcher application if ``options['gui']`` is
+                      ``True`` (otherwise, the native executable launcher is a
+                      console application).
+
       :returns: A list of absolute pathnames of files installed (or which
                 would have been installed, but for ``dry_run`` being true).
 
-   .. method:: make_multiple(specifications)
+   .. method:: make_multiple(specifications, options)
 
       Make multiple scripts from an iterable.
 
       running ``2to3`` on them).
 
       :param specifications: an iterable giving the specifications to follow.
+      :param options: As for the :meth:`make` method.
       :returns: A list of absolute pathnames of files installed (or which
                 would have been installed, but for ``dry_run`` being true).
 

File docs/tutorial.rst

 This entry format is used in the :mod:`distlib.scripts` package for installing
 scripts based on Python callables.
 
+.. note:: In :pep:`426`, the ``flags`` value is limited to a single flag
+   representing an extra (optional set of dependencies, for optional features
+   of a distribution).
+
 Distribution dependencies
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
       name = some_package.some_module:some_callable [flags]
 
-  where the *flags* part is optional. The only flag currently in use is
-  ``'gui'``, which indicates on Windows that a Windows executable launcher
-  (rather than a launcher which is a console application) should be used.
-  (This only applies if ``add_launchers`` is true.)
+  where the *flags* part is optional.
 
   For more information about flags, see :ref:`flag-formats`.
 
   Note that this format is exactly the same as for export entries in a
   distribution (see :ref:`dist-exports`).
 
-  When this form is passed to the :meth:`ScriptMaker.make`
-  method, a Python stub script is created with the appropriate shebang line
-  and with code to load and call the specified callable with no arguments,
-  returning its value as the return code from the script.
+  When this form is passed to the :meth:`ScriptMaker.make` method, a Python
+  stub script is created with the appropriate shebang line and with code to
+  load and call the specified callable with no arguments, returning its value
+  as the return code from the script.
+
+  You can pass an optional ``options`` dictionary to the :meth:`make` method.
+  This is meant to contain options which control script generation. The only
+  option currently in use is ``'gui'``, which indicates on Windows that a
+  Windows executable launcher (rather than a launcher which is a console
+  application) should be used. (This only applies if ``add_launchers`` is
+  true.)
+
+  For example, you can pass ``{'gui': True}`` to generate a windowed script.
 
 Wrapping callables with scripts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ``False`` by default, which prevents overwriting; to force overwriting, set it
 to ``True``.
 
+Generating windowed scripts on Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. index::
+   single: Scripts; windowed
+
+The :meth:`make` and :meth:`make_multiple` methods take an optional second
+``options`` argument, which can be used to control script generation. If
+specified, this should be a dictionary of options. Currently, only the value
+for the ``gui`` key in the dictionary is inspected: if ``True``, it generates
+scripts with ``.pyw`` extensions (rather than ``.py``) and, if
+``add_launchers`` is specified as ``True`` in the :class:`ScriptMaker`
+instance, then (on Windows) a windowed native executable launcher is created
+(otherwise, the native executable launcher will be a console application).
+
 
 Using the version API
 ^^^^^^^^^^^^^^^^^^^^^