Merge branch 'separate-binary'

NEWS

@@ -17,6 +17,9 @@ Other changes:
 What's new in psycopg 2.7.4
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+- Moving away from installing the wheel package by default.
+  Packages installed from wheel raise a warning on import. Added package
+  ``psycopg2-binary`` to install from wheel instead (:ticket:`#543`).
 - Fixed Solaris 10 support (:ticket:`#532`).
 - `cursor.mogrify()` can be called on closed cursors (:ticket:`#579`).
 - Fixed setting session characteristics in corner cases on autocommit
@@ -25,8 +28,8 @@ What's new in psycopg 2.7.4
 - Fixed parsing of array of points as floats (:ticket:`#613`).
 - Fixed `~psycopg2.__libpq_version__` building with libpq >= 10.1
   (:ticket:`632`).
-- Fixed `~cursor.rowcount` after `~cursor.executemany()` with :sql:`RETURNING` statements
+- Fixed `~cursor.rowcount` after `~cursor.executemany()` with :sql:`RETURNING`
-  (:ticket:`633`).
+  statements (:ticket:`633`).
 - Fixed compatibility problem with pypy3 (:ticket:`#649`).
 - Wheel packages compiled against PostgreSQL 10.1 libpq and OpenSSL 1.0.2m.
 

README.rst

@@ -25,29 +25,39 @@ Documentation is included in the ``doc`` directory and is `available online`__.
 
 .. __: http://initd.org/psycopg/docs/
 
+For any other resource (source code repository, bug tracker, mailing list)
+please check the `project homepage`__.
+
 
 Installation
 ------------
 
-If your ``pip`` version supports wheel_ packages it should be possible to
+Building Psycopg requires a few prerequisites (a C compiler, some development
-install a binary version of Psycopg including all the dependencies from PyPI_.
+packages): please check the install_ and the faq_ documents in the ``doc`` dir
-Just run::
+or online for the details.
+
+If prerequisites are met, you can install psycopg like any other Python
+package, using ``pip`` to download it from PyPI_::
 
-    $ pip install -U pip      # make sure your pip is up-to-date
     $ pip install psycopg2
 
-If you want to build Psycopg from source you will need some prerequisites (a C
+or using ``setup.py`` if you have downloaded the source package locally::
-compiler, development packages): please check the install_ and the faq_
+
-documents in the ``doc`` dir for the details.
+    $ python setup.py build
+    $ sudo python setup.py install
+
+You can also obtain a stand-alone package, not requiring a compiler or
+external libraries, by installing the ``psycopg2-binary`` package from PyPI::
+
+    $ pip install psycopg2-binary
+
+The binary package is a practical choice for development and testing but in
+production it is advised to use the package built from sources.
 
-.. _wheel: http://pythonwheels.com/
 .. _PyPI: https://pypi.python.org/pypi/psycopg2
 .. _install: http://initd.org/psycopg/docs/install.html#install-from-source
 .. _faq: http://initd.org/psycopg/docs/faq.html#faq-compile
 
-For any other resource (source code repository, bug tracker, mailing list)
-please check the `project homepage`__.
-
 .. __: http://initd.org/psycopg/
 
 

doc/src/install.rst

@@ -12,16 +12,6 @@ to use Psycopg on a different Python implementation (PyPy, Jython, IronPython)
 there is an experimental `porting of Psycopg for Ctypes`__, but it is not as
 mature as the C implementation yet.
 
-The current `!psycopg2` implementation supports:
-
-..
-    NOTE: keep consistent with setup.py and the /features/ page.
-
-- Python version 2.7
-- Python 3 versions from 3.4 to 3.6
-- PostgreSQL server versions from 7.4 to 10
-- PostgreSQL client library version from 9.1
-
 .. _PostgreSQL: http://www.postgresql.org/
 .. _Python: http://www.python.org/
 .. _libpq: http://www.postgresql.org/docs/current/static/libpq.html
@@ -32,94 +22,20 @@ The current `!psycopg2` implementation supports:
 
 
 .. index::
-    single: Install; from PyPI
+    single: Prerequisites
-    single: Install; wheel
-    single: Wheel
 
-Binary install from PyPI
+Prerequisites
-------------------------
+-------------
 
-`!psycopg2` is `available on PyPI`__ in the form of wheel_ packages for the
+The current `!psycopg2` implementation supports:
-most common platform (Linux, OSX, Windows): this should make you able to
-install a binary version of the module including all the dependencies simply
-using:
 
-.. code-block:: console
+..
+    NOTE: keep consistent with setup.py and the /features/ page.
 
