diff --git a/README.rst b/README.rst index f18be564..03c84c41 100644 --- a/README.rst +++ b/README.rst @@ -29,8 +29,14 @@ Documentation is included in the 'doc' directory and is `available online`__. Installation ------------ -If all the dependencies are met (i.e. you have the Python and libpq -development packages installed in your system) the standard:: +If your ``pip`` version supports wheel_ packages it should be possible to +install a binary version of Psycopg including all the dependencies. Just run:: + + pip install psycopg2 + +If you want to build Psycopg from source you will need some prerequisite (a C +compiler, Python and libpq development packages). If you have what you need +the standard:: python setup.py build sudo python setup.py install @@ -38,7 +44,8 @@ development packages installed in your system) the standard:: should work no problem. In case you have any problem check the 'install' and the 'faq' documents in the docs or online__. -.. __: http://initd.org/psycopg/docs/install.html +.. _wheel: http://pythonwheels.com/ +.. __: http://initd.org/psycopg/docs/install.html#install-from-source For any other resource (source code repository, bug tracker, mailing list) please check the `project homepage`__. diff --git a/doc/src/install.rst b/doc/src/install.rst index 0ff46934..a45b74ca 100644 --- a/doc/src/install.rst +++ b/doc/src/install.rst @@ -30,96 +30,26 @@ The current `!psycopg2` implementation supports: .. __: https://github.com/mvantellingen/psycopg2-ctypes -.. note:: - - `!psycopg2` usually depends at runtime on the libpq dynamic library. - However it can connect to PostgreSQL servers of any supported version, - independently of the version of the libpq used: just install the most - recent libpq version or the most practical, without trying to match it to - the version of the PostgreSQL server you will have to connect to. - - -Installation -============ - -If possible, and usually it is, please :ref:`install Psycopg from a package -` available for your distribution or operating system. - -Compiling from source is a very easy task, however `!psycopg2` is a C -extension module and as such it requires a few more things in place respect to -a pure Python module. So, if you don't have experience compiling Python -extension packages, *above all if you are a Windows or a Mac OS user*, please -use a pre-compiled package and go straight to the :ref:`module usage ` -avoid bothering with the gory details. - -.. note:: - - Regardless of the way `!psycopg2` is installed, at runtime it will need to - use the libpq_ library. `!psycopg2` relies on the host OS to find the - library file (usually ``libpq.so`` or ``libpq.dll``): if the library is - installed in a standard location there is usually no problem; if the - library is in a non-standard location you will have to tell somehow - psycopg how to find it, which is OS-dependent (for instance setting a - suitable :envvar:`LD_LIBRARY_PATH` on Linux). - - - -.. _install-from-package: - -Install from a package ----------------------- .. index:: - pair: Install; Linux + single: Install; from PyPI -**Linux** - Psycopg is available already packaged in many Linux distributions: look - for a package such as ``python-psycopg2`` using the package manager of - your choice. +Binary install from PyPI +------------------------ - On Debian, Ubuntu and other deb-based distributions you should just need:: +`!psycopg2` is `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 including all the dependencies simply +using:: - sudo apt-get install python-psycopg2 + pip install psycopg2 - to install the package with all its dependencies. +Make sure to use an up-to-date version of :program:`pip` (you can upgrade it +using something like ``pip install -U pip``) - -.. index:: - pair: Install; Mac OS X - -**Mac OS X** - Psycopg is available as a `fink package`__ in the *unstable* tree: you may - install it with:: - - fink install psycopg2-py27 - - .. __: http://pdb.finkproject.org/pdb/package.php/psycopg2-py27 - - The library is also available on `MacPorts`__ try:: - - sudo port install py27-psycopg2 - - .. __: http://www.macports.org/ - - -.. index:: - pair: Install; Windows - -**Microsoft Windows** - There are two options to install a precompiled `psycopg2` package under windows: - - **Option 1:** Using `pip`__ (Included in python 2.7.9+ and python 3.4+) - and a binary wheel package. Launch windows' command prompt (`cmd.exe`) - and execute the following command:: - - pip install psycopg2 - - .. __: https://pip.pypa.io/en/stable/installing/ - - **Option 2:** Jason Erickson maintains a packaged `Windows port of Psycopg`__ with - installation executable. Download. Double click. Done. - - .. __: http://www.stickpeople.com/projects/python/win-psycopg/ +.. __: PyPI_ +.. _PyPI: https://pypi.python.org/pypi/psycopg2/ +.. _wheel: http://pythonwheels.com/ @@ -131,11 +61,23 @@ Install from a package 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/ + + + +.. _build-prerequisites: + +Build prerequisites +^^^^^^^^^^^^^^^^^^^ + These notes illustrate how to compile Psycopg on Linux. If you want to compile Psycopg on other platforms you may have to adjust some details accordingly. -.. _requirements: - Psycopg is a C wrapper to the libpq PostgreSQL client library. To install it from sources you will need: @@ -158,9 +100,22 @@ from sources you will need: ``/usr/lib/postgresql/X.Y/bin/``) and add it to the :envvar:`PATH`:: $ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH - - You only need it to compile and install `!psycopg2`, not for its regular - usage. + + You only need :program:`pg_config` to compile `!psycopg2`, not for its + regular usage. + + +Runtime requirements +^^^^^^^^^^^^^^^^^^^^ + +Unless you compile `!psycopg2` as a static library, or you install it from a +self-contained wheel package, it will need the libpq_ library at runtime +(usually distributed in a ``libpq.so`` or ``libpq.dll`` file). `!psycopg2` +relies on the host OS to find the library if the library is installed in a +standard location there is usually no problem; if the library is in a +non-standard location you will have to tell somehow Psycopg how to find it, +which is OS-dependent (for instance setting a suitable +:envvar:`LD_LIBRARY_PATH` on Linux). .. note:: @@ -170,40 +125,22 @@ from sources you will need: :program:`ldd`) if the module ``psycopg2/_psycopg.so`` is linked to the right ``libpq.so``. +.. note:: + Whatever version of libpq `!psycopg2` is compiled with, it will be + possible to connect to PostgreSQL servers of any supported version: just + install the most recent libpq version or the most practical, without + trying to match it to the version of the PostgreSQL server you will have + to connect to. -.. index:: - single: Install; from PyPI - -.. _package-manager: - -Use a Python package manager -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If the above requirements are satisfied, you can use :program:`easy_install`, -:program:`pip` or whatever the Python package manager of the week:: - - $ pip install psycopg2 - -Please refer to your package manager documentation about performing a local or -global installation, :program:`virtualenv` (fully supported by recent Psycopg -versions), using different Python versions and other nuances. .. index:: single: setup.py single: setup.cfg -.. _source-package: - -Use the source package -^^^^^^^^^^^^^^^^^^^^^^ - -You can download a copy of Psycopg source files from the `Psycopg download -page`__. Once unpackaged, to compile and install the package you can run:: - - $ python setup.py build - $ sudo python setup.py install +Non-standard builds +^^^^^^^^^^^^^^^^^^^ If you have less standard requirements such as: @@ -215,43 +152,13 @@ then take a look at the ``setup.cfg`` file. Some of the options available in ``setup.cfg`` are also available as command line arguments of the ``build_ext`` sub-command. For instance you can specify -an alternate :program:`pg_config` version using:: +an alternate :program:`pg_config` location using:: $ python setup.py build_ext --pg-config /path/to/pg_config build Use ``python setup.py build_ext --help`` to get a list of the options supported. -.. __: http://initd.org/psycopg/download/ - - - -.. index:: - single: tests - -.. _test-suite: - -Running the test suite -^^^^^^^^^^^^^^^^^^^^^^ - -The included ``Makefile`` allows to run all the tests included in the -distribution. Just run:: - - make - make check - -The tests run against a database called ``psycopg2_test`` on UNIX socket and -the standard port. You can configure a different database to run the test by -setting the environment variables: - -- :envvar:`PSYCOPG2_TESTDB` -- :envvar:`PSYCOPG2_TESTDB_HOST` -- :envvar:`PSYCOPG2_TESTDB_PORT` -- :envvar:`PSYCOPG2_TESTDB_USER` - -The database should already exist before running the tests. - - .. index:: single: debug @@ -260,7 +167,7 @@ The database should already exist before running the tests. .. _debug-build: Creating a debug build ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ In case of problems, Psycopg can be configured to emit detailed debug messages, which can be very useful for diagnostics and to report a bug. In @@ -285,6 +192,32 @@ order to create a debug package: +.. index:: + single: tests + +.. _test-suite: + +Running the test suite +---------------------- + +Once `!psycopg2` is installed you can run the test suite to verify it is +working correctly. You can run:: + + python -c "from psycopg2 import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose + +The tests run against a database called ``psycopg2_test`` on UNIX socket and +the standard port. You can configure a different database to run the test by +setting the environment variables: + +- :envvar:`PSYCOPG2_TESTDB` +- :envvar:`PSYCOPG2_TESTDB_HOST` +- :envvar:`PSYCOPG2_TESTDB_PORT` +- :envvar:`PSYCOPG2_TESTDB_USER` + +The database should already exist before running the tests. + + + .. _other-problems: If you still have problems @@ -292,7 +225,7 @@ If you still have problems Try the following. *In order:* -- Read again the :ref:`requirements `. +- Read again the :ref:`build-prerequisites`. - Read the :ref:`FAQ `. @@ -306,4 +239,3 @@ Try the following. *In order:* :envvar:`ARCHFLAGS`. Especially useful from the Starbucks near you. .. __: http://mail.postgresql.org/mj/mj_wwwusr/domain=postgresql.org?func=lists-long-full&extra=psycopg -