From ed3d44562d26dd4a3d9cba151d80beaefc1c35d0 Mon Sep 17 00:00:00 2001 From: Edan Schwartz Date: Fri, 7 Aug 2020 14:53:57 -0500 Subject: [PATCH] Move pyscopg-binary install docs to "quick start" section This is the fastest way for most folks to get up-and-running with psycopg. We've seen a lot of noise in the GH issues with people failng to install the non-binary version. Hopefully this will make life easier for people new to psycopg/python. See https://github.com/psycopg/psycopg2/issues/1085#issuecomment-659028139 --- doc/src/install.rst | 239 ++++++++++++++++++++++++-------------------- 1 file changed, 130 insertions(+), 109 deletions(-) diff --git a/doc/src/install.rst b/doc/src/install.rst index 8cebee0f..4100aaa1 100644 --- a/doc/src/install.rst +++ b/doc/src/install.rst @@ -8,27 +8,116 @@ Installation Psycopg is a PostgreSQL_ adapter for the Python_ programming language. It is a wrapper for the libpq_, the official PostgreSQL client library. -The `psycopg2` package is the current mature implementation of the adapter: it -is a C extension and as such it is only compatible with CPython_. If you want -to use Psycopg on a different Python implementation (PyPy, Jython, IronPython) -there is a couple of alternative: - -- a `Ctypes port`__, but it is not as mature as the C implementation yet - and it is not as feature-complete; - -- a `CFFI port`__ which is currently more used and reported more efficient on - PyPy, but please be careful of its version numbers because they are not - aligned to the official psycopg2 ones and some features may differ. - .. _PostgreSQL: https://www.postgresql.org/ .. _Python: https://www.python.org/ -.. _libpq: https://www.postgresql.org/docs/current/static/libpq.html -.. _CPython: https://en.wikipedia.org/wiki/CPython -.. _Ctypes: https://docs.python.org/library/ctypes.html -.. __: https://github.com/mvantellingen/psycopg2-ctypes -.. __: https://github.com/chtd/psycopg2cffi +.. index:: + single: Install; from PyPI + single: Install; wheel + single: Wheel + +.. _binary-packages: + +Quick Install +------------- + +For most operating systems, the quickest way to install psycopg is using the wheel_ package available on PyPI_: + +.. code-block:: console + + $ pip install psycopg2-binary + +This will install a pre-compiled binary version of the module which does not require the build or runtime prerequisites described below. Make sure to sue an up-date-date version of :program:`pip` (you can upgrade it +using something like ``pip install -U pip``). + +You may then import the ``psycopg`` package, as usual: + +.. code-block:: python + + import psycopg + + # Connect to your postgres DB + conn = psycopg.connect("dbname=test user=postgres") + + # Open a cursor to perform database operations + cur = conn.cursor() + + # Execute a query + cur.execute("SELECT * FROM my_data"); + + # Retrieve query results + records = cur.fetchall() + +.. __: PyPI-binary_ +.. _PyPI: https://pypi.org/project/psycopg2-binary/ +.. _wheel: https://pythonwheels.com/ + +psycopg vs psycopg-binary +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``psycopg2-binary`` package is meant for beginners to start playing +with Python and PostgreSQL without the need to meet the build +requirements. + +If you are the maintainer of a published package depending on `!psycopg2` +you shouldn't use 'psycopg2-binary' as a module dependency. **For +production use you are advised to use the source distribution.** + + +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: + +Change in binary packages between Psycopg 2.7 and 2.8 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In version 2.7.x, :command:`pip install psycopg2` would have tried to install +automatically the binary package of Psycopg. Because of concurrency problems +binary packages 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 libraries available on your client, you +can use the :command:`pip` |--no-binary option|__, e.g.: + +.. code-block:: console + + $ pip install --no-binary :all: 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 `. + .. index:: single: Prerequisites @@ -131,97 +220,6 @@ which is OS-dependent (for instance setting a suitable -.. index:: - single: Install; from PyPI - single: Install; wheel - single: Wheel - -.. _binary-packages: - -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. - -.. note:: - - The ``psycopg2-binary`` package is meant for beginners to start playing - with Python and PostgreSQL without the need to meet the build - requirements. - - If you are the maintainer of a published package depending on `!psycopg2` - **you shouldn't use 'psycopg2-binary' as a module dependency**. For - production use you are advised to use the source distribution. - - -Make sure to use an up-to-date version of :program:`pip` (you can upgrade it -using something like ``pip install -U pip``), then you can run: - -.. code-block:: console - - $ pip install psycopg2-binary - -.. __: PyPI-binary_ -.. _PyPI-binary: https://pypi.org/project/psycopg2-binary/ -.. _wheel: https://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: - -Change in binary packages between Psycopg 2.7 and 2.8 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In version 2.7.x, :command:`pip install psycopg2` would have tried to install -automatically the binary package of Psycopg. Because of concurrency problems -binary packages 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 libraries available on your client, you -can use the :command:`pip` |--no-binary option|__, e.g.: - -.. code-block:: console - - $ pip install --no-binary :all: 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 `. @@ -286,6 +284,29 @@ order to create a debug package: .. __: https://pypi.org/project/psycopg2/#files +Non-standard Python Implementation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `psycopg2` package is the current mature implementation of the adapter: it +is a C extension and as such it is only compatible with CPython_. If you want +to use Psycopg on a different Python implementation (PyPy, Jython, IronPython) +there is a couple of alternative: + +- a `Ctypes port`__, but it is not as mature as the C implementation yet + and it is not as feature-complete; + +- a `CFFI port`__ which is currently more used and reported more efficient on + PyPy, but please be careful of its version numbers because they are not + aligned to the official psycopg2 ones and some features may differ. + +.. _PostgreSQL: https://www.postgresql.org/ +.. _Python: https://www.python.org/ +.. _libpq: https://www.postgresql.org/docs/current/static/libpq.html +.. _CPython: https://en.wikipedia.org/wiki/CPython +.. _Ctypes: https://docs.python.org/library/ctypes.html +.. __: https://github.com/mvantellingen/psycopg2-ctypes +.. __: https://github.com/chtd/psycopg2cffi + .. index:: single: tests @@ -339,4 +360,4 @@ Try the following. *In order:* :envvar:`ARCHFLAGS`. Especially useful from the Starbucks near you. .. _mailing list: https://www.postgresql.org/list/psycopg/ -.. _bug tracker: https://github.com/psycopg/psycopg2/issues +.. _bug tracker: https://github.com/psycopg/psycopg2/issues \ No newline at end of file