Merge branch 'develop' into feature/pep381-verification

Conflicts:
	pip/basecommand.py
	pip/download.py

AUTHORS.txt

@@ -30,6 +30,7 @@ Oliver Tonnhofer
 Olivier Girardot
 Patrick Jenkins
 Paul Nasrat
+Paul Oswald
 Peter Waller
 Rene Dudfield
 Ronny Pfannschmidt

docs/news.txt

@@ -41,6 +41,8 @@ develop (unreleased)
 
 * Fixed issue #366 - pip throws IndexError when it calls `scraped_rel_links`
 
+* Fixed issue #22 - pip search should set and return a userful shell status code
+
 
 1.0.2 (2011-07-16)
 ------------------

docs/requirements.txt

@@ -59,8 +59,7 @@ break MyApp.  If that happens you can update the requirements file to
 force an earlier version of Library, and you can do that without
 having to re-release MyApp at all.
 
-Read the `requirements file format <http://pip.openplans.org/requirement-format.html>`_ to
-learn about other features.
+Read the `requirements file format`_ to learn about other features.
 
 Freezing Requirements
 =====================
@@ -86,8 +85,8 @@ sort of template for the new file.  So if you do::
 it will keep the packages listed in ``devel-req.txt`` in order and preserve
 comments.
 
-The requirements file format
-============================
+The _`requirements file format`
+===============================
 
 The requirements file is a way to get pip to install specific packages
 to make up an *environment*.  This document describes that format.  To
@@ -99,9 +98,15 @@ installed.  For example::
 
     MyPackage==3.0
 
-tells pip to install the 3.0 version of MyPackage.  
+tells pip to install the 3.0 version of MyPackage.
 
-You can also install a package in an "editable" form.  This puts the
+You can also request `extras`_ in the requirements file::
+
+    MyPackage==3.0 [PDF]
+
+.. _extras: http://peak.telecommunity.com/DevCenter/setuptools#declaring-extras-optional-features-with-their-own-dependencies
+
+Packages may also be installed in an "editable" form.  This puts the
 source code into ``src/distname`` (making the name lower case) and
 runs ``python setup.py develop`` on the package.  To indicate
 editable, use ``-e``, like::
@@ -164,7 +169,7 @@ Pip currently supports cloning over ``git``, ``git+http`` and ``git+ssh``::
     -e git+http://git.myproject.org/MyProject/#egg=MyProject
     -e git+ssh://git@myproject.org/MyProject/#egg=MyProject
 
-Passing branch names, a commit hash or a tag name is also possible:: 
+Passing branch names, a commit hash or a tag name is also possible::
 
     -e git://git.myproject.org/MyProject.git@master#egg=MyProject
     -e git://git.myproject.org/MyProject.git@v1.0#egg=MyProject

docs/usage.txt

@@ -12,16 +12,20 @@ The simplest way to install a package is by specifying its name::
 `SomePackage` is downloaded from :term:`PyPI`, along with its
 dependencies, and installed.
 
-If `SomePackage` is already installed, and you need a newer version, use
-``pip install --upgrade SomePackage``. You can also request a specific
-version: ``pip install SomePackage==1.0.4``.
+If `SomePackage` is already installed, and you need a newer version, use ``pip
+install --upgrade SomePackage``. You can also request a specific version (``pip
+install SomePackage==1.0.4``) and specify `setuptools extras`_ (``pip install
+SomePackage[PDF]``).
 
 You can also install from a particular source distribution file, either
 local or remote::
 
     $ pip install ./downloads/SomePackage-1.0.4.tar.gz
     $ pip install http://my.package.repo/SomePackage-1.0.4.zip
 
+.. _setuptools extras: http://peak.telecommunity.com/DevCenter/setuptools#declaring-extras-optional-features-with-their-own-dependencies
+
+
 Edit mode
 *********
 
@@ -35,6 +39,7 @@ package::
 
 .. _normally: http://docs.python.org/install/index.html#how-installation-works
 
+
 Version control systems
 ***********************
 
@@ -51,6 +56,10 @@ folder by appending a hash to the repository URL::
 
     $ pip install -e git+https://github.com/lakshmivyas/hyde.git#egg=hyde
 
