From 82dc32cebd4935f37c95377c336055c9432d1548 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Sun, 7 Oct 2012 02:04:39 +0100 Subject: [PATCH] Added install section to the manual --- doc/src/faq.rst | 8 ++ doc/src/index.rst | 1 + doc/src/install.rst | 258 ++++++++++++++++++++++++++++++++++++++++++++ doc/src/usage.rst | 2 + 4 files changed, 269 insertions(+) create mode 100644 doc/src/install.rst diff --git a/doc/src/faq.rst b/doc/src/faq.rst index 01527ca0..12aa99c5 100644 --- a/doc/src/faq.rst +++ b/doc/src/faq.rst @@ -7,6 +7,8 @@ Here are a few gotchas you may encounter using `psycopg2`. Feel free to suggest new entries! +.. _faq-transactions: + Problems with transactions handling ----------------------------------- @@ -51,6 +53,8 @@ Why do I get the error *current transaction is aborted, commands ignored until e informations. +.. _faq-types: + Problems with type conversions ------------------------------ @@ -151,6 +155,8 @@ Arrays of *TYPE* are not casted to list. provided in the `~psycopg2.extensions.new_array_type()` documentation. +.. _faq-best-practices: + Best practices -------------- @@ -191,6 +197,8 @@ What are the advantages or disadvantages of using named cursors? little memory on the client and to skip or discard parts of the result set. +.. _faq-compile: + Problems compiling and deploying psycopg2 ----------------------------------------- diff --git a/doc/src/index.rst b/doc/src/index.rst index e15e7bb7..f06582d9 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -42,6 +42,7 @@ Psycopg 2 is both Unicode and Python 3 friendly. .. toctree:: :maxdepth: 2 + install usage module connection diff --git a/doc/src/install.rst b/doc/src/install.rst new file mode 100644 index 00000000..4223d1b8 --- /dev/null +++ b/doc/src/install.rst @@ -0,0 +1,258 @@ +Introduction +============ + +.. sectionauthor:: Daniele Varrazzo + +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 an experimental `porting of Psycopg for Ctypes`__, but it is not as +mature as the C implementation yet. + +The current `!psycopg2` implementation supports: + +- Python 2 versions from 2.4 to 2.7 +- Python 3 versions from 3.1 to 3.2 +- PostgreSQL versions from 7.4 to 9.2 + +.. _PostgreSQL: http://www.postgresql.org/ +.. _Python: http://www.python.org/ +.. _libpq: http://www.postgresql.org/docs/current/static/libpq.html +.. _CPython: http://en.wikipedia.org/wiki/CPython +.. _Ctypes: http://docs.python.org/library/ctypes.html +.. __: 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. + + + +.. _install-from-package: + +Install from a package +---------------------- + +.. index:: + pair: Install; Linux + +**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. + + On Debian, Ubuntu and other deb-based distributions you should just need:: + + sudo apt-get install python-psycopg2 + + to install the package with all its dependencies. + + +.. 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** + Jason Erickson maintains a packaged `Windows port of Psycopg`__ with + installation executable. Download. Double click. Done. + + .. __: http://www.stickpeople.com/projects/python/win-psycopg/ + + + +.. index:: + single: Install; from source + +.. _install-from-source: + +Install from source +------------------- + +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: + +- A C compiler. + +- The Python header files. They are usually installed in a package such as + **python-dev**. A message such as *error: Python.h: No such file or + directory* is an indication that the Python headers are missing. + +- The libpq header files. They are usually installed in a package such as + **libpq-dev**. If you get an *error: libpq-fe.h: No such file or directory* + you are missing them. + +- The :program:`pg_config` program: it is usually installed by the + **libpq-dev** package but sometimes it is not in a :envvar:`PATH` directory. + Having it in the :envvar:`PATH` greatly streamlines the installation, so try + running ``pg_config --version``: if it returns an error or an unexpected + version number then locate the directory containing the :program:`pg_config` + shipped with the right libpq version (usually + ``/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. + +.. note:: + + The libpq header files used to compile `!psycopg2` should match the + version of the library linked at runtime. If you get errors about missing + or mismatching libraries when importing `!psycopg2` check (e.g. using + :program:`ldd`) if the module ``psycopg2/_psycopg.so`` is linked to the + right ``libpq.so``. + + + +.. 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 + +If you have less standard requirements such as: + +- creating a :ref:`debug build `, +- using :program:`pg_config` not in the :envvar:`PATH`, +- supporting ``mx.DateTime``, + +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:: + + $ 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: debug + single: PSYCOPG_DEBUG + +.. _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 +order to create a debug package: + +- `Download`__ and unpack the Psycopg source package. + +- Edit the ``setup.cfg`` file adding the ``PSYCOPG_DEBUG`` flag to the + ``define`` option. + +- :ref:`Compile and install ` the package. + +- Set the :envvar:`PSYCOPG_DEBUG` variable:: + + $ export PSYCOPG_DEBUG=1 + +- Run your program (making sure that the `!psycopg2` package imported is the + one you just compiled and not e.g. the system one): you will have a copious + stream of informations printed on stdout. + +.. __: http://initd.org/psycopg/download/ + + + +.. _other-problems: + +If you still have problems +-------------------------- + +Try the following. *In order:* + +- Read again the :ref:`requirements `. + +- Read the :ref:`FAQ `. + +- Google for `!psycopg2` *your error message*. Especially useful the week + after the release of a new OS X version. + +- Write to the `Mailing List`__. + +- Complain on your blog or on Twitter that `!psycopg2` is the worst package + ever and about the quality time you have wasted figuring out the correct + :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 + diff --git a/doc/src/usage.rst b/doc/src/usage.rst index 136f677b..06e51794 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -1,3 +1,5 @@ +.. _usage: + Basic module usage ==================