-    $ pip install psycopg2
+- Python version 2.7
-
+- Python 3 versions from 3.4 to 3.6
-Make sure to use an up-to-date version of :program:`pip` (you can upgrade it
+- PostgreSQL server versions from 7.4 to 10
-using something like ``pip install -U pip``)
+- PostgreSQL client library version from 9.1
-
-.. __: PyPI_
-.. _PyPI: https://pypi.python.org/pypi/psycopg2/
-.. _wheel: http://pythonwheels.com/
-
-.. note::
-
-    The binary packages come with their own versions of a few C libraries,
-    among which ``libpq`` and ``libssl``, which will be used regardless of other
-    libraries available on the client: upgrading the system libraries will not
-    upgrade the libraries used by `!psycopg2`. Please build `!psycopg2` from
-    source if you want to maintain binary upgradeability.
-
-.. warning::
-
-    Because the `!psycopg` wheel package uses its own ``libssl`` binary, it is
-    incompatible with other extension modules binding with ``libssl`` as well,
-    for instance the Python `ssl` module: the result will likely be a
-    segfault. If you need using both `!psycopg2` and other libraries using
-    ``libssl`` please :ref:`disable the use of wheel packages for Psycopg
-    <disable-wheel>`.
-
-
-
-.. index::
-    single: Install; disable wheel
-    single: Wheel; disable
-
-.. _disable-wheel:
-
-Disabling wheel packages
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you want to disable the use of wheel binary packages and use the system
-system libraries available on your client you can use the :command:`pip`
-|--no-binary option|__:
-
-.. code-block:: console
-
-    $ pip install --no-binary psycopg2
-
-.. |--no-binary option| replace:: ``--no-binary`` option
-.. __: https://pip.pypa.io/en/stable/reference/pip_install/#install-no-binary
-
-which can be specified in your :file:`requirements.txt` files too, e.g. use:
-
-.. code-block:: none
-
-    psycopg2>=2.7,<2.8 --no-binary psycopg2
-
-to use the last bugfix release of the `!psycopg2` 2.7 package, specifying to
-always compile it from source. Of course in this case you will have to meet
-the :ref:`build prerequisites <build-prerequisites>`.
-
-
-
-.. index::
-    single: Install; from source
-
-.. _install-from-source:
-
-Install from source
--------------------
-
-.. _source-package:
-
-You can download a copy of Psycopg source files from the `Psycopg download
-page`__ or from PyPI_.
-
-.. __: http://initd.org/psycopg/download/
 
 
 