+Note that only basic checking-out of a repo is supported; pip will not
+handle advanced VCS-specific features such as submodules or subrepos.
+
+
 Alternate package repositories
 ******************************
 
@@ -114,6 +123,7 @@ from conflicting versions aren't left hanging around to cause trouble. The
 old version of the package is automatically restored if the new version
 fails to download or install.
 
+
 Searching for packages
 ----------------------
 
@@ -126,6 +136,7 @@ The query will be used to search the names and summaries of all
 packages. With the ``--index`` option you can search in a different
 repository.
 
+
 Bundles
 -------
 

pip/basecommand.py

@@ -13,8 +13,11 @@
 from pip.download import urlopen
 from pip.exceptions import (BadCommand, InstallationError,
                             UninstallationError, CommandError)
+from pip.backwardcompat import StringIO, walk_packages
 from pip.log import logger
 from pip.locations import serverkey_file
+from pip.status_codes import SUCCESS, ERROR, UNKNOWN_ERROR, VIRTUALENV_NOT_FOUND
+
 
 __all__ = ['command_dict', 'Command', 'load_all_commands',
            'load_command', 'command_names']
@@ -24,7 +27,6 @@
 # for backwards compatibiliy
 get_proxy = urlopen.get_proxy
 
-
 class Command(object):
     name = None
     usage = None
@@ -100,7 +102,7 @@ def main(self, args, initial_options):
             if not os.environ.get('VIRTUAL_ENV'):
                 logger.fatal('Could not find an activated '
                              'virtualenv (required).')
-                sys.exit(3)
+                sys.exit(VIRTUALENV_NOT_FOUND)
 
         if not os.path.exists(serverkey_file) or options.refresh_serverkey:
             self.refresh_serverkey()
@@ -115,37 +117,40 @@ def main(self, args, initial_options):
 
         urlopen.setup(proxystr=options.proxy, prompting=not options.no_input)
 
-        exit = 0
+        exit = SUCCESS
         store_log = False
         try:
-            self.run(options, args)
+            status = self.run(options, args)
+            # FIXME: all commands should return an exit status
+            # and when it is done, isinstance is not needed anymore
+            if isinstance(status, int):
+                exit = status
         except (InstallationError, UninstallationError):
             e = sys.exc_info()[1]
             logger.fatal(str(e))
             logger.info('Exception information:\n%s' % format_exc())
             store_log = True
-            exit = 1
+            exit = ERROR
         except BadCommand:
             e = sys.exc_info()[1]
             logger.fatal(str(e))
             logger.info('Exception information:\n%s' % format_exc())
             store_log = True
-            exit = 1
+            exit = ERROR
         except CommandError:
             e = sys.exc_info()[1]
             logger.fatal('ERROR: %s' % e)
             logger.info('Exception information:\n%s' % format_exc())
-            exit = 1
+            exit = ERROR
         except KeyboardInterrupt:
             logger.fatal('Operation cancelled by user')
             logger.info('Exception information:\n%s' % format_exc())
             store_log = True
-            exit = 1
+            exit = ERROR
         except:
             logger.fatal('Exception:\n%s' % format_exc())
             store_log = True
-            exit = 2
-
+            exit = UNKNOWN_ERROR
         if log_fp is not None:
             log_fp.close()
         if store_log:

pip/commands/help.py

@@ -1,5 +1,7 @@
-from pip.basecommand import Command, command_dict, load_all_commands
-from pip.exceptions import InstallationError
+from pip.basecommand import (Command, command_dict,
+                             load_all_commands, SUCCESS,
+                             ERROR)
+from pip.exceptions import CommandError
 from pip.baseparser import parser
 
 
@@ -14,10 +16,10 @@ def run(self, options, args):
             ## FIXME: handle errors better here
             command = args[0]
             if command not in command_dict:
-                raise InstallationError('No command with the name: %s' % command)
+                raise CommandError('No command with the name: %s' % command)
             command = command_dict[command]
             command.parser.print_help()
-            return
+            return SUCCESS
         parser.print_help()
         print('\nCommands available:')
         commands = list(set(command_dict.values()))
