- Added a section named "Making Your Script into a Console Script" in the

  "Command-Line Pyramid" chapter.

3 files changed, 240 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 795824e0b..63c84d0f8 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -14,6 +14,12 @@ Bug Fixes
 - Normalized exit values and ``-h`` output for all ``p*`` scripts
   (``pviews``, ``proutes``, etc).
 
+Documentation
+-------------
+
+- Added a section named "Making Your Script into a Console Script" in the
+  "Command-Line Pyramid" chapter.
+
 1.3a2 (2011-12-14)
 ==================
 
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index b9aa2c8c3..dc3cff8ac 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -654,3 +654,234 @@ use the following command:
 
    import logging.config
    logging.config.fileConfig('/path/to/my/development.ini')
+
+.. index::
+   single: console script
+
+.. _making_a_console_script:
+
+Making Your Script into a Console Script
+----------------------------------------
+
+A "console script" is :term:`setuptools` terminology for a script that gets
+installed into the ``bin`` directory of a Python :term:`virtualenv` (or
+"base" Python environment) when a :term:`distribution` which houses that
+script is installed.  Because it's installed into the ``bin`` directory of a
+virtualenv when the distribution is installed, it's a convenient way to
+package and distribute functionality that you can call from the command-line.
+It's often more convenient to create a console script than it is to create a
+``.py`` script and instruct people to call it with "the right Python
+interpreter": because it generates a file that lives in ``bin``, when it's
+invoked, it will always use "the right" Python environment, which means it
+will always be invoked in an environment where all the libraries it needs
+(such as Pyramid) are available.
+
+In general, you can make your script into a console script by doing the
+following:
+
+- Use an existing distribution (such as one you've already created via
+  ``pcreate``) or create a new distribution that possesses at least one
+  package or module.  It should, within any module within the distribution,
+  house a callable (usually a function) that takes no arguments and which
+  runs any of the code you wish to run.
+
+- Add a ``[console_scripts]`` section to the ``entry_points`` argument of the
+  distribution which creates a mapping between a script name and a dotted
+  name representing the callable you added to your distribution.
+
+- Run ``setup.py develop``, ``setup.py install``, or ``easy_install`` to get
+  your distribution reinstalled.  When you reinstall your distribution, a
+  file representing the script that you named in the last step will be in the
+  ``bin`` directory of the virtualenv in which you installed the
+  distribution.  It will be executable.  Invoking it from a terminal will
+  execute your callable.
+
+As an example, let's create some code that can be invoked by a console script
+that prints the deployment settings of a Pyramid application.  To do so,
+we'll pretend you have a distribution with a package in it named
+``myproject``.  Within this package, we'll pretend you've added a
+``scripts.py`` module which contains the following code:
+
+.. code-block:: python
+   :linenos:
+
+   # myproject.scripts module
+
+   import optparse
+   import sys
+   import textwrap
+
+   from pyramid.paster import bootstrap
+
+   def settings_show():
+       description = """\
+       Print the deployment settings for a Pyramid application.  Example:
+       'psettings deployment.ini'
+       """
+       usage = "usage: %prog config_uri"
+       parser = optparse.OptionParser(
+           usage=usage,
+           description=textwrap.dedent(description)
+           )
+       parser.add_option(
+           '-o', '--omit',
+           dest='omit',
+           metavar='PREFIX',
+           type='string',
+           action='append',
+           help=("Omit settings which start with PREFIX (you can use this "
+                 "option multiple times)")
+           )
+
+       options, args = parser.parse_args(sys.argv[1:])
+       if not len(args) >= 1:
+           print('You must provide at least one argument')
+           return 2
+       config_uri = args[0]
+       omit = options.omit
+       if omit is None:
+           omit = []
+       env = bootstrap(config_uri)
+       settings, closer = env['registry'].settings, env['closer']
+       try:
+           for k, v in settings.items():
+               if any([k.startswith(x) for x in omit]):
+                   continue
+               print('%-40s     %-20s' % (k, v))
+       finally:
+           closer()
+
+This script uses the Python ``optparse`` module to allow us to make sense out
+of extra arguments passed to the script.  It uses the
+:func:`pyramid.paster.bootstrap` function to get information about the the
+application defined by a config file, and prints the deployment settings
+defined in that config file.
+
+After adding this script to the package, you'll need to tell your
+distribution's ``setup.py`` about its existence.  Within your distribution's
+top-level directory your ``setup.py`` file will look something like this:
+
+.. code-block:: python
+   :linenos:
+
+   import os
+
+   from setuptools import setup, find_packages
+
+   here = os.path.abspath(os.path.dirname(__file__))
+   README = open(os.path.join(here, 'README.txt')).read()
+   CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+
+   requires = ['pyramid', 'pyramid_debugtoolbar']
+
+   setup(name='MyProject',
+         version='0.0',
+         description='My project',
+         long_description=README + '\n\n' +  CHANGES,
+         classifiers=[
+           "Programming Language :: Python",
+           "Framework :: Pylons",
+           "Topic :: Internet :: WWW/HTTP",
+           "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+           ],
+         author='',
+         author_email='',
+         url='',
+         keywords='web pyramid pylons',
+         packages=find_packages(),
+         include_package_data=True,
+         zip_safe=False,
+         install_requires=requires,
+         tests_require=requires,
+         test_suite="wiggystatic",
+         entry_points = """\
+         [paste.app_factory]
+         main = wiggystatic:main
+         """,
+         )
+
+We're going to change the setup.py file to add an ``[console_scripts]``
+section with in the ``entry_points`` string.  Within this section, you should
+specify a ``scriptname = dotted.path.to:yourfunction`` line.  For example::
+
+  [console_scripts]
+  show_settings = myproject.scripts:settings_show
+
+The ``show_settings`` name will be the name of the script that is installed
+into ``bin``.  The colon (``:``) between ``myproject.scripts`` and
+``settings_show`` above indicates that ``myproject.scripts`` is a Python
+module, and ``settings_show`` is the function in that module which contains
+the code you'd like to run as the result of someone invoking the
+``show_settings`` script from their command line.
+
+The result will be something like:
+
+.. code-block:: python
+   :linenos:
+
+   import os
+
+   from setuptools import setup, find_packages
+
+   here = os.path.abspath(os.path.dirname(__file__))
+   README = open(os.path.join(here, 'README.txt')).read()
+   CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
+
+   requires = ['pyramid', 'pyramid_debugtoolbar']
+
+   setup(name='MyProject',
+         version='0.0',
+         description='My project',
+         long_description=README + '\n\n' +  CHANGES,
+         classifiers=[
+           "Programming Language :: Python",
+           "Framework :: Pylons",
+           "Topic :: Internet :: WWW/HTTP",
+           "Topic :: Internet :: WWW/HTTP :: WSGI :: Application",
+           ],
+         author='',
+         author_email='',
+         url='',
+         keywords='web pyramid pylons',
+         packages=find_packages(),
+         include_package_data=True,
+         zip_safe=False,
+         install_requires=requires,
+         tests_require=requires,
+         test_suite="wiggystatic",
+         entry_points = """\
+         [paste.app_factory]
+         main = wiggystatic:main
+         [console_scripts]
+         show_settings = myproject.scripts:settings_show
+         """,
+         )
+
+Once you've done this, invoking ``$somevirtualenv/bin/python setup.py
+develop`` will install a file named ``show_settings`` into the
+``$somevirtualenv/bin`` directory with a small bit of Python code that points
+to your entry point.  It will be executable.  Running it without any
+arguments will print an error and exit.  Running it with a single argument
+that is the path of a config file will print the settings.  Running it with
+an ``--omit=foo`` argument will omit the settings that have keys that start
+with ``foo``.  Running it with two "omit" options (e.g. ``--omit=foo
+--omit=bar``) will omit all settings that have keys that start with either
+``foo`` or ``bar``::
+
+  [chrism@thinko somevenv]$ bin/show_settings development.ini \
+                            --omit=pyramid \
+                            --omit=debugtoolbar
+  debug_routematch                             False               
+  debug_templates                              True                
+  reload_templates                             True                
+  mako.directories                             []                  
+  debug_notfound                               False               
+  default_locale_name                          en                  
+  reload_resources                             False               
+  debug_authorization                          False               
+  reload_assets                                False               
+  prevent_http_cache                           False               
+
+Pyramid's ``pserve``, ``pcreate``, ``pshell``, ``prequest``, ``ptweens`` and
+other ``p*`` scripts are implemented as console scripts.  When you invoke one
+of those, you are using a console script.
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index a69efd268..8dd3c3cdb 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -299,6 +299,9 @@ Documentation Enhancements
 - Added a description of the ``prequest`` command-line script at
   :ref:`invoking_a_request`.
 
+- Added a section to the "Command-Line Pyramid" chapter named
+  :ref:`making_a_console_script`.
+
 Dependency Changes
 ------------------