From ed3d44562d26dd4a3d9cba151d80beaefc1c35d0 Mon Sep 17 00:00:00 2001 From: Edan Schwartz Date: Fri, 7 Aug 2020 14:53:57 -0500 Subject: 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 | 237 ++++++++++++++++++++++++++++------------------------ 1 file changed, 129 insertions(+), 108 deletions(-) diff --git a/doc/src/install.rst b/doc/src/install.rst index 8cebee0..4100aaa 100644 --- a/doc/src/install.rst +++ b/doc/src/install.rst @@ -8,26 +8,115 @@ 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: +.. _PostgreSQL: https://www.postgresql.org/ +.. _Python: https://www.python.org/ -- 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. +.. index:: + single: Install; from PyPI + single: Install; wheel + single: Wheel -.. _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 +.. _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:: @@ -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 -- cgit v1.2.1 From 9c30fdbc63a4c791949e977d41e6ca4e23404e3e Mon Sep 17 00:00:00 2001 From: Edan Schwartz Date: Mon, 10 Aug 2020 09:18:45 -0500 Subject: minor typo in docs --- doc/src/install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/install.rst b/doc/src/install.rst index 4100aaa..53798d7 100644 --- a/doc/src/install.rst +++ b/doc/src/install.rst @@ -28,7 +28,7 @@ For most operating systems, the quickest way to install psycopg is using the whe $ 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 +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 use 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: -- cgit v1.2.1 From 82d679cdb33e83ea52522618616d502d06707347 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Mon, 24 Aug 2020 01:44:45 +0100 Subject: A few corrections to the install page Spacing, lines length, a spurious link targed, reST formatting. --- doc/src/install.rst | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/doc/src/install.rst b/doc/src/install.rst index 53798d7..ee845f7 100644 --- a/doc/src/install.rst +++ b/doc/src/install.rst @@ -22,14 +22,17 @@ wrapper for the libpq_, the official PostgreSQL client library. Quick Install ------------- -For most operating systems, the quickest way to install psycopg is using the wheel_ package available on PyPI_: +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 use an up-date-date version of :program:`pip` (you can upgrade it -using something like ``pip install -U pip``). +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 use +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: @@ -49,10 +52,10 @@ You may then import the ``psycopg`` package, as usual: # Retrieve query results records = cur.fetchall() -.. __: PyPI-binary_ .. _PyPI: https://pypi.org/project/psycopg2-binary/ .. _wheel: https://pythonwheels.com/ + psycopg vs psycopg-binary ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -61,10 +64,9 @@ 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 +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 @@ -81,7 +83,6 @@ source if you want to maintain binary upgradeability. advised to use a package built from source. - .. index:: single: Install; disable wheel single: Wheel; disable @@ -219,10 +220,6 @@ which is OS-dependent (for instance setting a suitable to connect to. - - - - .. index:: single: setup.py single: setup.cfg @@ -335,7 +332,6 @@ setting the environment variables: The database should already exist before running the tests. - .. _other-problems: If you still have problems @@ -360,4 +356,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 \ No newline at end of file +.. _bug tracker: https://github.com/psycopg/psycopg2/issues -- cgit v1.2.1