@@ -26,6 +28,6 @@ def run(self, options, args):
             if command.hidden:
                 continue
             print('  %s: %s' % (command.name, command.summary))
-
+        return SUCCESS
 
 HelpCommand()

pip/commands/search.py

@@ -2,18 +2,15 @@
 import textwrap
 import pkg_resources
 import pip.download
-from pip.basecommand import Command
+from pip.basecommand import Command, SUCCESS
 from pip.util import get_terminal_size
 from pip.log import logger
 from pip.backwardcompat import xmlrpclib, reduce, cmp
 from pip.exceptions import CommandError
+from pip.status_codes import NO_MATCHES_FOUND
 from distutils.version import StrictVersion, LooseVersion
 
 
-class SearchCommandError(CommandError):
-    pass
-
-
 class SearchCommand(Command):
     name = 'search'
     usage = '%prog QUERY'
@@ -42,6 +39,9 @@ def run(self, options, args):
             terminal_width = get_terminal_size()[0]
 
         print_results(hits, terminal_width=terminal_width)
+        if pypi_hits:
+            return SUCCESS
+        return NO_MATCHES_FOUND
 
     def search(self, query, index_url):
         pypi = xmlrpclib.ServerProxy(index_url, pip.download.xmlrpclib_transport)

pip/download.py

@@ -184,8 +184,8 @@ def setup(self, proxystr='', prompting=True):
         self.prompting = prompting
         proxy = self.get_proxy(proxystr)
         if proxy:
-            handler = urllib2.ProxyHandler({"http": proxy, "ftp": proxy})
-            opener = urllib2.build_opener(handler, urllib2.CacheFTPHandler)
+            proxy_support = urllib2.ProxyHandler({"http": proxy, "ftp": proxy, "https": proxy})
+            opener = urllib2.build_opener(proxy_support, urllib2.CacheFTPHandler)
             urllib2.install_opener(opener)
 
     def parse_credentials(self, netloc):

pip/status_codes.py

@@ -0,0 +1,5 @@
+SUCCESS = 0
+ERROR = 1
+UNKNOWN_ERROR = 2
+VIRTUALENV_NOT_FOUND = 3
+NO_MATCHES_FOUND = 23

tests/test_help.py

@@ -0,0 +1,62 @@
+from pip.exceptions import CommandError
+from pip.commands.help import (HelpCommand,
+                               SUCCESS,
+                               ERROR,)
+from mock import Mock
+from nose.tools import assert_raises
+from tests.test_pip import run_pip, reset_env
+
+
+def test_run_method_should_return_sucess_when_finds_command_name():
+    """
+    Test HelpCommand.run for existing command
+    """
+    options_mock = Mock()
+    args = ('freeze',)
+    help_cmd = HelpCommand()
+    status = help_cmd.run(options_mock, args)
+    assert status == SUCCESS
+
+def test_run_method_should_return_sucess_when_command_name_not_specified():
+    """
+    Test HelpCommand.run when there are no args
+    """
+    options_mock = Mock()
+    args = ()
+    help_cmd = HelpCommand()
+    status = help_cmd.run(options_mock, args)
+    assert status == SUCCESS
+
+def test_run_method_should_raise_command_error_when_command_does_not_exist():
+    """
+    Test HelpCommand.run for non-existing command
+    """
+    options_mock = Mock()
+    args = ('mycommand',)
+    help_cmd = HelpCommand()
+    assert_raises(CommandError, help_cmd.run, options_mock, args)
+
+def test_help_command_should_exit_status_ok_when_command_exists():
+    """
+    Test `help` command for existing command
+    """
+    reset_env()
+    result = run_pip('help', 'freeze')
+    assert result.returncode == SUCCESS
+
+def test_help_command_should_exit_status_ok_when_no_command_is_specified():
+    """
+    Test `help` command for no command
+    """
+    reset_env()
+    result = run_pip('help')
+    assert result.returncode == SUCCESS
+
+def test_help_command_should_exit_status_error_when_command_does_not_exist():
+    """
+    Test `help` command for non-existing command
+    """
+    reset_env()
+    result = run_pip('help', 'mycommand', expect_error=True)
+    assert result.returncode == ERROR
+