From: Daniele Varrazzo Date: Wed, 30 Jun 2021 16:05:22 +0000 (+0100) Subject: Cleanup of install docs X-Git-Tag: 3.0.dev1~30 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b363aa881f678cd79a5755bf1578886df1a40fb7;p=thirdparty%2Fpsycopg.git Cleanup of install docs --- diff --git a/docs/api/pq.rst b/docs/api/pq.rst index 2d93f9894..85a1591c0 100644 --- a/docs/api/pq.rst +++ b/docs/api/pq.rst @@ -50,7 +50,12 @@ module constant. At import, Psycopg 3 will try to use the best implementation available and will fail if none is usable. You can force the use of a specific implementation by exporting the env var :envvar:`PSYCOPG_IMPL`: importing the -library will fail if the requested implementation is not available. +library will fail if the requested implementation is not available:: + + $ PSYCOPG_IMPL=c python -c "import psycopg" + Traceback (most recent call last): + ... + ImportError: couldn't import requested psycopg 'c' implementation: No module named 'psycopg_c' Module content diff --git a/docs/basic/install.rst b/docs/basic/install.rst index ea8c23108..6e13c4164 100644 --- a/docs/basic/install.rst +++ b/docs/basic/install.rst @@ -6,8 +6,8 @@ Installation Installing the development state -------------------------------- -Psycopg 3 packages have not been released yet, but you can try it out -already by installing it `from the GitHub project`__: +Psycopg 3 packages have not been released on the PyPI index yet: you can try +it out by installing it `from the GitHub project`__: .. code:: bash @@ -17,11 +17,11 @@ already by installing it `from the GitHub project`__: .. __: https://github.com/psycopg/psycopg +or from `the TestPyPI index`__:: -.. _binary-install: + pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ psycopg -Binary installation -------------------- +.. __: https://test.pypi.org/project/psycopg/ .. warning:: @@ -33,20 +33,35 @@ Binary installation .. __: https://github.com/psycopg/psycopg#readme - The following is how it will be *supposed* to work, once it is released... +.. _binary-install: + +Binary installation +------------------- The quickest way to start developing with Psycopg 3 is to install the binary packages by running:: pip install psycopg[binary] +.. warning:: + + Add the following options to pip:: + + -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ + + to install the Psycopg from TestPyPI, before the final packages are + uploaded on PyPI. + This will install a self-contained package with all the libraries needed. +You will need pip >= 20.3 at least: please run ``pip install -U pip`` to update +it beforehand. The above package should work in most situations. It **will not work** in -some though: +some cases though: -- the ``binary`` package doesn't work on Alpine Linux; +- you need a glibc-based Linux distribution: the ``binary`` package doesn't + work on Alpine Linux for instance; - you have a newly released Python or Mac Os X version for which binary packages are not ready yet. @@ -62,6 +77,9 @@ In these case you should proceed to a :ref:`local installation You can come back here if you the above method didn't work and you need a way to install Psycopg 3 past the basic one. + For further information about the differences between the packages see + :ref:`pq-impl`. + .. _local-installation: @@ -71,7 +89,8 @@ Local installation A "Local installation" means obtaining a performing and maintainable library. The library will include a performing C module and will be bound to the system libraries (``libpq``, ``libssl``...) so that system upgrade of libraries will -upgrade the libraries used by Psycopg 3 too. +upgrade the libraries used by Psycopg 3 too. This is the preferred way to +install Psycopg for a production site. In order to perform a local installation you need some prerequisites: @@ -88,6 +107,15 @@ If your build prerequisites are in place you can run:: pip install psycopg[c] +.. warning:: + + Add the following options to pip:: + + -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ + + to install the Psycopg from TestPyPI, before the final packages are + uploaded on PyPI. + .. _pure-python-installation: @@ -100,19 +128,45 @@ If you simply install:: without ``[c]`` or ``[binary]`` extras you will obtain a pure Python implementation. This is particularly handy to debug and hack, but it still -requires the system libpq to operate (which will be used dynamically via +requires the system libpq to operate (which will be imported dynamically via `ctypes`). In order to use the pure Python installation you will need the ``libpq`` installed in the system: for instance on Debian system you will probably need:: - sudo apt-get install libpq5 + sudo apt install libpq5 If you are not able to fulfill this requirement please follow the `binary installation`_. +Handling dependencies +--------------------- + +If you need to specify your project dependencies (for instance in a +``requirements.txt`` file, ``setup.py``, ``pyproject.toml`` dependencies...) +you should probably specify one of the following: + +- If your project is a library, add a dependency on ``psycopg``. This will + make sure that your library will have the ``psycopg`` package with the right + interface and leaves the possibility of choosing a specific implementation + to the end user of your library. + +- If your project if a final application (e.g. a service running on a server) + you can require a specific implementation, for instance ``psycopg[c]``, + after you have made sure that the prerequisites are met (e.g. the depending + libraries and tools are installed in the host machine). + +In both cases you can specify which version of Psycopg to use using +`requirement specifiers`__. + +.. __: https://pip.pypa.io/en/stable/cli/pip_install/#requirement-specifiers + +If you want to make sure that a specific implementation is used you can +specify the :envvar:`PSYCOPG_IMPL` environment variable: importing the library +will fail if the implementation specified is not available. See :ref:`pq-impl`. + Psycopg 3 and the ``libpq`` ---------------------------