@@ -128,8 +44,8 @@ page`__ or from PyPI_.
 Build prerequisites
 ^^^^^^^^^^^^^^^^^^^
 
-These notes illustrate how to compile Psycopg on Linux. If you want to compile
+The build prerequisites are to be met in order to install Psycopg from source
-Psycopg on other platforms you may have to adjust some details accordingly.
+code, either from a source distribution package or from PyPI.
 
 Psycopg is a C wrapper around the libpq_ PostgreSQL client library. To install
 it from sources you will need:
@@ -161,6 +77,12 @@ it from sources you will need:
 
 Once everything is in place it's just a matter of running the standard:
 
+.. code-block:: console
+
+    $ pip install psycopg2
+
+or, from the directory containing the source code:
+
 .. code-block:: console
 
     $ python setup.py build
@@ -197,12 +119,92 @@ which is OS-dependent (for instance setting a suitable
 
 
 
+.. index::
+    single: Install; from PyPI
+    single: Install; wheel
+    single: Wheel
+
+Binary install from PyPI
+------------------------
+
+`!psycopg2` is also `available on PyPI`__ in the form of wheel_ packages for
+the most common platform (Linux, OSX, Windows): this should make you able to
+install a binary version of the module, not requiring the above build or
+runtime prerequisites, simply using:
+
+.. code-block:: console
+
+    $ pip install psycopg2-binary
+
+Make sure to use an up-to-date version of :program:`pip` (you can upgrade it
+using something like ``pip install -U pip``)
+
+.. __: PyPI-binary_
+.. _PyPI-binary: https://pypi.python.org/pypi/psycopg2-binary/
+.. _wheel: http://pythonwheels.com/
+
+.. note::
+
+    The binary packages come with their own versions of a few C libraries,
+    among which ``libpq`` and ``libssl``, which will be used regardless of other
+    libraries available on the client: upgrading the system libraries will not
+    upgrade the libraries used by `!psycopg2`. Please build `!psycopg2` from
+    source if you want to maintain binary upgradeability.
+
+.. warning::
+
+    The `!psycopg2` wheel package comes packaged, among the others, with its
+    own ``libssl`` binary. This may create conflicts with other extension
+    modules binding with ``libssl`` as well, for instance with the Python
+    `ssl` module: in some cases, under concurrency, the interaction between
+    the two libraries may result in a segfault. In case of doubts you are
+    advised to use a package built from source.
+
+
+
+.. index::
+    single: Install; disable wheel
+    single: Wheel; disable
+
+.. _disable-wheel:
+
+Disabling wheel packages for Psycopg 2.7
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In version 2.7.x, `pip install psycopg2` would have tried to install the wheel
+binary package of Psycopg. Because of the problems the wheel package have
+displayed, `psycopg2-binary` has become a separate package, and from 2.8 it
+has become the only way to install the binary package.
+
+If you are using psycopg 2.7 and you want to disable the use of wheel binary
+packages, relying on the system system libraries available on your client, you
+can use the :command:`pip` |--no-binary option|__:
+
+.. code-block:: console
+
+    $ pip install --no-binary psycopg2
+
+.. |--no-binary option| replace:: ``--no-binary`` option
+.. __: https://pip.pypa.io/en/stable/reference/pip_install/#install-no-binary
+
+which can be specified in your :file:`requirements.txt` files too, e.g. use:
+
+.. code-block:: none
+
+    psycopg2>=2.7,<2.8 --no-binary psycopg2
+
+to use the last bugfix release of the `!psycopg2` 2.7 package, specifying to
+always compile it from source. Of course in this case you will have to meet
+the :ref:`build prerequisites <build-prerequisites>`.
+
+
+
 .. index::
     single: setup.py
     single: setup.cfg
 
 Non-standard builds
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
 If you have less standard requirements such as:
 
@@ -242,7 +244,7 @@ order to create a debug package:
 - Edit the ``setup.cfg`` file adding the ``PSYCOPG_DEBUG`` flag to the
   ``define`` option.
 
-- :ref:`Compile and install <source-package>` the package.
+- :ref:`Compile and install <build-prerequisites>` the package.
 
 - Set the :envvar:`PSYCOPG_DEBUG` environment variable:
 

setup.py

@@ -39,6 +39,7 @@ except ImportError:
 from distutils.command.build_ext import build_ext
 from distutils.sysconfig import get_python_inc
 from distutils.ccompiler import get_default_compiler
+from distutils.errors import CompileError
 from distutils.util import get_platform
 
 try:
@@ -104,15 +105,23 @@ class PostgresConfig:
         if not self.pg_config_exe:
             self.pg_config_exe = self.autodetect_pg_config_path()
         if self.pg_config_exe is None:
-            sys.stderr.write("""\
+            sys.stderr.write("""
 Error: pg_config executable not found.
 
-Please add the directory containing pg_config to the PATH
+pg_config is required to build psycopg2 from source.  Please add the directory
-or specify the full executable path with the option:
+containing pg_config to the $PATH or specify the full executable path with the
+option:
 
     python setup.py build_ext --pg-config /path/to/pg_config build ...
 
 or with the pg_config option in 'setup.cfg'.
+
+If you prefer to avoid building psycopg2 from source, please install the PyPI
+'psycopg2-binary' package instead.
+
+For further information please check the 'doc/src/install.rst' file (also at
+<http://initd.org/psycopg/docs/install.html>).
+
 """)
             sys.exit(1)
 
@@ -286,8 +295,37 @@ class psycopg_build_ext(build_ext):
         else:
             return build_ext.get_export_symbols(self, extension)
 
+    built_files = 0
+
     def build_extension(self, extension):
-        build_ext.build_extension(self, extension)
+        # Count files compiled to print the binary blurb only if the first fails
+        compile_orig = getattr(self.compiler, '_compile', None)
+        if compile_orig is not None:
+            def _compile(*args, **kwargs):
+                rv = compile_orig(*args, **kwargs)
+                psycopg_build_ext.built_files += 1
+                return rv
+
+            self.compiler._compile = _compile
+
+        try:
+            build_ext.build_extension(self, extension)
+            psycopg_build_ext.built_files += 1
+        except CompileError:
+            if self.built_files == 0:
+                sys.stderr.write("""
+It appears you are missing some prerequisite to build the package from source.
+
+You may install a binary package by installing 'psycopg2-binary' from PyPI.
+If you want to install psycopg2 from source, please install the packages
+required for the build and try again.
+
+For further information please check the 'doc/src/install.rst' file (also at
+<http://initd.org/psycopg/docs/install.html>).
+
+""")
+            raise
+
         sysVer = sys.version_info[:2]
 
         # For Python versions that use MSVC compiler 2008, re-insert the

tests/test_connection.py

@@ -1549,9 +1549,13 @@ import os
 import sys
 import time
 import signal
+import warnings
 import threading
 
-import psycopg2
+# ignore wheel deprecation warning
+with warnings.catch_warnings():
+    warnings.simplefilter('ignore')
+    import psycopg2
 
 def handle_sigabort(sig, frame):
     sys.exit(1)