.github/FUNDING.yml

@@ -1,4 +0,0 @@
-github:
-  - dvarrazzo
-custom:
-  - "https://www.paypal.me/dvarrazzo"

.github/ISSUE_TEMPLATE/problem-installing-psycopg2.md

@@ -1,23 +0,0 @@
----
-name: Problem installing psycopg2
-about: Report a case in which psycopg2 failed to install on your platform
-title: ''
-labels: ''
-assignees: ''
-
----
-
-**This is a bug tracker**
-If you have a question, such has "how do you do X with Python/PostgreSQL/psycopg2" please [write to the mailing list](https://lists.postgresql.org/manage/) or [open a question](https://github.com/psycopg/psycopg2/discussions) instead.
-
-**Before opening this ticket, please confirm that:**
-- [ ] I am running the latest version of pip, i.e. typing ``pip --version`` you get [this version](https://pypi.org/project/pip/).
-- [ ] I have read the [installation documentation](https://www.psycopg.org/docs/install.html) and the [frequently asked questions](https://www.psycopg.org/docs/faq.html)
-- [ ] If install failed, I typed `pg_config` on the command line and I obtained an output instead of an error.
-
-**Please complete the following information:**
-- OS:
-- Psycopg version:
-- Python version:
-- PostgreSQL version:
-- pip version

.github/ISSUE_TEMPLATE/problem-using-psycopg2.md

@@ -1,27 +0,0 @@
----
-name: Problem using psycopg2
-about: Report a case in which psycopg2 is not working as expected
-title: ''
-labels: ''
-assignees: ''
-
----
-
-**This is a bug tracker**
-If you have a question, such has "how do you do X with Python/PostgreSQL/psycopg2" please [write to the mailing list](https://lists.postgresql.org/manage/) or [open a question](https://github.com/psycopg/psycopg2/discussions) instead.
-
-**Please complete the following information:**
-- OS:
-- Psycopg version:
-- Python version:
-- PostgreSQL version:
-- pip version
-
-**Describe the bug**
-Please let us know:
-
-1: what you did
-2: what you expected to happen
-3: what happened instead
-
-If possible, provide a script reproducing the issue.

.github/dependabot.yml

@@ -1,6 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "monthly"

.github/workflows/docs.yml

@@ -1,18 +0,0 @@
-name: Build documentation
-
-on:
-  push:
-    branches:
-      # This should match the DOC_BRANCH value in the psycopg-website Makefile
-      - master
-
-jobs:
-  docs:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger docs build
-        uses: peter-evans/repository-dispatch@v3
-        with:
-          repository: psycopg/psycopg-website
-          event-type: psycopg2-commit
-          token: ${{ secrets.ACCESS_TOKEN }}

.github/workflows/packages.yml

@@ -1,266 +0,0 @@
----
-name: Build packages
-on:
-  - workflow_dispatch
-
-env:
-  PIP_BREAK_SYSTEM_PACKAGES: "1"
-  LIBPQ_VERSION: "16.0"
-  OPENSSL_VERSION: "1.1.1w"
-
-jobs:
-  sdist:  # {{{
-    if: true
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - package_name: psycopg2
-          - package_name: psycopg2-binary
-
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repos
-        uses: actions/checkout@v4
-
-      - name: Build sdist
-        run: ./scripts/build/build_sdist.sh
-        env:
-          PACKAGE_NAME: ${{ matrix.package_name }}
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: sdist-${{ matrix.package_name }}
-          path: |
-            dist/*.tar.gz
-
-    env:
-      PSYCOPG2_TESTDB: postgres
-      PSYCOPG2_TESTDB_HOST: 172.17.0.1
-      PSYCOPG2_TESTDB_USER: postgres
-      PSYCOPG2_TESTDB_PASSWORD: password
-      PSYCOPG2_TEST_FAST: 1
-
-    services:
-      postgresql:
-        image: postgres:16
-        env:
-          POSTGRES_PASSWORD: password
-        ports:
-          - 5432:5432
-        # Set health checks to wait until postgres has started
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-  # }}}
-
-  linux:  # {{{
-    if: true
-
-    strategy:
-      fail-fast: false
-      matrix:
-        platform: [manylinux, musllinux]
-        arch: [x86_64, i686, aarch64, ppc64le]
-        pyver: [cp38, cp39, cp310, cp311, cp312, cp313]
-
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repos
-        uses: actions/checkout@v4
-
-      - name: Set up QEMU for multi-arch build
-        uses: docker/setup-qemu-action@v3
-
-      - name: Cache libpq build
-        uses: actions/cache@v4
-        with:
-          path: /tmp/libpq.build
-          key: libpq-${{ env.LIBPQ_VERSION }}-${{ matrix.platform }}-${{ matrix.arch }}
-
-      - name: Build wheels
-        uses: pypa/cibuildwheel@v2.23.3
-        env:
-          CIBW_MANYLINUX_X86_64_IMAGE: manylinux2014
-          CIBW_MANYLINUX_I686_IMAGE: manylinux2014
-          CIBW_MANYLINUX_AARCH64_IMAGE: manylinux2014
-          CIBW_MANYLINUX_PPC64LE_IMAGE: manylinux2014
-          CIBW_BUILD: ${{matrix.pyver}}-${{matrix.platform}}_${{matrix.arch}}
-          CIBW_ARCHS_LINUX: auto aarch64 ppc64le
-          CIBW_BEFORE_ALL_LINUX: ./scripts/build/wheel_linux_before_all.sh
-          CIBW_REPAIR_WHEEL_COMMAND: >-
-            ./scripts/build/strip_wheel.sh {wheel}
-            && auditwheel repair -w {dest_dir} {wheel}
-          CIBW_TEST_COMMAND: >-
-            export PYTHONPATH={project} &&
-            python -c "import tests; tests.unittest.main(defaultTest='tests.test_suite')"
-          CIBW_ENVIRONMENT_PASS_LINUX: LIBPQ_VERSION OPENSSL_VERSION
-          CIBW_ENVIRONMENT: >-
-            PACKAGE_NAME=psycopg2-binary
-            LIBPQ_BUILD_PREFIX=/host/tmp/libpq.build
-            PATH="$LIBPQ_BUILD_PREFIX/bin:$PATH"
-            LD_LIBRARY_PATH="$LIBPQ_BUILD_PREFIX/lib:$LIBPQ_BUILD_PREFIX/lib64"
-            PSYCOPG2_TESTDB=postgres
-            PSYCOPG2_TESTDB_HOST=172.17.0.1
-            PSYCOPG2_TESTDB_USER=postgres
-            PSYCOPG2_TESTDB_PASSWORD=password
-            PSYCOPG2_TEST_FAST=1
-
-      - uses: actions/upload-artifact@v4
-        with:
-          name: linux-${{matrix.pyver}}-${{matrix.platform}}_${{matrix.arch}}
-          path: ./wheelhouse/*.whl
-
-    services:
-      postgresql:
-        image: postgres:16
-        env:
-          POSTGRES_PASSWORD: password
-        ports:
-          - 5432:5432
-        # Set health checks to wait until postgres has started
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-  # }}}
-
-  macos:  # {{{
-    runs-on: macos-latest
-    if: true
-
-    strategy:
-      fail-fast: false
-      matrix:
-        # These archs require an Apple M1 runner: [arm64, universal2]
-        arch: [x86_64, arm64]
-        pyver: [cp39, cp310, cp311, cp312, cp313]
-
-    steps:
-      - name: Checkout repos
-        uses: actions/checkout@v4
-
-      - name: Cache libpq build
-        uses: actions/cache@v4
-        with:
-          path: /tmp/libpq.build
-          key: libpq-${{ env.LIBPQ_VERSION }}-macos-${{ matrix.arch }}
-
-      - name: Build wheels
-        uses: pypa/cibuildwheel@v2.23.3
-        env:
-          CIBW_BUILD: ${{matrix.pyver}}-macosx_${{matrix.arch}}
-          CIBW_ARCHS_MACOS: ${{matrix.arch}}
-          MACOSX_ARCHITECTURE: ${{matrix.arch}}
-          CIBW_BEFORE_ALL_MACOS: ./scripts/build/wheel_macos_before_all.sh
-          CIBW_TEST_COMMAND: >-
-            export PYTHONPATH={project} &&
-            python -c "import tests; tests.unittest.main(defaultTest='tests.test_suite')"
-          CIBW_ENVIRONMENT: >-
-            PG_VERSION=16
-            PACKAGE_NAME=psycopg2-binary
-            PSYCOPG2_TESTDB=postgres
-            PATH="/tmp/libpq.build/bin:$PATH"
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos-${{matrix.pyver}}-macos-${{matrix.arch}}
-          path: ./wheelhouse/*.whl
-
-  # }}}
-
-  windows:  # {{{
-    runs-on: windows-latest
-    if: true
-
-    strategy:
-      fail-fast: false
-      matrix:
-        arch: [win_amd64]
-        pyver: [cp38, cp39, cp310, cp311, cp312, cp313]
-        package_name: [psycopg2, psycopg2-binary]
-
-    defaults:
-      run:
-        shell: bash
-
-    steps:
-      # there are some other libpq in PATH
-      - name: Drop spurious libpq in the path
-        run: rm -rf c:/tools/php C:/Strawberry/c/bin
-
-      - name: Checkout repo
-        uses: actions/checkout@v4
-
-      - name: Start PostgreSQL service for test
-        run: |
-          $PgSvc = Get-Service "postgresql*"
-          Set-Service $PgSvc.Name -StartupType manual
-          $PgSvc.Start()
-        shell: powershell
-
-      - name: Export GitHub Actions cache environment variables
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const path = require('path')
-            core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
-            core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');
-            core.addPath(path.join(process.env.VCPKG_INSTALLATION_ROOT, 'installed/x64-windows-release/lib'));
-            core.addPath(path.join(process.env.VCPKG_INSTALLATION_ROOT, 'installed/x64-windows-release/bin'));
-
-      - name: Create the binary package source tree
-        run: >-
-          sed -i 's/^setup(name="psycopg2"/setup(name="${{matrix.package_name}}"/'
-          setup.py
-        if: ${{ matrix.package_name != 'psycopg2' }}
-
-      - name: Build wheels
-        uses: pypa/cibuildwheel@v2.23.3
-        env:
-          VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite" # cache vcpkg
-          CIBW_BUILD: ${{matrix.pyver}}-${{matrix.arch}}
-          CIBW_ARCHS_WINDOWS: AMD64 x86
-          CIBW_BEFORE_BUILD_WINDOWS: '.\scripts\build\wheel_win32_before_build.bat'
-          CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: >-
-            delvewheel repair -w {dest_dir}
-            --no-mangle "libiconv-2.dll;libwinpthread-1.dll" {wheel}
-          CIBW_TEST_COMMAND: >-
-            set PYTHONPATH={project} &&
-            python -c "import tests; tests.unittest.main(defaultTest='tests.test_suite')"
-          # Note: no fast test because we don't run Windows tests
-          CIBW_ENVIRONMENT_WINDOWS: >-
-            PSYCOPG2_TESTDB=postgres
-            PSYCOPG2_TESTDB_USER=postgres
-            PSYCOPG2_TESTDB_HOST=localhost
-
-      - name: Upload artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: windows-${{ matrix.package_name }}-${{matrix.pyver}}-${{matrix.arch}}
-          path: ./wheelhouse/*.whl
-
-  # }}}
-
-  merge:  # {{{
-    runs-on: ubuntu-latest
-    needs:
-      - sdist
-      - linux
-      - macos
-      - windows
-    steps:
-      - name: Merge Artifacts
-        uses: actions/upload-artifact/merge@v4
-        with:
-          name: psycopg2-artifacts
-          delete-merged: true
-
-  # }}}

.github/workflows/tests.yml

@@ -1,79 +0,0 @@
-name: Tests
-
-env:
-  PIP_BREAK_SYSTEM_PACKAGES: "1"
-
-on:
-  push:
-  pull_request:
-
-jobs:
-  linux:
-    runs-on: ubuntu-latest
-    if: true
-
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {python: "3.8", postgres: "12"}
-          - {python: "3.9", postgres: "13"}
-          - {python: "3.10", postgres: "14"}
-          - {python: "3.11", postgres: "15"}
-          - {python: "3.12", postgres: "16"}
-          - {python: "3.13", postgres: "17"}
-
-          # Opposite extremes of the supported Py/PG range, other architecture
-          - {python: "3.8", postgres: "17", architecture: "x86"}
-          - {python: "3.9", postgres: "16", architecture: "x86"}
-          - {python: "3.10", postgres: "15", architecture: "x86"}
-          - {python: "3.11", postgres: "14", architecture: "x86"}
-          - {python: "3.12", postgres: "13", architecture: "x86"}
-          - {python: "3.13", postgres: "12", architecture: "x86"}
-
-    env:
-      PSYCOPG2_TESTDB: postgres
-      PSYCOPG2_TESTDB_HOST: 127.0.0.1
-      PSYCOPG2_TESTDB_USER: postgres
-      PSYCOPG2_TESTDB_PASSWORD: password
-
-    services:
-      postgresql:
-        image: postgres:${{ matrix.postgres }}
-        env:
-          POSTGRES_PASSWORD: password
-        ports:
-          - 5432:5432
-        # Set health checks to wait until postgres has started
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-    steps:
-      - uses: actions/checkout@v4
-
-      # Can enable to test an unreleased libpq version.
-      - name: install libpq 16
-        if: false
-        run: |
-          set -x
-          rel=$(lsb_release -c -s)
-          echo "deb http://apt.postgresql.org/pub/repos/apt ${rel}-pgdg main 16" \
-            | sudo tee -a /etc/apt/sources.list.d/pgdg.list
-          sudo apt-get -qq update
-          pqver=$(apt-cache show libpq5  | grep ^Version: | head -1 \
-            | awk '{print $2}')
-          sudo apt-get -qq -y install "libpq-dev=${pqver}" "libpq5=${pqver}"
-
-      - name: Install tox
-        run: pip install "tox < 4"
-      - uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python }}
-      - name: Run tests
-        env:
-          MATRIX_PYTHON: ${{ matrix.python }}
-        run: tox -e ${MATRIX_PYTHON%-dev}
-        timeout-minutes: 5

.gitignore

@@ -1,18 +0,0 @@
-MANIFEST
-*~
-*.userprefs
-*.pidb
-*.pyc
-*.sw[po]
-*.egg-info/
-dist/*
-/build
-env
-env?
-.idea
-.tox
-.vscode/
-/rel
-/wheels
-/packages
-/wheelhouse

AUTHORS

@@ -1,15 +1,8 @@
 Main authors:
   Federico Di Gregorio <fog@debian.org>
-  Daniele Varrazzo <daniele.varrazzo@gmail.com>
 
 For the win32 port:
-  Jason Erickson <jerickso@indian.com>
+  Jason Erickson <jerickso@indian.com> (most of his changes are still in 2.0)
 
 Additional Help:
-
-  Peter Fein contributed a logging connection/cursor class that even if it
-  was not used directly heavily influenced the implementation currently in
-  psycopg2.extras.
-
-  Jan Urbański (re)started the work on asynchronous queries and contributed
-  both on that and on other parts of psycopg2.
+  

ChangeLog

@@ -0,0 +1,533 @@
+2005-03-04  Federico Di Gregorio  <fog@initd.org>
+
+	* Release 1.99.13.1.
+
+	* psycopg/adapter_asis.c (asis_str): changed call to PyObject_Repr
+	to PyObject_Str to avoid problems with long integers.
+
+2005-03-02  Federico Di Gregorio  <fog@debian.org>
+
+	* Release 1.99.13.
+	
+	* psycopg/adapter_*.c: added __conform__ to all adapters.
+	
+	* psycopg/adapter_qstring.c (qstring_quote): we now use
+	PyString_AsStringAndSize() instead of strlen() that would stop at
+	the first embedded \0 (but note that libpq quoting function will
+	truncate the string anyway!)
+	
+	* COPY TO implemented using both old and new (v3) protocol.
+
+	* psycopg/pqpath.c (_pq_copy_out_v3): implemented and working.
+
+	* psycopg/cursor_type.c (psyco_curs_copy_to): added cursor object
+	interface for copy_to.
+
+	* COPY FROM implemented using both old and new (v3) protocol.
+
+	* psycopg/config.h (Dprintf): declaration for asprintf is gone.
+
+	* psycopg/pqpath.c (_pq_copy_in_v3): implemented.
+
+2005-03-01  Federico Di Gregorio  <fog@debian.org>
+
+	* setup.py: now we generate a slighly more verbose version string
+	that embeds some of the compile options, to facilitate users' bug
+	reports.
+
+	* psycopg/cursor_type.c (psyco_curs_copy_from): we now use
+	PyOS_snprintf instead of asprintf. On some platforms this can be
+	bad (win32).. if that's your case, get a better platform. :/
+
+	* psycopg/microprotocols.c (microprotocols_adapt): fixed small
+	typo that made adaptation using __conform__ impossible.
+
+2005-02-28  Federico Di Gregorio  <fog@debian.org>
+
+	* lib/extras.py: removed AsIs adapter (now a built-in); also
+	removed prepare() method from the adapters that don't use it to
+	avoid an extra method call at mogrification time.
+
+	* psycopg/psycopgmodule.c (psyco_adapters_init): added
+	initialization of the AsIs adapter (adapts int, long, float and
+	*wonder* None!)
+
+	* psycopg/cursor_type.c (_mogrify_getquoted): reorganized the code
+	to adapt and then call .getquoted() to obtain the quoted data into
+	this new function.
+
+2005-2-27  Federico Di Gregorio  <fog@initd.org>
+
+	* examples/myfirstrecipe.py: fixed adapter registration. 
+
+2005-2-7  Federico Di Gregorio  <fog@initd.org>
+
+	* setup.py: added patch by Valentino Volonghi to build on MacOS X.
+
+2005-01-29  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/pqpath.c (_pq_fetch_tuples): fixed scale-related
+	segfault (*fourth* mail from Andrea. Another couple like this and
+	psycopg 2 will exit alpha at warp speed.)
+	
+	* psycopg/pqpath.c (pq_fetch): _pq_copy_out_3 -> _pq_copy_out_v3
+	(second and third mail from Andrea. :/)
+
+	* psycopg/cursor_type.c (_psyco_curs_has_write_check): added check
+	on .write() attribute, fixed compilation problems (first mail from
+	Andrea Arcangeli.)
+
+2005-01-20  Federico Di Gregorio  <fog@debian.org>
+
+	* lib/extensions.py (register_adapter): added register_adapter
+	function, exported ISQLQuote in psycopg.extensions.
+
+2005-01-18  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/pqpath.c (_pq_fetch_tuples): ported scale/precision fix
+	from psycopg 1.1.
+
+	* LICENSE: detailed licensing information. Re-licensed some parts
+	under BSD-like to allow integration is pysqlite.
+
+2005-01-13  Federico Di Gregorio  <fog@debian.org>
+
+	* ZPsycopgDA/db.py (DB.query
+	): ported ZPsycopgDA connection fix
+	from psycopg 1.1.
+
+	* lib/*.py: added pydoc-friendly messages.
+
+2005-01-12  Federico Di Gregorio  <fog@debian.org>
+
+	* Added debian directory (thanks to W. Borgert who sent initial
+	patch based on cdbs.)
+
+2004-12-20  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/pqpath.c (pq_execute): removed multiple calls to
+	pq_fetch in syncronous DBAPI compatibility mode to solve rowcount
+	problem.
+
+2004-12-14  Federico Di Gregorio  <fog@debian.org>
+
+	* Mm.. release 1.99.11.
+
+	* psycopg/cursor_type.c (_psyco_curs_prefetch): fixed bug in
+	interaction between the .isready() method and
+	_psyco_curs_prefetch: isready now store away the pgres but leave
+	prefetch do its work.
+
+	* psycopg/*.c: changed the names of most of the psycopg's built-in
+	types to replect their position in the psycopg._psycopg module.
+
+2004-12-10  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c: now *all* write or async accesses to the
+	connection object are arbitrated using the connection lock.
+	
+	* psycopg/cursor_type.c (psyco_curs_isready): now we reset the
+	current async cursor if it is ready, to allow other cursors to
+	.execute() without raising the "transaction in progress" error.
+
+	* psycopg/pqpath.c (pq_is_busy): gained status of high-level
+	function with its own blocking and locking.
+
+	* psycopg/cursor.h (EXC_IF_CURS_CLOSED): also checks the
+	connection (a closed connection implies a closed cursor.)
+
+	* psycopg/cursor_type.c: cursor's connection is correctly
+	INCREFfed and DECREFfed.
+
+	* psycopg/connection_type.c: removed the cursors list from the
+	connection object. It is not necessary anymore for the connection
+	to know about the cursors and the reference counting will keep the
+	connection alive (but possibly closed) until all cursors are
+	garbage collected.
+
+2004-11-20  Federico Di Gregorio  <fog@initd.org>
+
+	* psycopg/cursor_type.c (_mogrify): ported %% fix from 1.1.15. 
+
+2004-11-20  Federico Di Gregorio  <fog@initd.org>
+
+	* psycopg/cursor_type.c (psyco_curs_execute): added check to raise an
+	exception if a cursor tries to .execute() while an async query is
+	already in execution froma  different cursor. 
+
+2004-11-20  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/connection_type.c (psyco_conn_cursor): renamed 'cursor'
+	argument to 'cursor_factory'.
+
+2004-11-19  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c (_psyco_curs_buildrow_fill): now standard
+	tuples are filled using PyTuple_SET_ITEM while extended types
+	(created via row_factory) are filled using PySequence_SetItem.
+	
+	* psycopg/cursor_type.c: changed cursor attribute name from
+	tuple_factory to row_factory.
+
+2004-10-14  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c (_psyco_curs_buildrow_fill): now we use
+	PySequence_SetItem to avoid problems with containers created from
+	cursor's .tuple_factory attribute.
+
+	* lib/extras.py (DictCursor.execute): fixed stupid bug with cursor
+	setting self.tuplefactory instead of self.tuple_factory.
+
+2004-10-02  Federico Di Gregorio  <fog@debian.org>
+
+	* Release 1.99.10.
+	
+	* psycopg/cursor_type.c (_psyco_curs_buildrow_*): unified normal
+	and factory code into the _psyco_curs_buildrow_fill function; no
+	more memory leaks here. 
+
+	* psycopg/config.h (round): added check for __FreeBSD__ (that
+	should be defined when compiling with gcc, I hope.)
+
+	* setup.py: removed a lot of code now in setup.cfg.
+
+2004-09-24  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c (cursor_dealloc): fixed small memory leak
+	due to missing disposal of self->pgres.
+
+2004-9-14  Federico Di Gregorio  <fog@initd.org>
+
+	*  examples/dialtone.py: Added adapt() example by Valentino
+	Volonghi.
+
+2004-09-14  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/microprotocols.c (microprotocols_adapt): lots of changes
+	to the microprotocols layer (it is not micro anymore);
+	implementing almost all the PEP 246. The adapter registry is now
+	indexed by (type, protocol) and not by type alone.
+
+2004-09-13  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c (_mogrify): and qattr is gone.
+
+2004-09-05  Federico Di Gregorio  <fog@debian.org>
+
+	* Release 1.99.9 (or, the "twisting by the pool" release).
+
+	* psycopg/pqpath.c (_pq_fetch_tuples): changed to "static void"
+	instead of "static int", no ways for this function to fail.
+
+2004-09-04  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/pqpath.c (_pq_fetch_tuples): ported rowcount fix from
+	1.1.15.
+
+	* ZPsycopgDA/*: ZPsycopgDA back in action, using the new pooling
+	code.
+
+2004-08-29  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/typecast_basic.c (typecast_DECIMAL_cast): added DECIMAL
+	typecaster; it even works :).
+
+	* scripts/buildtypes.py (basic_types): added DECIMAL typecaster
+	for the NUMERIC oid.
+
+	* examples/threads.py: updated threads example to use pooling code. 
+
+	* lib/pool.py: added very simple and thread-safe connection
+	pooling class.
+
+	* psycopg/cursor_type.c (psyco_curs_fetchmany): fixed problem with
+	.fetchall() and .fetchmany() returning None instead of [] on empty
+	result sets.
+
+	* Release 1.99.8.
+
+2004-08-28  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c (psyco_curs_execute): added processing of
+	unicode queries.
+
+	* examples/encoding.py: much better encoding example, also using
+	the new UNICODE typecaster.
+
+	* psycopg/typecast_basic.c (typecast_UNICODE_cast): added UNICODE
+	typecaster.
+
+	* lib/extensions.py: the encodings dictionary is not available by
+	default but can be accessed from the psycopg.extensions module.
+
+	* psycopg/adapter_qstring.h: remove encoding information from
+	qstring adapter and moved it into psycopg module.
+
+2004-08-26  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c (_psyco_curs_prefetch): added check for
+	asynchronous fetch by wrong cursor.
+
+	* psycopg/pqpath.c (pq_fetch): fixed backend status message (bug
+	reported by Daniele Varrazzo.)
+
+2004-07-29  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/typecast_basic.c (typecast_BINARY_cast): reverted to
+	using strings instead of buffers when converting postgresql binary
+	objects (should *temporarily* fix corruption bug reported on
+	win32.)
+
+2004-07-21  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c: removed __iter__ and next methods from
+	object methods and moved them where they do belong (tp_iter and
+	tp_iternext.) Bug reported by Daniele Varrazzo (again!)
+
+2004-07-19  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/typecast_datetime.c (typecast_PYINTERVAL_cast): replaced
+	round() with micro() when rounding seconds (fixes bugs reported by
+	Daniele Varrazzo.)
+
+2004-07-16  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/pqpath.c (pq_set_critical): allow for a custom message
+	insted of the one from PQerrorMessage.
+	(pq_resolve_critical): added argument to specify if connection is
+	to be closed (used to not close it during COPY FROM/TO criticals.)
+
+	* psycopg/cursor_type.c (psyco_curs_fileno, psyco_curs_isready):
+	added extension methods related to async queries. 
+
+2004-07-15  Federico Di Gregorio  <fog@debian.org>
+
+	* Release 1.99.7.
+
+	* examples/tz.py: added example about time zones.
+
+	* psycopg/typecast_datetime.c (typecast_PYDATETIME_cast): create
+	FixedOffsetTimezone for postgresql "timestamp with time zone"
+	types.
+
+	* lib/tz.py: added (even more than) needed tzinfo classes.
+
+	* psycopg/typecast.c (typecast_call): changed typecast call code
+	to take the additional cursor parameter, needed for
+	cursor-dependent type casting (tzinfo & friends.)
+
+	* psycopg/cursor_type.c (_psyco_curs_buildrow_with_factory): added
+	use of tuple factories to fetcXXX methods.
+
+	* lib/extras.py: little extra goodies for psycopg.
+
+2004-07-14  Federico Di Gregorio  <fog@debian.org>
+
+	* Release 1.99.6. 
+	
+	* psycopg/connection_type.c: added .dsn attribute to connection
+	objects.
+
+	* psycopg/cursor_type.c (psyco_curs_mogrify): added .mogrify()
+	method.
+
+	* psycopg/adapter_qstring.c: copy the connection encoding only if
+	wrapped object is unicode and added table of encodings.
+
+2004-07-13  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/cursor_type.c (_mogrify): moved Dprintf statement to
+	avoid dereferencing empty pointer (from 1.1.x)
+	(psyco_curs_execute): now we save the query in self->query instead
+	of freeing the memory ASAP.
+	(cursorObject_members): and we finally export the saved query
+	through the cursor members interface. that's all folks.
+
+	* lib/extensions.py: added extensions module to clearly separate
+	psycopg own extensions from DBAPI-2.0
+
+2004-07-10  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/typecast_datetime.c: ported interval fix from 1.1.x.
+
+2004-05-16  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/typecast_datetime.c (typecast_*_cast): fixed Value error
+	when seconds > 59 by setting minutes += 1 and seconds -= 60
+	(reported by Marcel Gsteiger.) 
+
+2004-04-24  Federico Di Gregorio  <fog@debian.org>
+
+	* ported time interval patch by Ross Cohen from 1.1.12.
+
+2004-04-19  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/typecast_datetime.c (typecast_PYDATE_cast): applied
+	patch from Jason Erickson: min and max taken from datetime.Date
+	type.
+	
+2004-04-18  Federico Di Gregorio  <fog@debian.org>
+
+	* Applied changes from Jason Erickson to build on win32; see his
+	(slightly edited) entry below. (Still builds on Linux :)
+
+	* psycopg/*.c: removed inclusion of pthread.h from all files
+	except psycopg/config.h to build on win32 without faking the file.
+
+2004-04-15  Jason Erickson <jerickso@stickpeople.com>
+ 
+        * setup.py: Various changes. The critical ones: 
+	  - Make an empty pthread.h file so all the code doing an 
+	    #include <pthread.h> will find something.
+	  - Appended the winsock2 library and the PostgreSQL library to 
+	    the library path.
+	  - Setup the include path.
+	  - Have the PSYCOPG_VERSION macro be included with quotes.
+ 
+        * config.h: Added/Cleaned up Win32 includes, defines, stub functions.
+ 
+        * typecast.h: Removed ';' after PyObject_HEAD in the
+	typecastObject structure since Microsoft Visual Studio does not
+	like it.
+
+2004-04-15  Federico Di Gregorio  <fog@debian.org>
+
+	* Release 1.99.5 (bug-fixing and reorganization)
+
+	* setup.py et al.: moved psycopg to psycopg._psycopg to make
+	easier to provide high level python-only utilities (like the
+	promised pooling code). psycopg/__init__.py imports _psycopg and
+	make all the default DBAPI-2.0 stuff available. 
+
+2004-04-14  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/psycopgmodule.c (initpsycopg): wrapped initialization of
+	date/time adapters in #ifdefs to have psycopg compile without mx
+	or builtin datetime.
+
+2004-04-10  Federico Di Gregorio  <fog@debian.org>
+
+	* Release 1.99.4.
+
+2004-04-09  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/typecast_builtins.c: changed DATE to not include
+	DATETIME types anymore.
+
+	* psycopg/adapter_datetime.c (pydatetime_str): switched from
+	strftime to isoformat to preserve fractional seconds.
+
+2004-04-08  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/psycopgmodule.c (psyco_connect): ported sslmode
+	parameter from 1.1 branch.
+
+	* psycopg/adapter_datetime.*: added python built-in datetime
+	adapters. also added the datetime typecasters (still using mx as
+	default).
+
+	* psycopg/typecast.h: removed aliases, they now live in the right
+	typecast_xxx.c file.
+
+2004-03-08  Federico Di Gregorio  <fog@debian.org>
+
+	* Release 1.99.3 (alpha 4).
+
+	* examples/lastrowid.py: and the .lastrowid example is in. 
+
+	* psycopg/cursor_type.c (_mogrify): added call to .prepare()
+	method in both dict and sequence path.
+
+	* psycopg/connection_int.c (conn_set_client_encoding): added
+	encoding-change code.
+
+	* psycopg/adapter_qstring.c (qstring_quote): added hard-coded
+	support for utf8 and latin1 encodings.
+
+2004-03-01  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/connection_int.c (conn_close): does not use libpq
+	functions on NULL pgconn (this can happen when conn_close is
+	called after a failed PQconnect.)
+
+2004-02-29  Federico Di Gregorio  <fog@debian.org> 
+
+	* Release 1.99.2 (alpha 3).
+	
+	* psycopg/cursor_type.c: added .rownumber and .connection
+	attributes. Also added .scroll(), .next() and .__iter__() methods
+	(see DBAPI2-.0 extensions on PEP.)
+
+	* psycopg/connection_type.c (psyco_conn_set_isolation_level):
+	added connection method .set_isolation_level(). Also added all
+	error objects to the connection (see DBAPI2-.0 extensions on PEP.)
+
+	* psycopg/connection_int.c (conn_switch_isolation_level): added
+	isolation level switching code.
+
+	* setup.py: removed all references to PSYCOPG_NEWSTYLE: support
+	for python < 2.2 has been dropped.
+
+	* typecast_basic.c (typecast_BINARY_cast): now binary objects are
+	returned as true buffers.
+
+	* adapter_binary.*: added adapter for buffers and binary (bytea)
+	objects.
+
+	* Release 1.99.1 (alpha 2).
+
+	* adapter_mxdatetime.*: added adapters for all mx.DateTime types.
+
+2004-02-28  Federico Di Gregorio  <fog@debian.org>
+
+	* cursor_type.c (_mogrify): complete rework of the mogrification
+	code to use the microprotocols_adapt function.
+
+	* typecast_basic.c (typecast_BOOLEAN_cast): we now return real
+	Py_True and Py_False values.
+
+	* microprotocols.h: added very simple microprotocols
+	implementation to allow for python->postgresql types registry.
+
+2004-01-05  Federico Di Gregorio  <fog@debian.org>
+
+	* connection_int.c (conn_commit/conn_rollback): added code to
+	commit/rollback and connection methods. 
+
+2004-01-04  Federico Di Gregorio  <fog@debian.org>
+
+	* cursor_type.c (psyco_curs_fetchone): added fetchone method.
+
+2004-01-03  Federico Di Gregorio  <fog@debian.org>
+
+	* added (empty) INSTALL file.
+
+	* cursor_type.c (cursor_dealloc): added qattr for custom object
+	quoting using a callable attribute.
+	(_mogrify): ported new, fixed mogrification code from 1.1.12.
+
+2003-08-01  Federico Di Gregorio  <fog@debian.org>
+
+	* cursor_type.c (_mogrify_sequence): added sequence mogrification,
+	can be done better, on the dict model.
+
+2003-07-28  Federico Di Gregorio  <fog@debian.org>
+
+	* typeobj_qstring.c: added quoted strings (can use both own code,
+	like psycopg 1.x or PQescapeString from lipq.)
+
+2003-07-21  Federico Di Gregorio  <fog@debian.org>
+
+	* connection_type.c (psyco_conn_close): added .close()
+	method. wow.
+
+	* cursor_*.c: added basic cursor interface (new-style.)
+
+2003-07-20  Federico Di Gregorio  <fog@debian.org>
+
+	* psycopg/*: beginning of new source layout. if you think this
+	changelog is somewhat empty, you're right. look at
+	doc/ChangeLog-1.x for psycopg 1.x changelog just before the
+	branch.
+
+

INSTALL

@@ -1,4 +1,18 @@
-Installation instructions are included in the docs.
+Compiling and installing psycopg
+********************************
+
+While psycopg 1.x used autoconf for its build process psycopg 2 switched to
+the more pythoning setup.py. Currently both psycopg's author and distutils
+have some limitations so the file setup.cfg is almost unused and most build
+options are hidden in setup.py. Before building psycopg look at the very
+first lines of setup.py and change any settings to follow your system (or
+taste); then:
+
+    python setup.py build
+
+to build in the local directory; and:
+
+    python setup.py install
+    
+to install system-wide.
 
-Please check the 'doc/src/install.rst' file or online at
-<https://www.psycopg.org/docs/install.html>.

LICENSE

@@ -1,38 +1,19 @@
-psycopg2 and the LGPL
----------------------
+psycopg is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version. See file COPYING for details.
 
-psycopg2 is free software: you can redistribute it and/or modify it
-under the terms of the GNU Lesser General Public License as published
-by the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
+As a special exception, specific permission is granted for the GPLed
+code in this distribition to be linked to OpenSSL and PostgreSQL libpq
+without invoking GPL clause 2(b).
 
-psycopg2 is distributed in the hope that it will be useful, but WITHOUT
-ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
-License for more details.
+If you prefer you can use the Zope Database Adapter ZPsycopgDA (i.e.,
+every file inside the ZPsycopgDA directory) user the ZPL license as
+published on the Zope web site, http://www.zope.org/Resources/ZPL.
 
-In addition, as a special exception, the copyright holders give
-permission to link this program with the OpenSSL library (or with
-modified versions of OpenSSL that use the same license as OpenSSL),
-and distribute linked combinations including the two.
-
-You must obey the GNU Lesser General Public License in all respects for
-all of the code used other than OpenSSL. If you modify file(s) with this
-exception, you may extend this exception to your version of the file(s),
-but you are not obligated to do so. If you do not wish to do so, delete
-this exception statement from your version. If you delete this exception
-statement from all source files in the program, then also delete it here.
-
-You should have received a copy of the GNU Lesser General Public License
-along with psycopg2 (see the doc/ directory.)
-If not, see <https://www.gnu.org/licenses/>.
-
-
-Alternative licenses
---------------------
-
-The following BSD-like license applies (at your option) to the files following
-the pattern ``psycopg/adapter*.{h,c}`` and ``psycopg/microprotocol*.{h,c}``:
+Also, the following BSD-like license applies (at your option) to the
+files following the pattern psycopg/adapter*.{h,c} and
+psycopg/microprotocol*.{h,c}:
 
  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
@@ -42,8 +23,13 @@ the pattern ``psycopg/adapter*.{h,c}`` and ``psycopg/microprotocol*.{h,c}``:
     claim that you wrote the original software. If you use this
     software in a product, an acknowledgment in the product documentation
     would be appreciated but is not required.
-
+ 
  2. Altered source versions must be plainly marked as such, and must not
     be misrepresented as being the original software.
-
+ 
  3. This notice may not be removed or altered from any source distribution.
+
+psycopg is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.

MANIFEST.in

@@ -1,9 +1,8 @@
-recursive-include psycopg *.c *.h *.manifest
+recursive-include psycopg *.c *.h
 recursive-include lib *.py
-recursive-include tests *.py
-include doc/README.rst doc/SUCCESS doc/COPYING.LESSER doc/pep-0249.txt
-include doc/Makefile doc/requirements.txt
-recursive-include doc/src *.rst *.py *.css Makefile
-recursive-include scripts *.py *.sh
-include AUTHORS README.rst INSTALL LICENSE NEWS
-include MANIFEST.in setup.py setup.cfg Makefile
+recursive-include ZPsycopgDA *.py *.gif *.dtml
+recursive-include examples *.py somehackers.jpg whereareyou.jpg
+#recursive-include tests *.py
+recursive-include doc TODO HACKING SUCCESS ChangeLog-1.x
+include scripts/maketypes.sh scripts/buildtypes.py
+include AUTHORS README INSTALL ChangeLog setup.py setup.cfg

Makefile

@@ -1,104 +0,0 @@
-# Makefile for psycopg2. Do you want to...
-#
-# Build the library::
-#
-#   make
-#
-# Build the documentation::
-#
-#   make env (once)
-#   make docs
-#
-# Create a source package::
-#
-#   make sdist
-#
-# Run the test::
-#
-#   make check  # this requires setting up a test database with the correct user
-
-PYTHON := python$(PYTHON_VERSION)
-PYTHON_VERSION ?= $(shell $(PYTHON) -c 'import sys; print ("%d.%d" % sys.version_info[:2])')
-BUILD_DIR = $(shell pwd)/build/lib.$(PYTHON_VERSION)
-
-SOURCE_C := $(wildcard psycopg/*.c psycopg/*.h)
-SOURCE_PY := $(wildcard lib/*.py)
-SOURCE_TESTS := $(wildcard tests/*.py)
-SOURCE_DOC := $(wildcard doc/src/*.rst)
-SOURCE := $(SOURCE_C) $(SOURCE_PY) $(SOURCE_TESTS) $(SOURCE_DOC)
-
-PACKAGE := $(BUILD_DIR)/psycopg2
-PLATLIB := $(PACKAGE)/_psycopg.so
-PURELIB := $(patsubst lib/%,$(PACKAGE)/%,$(SOURCE_PY))
-
-BUILD_OPT := --build-lib=$(BUILD_DIR)
-BUILD_EXT_OPT := --build-lib=$(BUILD_DIR)
-SDIST_OPT := --formats=gztar
-
-ifdef PG_CONFIG
-	BUILD_EXT_OPT += --pg-config=$(PG_CONFIG)
-endif
-
-VERSION := $(shell grep PSYCOPG_VERSION setup.py | head -1 | sed -e "s/.*'\(.*\)'/\1/")
-SDIST := dist/psycopg2-$(VERSION).tar.gz
-
-.PHONY: check clean
-
-default: package
-
-all: package sdist
-
-package: $(PLATLIB) $(PURELIB)
-
-docs: docs-html
-
-docs-html: doc/html/genindex.html
-
-# for PyPI documentation
-docs-zip: doc/docs.zip
-
-sdist: $(SDIST)
-
-env:
-	$(MAKE) -C doc $@
-
-check:
-	PYTHONPATH=$(BUILD_DIR) $(PYTHON) -c "import tests; tests.unittest.main(defaultTest='tests.test_suite')" --verbose
-
-testdb:
-	@echo "* Creating $(TESTDB)"
-	@if psql -l | grep -q " $(TESTDB) "; then \
-	    dropdb $(TESTDB) >/dev/null; \
-	fi
-	createdb $(TESTDB)
-	# Note to packagers: this requires the postgres user running the test
-	# to be a superuser.  You may change this line to use the superuser only
-	# to install the contrib.  Feel free to suggest a better way to set up the
-	# testing environment (as the current is enough for development).
-	psql -f `pg_config --sharedir`/contrib/hstore.sql $(TESTDB)
-
-
-$(PLATLIB): $(SOURCE_C)
-	$(PYTHON) setup.py build_ext $(BUILD_EXT_OPT)
-
-$(PACKAGE)/%.py: lib/%.py
-	$(PYTHON) setup.py build_py $(BUILD_OPT)
-	touch $@
-
-$(PACKAGE)/tests/%.py: tests/%.py
-	$(PYTHON) setup.py build_py $(BUILD_OPT)
-	touch $@
-
-$(SDIST): $(SOURCE)
-	$(PYTHON) setup.py sdist $(SDIST_OPT)
-
-# docs depend on the build as it partly use introspection.
-doc/html/genindex.html: $(PLATLIB) $(PURELIB) $(SOURCE_DOC)
-	$(MAKE) -C doc html
-
-doc/docs.zip: doc/html/genindex.html
-	(cd doc/html && zip -r ../docs.zip *)
-
-clean:
-	rm -rf build
-	$(MAKE) -C doc clean

README

@@ -0,0 +1,45 @@
+psycopg - Python-PostgreSQL Database Adapter
+********************************************
+
+psycopg is a PostgreSQL database adapter for the Python programming
+language. This is version 2, a complete rewrite of the original code to
+provide new-style classes for connection and cursor objects and other sweet
+candies. Like the original, psycopg 2 was written with the aim of being
+very small and fast, and stable as a rock.
+
+psycopg is different from the other database adapter because it was
+designed for heavily multi-threaded applications that create and destroy
+lots of cursors and make a conspicuous number of concurrent INSERTs or
+UPDATEs. psycopg 2 also provide full asycronous operations for the really
+brave programmer.
+
+There are confirmed reports of psycopg 1.x compiling and running on Linux
+and FreeBSD on i386, Solaris, MacOS X and win32 architectures. psycopg 2
+does not introduce build-wise incompatible changes so it should be able to
+compile on all architectures just as its predecessor did.
+
+Now go read the INSTALL file. More information about psycopg extensions to
+the DBAPI-2.0 is available in the files located in the doc/ direcory.
+
+
+Licence
+-------
+
+psycopg is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version. See file COPYING for details.
+
+As a special exception, specific permission is granted for the GPLed code in
+this distribition to be linked to OpenSSL and PostgreSQL libpq without
+invoking GPL clause 2(b).
+
+If you prefer you can use the Zope Database Adapter ZPsycopgDA (i.e., every
+file inside the ZPsycopgDA directory) under the ZPL license as published on
+the Zope web site, http://www.zope.org/Resources/ZPL. The ZPL is perfectly
+compatible with the GPL
+
+psycopg is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+details.

README.rst

@@ -1,80 +0,0 @@
-psycopg2 - Python-PostgreSQL Database Adapter
-=============================================
-
-Psycopg is the most popular PostgreSQL database adapter for the Python
-programming language.  Its main features are the complete implementation of
-the Python DB API 2.0 specification and the thread safety (several threads can
-share the same connection).  It was designed for heavily multi-threaded
-applications that create and destroy lots of cursors and make a large number
-of concurrent "INSERT"s or "UPDATE"s.
-
-Psycopg 2 is mostly implemented in C as a libpq wrapper, resulting in being
-both efficient and secure.  It features client-side and server-side cursors,
-asynchronous communication and notifications, "COPY TO/COPY FROM" support.
-Many Python types are supported out-of-the-box and adapted to matching
-PostgreSQL data types; adaptation can be extended and customized thanks to a
-flexible objects adaptation system.
-
-Psycopg 2 is both Unicode and Python 3 friendly.
-
-.. Note::
-
-    The psycopg2 package is still widely used and actively maintained, but it
-    is not expected to receive new features.
-
-    `Psycopg 3`__ is the evolution of psycopg2 and is where `new features are
-    being developed`__: if you are starting a new project you should probably
-    start from 3!
-
-    .. __: https://pypi.org/project/psycopg/
-    .. __: https://www.psycopg.org/psycopg3/docs/index.html
-
-
-Documentation
--------------
-
-Documentation is included in the ``doc`` directory and is `available online`__.
-
-.. __: https://www.psycopg.org/docs/
-
-For any other resource (source code repository, bug tracker, mailing list)
-please check the `project homepage`__.
-
-.. __: https://psycopg.org/
-
-
-Installation
-------------
-
-Building Psycopg requires a few prerequisites (a C compiler, some development
-packages): please check the install_ and the faq_ documents in the ``doc`` dir
-or online for the details.
-
-If prerequisites are met, you can install psycopg like any other Python
-package, using ``pip`` to download it from PyPI_::
-
-    $ pip install psycopg2
-
-or using ``setup.py`` if you have downloaded the source package locally::
-
-    $ python setup.py build
-    $ sudo python setup.py install
-
-You can also obtain a stand-alone package, not requiring a compiler or
-external libraries, by installing the `psycopg2-binary`_ package from PyPI::
-
-    $ pip install psycopg2-binary
-
-The binary package is a practical choice for development and testing but in
-production it is advised to use the package built from sources.
-
-.. _PyPI: https://pypi.org/project/psycopg2/
-.. _psycopg2-binary: https://pypi.org/project/psycopg2-binary/
-.. _install: https://www.psycopg.org/docs/install.html#install-from-source
-.. _faq: https://www.psycopg.org/docs/faq.html#faq-compile
-
-:Build status: |gh-actions|
-
-.. |gh-actions| image:: https://github.com/psycopg/psycopg2/actions/workflows/tests.yml/badge.svg
-    :target: https://github.com/psycopg/psycopg2/actions/workflows/tests.yml
-    :alt: Build status

ZPsycopgDA/DA.py

@@ -0,0 +1,202 @@
+# ZPsycopgDA/DA.py - ZPsycopgDA Zope product: Database Connection
+#
+# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# Or, at your option this program (ZPsycopgDA) can be distributed under the
+# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
+# http://www.zope.org/Resources/ZPL.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See the LICENSE file for details.
+
+
+ALLOWED_PSYCOPG_VERSIONS = ('1.99.9',)
+
+import sys
+import db
+import DABase
+import Shared.DC.ZRDB.Connection
+
+from db import DB
+from Globals import DTMLFile
+from Globals import HTMLFile
+from ImageFile import ImageFile
+from ExtensionClass import Base
+from DateTime import DateTime
+
+# import psycopg and functions/singletons needed for date/time conversions
+
+import psycopg
+from psycopg import DATETIME
+from psycopg.extensions import TIME, DATE, INTERVAL
+from psycopg.extensions import new_type, register_type
+
+
+
+# add a new connection to a folder
+
+manage_addZPsycopgConnectionForm = DTMLFile('dtml/add',globals())
+
+def manage_addZPsycopgConnection(self, id, title, connection_string,
+                                 zdatetime=None, tilevel=2,
+                                 check=None, REQUEST=None):
+    """Add a DB connection to a folder."""
+    self._setObject(id, Connection(id, title, connection_string,
+                                   zdatetime, check, tilevel))
+    if REQUEST is not None: return self.manage_main(self, REQUEST)
+
+
+
+# the connection object
+
+class Connection(DABase.Connection):
+    """ZPsycopg Connection."""
+    id = 'Psycopg_database_connection' 
+    database_type     = 'Psycopg'
+    meta_type = title = 'Z Psycopg Database Connection'
+    icon              = 'misc_/ZPsycopg/conn'
+
+    def __init__(self, id, title, connection_string,
+                 zdatetime, check=None, tilevel=2, encoding=''):
+        self.zdatetime = zdatetime
+        self.id = str(id)
+        self.edit(title, connection_string, zdatetime,
+                  check=check, tilevel=tilevel, encoding=encoding)
+        
+    def factory(self):
+        return DB
+
+    def table_info(self):
+        return self._v_database_connection.table_info()
+
+    def edit(self, title, connection_string,
+             zdatetime, check=None, tilevel=2, encoding=''):
+        self.title = title
+        self.connection_string = connection_string
+        self.zdatetime = zdatetime
+        self.tilevel = tilevel
+        self.encoding = encoding
+
+        self.set_type_casts()
+        
+        if check: self.connect(self.connection_string)
+
+    manage_properties = DTMLFile('dtml/edit', globals())
+
+    def manage_edit(self, title, connection_string,
+                    zdatetime=None, check=None, tilevel=2, encoding='UTF-8',
+                    REQUEST=None):
+        """Edit the DB connection."""
+        self.edit(title, connection_string, zdatetime,
+                  check=check, tilevel=tilevel, encoding=encoding)
+        if REQUEST is not None:
+            msg = "Connection edited."
+            return self.manage_main(self,REQUEST,manage_tabs_message=msg)
+
+    def connect(self, s):
+        try:
+            self._v_database_connection.close()
+        except:
+            pass
+
+        # check psycopg version and raise exception if does not match
+        if psycopg.__version__ not in ALLOWED_PSYCOPG_VERSIONS:
+            raise ImportError("psycopg version mismatch (imported %s)" +
+                              psycopg.__version__)
+
+        self.set_type_casts()
+        self._v_connected = ''
+        dbf = self.factory()
+        
+        # TODO: let the psycopg exception propagate, or not?
+        self._v_database_connection = dbf(
+            self.connection_string, self.tilevel, self.encoding)
+        self._v_database_connection.open()
+        self._v_connected = DateTime()
+
+        return self
+
+    def set_type_casts(self):
+        # note that in both cases order *is* important
+        if self.zdatetime:
+            # use zope internal datetime routines
+            register_type(ZDATETIME)
+            register_type(ZDATE)
+            register_type(ZTIME)
+            register_type(ZINTERVAL)
+        else:
+            # use the standard
+            register_type(DATETIME)
+            register_type(DATE)
+            register_type(TIME)
+            register_type(INTERVAL)
+    
+# database connection registration data
+
+classes = (Connection,)
+
+meta_types = ({'name':'Z Psycopg Database Connection',
+               'action':'manage_addZPsycopgConnectionForm'},)
+
+folder_methods = {
+    'manage_addZPsycopgConnection': manage_addZPsycopgConnection,
+    'manage_addZPsycopgConnectionForm': manage_addZPsycopgConnectionForm}
+
+__ac_permissions__ = (
+    ('Add Z Psycopg Database Connections',
+     ('manage_addZPsycopgConnectionForm', 'manage_addZPsycopgConnection')),)
+
+# add icons
+
+misc_={'conn': ImageFile('Shared/DC/ZRDB/www/DBAdapterFolder_icon.gif')}
+
+for icon in ('table', 'view', 'stable', 'what', 'field', 'text', 'bin',
+             'int', 'float', 'date', 'time', 'datetime'):
+    misc_[icon] = ImageFile('icons/%s.gif' % icon, globals())
+
+# zope-specific psycopg typecasters
+
+# convert an ISO timestamp string from postgres to a Zope DateTime object
+def _cast_DateTime(str):
+    if str:
+        # this will split us into [date, time, GMT/AM/PM(if there)]
+        dt = split(str, ' ')
+        if len(dt) > 1:
+            # we now should split out any timezone info
+            dt[1] = split(dt[1], '-')[0]
+            dt[1] = split(dt[1], '+')[0]
+            return DateTime(join(dt[:2], ' '))
+        else:
+            return DateTime(dt[0])
+
+# convert an ISO date string from postgres to a Zope DateTime object
+def _cast_Date(str):
+    if str:
+        return DateTime(str)
+
+# Convert a time string from postgres to a Zope DateTime object.
+# NOTE: we set the day as today before feeding to DateTime so
+# that it has the same DST settings.
+def _cast_Time(str):
+    if str:
+        return DateTime(time.strftime('%Y-%m-%d %H:%M:%S',
+                                      time.localtime(time.time())[:3]+
+                                      time.strptime(str[:8], "%H:%M:%S")[3:]))
+
+# TODO: DateTime does not support intervals: what's the best we can do?
+def _cast_Interval(str):
+    return str
+
+ZDATETIME = new_type((1184, 1114), "ZDATETIME", _cast_DateTime)
+ZINTERVAL = new_type((1186,), "ZINTERVAL", _cast_Interval)
+ZDATE = new_type((1082,), "ZDATE", _cast_Date)
+ZTIME = new_type((1083,), "ZTIME", _cast_Time)
+

ZPsycopgDA/DABase.py

@@ -0,0 +1,67 @@
+# ZPsycopgDA/DABase.py - ZPsycopgDA Zope product: Database inspection
+#
+# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# Or, at your option this program (ZPsycopgDA) can be distributed under the
+# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
+# http://www.zope.org/Resources/ZPL.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See the LICENSE file for details.
+
+import sys
+import Shared.DC.ZRDB.Connection
+
+from db import DB
+from Globals import HTMLFile
+from ImageFile import ImageFile
+from ExtensionClass import Base
+from DateTime import DateTime
+
+# import psycopg and functions/singletons needed for date/time conversions
+
+import psycopg
+from psycopg.extensions import INTEGER, LONGINTEGER, FLOAT, BOOLEAN
+from psycopg import NUMBER, STRING, ROWID, DATETIME 
+
+
+
+class Connection(Shared.DC.ZRDB.Connection.Connection):
+    _isAnSQLConnection = 1
+
+    info = None
+    
+    #manage_options = Shared.DC.ZRDB.Connection.Connection.manage_options + (
+    #    {'label': 'Browse', 'action':'manage_browse'},)
+
+    #manage_tables = HTMLFile('tables', globals())
+    #manage_browse = HTMLFile('browse',globals())
+
+    def __getitem__(self, name):
+        if name == 'tableNamed':
+            if not hasattr(self, '_v_tables'): self.tpValues()
+            return self._v_tables.__of__(self)
+        raise KeyError, name
+
+    
+    ## old stuff from ZPsycopgDA 1.1 (never implemented) ##
+
+    def manage_wizard(self, tables):
+        "Wizard of what? Oozing?"
+
+    def manage_join(self, tables, select_cols, join_cols, REQUEST=None):
+        """Create an SQL join"""
+
+    def manage_insert(self, table, cols, REQUEST=None):
+        """Create an SQL insert"""
+
+    def manage_update(self, table, keys, cols, REQUEST=None):
+        """Create an SQL update"""

ZPsycopgDA/__init__.py

@@ -0,0 +1,32 @@
+# ZPsycopgDA/__init__.py - ZPsycopgDA Zope product
+#
+# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# Or, at your option this program (ZPsycopgDA) can be distributed under the
+# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
+# http://www.zope.org/Resources/ZPL.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See the LICENSE file for details.
+
+__doc__ = "ZPsycopg Database Adalper Registration." 
+__version__ = '2.0'
+
+import sys
+import string
+import DA
+
+methods    = DA.folder_methods
+classes    = DA.classes
+meta_types = DA.meta_types
+misc_      = DA.misc_
+
+__ac_permissions__=DA.__ac_permissions__

ZPsycopgDA/db.py

@@ -0,0 +1,224 @@
+# ZPsycopgDA/db.py - query execution
+#
+# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# Or, at your option this program (ZPsycopgDA) can be distributed under the
+# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
+# http://www.zope.org/Resources/ZPL.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See the LICENSE file for details.
+
+from Shared.DC.ZRDB.TM import TM
+from Shared.DC.ZRDB import dbi_db
+
+from ZODB.POSException import ConflictError
+
+import time
+import site
+import pool
+
+import psycopg
+from psycopg.extensions import INTEGER, LONGINTEGER, FLOAT, BOOLEAN
+from psycopg import NUMBER, STRING, ROWID, DATETIME 
+
+
+
+# the DB object, managing all the real query work
+
+class DB(TM, dbi_db.DB):
+    
+    _p_oid = _p_changed = _registered = None
+
+    def __init__(self, dsn, tilevel, enc='utf-8'):
+        self.dsn = dsn
+        self.tilevel = tilevel
+        self.encoding = enc
+        self.failures = 0
+        self.calls = 0
+
+    def getconn(self, create=True):
+        conn = pool.getconn(self.dsn)
+        conn.set_isolation_level(int(self.tilevel))
+        return conn
+
+    def putconn(self, close=False):
+        try:
+            conn = pool.getconn(self.dsn, False)
+        except AttributeError:
+            pass
+        pool.putconn(self.dsn, conn, close)
+        
+    def getcursor(self):
+        conn = self.getconn()
+        return conn.cursor()
+
+    def _finish(self, *ignored):
+        try:
+            conn = self.getconn(False)
+            conn.commit()
+            self.putconn()
+        except AttributeError:
+            pass
+            
+    def _abort(self, *ignored):
+        try:
+            conn = self.getconn(False)
+            conn.rollback()
+            self.putconn()
+        except AttributeError:
+            pass
+
+    def open(self):
+        # this will create a new pool for our DSN if not already existing,
+        # then get and immediately release a connection
+        self.getconn()
+        self.putconn()
+        
+    def close(self):
+        # FIXME: if this connection is closed we flush all the pool associated
+        # with the current DSN; does this makes sense?
+        pool.flushpool(self.dsn)
+
+    def sortKey(self):
+        return 1
+
+    ## tables and rows ##
+
+    def tables(self, rdb=0, _care=('TABLE', 'VIEW')):
+        self._register()
+        c = self.getcursor()
+        c.execute(
+            "SELECT t.tablename AS NAME, 'TABLE' AS TYPE "
+            "  FROM pg_tables t WHERE tableowner <> 'postgres' "
+            "UNION SELECT v.viewname AS NAME, 'VIEW' AS TYPE "
+            "  FROM pg_views v WHERE viewowner <> 'postgres' "
+            "UNION SELECT t.tablename AS NAME, 'SYSTEM_TABLE\' AS TYPE "
+            "  FROM pg_tables t WHERE tableowner = 'postgres' "
+            "UNION SELECT v.viewname AS NAME, 'SYSTEM_TABLE' AS TYPE "
+            "FROM pg_views v WHERE viewowner = 'postgres'")
+        res = []
+        for name, typ in c.fetchall():
+            if typ in _care:
+                res.append({'TABLE_NAME': name, 'TABLE_TYPE': typ})
+        self.putconn()
+        return res
+
+    def columns(self, table_name):
+        self._register()
+        c = self.getcursor()
+        try:
+            r = c.execute('SELECT * FROM "%s" WHERE 1=0' % table_name)
+        except:
+            return ()
+        res = []
+        for name, type, width, ds, p, scale, null_ok in c.description:
+            if type == NUMBER:
+                if type == INTEGER:
+                    type = INTEGER
+                elif type == FLOAT:
+                    type = FLOAT
+                else: type = NUMBER
+            elif type == BOOLEAN:
+                type = BOOLEAN
+            elif type == ROWID:
+                type = ROWID
+            elif type == DATETIME:
+                type = DATETIME
+            else:
+                type = STRING
+
+            res.append({'Name': name,
+                        'Type': type.name,
+                        'Precision': 0,
+                        'Scale': 0,
+                        'Nullable': 0})
+        self.putconn()
+        return res
+    
+    ## query execution ##
+
+    def query(self, query_string, max_rows=None, query_data=None):
+        self._register()
+        self.calls = self.calls+1
+
+        desc = ()
+        res = []
+        nselects = 0
+
+        c = self.getcursor()
+
+        try:
+            for qs in [x for x in query_string.split('\0') if x]:
+                if type(qs) == unicode:
+                    if self.encoding:
+                        qs = qs.encode(self.encoding)
+                try:
+                    if query_data:
+                        c.execute(qs, query_data)
+                    else:
+                        c.execute(qs)
+                except OperationalError, e:
+                    try:
+                        self.close()
+                    except:
+                        pass
+                    self.open()
+                    try:
+                        if   query_data:
+                            c.execute(qs, query_data)
+                        else:
+                            c.execute(qs)
+                    except (psycopg.ProgrammingError,psycopg.IntegrityError),e:
+                        if e.args[0].find("concurrent update") > -1:
+                            raise ConflictError
+                        raise e
+                except (psycopg.ProgrammingError,psycopg.IntegrityError), e:
+                    if e.args[0].find("concurrent update") > -1:
+                        raise ConflictError
+                    raise e
+                if c.description is not None:
+                    nselects += 1
+                    if c.description != desc and nselects > 1:
+                        raise psycopg.ProgrammingError(
+                            'multiple selects in single query not allowed')
+                    if max_rows:
+                        res = c.fetchmany(max_rows)
+                    else:
+                        res = c.fetchall()
+                    desc = c.description
+            self.failures = 0
+
+        except StandardError, err:
+            self._abort()
+            raise err
+        
+        items = []
+        for name, typ, width, ds, p, scale, null_ok in desc:
+            if typ == NUMBER:
+                if typ == INTEGER or typ == LONGINTEGER: typs = 'i'
+                else: typs = 'n'
+            elif typ == BOOLEAN:
+                typs = 'n'
+            elif typ == ROWID:
+                typs = 'i'
+            elif typ == DATETIME:
+                typs = 'd'
+            else:
+                typs = 's'
+            items.append({
+                'name': name,
+                'type': typs,
+                'width': width,
+                'null': null_ok,
+                })
+
+        return items, res

ZPsycopgDA/dtml/add.dtml

@@ -0,0 +1,96 @@
+<dtml-var manage_page_header>
+
+<dtml-var "manage_form_title(this(), _,
+           form_title='Add Z Psycopg Database Connection',
+           help_product='ZPsycopgDA',
+           help_topic='ZPsycopgDA-Method-Add.stx'
+           )">
+
+<p class="form-help">
+A Zope Psycopg Database Connection is used to connect and execute
+queries on a PostgreSQL database.
+</p>
+
+<p class="form-help"> 
+In the form below <em>Connection String</em> (also called the Data Source Name
+or DSN for short) is a string... (TODO: finish docs)
+</p>
+
+<form action="manage_addZPsycopgConnection" method="POST">
+<table cellspacing="0" cellpadding="2" border="0">
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Id
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="text" name="id" size="40"
+           value="Psycopg_database_connection" />
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-optional">
+    Title
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="text" name="title" size="40"
+        value="Z Psycopg Database Connection"/>
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Connection string
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="text" name="connection_string" size="40" value="" />
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Connect immediately
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="checkbox" name="check" value="YES" checked="YES" />
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Use Zope's internal DateTime
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="checkbox" name="zdatetime" value="YES" checked="YES" />
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Transaction isolation level
+    </div>
+    </td>
+    <td align="left" valign="top">
+      <select name="tilevel:int">
+        <option value="1">Read committed</option>
+        <option value="2" selected="YES">Serializable</option>
+      </select>
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top" colspan="2">
+    <div class="form-element">
+    <input class="form-element" type="submit" name="submit" value=" Add " />
+    </div>
+    </td>
+  </tr>
+</table>
+</form>
+
+<dtml-var manage_page_footer>

ZPsycopgDA/dtml/edit.dtml

@@ -0,0 +1,67 @@
+<dtml-var manage_page_header>
+<dtml-var manage_tabs>
+
+<form action="manage_edit" method="POST">
+<table cellspacing="0" cellpadding="2" border="0">
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-optional">
+    Title
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="text" name="title" size="40"
+        value="&dtml-title;"/>
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Connection string
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="text" name="connection_string" size="40"
+           value="&dtml-connection_string;" />
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Use Zope's internal DateTime
+    </div>
+    </td>
+    <td align="left" valign="top">
+    <input type="checkbox" name="zdatetime" value="YES"
+      <dtml-if expr="zdatetime">checked="YES"</dtml-if> />
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top">
+    <div class="form-label">
+    Transaction isolation level
+    </div>
+    </td>
+    <td align="left" valign="top">
+      <select name="tilevel:int">
+        <option value="1"
+                <dtml-if expr="tilevel==1">selected="YES"</dtml-if">>
+        Read committed</option>
+        <option value="2"
+                <dtml-if expr="tilevel==2">selected="YES"</dtml-if">>
+        Serializable</option>
+      </select>
+    </td>
+  </tr>
+  <tr>
+    <td align="left" valign="top" colspan="2">
+    <div class="form-element">
+    <input class="form-element" type="submit" name="submit"
+     value=" Save Changes " />
+    </div>
+    </td>
+  </tr>
+</table>
+</form>
+
+<dtml-var manage_page_footer>

ZPsycopgDA/pool.py

@@ -0,0 +1,51 @@
+# ZPsycopgDA/pool.py - ZPsycopgDA Zope product: connection pooling
+#
+# Copyright (C) 2004 Federico Di Gregorio <fog@initd.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# Or, at your option this program (ZPsycopgDA) can be distributed under the
+# Zope Public License (ZPL) Version 1.0, as published on the Zope web site,
+# http://www.zope.org/Resources/ZPL.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See the LICENSE file for details.
+
+# all the connections are held in a pool of pools, directly accessible by the
+# ZPsycopgDA code in db.py
+
+import threading
+import psycopg.pool
+
+_connections_pool = {}
+_connections_lock = threading.Lock()
+
+def getpool(dsn, create=True):
+    _connections_lock.acquire()
+    try:
+        if not _connections_pool.has_key(dsn) and create:
+            _connections_pool[dsn] = \
+                psycopg.pool.ThreadedConnectionPool(4, 200, dsn)
+    finally:
+        _connections_lock.release()
+    return _connections_pool[dsn]
+
+def flushpool(dsn):
+    _connections_lock.acquire()
+    try:
+        _connections_pool[dsn].closeall()
+        del _connections_pool[dsn]
+    finally:
+        _connections_lock.release()
+        
+def getconn(dsn, create=True):
+    return getpool(dsn, create=create).getconn()
+
+def putconn(dsn, conn, close=False):
+    getpool(dsn).putconn(conn, close=close)

debian/changelog

@@ -0,0 +1,12 @@
+psycopg2 (1.99.11-1) experimental; urgency=low
+
+  * Adapted from patches sent by W. Borgert.
+  * Renamed source package to psycopg2.
+
+ --
+
+psycopg2 (1.99.11-0.1) unstable; urgency=low
+  
+  * Experimental package.
+
+ -- W. Borgert <debacle@debian.org>  Sun, 09 Jan 2005 10:14:09 +0000

debian/control

@@ -0,0 +1,51 @@
+Source: psycopg2
+Section: python
+Priority: optional
+Build-depends: postgresql-dev, debhelper (>> 3), python2.3-dev, cdbs
+Maintainer: Federico Di Gregorio <fog@debian.org>
+Standards-Version: 3.6.1.1
+
+Package: python-psycopg2
+Architecture: any
+Section: python
+Depends: python (>= 2.3), python (<< 2.4), python2.3-psycopg
+Description: Python module for PostgreSQL [dummy package]
+ psycopg is a PostgreSQL database adapter for the Python programming
+ language. It was written from scratch with the aim of being very small
+ and fast, and stable as a rock. The main advantages of psycopg are that
+ it supports the full Python DBAPI-2.0 and being thread safe at level 2.
+ .
+ psycopg 2 is the next generation psycopg, implementing a much better
+ type system and even more DBAPI extensions:
+ .
+ * support for Python datetime and Decimal types;
+ * complete implementation of adapt() from PEP 246 to convert Python
+   types to PostgreSQL ones;
+ * COPY FROM/COPY TO support
+ * inehritable connection and cursor objects and support for connection
+   and cursor factories;
+ * automatic encoding conversion and support for unicode queries.
+ .
+ This dummy package just depends on the right, default version of Python 
+ and psycopg 2.
+
+Package: python2.3-psycopg2
+Architecture: any
+Section: python
+Depends: ${shlibs:Depends}, python2.3
+Description: Python 2.3 module for PostgreSQL
+ psycopg is a PostgreSQL database adapter for the Python programming
+ language. It was written from scratch with the aim of being very small
+ and fast, and stable as a rock. The main advantages of psycopg are that
+ it supports the full Python DBAPI-2.0 and being thread safe at level 2.
+ .
+ psycopg 2 is the next generation psycopg, implementing a much better
+ type system and even more DBAPI extensions:
+ .
+ * support for Python datetime and Decimal types;
+ * complete implementation of adapt() from PEP 246 to convert Python
+   types to PostgreSQL ones;
+ * COPY FROM/COPY TO support
+ * inehritable connection and cursor objects and support for connection
+   and cursor factories;
+ * automatic encoding conversion and support for unicode queries.

debian/copyright

@@ -0,0 +1,10 @@
+psycopg can be downloaded from its homepage:
+
+    http://initd.org/pub/software/psycopg/ALPHA/
+
+Copyright (c) 2001-2005 Federico Di Gregorio <fog@debian.org>
+
+This program is distributed under the GNU GPL.
+ 
+On Debian GNU/Linux systems, the complete text of the GNU General
+Public License can be found in '/usr/share/common-licenses/GPL'.

debian/rules

@@ -0,0 +1,5 @@
+#!/usr/bin/make -f
+
+include /usr/share/cdbs/1/rules/debhelper.mk
+include /usr/share/cdbs/1/class/python-distutils.mk
+

doc/.gitignore

@@ -1,8 +0,0 @@
-env
-src/_build/*
-html/*
-psycopg2.txt
-src/sqlstate_errors.rst
-
-# Added by psycopg-website to customize published docs
-src/_templates/layout.html

doc/COPYING.LESSER

@@ -1,165 +0,0 @@
-		   GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-  This version of the GNU Lesser General Public License incorporates
-the terms and conditions of version 3 of the GNU General Public
-License, supplemented by the additional permissions listed below.
-
-  0. Additional Definitions.
-
-  As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the GNU
-General Public License.
-
-  "The Library" refers to a covered work governed by this License,
-other than an Application or a Combined Work as defined below.
-
-  An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-  A "Combined Work" is a work produced by combining or linking an
-Application with the Library.  The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-  The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-  The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-  1. Exception to Section 3 of the GNU GPL.
-
-  You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-  2. Conveying Modified Versions.
-
-  If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
-   a) under this License, provided that you make a good faith effort to
-   ensure that, in the event an Application does not supply the
-   function or data, the facility still operates, and performs
-   whatever part of its purpose remains meaningful, or
-
-   b) under the GNU GPL, with none of the additional permissions of
-   this License applicable to that copy.
-
-  3. Object Code Incorporating Material from Library Header Files.
-
-  The object code form of an Application may incorporate material from
-a header file that is part of the Library.  You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
-   a) Give prominent notice with each copy of the object code that the
-   Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the object code with a copy of the GNU GPL and this license
-   document.
-
-  4. Combined Works.
-
-  You may convey a Combined Work under terms of your choice that,
-taken together, effectively do not restrict modification of the
-portions of the Library contained in the Combined Work and reverse
-engineering for debugging such modifications, if you also do each of
-the following:
-
-   a) Give prominent notice with each copy of the Combined Work that
-   the Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
-   document.
-
-   c) For a Combined Work that displays copyright notices during
-   execution, include the copyright notice for the Library among
-   these notices, as well as a reference directing the user to the
-   copies of the GNU GPL and this license document.
-
-   d) Do one of the following:
-
-       0) Convey the Minimal Corresponding Source under the terms of this
-       License, and the Corresponding Application Code in a form
-       suitable for, and under terms that permit, the user to
-       recombine or relink the Application with a modified version of
-       the Linked Version to produce a modified Combined Work, in the
-       manner specified by section 6 of the GNU GPL for conveying
-       Corresponding Source.
-
-       1) Use a suitable shared library mechanism for linking with the
-       Library.  A suitable mechanism is one that (a) uses at run time
-       a copy of the Library already present on the user's computer
-       system, and (b) will operate properly with a modified version
-       of the Library that is interface-compatible with the Linked
-       Version.
-
-   e) Provide Installation Information, but only if you would otherwise
-   be required to provide such information under section 6 of the
-   GNU GPL, and only to the extent that such information is
-   necessary to install and execute a modified version of the
-   Combined Work produced by recombining or relinking the
-   Application with a modified version of the Linked Version. (If
-   you use option 4d0, the Installation Information must accompany
-   the Minimal Corresponding Source and Corresponding Application
-   Code. If you use option 4d1, you must provide the Installation
-   Information in the manner specified by section 6 of the GNU GPL
-   for conveying Corresponding Source.)
-
-  5. Combined Libraries.
-
-  You may place library facilities that are a work based on the
-Library side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
-   a) Accompany the combined library with a copy of the same work based
-   on the Library, uncombined with any other library facilities,
-   conveyed under the terms of this License.
-
-   b) Give prominent notice with the combined library that part of it
-   is a work based on the Library, and explaining where to find the
-   accompanying uncombined form of the same work.
-
-  6. Revised Versions of the GNU Lesser General Public License.
-
-  The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-  Each version is given a distinguishing version number. If the
-Library as you received it specifies that a certain numbered version
-of the GNU Lesser General Public License "or any later version"
-applies to it, you have the option of following the terms and
-conditions either of that published version or of any later version
-published by the Free Software Foundation. If the Library as you
-received it does not specify a version number of the GNU Lesser
-General Public License, you may choose any version of the GNU Lesser
-General Public License ever published by the Free Software Foundation.
-
-  If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.

doc/HACKING

@@ -0,0 +1,43 @@
+General information
+*******************
+
+Some help to people wanting to hack on psycopg. First of all, note that
+*every* function in the psycopg module source code is prefixed by one of the
+following words:
+
+    psyco is used for function directly callable from python (i.e., functions
+        in the psycopg module itself.) the only notable exception is the
+        source code for the module itself, that uses "psyco" even for C-only
+        functions.
+
+    conn is used for functions related to connection objects.
+
+    curs is used for functions related to cursor objects.
+
+    typecast is used for typecasters and utility function related to
+        typecaster creation and registration.
+
+Pythonic definition of types and functions available from python are defined
+in *_type.c files. Internal functions, callable only from C are located in
+*_int.c files and extensions to the DBAPI can be found in the *_ext.c files.
+
+
+Patches
+*******
+
+If you submit a patch, please send a diff generated with the "-u" switch.
+Also note that I don't like that much cosmetic changes (like renaming
+already existing variables) and I will rewrap the patch to 78 columns
+anyway, so it is much better if you do that beforehand.
+
+
+The type system
+***************
+
+Simple types, like integers and strings, are converted to python base types
+(the conversion functions are in typecast_base.c). Complex types are
+converted to ad-hoc types, defined in the typeobj_*.{c,h} files. The
+conversion function are in the other typecast_*.c files. typecast.c defines
+the basic utility functions (available through the psycopg module) used when
+defining new typecasters from C and python.
+

doc/Makefile

@@ -1,39 +0,0 @@
-.PHONY: env help clean html package doctest
-
-docs: html
-
-check: doctest
-
-# The environment is currently required to build the documentation.
-# It is not clean by 'make clean'
-
-PYTHON := python$(PYTHON_VERSION)
-PYTHON_VERSION ?= $(shell $(PYTHON) -c 'import sys; print("%d.%d" % sys.version_info[:2])')
-BUILD_DIR = $(shell pwd)/../build/lib.$(PYTHON_VERSION)
-
-SPHINXBUILD ?= $$(pwd)/env/bin/sphinx-build
-SPHOPTS = SPHINXBUILD=$(SPHINXBUILD)
-
-html: package src/sqlstate_errors.rst
-	$(MAKE) $(SPHOPTS) -C src $@
-	cp -r src/_build/html .
-
-src/sqlstate_errors.rst: ../psycopg/sqlstate_errors.h $(BUILD_DIR)
-	./env/bin/python src/tools/make_sqlstate_docs.py $< > $@
-
-$(BUILD_DIR):
-	$(MAKE) PYTHON=$(PYTHON) -C .. package
-
-doctest:
-	$(MAKE) PYTHON=$(PYTHON) -C .. package
-	$(MAKE) $(SPHOPTS) -C src $@
-
-clean:
-	$(MAKE) $(SPHOPTS) -C src $@
-	rm -rf html src/sqlstate_errors.rst
-
-env: requirements.txt
-	$(PYTHON) -m venv env
-	./env/bin/pip install -r requirements.txt
-	echo "$$(pwd)/../build/lib.$(PYTHON_VERSION)" \
-		> env/lib/python$(PYTHON_VERSION)/site-packages/psycopg.pth

doc/README.rst

@@ -1,20 +0,0 @@
-How to build psycopg documentation
-----------------------------------
-
-Building the documentation usually requires building the library too for
-introspection, so you will need the same prerequisites_.  The only extra
-prerequisite is virtualenv_: the packages needed to build the docs will be
-installed when building the env.
-
-.. _prerequisites: https://www.psycopg.org/docs/install.html#install-from-source
-.. _virtualenv: https://virtualenv.pypa.io/en/latest/
-
-Build the env once with::
-
-    make env
-
-Then you can build the documentation with::
-
-    make
-
-You should find the rendered documentation in the ``html`` directory.

doc/SUCCESS

@@ -1,10 +1,10 @@
 From: 	Jack Moffitt <jack@xiph.org>
 To: 	Psycopg Mailing List <psycopg@lists.initd.org>
 Subject: 	Re: [Psycopg] preparing for 1.0
-Date: 	22 Oct 2001 11:16:21 -0600
+Date: 	22 Oct 2001 11:16:21 -0600	
 
-www.vorbis.com is serving from 5-10k pages per day with psycopg serving
-data for most of that.
+www.vorbis.com is serving from 5-10k pages per day with psycopg serving 
+data for most of that.  
 
 I plan to use it for several of our other sites, so that number will
 increase.
@@ -19,11 +19,11 @@ jack.
 From: 	Yury Don <gercon@vpcit.ru>
 To: 	Psycopg Mailing List <psycopg@lists.initd.org>
 Subject: 	Re: [Psycopg] preparing for 1.0
-Date: 	23 Oct 2001 09:53:11 +0600
+Date: 	23 Oct 2001 09:53:11 +0600	
 
 We use psycopg and psycopg zope adapter since fisrt public
 release (it seems version 0.4). Now it works on 3 our sites and in intranet
-applications. We had few problems, but all problems were quickly
+applications. We had few problems, but all problems were quckly
 solved. The strong side of psycopg is that it's code is well organized
 and easy to understand. When I found a problem with non-ISO datestyle in first
 version of psycopg, it took for me 15 or 20 minutes to learn code and
@@ -32,7 +32,7 @@ to solve the problem, even thouth my knowledge of c were poor.
 BTW, segfault with dictfetchall on particular data set (see [Psycopg]
 dictfetchXXX() problems) disappeared in 0.99.8pre2.
 
---
+-- 
 Best regards,
 Yury Don
 
@@ -42,7 +42,7 @@ To: 	Federico Di Gregorio <fog@debian.org>
 Cc: 	Psycopg Mailing List <psycopg@lists.initd.org>
 Subject: 	Re: [Psycopg] preparing for 1.0
 Date: 	23 Oct 2001 08:25:52 -0400
-
+	
 The US Govt Department of Labor's Office of Disability Employment
 Policy's DisabilityDirect website is run on zope and zpsycopg.
 
@@ -50,7 +50,7 @@ Policy's DisabilityDirect website is run on zope and zpsycopg.
 From: 	Scott Leerssen <sleerssen@racemi.com>
 To: 	Federico Di Gregorio <fog@debian.org>
 Subject: 	Re: [Psycopg] preparing for 1.0
-Date: 	23 Oct 2001 09:56:10 -0400
+Date: 	23 Oct 2001 09:56:10 -0400	
 
 Racemi's load management software infrastructure uses psycopg to handle
 complex server allocation decisions, plus storage and access of
@@ -66,10 +66,10 @@ From: 	Andre Schubert <andre.schubert@geyer.kabeljournal.de>
 To: 	Federico Di Gregorio <fog@debian.org>
 Cc: 	Psycopg Mailing List <psycopg@lists.initd.org>
 Subject: 	Re: [Psycopg] preparing for 1.0
-Date: 	23 Oct 2001 11:46:07 +0200
+Date: 	23 Oct 2001 11:46:07 +0200	
 
 i have changed the psycopg version to 0.99.8pre2 on all devel-machines
-and all segfaults are gone. after my holiday i wil change to 0.99.8pre2
+and all segfaults are gone. after my holiday i wil change to 0.99.8pre2 
 or 1.0 on our production-server.
 this server contains several web-sites which are all connected to
 postgres over ZPsycopgDA.
@@ -81,7 +81,7 @@ From: 	Fred Wilson Horch <fhorch@ecoaccess.org>
 To: 	<psycopg@lists.initd.org>
 Subject: 	[Psycopg] Success story for psycopg
 Date: 	23 Oct 2001 10:59:17 -0400
-
+	
 Due to various quirks of PyGreSQL and PoPy, EcoAccess has been looking for
 a reliable, fast and relatively bug-free Python-PostgreSQL interface for
 our project.
@@ -98,7 +98,7 @@ reports and feature requests, and we're looking forward to using psycopg
 as the Python interface for additional database-backed web applications.
 
 Keep up the good work!
---
+-- 
 Fred Wilson Horch                       mailto:fhorch@ecoaccess.org
 Executive Director, EcoAccess           http://ecoaccess.org/
 

doc/TODO

@@ -0,0 +1,33 @@
+TODO list for psycopg 2 or later
+********************************
+
+Move items to the DONE section only after writing a test for the
+implementation. Also add a note on how the item was resolved.
+(Obviously I was joking about the test..)
+
+* Find a better way to compile the type-casting code instead of including it
+   in typecast.c directy. (Including is not that bad, but the need to touch
+   psycopg/typecast.c every time is bad bad bad.)
+
+* executemany() should _not_ take the async flag, remove it and force multiple
+   queries to be synchronous.
+
+* Fix all the docstrings.
+
+* Support the protocols API fully.
+
+* Unify the common code in typecast_datetime.c and typecast_mxdatetime.c.
+
+* Port typecasters to new-style classes.
+
+* Write a complete postgresql<->python encodings table.
+
+* Implement binary typecasters (should be easy, but it will take time.)
+
+DONE
+====
+
+* Convert type-casters to new-style types in Python 2.2+.
+
+* callproc() never worked, fix it or remove it and raise right exception.
+   [Removed callproc code, now an exception is raised.]

doc/async.txt

@@ -0,0 +1,65 @@
+psycopg asynchronous API
+************************
+
+Program code can initiate an asynchronous query by passing an 'async=1' flag
+to the .execute() method. A very simple example, from the connection to the
+query:
+
+    conn = psycopg.connect(database='test')
+    curs = conn.cursor()
+    curs.execute("SEECT * from test WHERE fielda > %s", (1971,), async=1)
+    
+From then on any query on other cursors derived from the same connection is
+doomed to fail (and raise an exception) until the original cursor (the one
+executing the query) complete the asynchronous operation. This can happen in
+a number of different ways:
+
+    1) one of the .fetchXXX() methods is called, effectively blocking untill
+       data has been sent from the backend to the client, terminating the
+       query.
+       
+    2) .cancel() is called. This method tries to abort the current query and
+       will block until the query is aborted or fully executed. The return
+       value is True if the query was successfully aborted or False if it
+       was executed. Query result are discarded in both cases.
+       
+    3) .execute() is called again on the same cursor (.execute() on a
+       different cursor will simply raise an exception.) This waits for the
+       complete execution of the current query, discard any data and execute
+       the new one.
+
+Note that calling .execute() two times in a row will not abort the former
+query and will temporarily go to synchronous mode until the first of the two
+queries is executed.
+
+Cursors now have some extra methods that make them usefull during
+asynchronous queries:
+
+    .fileno()
+      Returns the file descriptor associated with the current connection and
+      make possible to use a cursor in a context where a file object would be
+      expected (like in a select() call.)
+
+    .isbusy()
+      Returns True if the backend is still processing the query or false if
+      data is ready to be fetched (by one of the .fetchXXX() methods.)
+      
+A code snippet that shows how to use the cursor object in a select() call:
+
+    import psycopg
+    import select
+        
+    conn = psycopg.connect(database='test')
+    curs = conn.cursor()
+    curs.execute("SEECT * from test WHERE fielda > %s", (1971,), async=1)
+
+    # wait for input with a maximum timeout of 5 seconds
+    query_ended = False
+    while not query_ended:
+        rread, rwrite, rspec = select([cursor, another_file], [], [], 5)
+	if not cursor.isbusy():
+	   query_ended = True
+	# manage input from other sources like other_file, etc.
+    print "Query Results:"
+    for row in cursor:
+        print row

doc/release.rst

@@ -1,68 +0,0 @@
-How to make a psycopg2 release
-==============================
-
-- Edit ``setup.py`` and set a stable version release. Use PEP 440 to choose
-  version numbers, e.g.
-
-  - ``2.7``: a new major release, new features
-  - ``2.7.1``: a bugfix release
-  - ``2.7.1.1``: a release to fix packaging problems
-  - ``2.7.2.dev0``: version held during development, non-public test packages...
-  - ``2.8b1``: a beta for public tests
-
-  In the rest of this document we assume you have exported the version number
-  into an environment variable, e.g.::
-
-    $ export VERSION=2.8.4
-
-- Push psycopg2 to master or to the maint branch. Make sure tests on `GitHub
-  Actions`__.
-
-.. __: https://github.com/psycopg/psycopg2/actions/workflows/tests.yml
-
-- Create a signed tag with the content of the relevant NEWS bit and push it.
-  E.g.::
-
-    # Tag name will be 2_8_4
-    $ git tag -a -s ${VERSION//\./_}
-
-    Psycopg 2.8.4 released
-
-    What's new in psycopg 2.8.4
-    ---------------------------
-
-    New features:
-
-    - Fixed bug blah (:ticket:`#42`).
-    ...
-
-- Create the packages:
-
-  - On GitHub Actions run manually a `package build workflow`__.
-
-.. __: https://github.com/psycopg/psycopg2/actions/workflows/packages.yml
-
-- When the workflows have finished download the packages from the job
-  artifacts.
-
-- Only for stable packages: upload the signed packages on PyPI::
-
-    $ twine upload -s wheelhouse/psycopg2-${VERSION}/*
-
-- Create a release and release notes in the psycopg website, announce to
-  psycopg and pgsql-announce mailing lists.
-
-- Edit ``setup.py`` changing the version again (e.g. go to ``2.8.5.dev0``).
-
-
-Releasing test packages
------------------------
-
-Test packages may be uploaded on the `PyPI testing site`__ using::
-
-    $ twine upload -s -r testpypi wheelhouse/psycopg2-${VERSION}/*
-
-assuming `proper configuration`__ of ``~/.pypirc``.
-
-.. __: https://test.pypi.org/project/psycopg2/
-.. __: https://wiki.python.org/moin/TestPyPI

doc/requirements.in

@@ -1,2 +0,0 @@
-Sphinx
-sphinx-better-theme

doc/requirements.txt

@@ -1,50 +0,0 @@
-#
-# This file is autogenerated by pip-compile with Python 3.10
-# by the following command:
-#
-#    pip-compile requirements.in
-#
-alabaster==0.7.13
-    # via sphinx
-babel==2.12.1
-    # via sphinx
-certifi>=2023.7.22
-    # via requests
-charset-normalizer==3.1.0
-    # via requests
-docutils==0.19
-    # via sphinx
-idna==3.4
-    # via requests
-imagesize==1.4.1
-    # via sphinx
-jinja2==3.1.2
-    # via sphinx
-markupsafe==2.1.2
-    # via jinja2
-packaging==23.1
-    # via sphinx
-pygments==2.15.0
-    # via sphinx
-requests==2.31.0
-    # via sphinx
-snowballstemmer==2.2.0
-    # via sphinx
-sphinx==6.1.3
-    # via -r requirements.in
-sphinx-better-theme==0.1.5
-    # via -r requirements.in
-sphinxcontrib-applehelp==1.0.4
-    # via sphinx
-sphinxcontrib-devhelp==1.0.2
-    # via sphinx
-sphinxcontrib-htmlhelp==2.0.1
-    # via sphinx
-sphinxcontrib-jsmath==1.0.1
-    # via sphinx
-sphinxcontrib-qthelp==1.0.3
-    # via sphinx
-sphinxcontrib-serializinghtml==1.1.5
-    # via sphinx
-urllib3==1.26.17
-    # via requests

doc/src/Makefile

@@ -1,99 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
-
-# DSN for the doctest database
-PSYCOPG2_DSN="user=postgres dbname=test"
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  dirhtml   to make HTML files named index.html in directories"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  qthelp    to make HTML files and a qthelp project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	-rm -rf $(BUILDDIR)/*
-	-rm -rf ./html/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text pages are in $(BUILDDIR)/text."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/psycopg.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/psycopg.qhc"
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	PSYCOPG2_DSN=$(PSYCOPG2_DSN) \
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."

doc/src/_static/psycopg.css

@@ -1,136 +0,0 @@
-blockquote {
-    font-style: italic;
-}
-
-div.admonition-todo {
-    background-color: #ffa;
-    border: 1px solid #ee2;
-}
-
-div.dbapi-extension {
-    background-color: #eef;
-    border: 1px solid #aaf;
-}
-
-code.sql,
-tt.sql {
-    font-size: 1em;
-    background-color: transparent;
-}
-
-a > code.sql,
-a > tt.sql {
-    font-weight: normal;
-}
-
-a > code.sql:hover,
-a > tt.sql:hover {
-    text-decoration: underline;
-}
-
-dl.faq dt {
-    font-weight: bold;
-}
-
-table.data-types div.line-block {
-    margin-bottom: 0;
-}
-
-
-/* better theme customisation */
-
-body {
-    background-color: #216464;
-}
-
-header, .related, .document, footer {
-    background-color: white;
-}
-
-header h1 {
-    font-size: 150%;
-    margin-bottom: 0;
-    padding: 0.5rem 10px 0.5rem 10px;
-}
-
-h1, h2, h3 {
-    font-weight: normal;
-}
-
-.body h1, .body h2, .body h3 {
-    color: #074848;
-}
-
-h1 {
-    font-size: 200%;
-}
-
-h2 {
-    font-size: 160%;
-}
-
-h3 {
-    font-size: 140%;
-}
-
-footer#pagefooter {
-    margin-bottom: 1rem;
-    font-size: 85%;
-    color: #444;
-}
-
-#rellinks, #breadcrumbs {
-    padding-right: 10px;
-    padding-left: 10px;
-}
-
-.sphinxsidebar {
-    padding-left: 10px;
-}
-
-.bodywrapper {
-    padding-right: 10px;
-}
-
-div.body h1, div.body h2, div.body h3 {
-    background-color: #f2f2f2;
-    border-bottom: 1px solid #d0d0d0;
-}
-
-div.body p.rubric {
-    border-bottom: 1px solid #d0d0d0;
-}
-
-body .sphinxsidebar .search {
-    margin-top: 0;
-}
-
-html pre {
-    background-color: #efc;
-    border: 1px solid #ac9;
-    border-left: none;
-    border-right: none;
-}
-
-a, a:visited {
-    color: #0b6868;
-}
-
-th {
-    background-color: #ede;
-}
-
-code.xref, a code {
-    font-weight: bold;
-}
-
-code.descname {
-    font-weight: bold;
-    font-size: 120%;
-}
-
-@media (max-width: 820px) {
-    body {
-        background-color: white;
-    }
-}

doc/src/_templates/searchbox.html

@@ -1,6 +0,0 @@
-{# Add a title over the search box #}
-
-{%- if pagename != "search" %}
-<h3>Quick search</h3>
-{%- include "!searchbox.html" %}
-{%- endif %}

doc/src/advanced.rst

@@ -1,599 +0,0 @@
-More advanced topics
-====================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. testsetup:: *
-
-    import re
-    import select
-
-    cur.execute("CREATE TABLE atable (apoint point)")
-    conn.commit()
-
-    def wait(conn):
-        while True:
-            state = conn.poll()
-            if state == psycopg2.extensions.POLL_OK:
-                break
-            elif state == psycopg2.extensions.POLL_WRITE:
-                select.select([], [conn.fileno()], [])
-            elif state == psycopg2.extensions.POLL_READ:
-                select.select([conn.fileno()], [], [])
-            else:
-                raise psycopg2.OperationalError("poll() returned %s" % state)
-
-    aconn = psycopg2.connect(database='test', async=1)
-    wait(aconn)
-    acurs = aconn.cursor()
-
-
-.. index::
-    double: Subclassing; Cursor
-    double: Subclassing; Connection
-
-.. _subclassing-connection:
-.. _subclassing-cursor:
-
-Connection and cursor factories
--------------------------------
-
-Psycopg exposes two new-style classes that can be sub-classed and expanded to
-adapt them to the needs of the programmer: `psycopg2.extensions.cursor`
-and `psycopg2.extensions.connection`.  The `connection` class is
-usually sub-classed only to provide an easy way to create customized cursors
-but other uses are possible. `cursor` is much more interesting, because
-it is the class where query building, execution and result type-casting into
-Python variables happens.
-
-The `~psycopg2.extras` module contains several examples of :ref:`connection
-and cursor subclasses <cursor-subclasses>`.
-
-.. note::
-
-    If you only need a customized cursor class, since Psycopg 2.5 you can use
-    the `~connection.cursor_factory` parameter of a regular connection instead
-    of creating a new `!connection` subclass.
-
-
-.. index::
-    single: Example; Cursor subclass
-
-An example of cursor subclass performing logging is::
-
-    import psycopg2
-    import psycopg2.extensions
-    import logging
-
-    class LoggingCursor(psycopg2.extensions.cursor):
-        def execute(self, sql, args=None):
-            logger = logging.getLogger('sql_debug')
-            logger.info(self.mogrify(sql, args))
-
-            try:
-                psycopg2.extensions.cursor.execute(self, sql, args)
-            except Exception, exc:
-                logger.error("%s: %s" % (exc.__class__.__name__, exc))
-                raise
-
-    conn = psycopg2.connect(DSN)
-    cur = conn.cursor(cursor_factory=LoggingCursor)
-    cur.execute("INSERT INTO mytable VALUES (%s, %s, %s);",
-                 (10, 20, 30))
-
-
-
-.. index::
-    single: Objects; Creating new adapters
-    single: Adaptation; Creating new adapters
-    single: Data types; Creating new adapters
-
-.. _adapting-new-types:
-
-Adapting new Python types to SQL syntax
----------------------------------------
-
-Any Python class or type can be adapted to an SQL string.  Adaptation mechanism
-is similar to the Object Adaptation proposed in the :pep:`246` and is exposed
-by the `psycopg2.extensions.adapt()` function.
-
-The `~cursor.execute()` method adapts its arguments to the
-`~psycopg2.extensions.ISQLQuote` protocol.  Objects that conform to this
-protocol expose a `!getquoted()` method returning the SQL representation
-of the object as a string (the method must return `!bytes` in Python 3).
-Optionally the conform object may expose a
-`~psycopg2.extensions.ISQLQuote.prepare()` method.
-
-There are two basic ways to have a Python object adapted to SQL:
-
-- the object itself is conform, or knows how to make itself conform. Such
-  object must expose a `__conform__()` method that will be called with the
-  protocol object as argument. The object can check that the protocol is
-  `!ISQLQuote`, in which case it can return `!self` (if the object also
-  implements `!getquoted()`) or a suitable wrapper object. This option is
-  viable if you are the author of the object and if the object is specifically
-  designed for the database (i.e. having Psycopg as a dependency and polluting
-  its interface with the required methods doesn't bother you). For a simple
-  example you can take a look at the source code for the
-  `psycopg2.extras.Inet` object.
-
-- If implementing the `!ISQLQuote` interface directly in the object is not an
-  option (maybe because the object to adapt comes from a third party library),
-  you can use an *adaptation function*, taking the object to be adapted as
-  argument and returning a conforming object.  The adapter must be
-  registered via the `~psycopg2.extensions.register_adapter()` function.  A
-  simple example wrapper is `!psycopg2.extras.UUID_adapter` used by the
-  `~psycopg2.extras.register_uuid()` function.
-
-A convenient object to write adapters is the `~psycopg2.extensions.AsIs`
-wrapper, whose `!getquoted()` result is simply the `!str()`\ ing conversion of
-the wrapped object.
-
-.. index::
-    single: Example; Types adaptation
-
-Example: mapping of a `!Point` class into the |point|_ PostgreSQL
-geometric type:
-
-.. doctest::
-
-    >>> from psycopg2.extensions import adapt, register_adapter, AsIs
-
-    >>> class Point(object):
-    ...    def __init__(self, x, y):
-    ...        self.x = x
-    ...        self.y = y
-
-    >>> def adapt_point(point):
-    ...     x = adapt(point.x).getquoted()
-    ...     y = adapt(point.y).getquoted()
-    ...     return AsIs("'(%s, %s)'" % (x, y))
-
-    >>> register_adapter(Point, adapt_point)
-
-    >>> cur.execute("INSERT INTO atable (apoint) VALUES (%s)",
-    ...             (Point(1.23, 4.56),))
-
-
-.. |point| replace:: :sql:`point`
-.. _point: https://www.postgresql.org/docs/current/static/datatype-geometric.html#DATATYPE-GEOMETRIC
-
-The above function call results in the SQL command::
-
-    INSERT INTO atable (apoint) VALUES ('(1.23, 4.56)');
-
-
-
-.. index:: Type casting
-
-.. _type-casting-from-sql-to-python:
-
-Type casting of SQL types into Python objects
----------------------------------------------
-
-PostgreSQL objects read from the database can be adapted to Python objects
-through an user-defined adapting function.  An adapter function takes two
-arguments: the object string representation as returned by PostgreSQL and the
-cursor currently being read, and should return a new Python object.  For
-example, the following function parses the PostgreSQL :sql:`point`
-representation into the previously defined `!Point` class:
-
-    >>> def cast_point(value, cur):
-    ...    if value is None:
-    ...        return None
-    ...
-    ...    # Convert from (f1, f2) syntax using a regular expression.
-    ...    m = re.match(r"\(([^)]+),([^)]+)\)", value)
-    ...    if m:
-    ...        return Point(float(m.group(1)), float(m.group(2)))
-    ...    else:
-    ...        raise InterfaceError("bad point representation: %r" % value)
-
-
-In order to create a mapping from a PostgreSQL type (either standard or
-user-defined), its OID must be known. It can be retrieved either by the second
-column of the `cursor.description`:
-
-    >>> cur.execute("SELECT NULL::point")
-    >>> point_oid = cur.description[0][1]
-    >>> point_oid
-    600
-
-or by querying the system catalog for the type name and namespace (the
-namespace for system objects is :sql:`pg_catalog`):
-
-    >>> cur.execute("""
-    ...    SELECT pg_type.oid
-    ...      FROM pg_type JOIN pg_namespace
-    ...             ON typnamespace = pg_namespace.oid
-    ...     WHERE typname = %(typename)s
-    ...       AND nspname = %(namespace)s""",
-    ...    {'typename': 'point', 'namespace': 'pg_catalog'})
-    >>> point_oid = cur.fetchone()[0]
-    >>> point_oid
-    600
-
-After you know the object OID, you can create and register the new type:
-
-    >>> POINT = psycopg2.extensions.new_type((point_oid,), "POINT", cast_point)
-    >>> psycopg2.extensions.register_type(POINT)
-
-The `~psycopg2.extensions.new_type()` function binds the object OIDs
-(more than one can be specified) to the adapter function.
-`~psycopg2.extensions.register_type()` completes the spell.  Conversion
-is automatically performed when a column whose type is a registered OID is
-read:
-
-    >>> cur.execute("SELECT '(10.2,20.3)'::point")
-    >>> point = cur.fetchone()[0]
-    >>> print(type(point), point.x, point.y)
-    <class 'Point'> 10.2 20.3
-
-A typecaster created by `!new_type()` can be also used with
-`~psycopg2.extensions.new_array_type()` to create a typecaster converting a
-PostgreSQL array into a Python list.
-
-
-.. index::
-    pair: Asynchronous; Notifications
-    pair: LISTEN; SQL command
-    pair: NOTIFY; SQL command
-
-.. _async-notify:
-
-Asynchronous notifications
---------------------------
-
-Psycopg allows asynchronous interaction with other database sessions using the
-facilities offered by PostgreSQL commands |LISTEN|_ and |NOTIFY|_. Please
-refer to the PostgreSQL documentation for examples about how to use this form of
-communication.
-
-Notifications are instances of the `~psycopg2.extensions.Notify` object made
-available upon reception in the `connection.notifies` list. Notifications can
-be sent from Python code simply executing a :sql:`NOTIFY` command in an
-`~cursor.execute()` call.
-
-Because of the way sessions interact with notifications (see |NOTIFY|_
-documentation), you should keep the connection in `~connection.autocommit`
-mode if you wish to receive or send notifications in a timely manner.
-
-.. |LISTEN| replace:: :sql:`LISTEN`
-.. _LISTEN: https://www.postgresql.org/docs/current/static/sql-listen.html
-.. |NOTIFY| replace:: :sql:`NOTIFY`
-.. _NOTIFY: https://www.postgresql.org/docs/current/static/sql-notify.html
-
-Notifications are received after every query execution. If the user is
-interested in receiving notifications but not in performing any query, the
-`~connection.poll()` method can be used to check for new messages without
-wasting resources.
-
-A simple application could poll the connection from time to time to check if
-something new has arrived. A better strategy is to use some I/O completion
-function such as :py:func:`~select.select` to sleep until awakened by the kernel when there is
-some data to read on the connection, thereby using no CPU unless there is
-something to read::
-
-    import select
-    import psycopg2
-    import psycopg2.extensions
-
-    conn = psycopg2.connect(DSN)
-    conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)
-
-    curs = conn.cursor()
-    curs.execute("LISTEN test;")
-
-    print("Waiting for notifications on channel 'test'")
-    while True:
-        if select.select([conn],[],[],5) == ([],[],[]):
-            print("Timeout")
-        else:
-            conn.poll()
-            while conn.notifies:
-                notify = conn.notifies.pop(0)
-                print("Got NOTIFY:", notify.pid, notify.channel, notify.payload)
-
-Running the script and executing a command such as :sql:`NOTIFY test, 'hello'`
-in a separate :program:`psql` shell, the output may look similar to:
-
-.. code-block:: none
-
-    Waiting for notifications on channel 'test'
-    Timeout
-    Timeout
-    Got NOTIFY: 6535 test hello
-    Timeout
-    ...
-
-Note that the payload is only available from PostgreSQL 9.0: notifications
-received from a previous version server will have the
-`~psycopg2.extensions.Notify.payload` attribute set to the empty string.
-
-.. versionchanged:: 2.3
-    Added `~psycopg2.extensions.Notify` object and handling notification
-    payload.
-
-.. versionchanged:: 2.7
-    The `~connection.notifies` attribute is writable: it is possible to
-    replace it with any object exposing an `!append()` method. An useful
-    example would be to use a `~collections.deque` object.
-
-
-.. index::
-    double: Asynchronous; Connection
-
-.. _async-support:
-
-Asynchronous support
---------------------
-
-.. versionadded:: 2.2
-
-Psycopg can issue asynchronous queries to a PostgreSQL database. An asynchronous
-communication style is established passing the parameter *async*\=1 to the
-`~psycopg2.connect()` function: the returned connection will work in
-*asynchronous mode*.
-
-In asynchronous mode, a Psycopg connection will rely on the caller to poll the
-socket file descriptor, checking if it is ready to accept data or if a query
-result has been transferred and is ready to be read on the client. The caller
-can use the method `~connection.fileno()` to get the connection file
-descriptor and `~connection.poll()` to make communication proceed according to
-the current connection state.
-
-The following is an example loop using methods `!fileno()` and `!poll()`
-together with the Python :py:func:`~select.select` function in order to carry on
-asynchronous operations with Psycopg::
-
-    def wait(conn):
-        while True:
-            state = conn.poll()
-            if state == psycopg2.extensions.POLL_OK:
-                break
-            elif state == psycopg2.extensions.POLL_WRITE:
-                select.select([], [conn.fileno()], [])
-            elif state == psycopg2.extensions.POLL_READ:
-                select.select([conn.fileno()], [], [])
-            else:
-                raise psycopg2.OperationalError("poll() returned %s" % state)
-
-The above loop of course would block an entire application: in a real
-asynchronous framework, `!select()` would be called on many file descriptors
-waiting for any of them to be ready.  Nonetheless the function can be used to
-connect to a PostgreSQL server only using nonblocking commands and the
-connection obtained can be used to perform further nonblocking queries.  After
-`!poll()` has returned `~psycopg2.extensions.POLL_OK`, and thus `!wait()` has
-returned, the connection can be safely used:
-
-    >>> aconn = psycopg2.connect(database='test', async=1)
-    >>> wait(aconn)
-    >>> acurs = aconn.cursor()
-
-Note that there are a few other requirements to be met in order to have a
-completely non-blocking connection attempt: see the libpq documentation for
-|PQconnectStart|_.
-
-.. |PQconnectStart| replace:: `!PQconnectStart()`
-.. _PQconnectStart: https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS
-
-The same loop should be also used to perform nonblocking queries: after
-sending a query via `~cursor.execute()` or `~cursor.callproc()`, call
-`!poll()` on the connection available from `cursor.connection` until it
-returns `!POLL_OK`, at which point the query has been completely sent to the
-server and, if it produced data, the results have been transferred to the
-client and available using the regular cursor methods:
-
-    >>> acurs.execute("SELECT pg_sleep(5); SELECT 42;")
-    >>> wait(acurs.connection)
-    >>> acurs.fetchone()[0]
-    42
-
-When an asynchronous query is being executed, `connection.isexecuting()` returns
-`!True`. Two cursors can't execute concurrent queries on the same asynchronous
-connection.
-
-There are several limitations in using asynchronous connections: the
-connection is always in `~connection.autocommit` mode and it is not
-possible to change it. So a
-transaction is not implicitly started at the first query and is not possible
-to use methods `~connection.commit()` and `~connection.rollback()`: you can
-manually control transactions using `~cursor.execute()` to send database
-commands such as :sql:`BEGIN`, :sql:`COMMIT` and :sql:`ROLLBACK`. Similarly
-`~connection.set_session()` can't be used but it is still possible to invoke the
-:sql:`SET` command with the proper :sql:`default_transaction_...` parameter.
-
-With asynchronous connections it is also not possible to use
-`~connection.set_client_encoding()`, `~cursor.executemany()`, :ref:`large
-objects <large-objects>`, :ref:`named cursors <server-side-cursors>`.
-
-:ref:`COPY commands <copy>` are not supported either in asynchronous mode, but
-this will be probably implemented in a future release.
-
-
-
-
-.. index::
-    single: Greenlet
-    single: Coroutine
-    single: Eventlet
-    single: gevent
-    single: Wait callback
-
-.. _green-support:
-
-Support for coroutine libraries
--------------------------------
-
-.. versionadded:: 2.2
-
-Psycopg can be used together with coroutine_\-based libraries and participate
-in cooperative multithreading.
-
-Coroutine-based libraries (such as Eventlet_ or gevent_) can usually patch the
-Python standard library in order to enable a coroutine switch in the presence of
-blocking I/O: the process is usually referred as making the system *green*, in
-reference to the `green threads`_.
-
-Because Psycopg is a C extension module, it is not possible for coroutine
-libraries to patch it: Psycopg instead enables cooperative multithreading by
-allowing the registration of a *wait callback* using the
-`psycopg2.extensions.set_wait_callback()` function. When a wait callback is
-registered, Psycopg will use `libpq non-blocking calls`__ instead of the regular
-blocking ones, and will delegate to the callback the responsibility to wait
-for the socket to become readable or writable.
-
-Working this way, the caller does not have the complete freedom to schedule the
-socket check whenever they want as with an :ref:`asynchronous connection
-<async-support>`, but has the advantage of maintaining a complete |DBAPI|
-semantics: from the point of view of the end user, all Psycopg functions and
-objects will work transparently in the coroutine environment (blocking the
-calling green thread and giving other green threads the possibility to be
-scheduled), allowing non modified code and third party libraries (such as
-SQLAlchemy_) to be used in coroutine-based programs.
-
-.. warning::
-    Psycopg connections are not *green thread safe* and can't be used
-    concurrently by different green threads. Trying to execute more than one
-    command at time using one cursor per thread will result in an error (or a
-    deadlock on versions before 2.4.2).
-
-    Therefore, programmers are advised to either avoid sharing connections
-    between coroutines or to use a library-friendly lock to synchronize shared
-    connections, e.g. for pooling.
-
-Coroutine libraries authors should provide a callback implementation (and
-possibly a method to register it) to make Psycopg as green as they want. An
-example callback (using `!select()` to block) is provided as
-`psycopg2.extras.wait_select()`: it boils down to something similar to::
-
-    def wait_select(conn):
-        while True:
-            state = conn.poll()
-            if state == extensions.POLL_OK:
-                break
-            elif state == extensions.POLL_READ:
-                select.select([conn.fileno()], [], [])
-            elif state == extensions.POLL_WRITE:
-                select.select([], [conn.fileno()], [])
-            else:
-                raise OperationalError("bad state from poll: %s" % state)
-
-Providing callback functions for the single coroutine libraries is out of
-psycopg2 scope, as the callback can be tied to the libraries' implementation
-details. You can check the `psycogreen`_ project for further informations and
-resources about the topic.
-
-.. _coroutine: https://en.wikipedia.org/wiki/Coroutine
-.. _greenlet: https://pypi.org/project/greenlet/
-.. _green threads: https://en.wikipedia.org/wiki/Green_threads
-.. _Eventlet: https://eventlet.net/
-.. _gevent: http://www.gevent.org/
-.. _SQLAlchemy: https://www.sqlalchemy.org/
-.. _psycogreen: https://github.com/psycopg/psycogreen/
-.. __: https://www.postgresql.org/docs/current/static/libpq-async.html
-
-.. warning::
-
-    :ref:`COPY commands <copy>` are currently not supported when a wait callback
-    is registered, but they will be probably implemented in a future release.
-
-    :ref:`Large objects <large-objects>` are not supported either: they are
-    not compatible with asynchronous connections.
-
-
-.. testcode::
-    :hide:
-
-    aconn.close()
-    conn.rollback()
-    cur.execute("DROP TABLE atable")
-    conn.commit()
-    cur.close()
-    conn.close()
-
-
-
-.. index::
-    single: Replication
-
-.. _replication-support:
-
-Replication protocol support
-----------------------------
-
-.. versionadded:: 2.7
-
-Modern PostgreSQL servers (version 9.0 and above) support replication.  The
-replication protocol is built on top of the client-server protocol and can be
-operated using ``libpq``, as such it can be also operated by ``psycopg2``.
-The replication protocol can be operated on both synchronous and
-:ref:`asynchronous <async-support>` connections.
-
-Server version 9.4 adds a new feature called *Logical Replication*.
-
-.. seealso::
-
-   - PostgreSQL `Streaming Replication Protocol`__
-
-   .. __: https://www.postgresql.org/docs/current/static/protocol-replication.html
-
-
-Logical replication Quick-Start
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You must be using PostgreSQL server version 9.4 or above to run this quick
-start.
-
-Make sure that replication connections are permitted for user ``postgres`` in
-``pg_hba.conf`` and reload the server configuration.  You also need to set
-``wal_level=logical`` and ``max_wal_senders``, ``max_replication_slots`` to
-value greater than zero in ``postgresql.conf`` (these changes require a server
-restart).  Create a database ``psycopg2_test``.
-
-Then run the following code to quickly try the replication support out.  This
-is not production code -- it's only intended as a simple demo of logical
-replication::
-
-  from __future__ import print_function
-  import sys
-  import psycopg2
-  import psycopg2.extras
-
-  conn = psycopg2.connect('dbname=psycopg2_test user=postgres',
-     connection_factory=psycopg2.extras.LogicalReplicationConnection)
-  cur = conn.cursor()
-  try:
-      # test_decoding produces textual output
-      cur.start_replication(slot_name='pytest', decode=True)
-  except psycopg2.ProgrammingError:
-      cur.create_replication_slot('pytest', output_plugin='test_decoding')
-      cur.start_replication(slot_name='pytest', decode=True)
-
-  class DemoConsumer(object):
-      def __call__(self, msg):
-          print(msg.payload)
-          msg.cursor.send_feedback(flush_lsn=msg.data_start)
-
-  democonsumer = DemoConsumer()
-
-  print("Starting streaming, press Control-C to end...", file=sys.stderr)
-  try:
-     cur.consume_stream(democonsumer)
-  except KeyboardInterrupt:
-     cur.close()
-     conn.close()
-     print("The slot 'pytest' still exists. Drop it with "
-        "SELECT pg_drop_replication_slot('pytest'); if no longer needed.",
-        file=sys.stderr)
-     print("WARNING: Transaction logs will accumulate in pg_xlog "
-        "until the slot is dropped.", file=sys.stderr)
-
-
-You can now make changes to the ``psycopg2_test`` database using a normal
-psycopg2 session, ``psql``, etc. and see the logical decoding stream printed
-by this demo client.
-
-This will continue running until terminated with ``Control-C``.
-
-For the details see :ref:`replication-objects`.

doc/src/conf.py

@@ -1,289 +0,0 @@
-#
-# Psycopg documentation build configuration file, created by
-# sphinx-quickstart on Sun Feb  7 13:48:41 2010.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import os
-import sys
-from better import better_theme_path
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.append(os.path.abspath('tools/lib'))
-
-# -- General configuration -----------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.todo',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-]
-
-# Specific extensions for Psycopg documentation.
-extensions += ['dbapi_extension', 'sql_role', 'ticket_role']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-# source_encoding = 'utf-8'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = 'Psycopg'
-copyright = (
-    '2001-2021, Federico Di Gregorio, Daniele Varrazzo, The Psycopg Team'
-)
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '2.0'
-
-# The full version, including alpha/beta/rc tags.
-try:
-    import psycopg2
-except ImportError:
-    print("WARNING: couldn't import psycopg to read version.")
-    release = version
-else:
-    release = psycopg2.__version__.split()[0]
-    version = '.'.join(release.split('.')[:2])
-
-intersphinx_mapping = {'py': ('https://docs.python.org/3', None)}
-
-# Pattern to generate links to the bug tracker
-ticket_url = 'https://github.com/psycopg/psycopg2/issues/%s'
-ticket_remap_until = 25
-ticket_remap_offset = 230
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-# language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-# today = ''
-# Else, today_fmt is used as the format for a strftime call.
-# today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-# unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = ['_build', 'html']
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-default_role = 'obj'
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-# add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-# show_authors = False
-
-# Using 'python' instead of the default gives warnings if parsing an example
-# fails, instead of defaulting to none
-highlight_language = 'python'
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# Include TODO items in the documentation
-todo_include_todos = False
-
-rst_epilog = """
-.. |DBAPI| replace:: DB API 2.0
-
-.. _DBAPI: https://www.python.org/dev/peps/pep-0249/
-
-.. _transaction isolation level:
-    https://www.postgresql.org/docs/current/static/transaction-iso.html
-
-.. |MVCC| replace:: :abbr:`MVCC (Multiversion concurrency control)`
-"""
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'better'
-
-# The stylesheet to use with HTML output: this will include the original one
-# adding a few classes.
-# html_style = 'psycopg.css'
-
-# Hide the sphinx footer
-html_show_sphinx = False
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-html_theme_options = {
-    'linktotheme': False,
-    'cssfiles': ['_static/psycopg.css'],
-}
-
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [better_theme_path]
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-# html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-html_short_title = 'Home'
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-# html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-# html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-# no need for the prev/next topic link using better theme: they are on top
-html_sidebars = {
-    '**': ['localtoc.html', 'searchbox.html'],
-}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-# html_use_modindex = True
-
-# If false, no index is generated.
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-# html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-# html_show_sourcelink = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-# html_use_opensearch = ''
-
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = ''
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'psycopgdoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-# latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-# latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-    (
-        'index',
-        'psycopg.tex',
-        'Psycopg Documentation',
-        'Federico Di Gregorio',
-        'manual',
-    )
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# Additional stuff for the LaTeX preamble.
-# latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_use_modindex = True
-
-toc_object_entries = False
-
-doctest_global_setup = """
-
-import os
-import psycopg2
-
-def test_connect():
-    try:
-        dsn = os.environ['PSYCOPG2_DSN']
-    except KeyError:
-        assert False, "You need to set the environment variable PSYCOPG2_DSN" \
-                " in order to test the documentation!"
-    return psycopg2.connect(dsn)
-
-conn = test_connect()
-cur = conn.cursor()
-
-def drop_test_table(name):
-    cur.execute("SAVEPOINT drop_test_table;")
-    try:
-        cur.execute("DROP TABLE %s;" % name)
-    except:
-        cur.execute("ROLLBACK TO SAVEPOINT drop_test_table;")
-    conn.commit()
-
-def create_test_table():
-    drop_test_table('test')
-    cur.execute("CREATE TABLE test (id SERIAL PRIMARY KEY, num INT, data TEXT)")
-    conn.commit()
-
-"""

doc/src/connection.rst

@@ -1,916 +0,0 @@
-The ``connection`` class
-========================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. testsetup::
-
-    from pprint import pprint
-    import psycopg2.extensions
-
-    drop_test_table('foo')
-
-.. class:: connection
-
-    Handles the connection to a PostgreSQL database instance. It encapsulates
-    a database session.
-
-    Connections are created using the factory function
-    `~psycopg2.connect()`.
-
-    Connections are thread safe and can be shared among many threads. See
-    :ref:`thread-safety` for details.
-
-    Connections can be used as context managers. Note that a context wraps a
-    transaction: if the context exits with success the transaction is
-    committed, if it exits with an exception the transaction is rolled back.
-    Note that the connection is not closed by the context and it can be used
-    for several contexts.
-
-    .. code:: python
-
-        conn = psycopg2.connect(DSN)
-
-        with conn:
-            with conn.cursor() as curs:
-                curs.execute(SQL1)
-
-        with conn:
-            with conn.cursor() as curs:
-                curs.execute(SQL2)
-
-        # leaving contexts doesn't close the connection
-        conn.close()
-
-
-    .. method:: cursor(name=None, cursor_factory=None, scrollable=None, withhold=False)
-
-        Return a new `cursor` object using the connection.
-
-        If *name* is specified, the returned cursor will be a :ref:`server
-        side cursor <server-side-cursors>` (also known as *named cursor*).
-        Otherwise it will be a regular *client side* cursor.  By default a
-        named cursor is declared without :sql:`SCROLL` option and
-        :sql:`WITHOUT HOLD`: set the argument or property `~cursor.scrollable`
-        to `!True`/`!False` and or `~cursor.withhold` to `!True` to change the
-        declaration.
-
-        The name can be a string not valid as a PostgreSQL identifier: for
-        example it may start with a digit and contain non-alphanumeric
-        characters and quotes.
-
-        .. versionchanged:: 2.4
-            previously only valid PostgreSQL identifiers were accepted as
-            cursor name.
-
-        The *cursor_factory* argument can be used to create non-standard
-        cursors. The class returned must be a subclass of
-        `psycopg2.extensions.cursor`. See :ref:`subclassing-cursor` for
-        details. A default factory for the connection can also be specified
-        using the `~connection.cursor_factory` attribute.
-
-        .. versionchanged:: 2.4.3 added the *withhold* argument.
-        .. versionchanged:: 2.5 added the *scrollable* argument.
-
-        .. extension::
-
-            All the function arguments are Psycopg extensions to the |DBAPI|.
-
-
-    .. index::
-        pair: Transaction; Commit
-
-    .. method:: commit()
-
-        Commit any pending transaction to the database.
-
-        By default, Psycopg opens a transaction before executing the first
-        command: if `!commit()` is not called, the effect of any data
-        manipulation will be lost.
-
-        The connection can be also set in "autocommit" mode: no transaction is
-        automatically open, commands have immediate effect. See
-        :ref:`transactions-control` for details.
-
-        .. versionchanged:: 2.5 if the connection is used in a ``with``
-            statement, the method is automatically called if no exception is
-            raised in the ``with`` block.
-
-
-    .. index::
-        pair: Transaction; Rollback
-
-    .. method:: rollback()
-
-        Roll back to the start of any pending transaction.  Closing a
-        connection without committing the changes first will cause an implicit
-        rollback to be performed.
-
-        .. versionchanged:: 2.5 if the connection is used in a ``with``
-            statement, the method is automatically called if an exception is
-            raised in the ``with`` block.
-
-
-    .. method:: close()
-
-        Close the connection now (rather than whenever `del` is executed).
-        The connection will be unusable from this point forward; an
-        `~psycopg2.InterfaceError` will be raised if any operation is
-        attempted with the connection.  The same applies to all cursor objects
-        trying to use the connection.  Note that closing a connection without
-        committing the changes first will cause any pending change to be
-        discarded as if a :sql:`ROLLBACK` was performed (unless a different
-        isolation level has been selected: see
-        `~connection.set_isolation_level()`).
-
-        .. index::
-            single: PgBouncer; unclean server
-
-        .. versionchanged:: 2.2
-            previously an explicit :sql:`ROLLBACK` was issued by Psycopg on
-            `!close()`. The command could have been sent to the backend at an
-            inappropriate time, so Psycopg currently relies on the backend to
-            implicitly discard uncommitted changes. Some middleware are known
-            to behave incorrectly though when the connection is closed during
-            a transaction (when `~connection.status` is
-            `~psycopg2.extensions.STATUS_IN_TRANSACTION`), e.g. PgBouncer_
-            reports an ``unclean server`` and discards the connection. To
-            avoid this problem you can ensure to terminate the transaction
-            with a `~connection.commit()`/`~connection.rollback()` before
-            closing.
-
-            .. _PgBouncer: http://www.pgbouncer.org/
-
-
-    .. index::
-        single: Exceptions; In the connection class
-
-    .. rubric:: Exceptions as connection class attributes
-
-    The `!connection` also exposes as attributes the same exceptions
-    available in the `psycopg2` module.  See :ref:`dbapi-exceptions`.
-
-
-
-    .. index::
-        single: Two-phase commit; methods
-
-    .. rubric:: Two-phase commit support methods
-
-    .. versionadded:: 2.3
-
-    .. seealso:: :ref:`tpc` for an introductory explanation of these methods.
-
-    Note that PostgreSQL supports two-phase commit since release 8.1: these
-    methods raise `~psycopg2.NotSupportedError` if used with an older version
-    server.
-
-
-    .. _tpc_methods:
-
-    .. method:: xid(format_id, gtrid, bqual)
-
-        Returns a `~psycopg2.extensions.Xid` instance to be passed to the
-        `!tpc_*()` methods of this connection. The argument types and
-        constraints are explained in :ref:`tpc`.
-
-        The values passed to the method will be available on the returned
-        object as the members `~psycopg2.extensions.Xid.format_id`,
-        `~psycopg2.extensions.Xid.gtrid`, `~psycopg2.extensions.Xid.bqual`.
-        The object also allows accessing to these members and unpacking as a
-        3-items tuple.
-
-
-    .. method:: tpc_begin(xid)
-
-        Begins a TPC transaction with the given transaction ID *xid*.
-
-        This method should be called outside of a transaction (i.e. nothing
-        may have executed since the last `~connection.commit()` or
-        `~connection.rollback()` and `connection.status` is
-        `~psycopg2.extensions.STATUS_READY`).
-
-        Furthermore, it is an error to call `!commit()` or `!rollback()`
-        within the TPC transaction: in this case a `~psycopg2.ProgrammingError`
-        is raised.
-
-        The *xid* may be either an object returned by the `~connection.xid()`
-        method or a plain string: the latter allows to create a transaction
-        using the provided string as PostgreSQL transaction id. See also
-        `~connection.tpc_recover()`.
-
-
-    .. index::
-        pair: Transaction; Prepare
-
-    .. method:: tpc_prepare()
-
-        Performs the first phase of a transaction started with
-        `~connection.tpc_begin()`.  A `~psycopg2.ProgrammingError` is raised if
-        this method is used outside of a TPC transaction.
-
-        After calling `!tpc_prepare()`, no statements can be executed until
-        `~connection.tpc_commit()` or `~connection.tpc_rollback()` will be
-        called.  The `~connection.reset()` method can be used to restore the
-        status of the connection to `~psycopg2.extensions.STATUS_READY`: the
-        transaction will remain prepared in the database and will be
-        possible to finish it with `!tpc_commit(xid)` and
-        `!tpc_rollback(xid)`.
-
-        .. seealso:: the |PREPARE TRANSACTION|_ PostgreSQL command.
-
-        .. |PREPARE TRANSACTION| replace:: :sql:`PREPARE TRANSACTION`
-        .. _PREPARE TRANSACTION: https://www.postgresql.org/docs/current/static/sql-prepare-transaction.html
-
-
-    .. index::
-        pair: Commit; Prepared
-
-    .. method:: tpc_commit([xid])
-
-        When called with no arguments, `!tpc_commit()` commits a TPC
-        transaction previously prepared with `~connection.tpc_prepare()`.
-
-        If `!tpc_commit()` is called prior to `!tpc_prepare()`, a single phase
-        commit is performed.  A transaction manager may choose to do this if
-        only a single resource is participating in the global transaction.
-
-        When called with a transaction ID *xid*, the database commits
-        the given transaction.  If an invalid transaction ID is
-        provided, a `~psycopg2.ProgrammingError` will be raised.  This form
-        should be called outside of a transaction, and is intended for use in
-        recovery.
-
-        On return, the TPC transaction is ended.
-
-        .. seealso:: the |COMMIT PREPARED|_ PostgreSQL command.
-
-        .. |COMMIT PREPARED| replace:: :sql:`COMMIT PREPARED`
-        .. _COMMIT PREPARED: https://www.postgresql.org/docs/current/static/sql-commit-prepared.html
-
-
-    .. index::
-        pair: Rollback; Prepared
-
-    .. method:: tpc_rollback([xid])
-
-        When called with no arguments, `!tpc_rollback()` rolls back a TPC
-        transaction.  It may be called before or after
-        `~connection.tpc_prepare()`.
-
-        When called with a transaction ID *xid*, it rolls back the given
-        transaction.  If an invalid transaction ID is provided, a
-        `~psycopg2.ProgrammingError` is raised.  This form should be called
-        outside of a transaction, and is intended for use in recovery.
-
-        On return, the TPC transaction is ended.
-
-        .. seealso:: the |ROLLBACK PREPARED|_ PostgreSQL command.
-
-        .. |ROLLBACK PREPARED| replace:: :sql:`ROLLBACK PREPARED`
-        .. _ROLLBACK PREPARED: https://www.postgresql.org/docs/current/static/sql-rollback-prepared.html
-
-
-    .. index::
-        pair: Transaction; Recover
-
-    .. method:: tpc_recover()
-
-        Returns a list of `~psycopg2.extensions.Xid` representing pending
-        transactions, suitable for use with `tpc_commit()` or
-        `tpc_rollback()`.
-
-        If a transaction was not initiated by Psycopg, the returned Xids will
-        have attributes `~psycopg2.extensions.Xid.format_id` and
-        `~psycopg2.extensions.Xid.bqual` set to `!None` and the
-        `~psycopg2.extensions.Xid.gtrid` set to the PostgreSQL transaction ID: such Xids are still
-        usable for recovery.  Psycopg uses the same algorithm of the
-        `PostgreSQL JDBC driver`__ to encode a XA triple in a string, so
-        transactions initiated by a program using such driver should be
-        unpacked correctly.
-
-        .. __: https://jdbc.postgresql.org/
-
-        Xids returned by `!tpc_recover()` also have extra attributes
-        `~psycopg2.extensions.Xid.prepared`, `~psycopg2.extensions.Xid.owner`,
-        `~psycopg2.extensions.Xid.database` populated with the values read
-        from the server.
-
-        .. seealso:: the |pg_prepared_xacts|_ system view.
-
-        .. |pg_prepared_xacts| replace:: `pg_prepared_xacts`
-        .. _pg_prepared_xacts: https://www.postgresql.org/docs/current/static/view-pg-prepared-xacts.html
-
-
-
-    .. extension::
-
-        The above methods are the only ones defined by the |DBAPI| protocol.
-        The Psycopg connection objects exports the following additional
-        methods and attributes.
-
-
-    .. attribute:: closed
-
-        Read-only integer attribute: 0 if the connection is open, nonzero if
-        it is closed or broken.
-
-
-    .. method:: cancel
-
-        Cancel the current database operation.
-
-        The method interrupts the processing of the current operation. If no
-        query is being executed, it does nothing. You can call this function
-        from a different thread than the one currently executing a database
-        operation, for instance if you want to cancel a long running query if a
-        button is pushed in the UI. Interrupting query execution will cause the
-        cancelled method to raise a
-        `~psycopg2.extensions.QueryCanceledError`. Note that the termination
-        of the query is not guaranteed to succeed: see the documentation for
-        |PQcancel|_.
-
-        .. |PQcancel| replace:: `!PQcancel()`
-        .. _PQcancel: https://www.postgresql.org/docs/current/static/libpq-cancel.html#LIBPQ-PQCANCEL
-
-        .. versionadded:: 2.3
-
-
-    .. method:: reset
-
-        Reset the connection to the default.
-
-        The method rolls back an eventual pending transaction and executes the
-        PostgreSQL |RESET|_ and |SET SESSION AUTHORIZATION|__ to revert the
-        session to the default values. A two-phase commit transaction prepared
-        using `~connection.tpc_prepare()` will remain in the database
-        available for recover.
-
-        .. |RESET| replace:: :sql:`RESET`
-        .. _RESET: https://www.postgresql.org/docs/current/static/sql-reset.html
-
-        .. |SET SESSION AUTHORIZATION| replace:: :sql:`SET SESSION AUTHORIZATION`
-        .. __: https://www.postgresql.org/docs/current/static/sql-set-session-authorization.html
-
-        .. versionadded:: 2.0.12
-
-
-    .. attribute:: dsn
-
-        Read-only string containing the connection string used by the
-        connection.
-
-        If a password was specified in the connection string it will be
-        obscured.
-
-
-
-    .. rubric:: Transaction control methods and attributes.
-
-    .. index::
-        pair: Transaction; Autocommit
-        pair: Transaction; Isolation level
-
-    .. method:: set_session(isolation_level=None, readonly=None, deferrable=None, autocommit=None)
-
-        Set one or more parameters for the next transactions or statements in
-        the current session.
-
-        :param isolation_level: set the `isolation level`_ for the next
-            transactions/statements.  The value can be one of the literal
-            values ``READ UNCOMMITTED``, ``READ COMMITTED``, ``REPEATABLE
-            READ``, ``SERIALIZABLE`` or the equivalent :ref:`constant
-            <isolation-level-constants>` defined in the `~psycopg2.extensions`
-            module.
-        :param readonly: if `!True`, set the connection to read only;
-            read/write if `!False`.
-        :param deferrable: if `!True`, set the connection to deferrable;
-            non deferrable if `!False`. Only available from PostgreSQL 9.1.
-        :param autocommit: switch the connection to autocommit mode: not a
-            PostgreSQL session setting but an alias for setting the
-            `autocommit` attribute.
-
-        .. _isolation level:
-            https://www.postgresql.org/docs/current/static/transaction-iso.html
-
-        Arguments set to `!None` (the default for all) will not be changed.
-        The parameters *isolation_level*, *readonly* and *deferrable* also
-        accept the string ``DEFAULT`` as a value: the effect is to reset the
-        parameter to the server default.  Defaults are defined by the server
-        configuration: see values for |default_transaction_isolation|__,
-        |default_transaction_read_only|__, |default_transaction_deferrable|__.
-
-        .. |default_transaction_isolation| replace:: :sql:`default_transaction_isolation`
-        .. __: https://www.postgresql.org/docs/current/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-ISOLATION
-        .. |default_transaction_read_only| replace:: :sql:`default_transaction_read_only`
-        .. __: https://www.postgresql.org/docs/current/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY
-        .. |default_transaction_deferrable| replace:: :sql:`default_transaction_deferrable`
-        .. __: https://www.postgresql.org/docs/current/static/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-DEFERRABLE
-
-        The function must be invoked with no transaction in progress.
-
-        .. seealso:: |SET TRANSACTION|_ for further details about the behaviour
-            of the transaction parameters in the server.
-
-            .. |SET TRANSACTION| replace:: :sql:`SET TRANSACTION`
-            .. _SET TRANSACTION: https://www.postgresql.org/docs/current/static/sql-set-transaction.html
-
-        .. versionadded:: 2.4.2
-
-        .. versionchanged:: 2.7
-            Before this version, the function would have set
-            :sql:`default_transaction_*` attribute in the current session;
-            this implementation has the problem of not playing well with
-            external connection pooling working at transaction level and not
-            resetting the state of the session: changing the default
-            transaction would pollute the connections in the pool and create
-            problems to other applications using the same pool.
-
-            Starting from 2.7, if the connection is not autocommit, the
-            transaction characteristics are issued together with :sql:`BEGIN`
-            and will leave the :sql:`default_transaction_*` settings untouched.
-            For example::
-
-                conn.set_session(readonly=True)
-
-            will not change :sql:`default_transaction_read_only`, but
-            following transaction will start with a :sql:`BEGIN READ ONLY`.
-            Conversely, using::
-
-                conn.set_session(readonly=True, autocommit=True)
-
-            will set :sql:`default_transaction_read_only` to :sql:`on` and
-            rely on the server to apply the read only state to whatever
-            transaction, implicit or explicit, is executed in the connection.
-
-
-    .. attribute:: autocommit
-
-        Read/write attribute: if `!True`, no transaction is handled by the
-        driver and every statement sent to the backend has immediate effect;
-        if `!False` a new transaction is started at the first command
-        execution: the methods `commit()` or `rollback()` must be manually
-        invoked to terminate the transaction.
-
-        The autocommit mode is useful to execute commands requiring to be run
-        outside a transaction, such as :sql:`CREATE DATABASE` or
-        :sql:`VACUUM`.
-
-        The default is `!False` (manual commit) as per DBAPI specification.
-
-        .. warning::
-
-            By default, any query execution, including a simple :sql:`SELECT`
-            will start a transaction: for long-running programs, if no further
-            action is taken, the session will remain "idle in transaction", an
-            undesirable condition for several reasons (locks are held by
-            the session, tables bloat...). For long lived scripts, either
-            ensure to terminate a transaction as soon as possible or use an
-            autocommit connection.
-
-        .. versionadded:: 2.4.2
-
-
-    .. attribute:: isolation_level
-
-        Return or set the `transaction isolation level`_ for the current
-        session.  The value is one of the :ref:`isolation-level-constants`
-        defined in the `psycopg2.extensions` module.  On set it is also
-        possible to use one of the literal values ``READ UNCOMMITTED``, ``READ
-        COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``, ``DEFAULT``.
-
-        .. versionchanged:: 2.7
-
-            the property is writable.
-
-        .. versionchanged:: 2.7
-
-            the default value for `!isolation_level` is
-            `~psycopg2.extensions.ISOLATION_LEVEL_DEFAULT`; previously the
-            property would have queried the server and returned the real value
-            applied. To know this value you can run a query such as :sql:`show
-            transaction_isolation`. Usually the default value is `READ
-            COMMITTED`, but this may be changed in the server configuration.
-
-            This value is now entirely separate from the `autocommit`
-            property: in previous version, if `!autocommit` was set to `!True`
-            this property would have returned
-            `~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT`; it will now
-            return the server isolation level.
-
-
-    .. attribute:: readonly
-
-        Return or set the read-only status for the current session. Available
-        values are `!True` (new transactions will be in read-only mode),
-        `!False` (new transactions will be writable), `!None` (use the default
-        configured for the server by :sql:`default_transaction_read_only`).
-
-        .. versionadded:: 2.7
-
-
-    .. attribute:: deferrable
-
-        Return or set the `deferrable status`__ for the current session.
-        Available values are `!True` (new transactions will be in deferrable
-        mode), `!False` (new transactions will be in non deferrable mode),
-        `!None` (use the default configured for the server by
-        :sql:`default_transaction_deferrable`).
-
-        .. __: `SET TRANSACTION`_
-
-        .. versionadded:: 2.7
-
-
-    .. method:: set_isolation_level(level)
-
-        .. note::
-
-            This is a legacy method mixing `~conn.isolation_level` and
-            `~conn.autocommit`. Using the respective properties is a better
-            option.
-
-        Set the `transaction isolation level`_ for the current session.
-        The level defines the different phenomena that can happen in the
-        database between concurrent transactions.
-
-        The value set is an integer: symbolic constants are defined in
-        the module `psycopg2.extensions`: see
-        :ref:`isolation-level-constants` for the available values.
-
-        The default level is `~psycopg2.extensions.ISOLATION_LEVEL_DEFAULT`:
-        at this level a transaction is automatically started the first time a
-        database command is executed.  If you want an *autocommit* mode,
-        switch to `~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT` before
-        executing any command::
-
-            >>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)
-
-        See also :ref:`transactions-control`.
-
-
-    .. index::
-        pair: Client; Encoding
-
-    .. attribute:: encoding
-    .. method:: set_client_encoding(enc)
-
-        Read or set the client encoding for the current session. The default
-        is the encoding defined by the database. It should be one of the
-        `characters set supported by PostgreSQL`__
-
-        .. __: https://www.postgresql.org/docs/current/static/multibyte.html
-
-
-    .. index::
-        pair: Client; Logging
-
-    .. attribute:: notices
-
-        A list containing all the database messages sent to the client during
-        the session.
-
-        .. doctest::
-            :options: +NORMALIZE_WHITESPACE
-
-            >>> cur.execute("CREATE TABLE foo (id serial PRIMARY KEY);")
-            >>> pprint(conn.notices)
-            ['NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "foo_pkey" for table "foo"\n',
-             'NOTICE:  CREATE TABLE will create implicit sequence "foo_id_seq" for serial column "foo.id"\n']
-
-        .. versionchanged:: 2.7
-            The `!notices` attribute is writable: the user may replace it
-            with any Python object exposing an `!append()` method. If
-            appending raises an exception the notice is silently
-            dropped.
-
-        To avoid a leak in case excessive notices are generated, only the last
-        50 messages are kept. This check is only in place if the `!notices`
-        attribute is a list: if any other object is used it will be up to the
-        user to guard from leakage.
-
-        You can configure what messages to receive using `PostgreSQL logging
-        configuration parameters`__ such as ``log_statement``,
-        ``client_min_messages``, ``log_min_duration_statement`` etc.
-
-        .. __: https://www.postgresql.org/docs/current/static/runtime-config-logging.html
-
-
-    .. attribute:: notifies
-
-        List of `~psycopg2.extensions.Notify` objects containing asynchronous
-        notifications received by the session.
-
-        For other details see :ref:`async-notify`.
-
-        .. versionchanged:: 2.3
-            Notifications are instances of the `!Notify` object. Previously the
-            list was composed by 2 items tuples :samp:`({pid},{channel})` and
-            the payload was not accessible. To keep backward compatibility,
-            `!Notify` objects can still be accessed as 2 items tuples.
-
-        .. versionchanged:: 2.7
-            The `!notifies` attribute is writable: the user may replace it
-            with any Python object exposing an `!append()` method. If
-            appending raises an exception the notification is silently
-            dropped.
-
-
-    .. attribute:: cursor_factory
-
-        The default cursor factory used by `~connection.cursor()` if the
-        parameter is not specified.
-
-        .. versionadded:: 2.5
-
-
-    .. index::
-        pair: Connection; Info
-
-    .. attribute:: info
-
-        A `~psycopg2.extensions.ConnectionInfo` object exposing information
-        about the native libpq connection.
-
-        .. versionadded:: 2.8
-
-
-    .. index::
-        pair: Connection; Status
-
-    .. attribute:: status
-
-        A read-only integer representing the status of the connection.
-        Symbolic constants for the values are defined in the module
-        `psycopg2.extensions`: see :ref:`connection-status-constants`
-        for the available values.
-
-        The status is undefined for `closed` connections.
-
-
-    .. method:: lobject([oid [, mode [, new_oid [, new_file [, lobject_factory]]]]])
-
-        Return a new database large object as a `~psycopg2.extensions.lobject`
-        instance.
-
-        See :ref:`large-objects` for an overview.
-
-        :param oid: The OID of the object to read or write. 0 to create
-            a new large object and and have its OID assigned automatically.
-        :param mode: Access mode to the object, see below.
-        :param new_oid: Create a new object using the specified OID. The
-            function raises `~psycopg2.OperationalError` if the OID is already
-            in use. Default is 0, meaning assign a new one automatically.
-        :param new_file: The name of a file to be imported in the database
-            (using the |lo_import|_ function)
-        :param lobject_factory: Subclass of
-            `~psycopg2.extensions.lobject` to be instantiated.
-
-        .. |lo_import| replace:: `!lo_import()`
-        .. _lo_import: https://www.postgresql.org/docs/current/static/lo-interfaces.html#LO-IMPORT
-
-        Available values for *mode* are:
-
-        ======= =========
-        *mode*  meaning
-        ======= =========
-        ``r``   Open for read only
-        ``w``   Open for write only
-        ``rw``  Open for read/write
-        ``n``   Don't open the file
-        ``b``   Don't decode read data (return data as `!str` in Python 2 or `!bytes` in Python 3)
-        ``t``   Decode read data according to `connection.encoding` (return data as `!unicode` in Python 2 or `!str` in Python 3)
-        ======= =========
-
-        ``b`` and ``t`` can be specified together with a read/write mode. If
-        neither ``b`` nor ``t`` is specified, the default is ``b`` in Python 2
-        and ``t`` in Python 3.
-
-        .. versionadded:: 2.0.8
-
-        .. versionchanged:: 2.4 added ``b`` and ``t`` mode and unicode
-            support.
-
-
-    .. rubric:: Methods related to asynchronous support
-
-    .. versionadded:: 2.2
-
-    .. seealso:: :ref:`async-support` and :ref:`green-support`.
-
-
-    .. attribute:: async
-                   async_
-
-        Read only attribute: 1 if the connection is asynchronous, 0 otherwise.
-
-        .. versionchanged:: 2.7 added the `!async_` alias for Python versions
-            where `!async` is a keyword.
-
-
-    .. method:: poll()
-
-        Used during an asynchronous connection attempt, or when a cursor is
-        executing a query on an asynchronous connection, make communication
-        proceed if it wouldn't block.
-
-        Return one of the constants defined in :ref:`poll-constants`. If it
-        returns `~psycopg2.extensions.POLL_OK` then the connection has been
-        established or the query results are available on the client.
-        Otherwise wait until the file descriptor returned by `fileno()` is
-        ready to read or to write, as explained in :ref:`async-support`.
-        `poll()` should be also used by the function installed by
-        `~psycopg2.extensions.set_wait_callback()` as explained in
-        :ref:`green-support`.
-
-        `poll()` is also used to receive asynchronous notifications from the
-        database: see :ref:`async-notify` from further details.
-
-
-    .. method:: fileno()
-
-        Return the file descriptor underlying the connection: useful to read
-        its status during asynchronous communication.
-
-
-    .. method:: isexecuting()
-
-        Return `!True` if the connection is executing an asynchronous operation.
-
-
-    .. rubric:: Interoperation with other C API modules
-
-    .. attribute:: pgconn_ptr
-
-        Return the internal `!PGconn*` as integer. Useful to pass the libpq
-        raw connection structure to C functions, e.g. via `ctypes`::
-
-            >>> import ctypes
-            >>> import ctypes.util
-            >>> libpq = ctypes.pydll.LoadLibrary(ctypes.util.find_library('pq'))
-            >>> libpq.PQserverVersion.argtypes = [ctypes.c_void_p]
-            >>> libpq.PQserverVersion.restype = ctypes.c_int
-            >>> libpq.PQserverVersion(conn.pgconn_ptr)
-            90611
-
-        .. versionadded:: 2.8
-
-
-    .. method:: get_native_connection()
-
-        Return the internal `!PGconn*` wrapped in a PyCapsule object. This is
-        only useful for passing the `libpq` raw connection associated to this
-        connection object to other C-level modules that may have a use for it.
-
-        .. seealso:: Python C API `Capsules`__  docs.
-
-            .. __: https://docs.python.org/3.1/c-api/capsule.html
-
-        .. versionadded:: 2.8
-
-
-
-    .. rubric:: informative methods of the native connection
-
-    .. note::
-
-        These methods are better accessed using the `~connection.info`
-        attributes and may be dropped in future versions.
-
-
-    .. index::
-        pair: Transaction; Status
-
-    .. method:: get_transaction_status()
-
-        Also available as `~connection.info`\ `!.`\
-        `~psycopg2.extensions.ConnectionInfo.transaction_status`.
-
-        Return the current session transaction status as an integer.  Symbolic
-        constants for the values are defined in the module
-        `psycopg2.extensions`: see :ref:`transaction-status-constants`
-        for the available values.
-
-        .. seealso:: libpq docs for `PQtransactionStatus()`__ for details.
-
-            .. __: https://www.postgresql.org/docs/current/static/libpq-status.html#LIBPQ-PQTRANSACTIONSTATUS
-
-
-    .. index::
-        pair: Protocol; Version
-
-    .. attribute:: protocol_version
-
-        Also available as `~connection.info`\ `!.`\
-        `~psycopg2.extensions.ConnectionInfo.protocol_version`.
-
-        A read-only integer representing frontend/backend protocol being used.
-        Currently Psycopg supports only protocol 3, which allows connection
-        to PostgreSQL server from version 7.4. Psycopg versions previous than
-        2.3 support both protocols 2 and 3.
-
-        .. seealso:: libpq docs for `PQprotocolVersion()`__ for details.
-
-            .. __: https://www.postgresql.org/docs/current/static/libpq-status.html#LIBPQ-PQPROTOCOLVERSION
-
-        .. versionadded:: 2.0.12
-
-
-    .. index::
-        pair: Server; Version
-
-    .. attribute:: server_version
-
-        Also available as `~connection.info`\ `!.`\
-        `~psycopg2.extensions.ConnectionInfo.server_version`.
-
-        A read-only integer representing the backend version.
-
-        The number is formed by converting the major, minor, and revision
-        numbers into two-decimal-digit numbers and appending them together.
-        For example, version 8.1.5 will be returned as ``80105``.
-
-        .. seealso:: libpq docs for `PQserverVersion()`__ for details.
-
-            .. __: https://www.postgresql.org/docs/current/static/libpq-status.html#LIBPQ-PQSERVERVERSION
-
-        .. versionadded:: 2.0.12
-
-
-    .. index::
-        pair: Backend; PID
-
-    .. method:: get_backend_pid()
-
-        Also available as `~connection.info`\ `!.`\
-        `~psycopg2.extensions.ConnectionInfo.backend_pid`.
-
-        Returns the process ID (PID) of the backend server process *you
-        connected to*. Note that if you use a connection pool service such as
-        PgBouncer_ this value will not be updated if your connection is
-        switched to a different backend.
-
-        Note that the PID belongs to a process executing on the database
-        server host, not the local host!
-
-        .. seealso:: libpq docs for `PQbackendPID()`__ for details.
-
-            .. __: https://www.postgresql.org/docs/current/static/libpq-status.html#LIBPQ-PQBACKENDPID
-
-        .. versionadded:: 2.0.8
-
-
-    .. index::
-        pair: Server; Parameters
-
-    .. method:: get_parameter_status(parameter)
-
-        Also available as `~connection.info`\ `!.`\
-        `~psycopg2.extensions.ConnectionInfo.parameter_status()`.
-
-        Look up a current parameter setting of the server.
-
-        Potential values for ``parameter`` are: ``server_version``,
-        ``server_encoding``, ``client_encoding``, ``is_superuser``,
-        ``session_authorization``, ``DateStyle``, ``TimeZone``,
-        ``integer_datetimes``, and ``standard_conforming_strings``.
-
-        If server did not report requested parameter, return `!None`.
-
-        .. seealso:: libpq docs for `PQparameterStatus()`__ for details.
-
-            .. __: https://www.postgresql.org/docs/current/static/libpq-status.html#LIBPQ-PQPARAMETERSTATUS
-
-        .. versionadded:: 2.0.12
-
-
-    .. index::
-        pair: Connection; Parameters
-
-    .. method:: get_dsn_parameters()
-
-        Also available as `~connection.info`\ `!.`\
-        `~psycopg2.extensions.ConnectionInfo.dsn_parameters`.
-
-        Get the effective dsn parameters for the connection as a dictionary.
-
-        The *password* parameter is removed from the result.
-
-        Example::
-
-            >>> conn.get_dsn_parameters()
-            {'dbname': 'test', 'user': 'postgres', 'port': '5432', 'sslmode': 'prefer'}
-
-        Requires libpq >= 9.3.
-
-        .. seealso:: libpq docs for `PQconninfo()`__ for details.
-
-            .. __: https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNINFO
-
-        .. versionadded:: 2.7
-
-
-.. testcode::
-    :hide:
-
-    conn.rollback()

doc/src/cursor.rst

@@ -1,682 +0,0 @@
-The ``cursor`` class
-====================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. testsetup:: *
-
-    from StringIO import StringIO
-    import sys
-
-    create_test_table()
-
-    # initial data
-    cur.executemany("INSERT INTO test (num, data) VALUES (%s, %s)",
-        [(100, "abc'def"), (None, 'dada'), (42, 'bar')])
-    conn.commit()
-
-
-.. class:: cursor
-
-    Allows Python code to execute PostgreSQL command in a database session.
-    Cursors are created by the `connection.cursor()` method: they are
-    bound to the connection for the entire lifetime and all the commands are
-    executed in the context of the database session wrapped by the connection.
-
-    Cursors created from the same connection are not isolated, i.e., any
-    changes done to the database by a cursor are immediately visible by the
-    other cursors. Cursors created from different connections can or can not
-    be isolated, depending on the connections' :ref:`isolation level
-    <transactions-control>`. See also `~connection.rollback()` and
-    `~connection.commit()` methods.
-
-    Cursors are *not* thread safe: a multithread application can create
-    many cursors from the same connection and should use each cursor from
-    a single thread. See :ref:`thread-safety` for details.
-
-    Cursors can be used as context managers: leaving the context will close
-    the cursor.
-
-    .. code:: python
-
-        with conn.cursor() as curs:
-            curs.execute(SQL)
-
-        # the cursor is now closed
-
-
-    .. attribute:: description
-
-        Read-only attribute describing the result of a query.  It is a
-        sequence of `~psycopg2.extensions.Column` instances, each one
-        describing one result column in order. The attribute is `!None` for
-        operations that do not return rows or if the cursor has not had an
-        operation invoked via the |execute*|_ methods yet.
-
-        For compatibility with the DB-API, every object can be unpacked as a
-        7-items sequence: the attributes retuned this way are the following.
-        For further details and other attributes available check the
-        `~psycopg2.extensions.Column` documentation.
-
-        0.  `~psycopg2.extensions.Column.name`: the name of the column returned.
-
-        1.  `~psycopg2.extensions.Column.type_code`: the PostgreSQL OID of the
-            column.
-
-        2.  `~psycopg2.extensions.Column.display_size`: the actual length of
-            the column in bytes.
-
-        3.  `~psycopg2.extensions.Column.internal_size`: the size in bytes of
-            the column associated to this column on the server.
-
-        4.  `~psycopg2.extensions.Column.precision`: total number of
-            significant digits in columns of type |NUMERIC|. `!None`
-            for other types.
-
-        5.  `~psycopg2.extensions.Column.scale`: count of decimal digits in
-            the fractional part in columns of type |NUMERIC|. `!None`
-            for other types.
-
-        6.  `~psycopg2.extensions.Column.null_ok`: always `!None` as not easy
-            to retrieve from the libpq.
-
-        .. versionchanged:: 2.4
-            if possible, columns descriptions are named tuple instead of
-            regular tuples.
-
-        .. versionchanged:: 2.8
-            columns descriptions are instances of `!Column`, exposing extra
-            attributes.
-
-        .. |NUMERIC| replace:: :sql:`NUMERIC`
-
-    .. method:: close()
-
-        Close the cursor now (rather than whenever `del` is executed).
-        The cursor will be unusable from this point forward; an
-        `~psycopg2.InterfaceError` will be raised if any operation is
-        attempted with the cursor.
-
-        .. versionchanged:: 2.5 if the cursor is used in a ``with`` statement,
-            the method is automatically called at the end of the ``with``
-            block.
-
-
-    .. attribute:: closed
-
-        Read-only boolean attribute: specifies if the cursor is closed
-        (`!True`) or not (`!False`).
-
-        .. extension::
-
-            The `closed` attribute is a Psycopg extension to the
-            |DBAPI|.
-
-        .. versionadded:: 2.0.7
-
-
-    .. attribute:: connection
-
-        Read-only attribute returning a reference to the `connection`
-        object on which the cursor was created.
-
-
-    .. attribute:: name
-
-        Read-only attribute containing the name of the cursor if it was
-        created as named cursor by `connection.cursor()`, or `!None` if
-        it is a client side cursor.  See :ref:`server-side-cursors`.
-
-        .. extension::
-
-            The `name` attribute is a Psycopg extension to the |DBAPI|.
-
-
-    .. attribute:: scrollable
-
-        Read/write attribute: specifies if a named cursor is declared
-        :sql:`SCROLL`, hence is capable to scroll backwards (using
-        `~cursor.scroll()`). If `!True`, the cursor can be scrolled backwards,
-        if `!False` it is never scrollable. If `!None` (default) the cursor
-        scroll option is not specified, usually but not always meaning no
-        backward scroll (see the |declare-notes|__).
-
-        .. |declare-notes| replace:: :sql:`DECLARE` notes
-        .. __: https://www.postgresql.org/docs/current/static/sql-declare.html#SQL-DECLARE-NOTES
-
-        .. note::
-
-            set the value before calling `~cursor.execute()` or use the
-            `connection.cursor()` *scrollable* parameter, otherwise the value
-            will have no effect.
-
-        .. versionadded:: 2.5
-
-        .. extension::
-
-            The `scrollable` attribute is a Psycopg extension to the |DBAPI|.
-
-
-    .. attribute:: withhold
-
-        Read/write attribute: specifies if a named cursor lifetime should
-        extend outside of the current transaction, i.e., it is possible to
-        fetch from the cursor even after a `connection.commit()` (but not after
-        a `connection.rollback()`).  See :ref:`server-side-cursors`
-
-        .. note::
-
-            set the value before calling `~cursor.execute()` or use the
-            `connection.cursor()` *withhold* parameter, otherwise the value
-            will have no effect.
-
-        .. versionadded:: 2.4.3
-
-        .. extension::
-
-            The `withhold` attribute is a Psycopg extension to the |DBAPI|.
-
-
-    .. |execute*| replace:: `execute*()`
-
-    .. _execute*:
-
-    .. rubric:: Commands execution methods
-
-
-    .. method:: execute(query, vars=None)
-
-        Execute a database operation (query or command).
-
-        Parameters may be provided as sequence or mapping and will be bound to
-        variables in the operation.  Variables are specified either with
-        positional (``%s``) or named (:samp:`%({name})s`) placeholders. See
-        :ref:`query-parameters`.
-
-        The method returns `!None`. If a query was executed, the returned
-        values can be retrieved using |fetch*|_ methods.
-
-
-    .. method:: executemany(query, vars_list)
-
-        Execute a database operation (query or command) against all parameter
-        tuples or mappings found in the sequence *vars_list*.
-
-        The function is mostly useful for commands that update the database:
-        any result set returned by the query is discarded.
-
-        Parameters are bounded to the query using the same rules described in
-        the `~cursor.execute()` method.
-
-        .. code:: python
-
-            >>> nums = ((1,), (5,), (10,))
-            >>> cur.executemany("INSERT INTO test (num) VALUES (%s)", nums)
-
-            >>> tuples = ((123, "foo"), (42, "bar"), (23, "baz"))
-            >>> cur.executemany("INSERT INTO test (num, data) VALUES (%s, %s)", tuples)
-
-        .. warning::
-            In its current implementation this method is not faster than
-            executing `~cursor.execute()` in a loop. For better performance
-            you can use the functions described in :ref:`fast-exec`.
-
-
-    .. method:: callproc(procname [, parameters])
-
-        Call a stored database procedure with the given name. The sequence of
-        parameters must contain one entry for each argument that the procedure
-        expects. Overloaded procedures are supported. Named parameters can be
-        used by supplying the parameters as a dictionary.
-
-        This function is, at present, not DBAPI-compliant. The return value is
-        supposed to consist of the sequence of parameters with modified output
-        and input/output parameters. In future versions, the DBAPI-compliant
-        return value may be implemented, but for now the function returns None.
-
-        The procedure may provide a result set as output. This is then made
-        available through the standard |fetch*|_ methods.
-
-        .. versionchanged:: 2.7
-          added support for named arguments.
-
-        .. note::
-
-            `!callproc()` can only be used with PostgreSQL functions__, not
-            with the procedures__ introduced in PostgreSQL 11, which require
-            the :sql:`CALL` statement to run. Please use a normal
-            `execute()` to run them.
-
-            .. __: https://www.postgresql.org/docs/current/sql-createfunction.html
-            .. __: https://www.postgresql.org/docs/current/sql-createprocedure.html
-
-    .. method:: mogrify(operation [, parameters])
-
-        Return a query string after arguments binding. The string returned is
-        exactly the one that would be sent to the database running the
-        `~cursor.execute()` method or similar.
-
-        The returned string is always a bytes string.
-
-            >>> cur.mogrify("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
-            "INSERT INTO test (num, data) VALUES (42, E'bar')"
-
-        .. extension::
-
-            The `mogrify()` method is a Psycopg extension to the |DBAPI|.
-
-    .. method:: setinputsizes(sizes)
-
-        This method is exposed in compliance with the |DBAPI|. It currently
-        does nothing but it is safe to call it.
-
-
-
-    .. |fetch*| replace:: `!fetch*()`
-
-    .. _fetch*:
-
-    .. rubric:: Results retrieval methods
-
-
-    The following methods are used to read data from the database after an
-    `~cursor.execute()` call.
-
-    .. _cursor-iterable:
-
-    .. note::
-
-        `cursor` objects are iterable, so, instead of calling
-        explicitly `~cursor.fetchone()` in a loop, the object itself can
-        be used:
-
-            >>> cur.execute("SELECT * FROM test;")
-            >>> for record in cur:
-            ...     print(record)
-            ...
-            (1, 100, "abc'def")
-            (2, None, 'dada')
-            (3, 42, 'bar')
-
-        .. versionchanged:: 2.4
-            iterating over a :ref:`named cursor <server-side-cursors>`
-            fetches `~cursor.itersize` records at time from the backend.
-            Previously only one record was fetched per roundtrip, resulting
-            in a large overhead.
-
-    .. method:: fetchone()
-
-        Fetch the next row of a query result set, returning a single tuple,
-        or `!None` when no more data is available:
-
-            >>> cur.execute("SELECT * FROM test WHERE id = %s", (3,))
-            >>> cur.fetchone()
-            (3, 42, 'bar')
-
-        A `~psycopg2.ProgrammingError` is raised if the previous call
-        to |execute*|_ did not produce any result set or no call was issued
-        yet.
-
-
-    .. method:: fetchmany([size=cursor.arraysize])
-
-        Fetch the next set of rows of a query result, returning a list of
-        tuples. An empty list is returned when no more rows are available.
-
-        The number of rows to fetch per call is specified by the parameter.
-        If it is not given, the cursor's `~cursor.arraysize` determines
-        the number of rows to be fetched. The method should try to fetch as
-        many rows as indicated by the size parameter. If this is not possible
-        due to the specified number of rows not being available, fewer rows
-        may be returned:
-
-            >>> cur.execute("SELECT * FROM test;")
-            >>> cur.fetchmany(2)
-            [(1, 100, "abc'def"), (2, None, 'dada')]
-            >>> cur.fetchmany(2)
-            [(3, 42, 'bar')]
-            >>> cur.fetchmany(2)
-            []
-
-        A `~psycopg2.ProgrammingError` is raised if the previous call to
-        |execute*|_ did not produce any result set or no call was issued yet.
-
-        Note there are performance considerations involved with the size
-        parameter.  For optimal performance, it is usually best to use the
-        `~cursor.arraysize` attribute.  If the size parameter is used,
-        then it is best for it to retain the same value from one
-        `fetchmany()` call to the next.
-
-
-    .. method:: fetchall()
-
-        Fetch all (remaining) rows of a query result, returning them as a list
-        of tuples.  An empty list is returned if there is no more record to
-        fetch.
-
-            >>> cur.execute("SELECT * FROM test;")
-            >>> cur.fetchall()
-            [(1, 100, "abc'def"), (2, None, 'dada'), (3, 42, 'bar')]
-
-        A `~psycopg2.ProgrammingError` is raised if the previous call to
-        |execute*|_ did not produce any result set or no call was issued yet.
-
-
-    .. method:: scroll(value [, mode='relative'])
-
-        Scroll the cursor in the result set to a new position according
-        to mode.
-
-        If `mode` is ``relative`` (default), value is taken as offset to
-        the current position in the result set, if set to ``absolute``,
-        value states an absolute target position.
-
-        If the scroll operation would leave the result set, a
-        `~psycopg2.ProgrammingError` is raised and the cursor position is
-        not changed.
-
-        .. note::
-
-            According to the |DBAPI|_, the exception raised for a cursor out
-            of bound should have been `!IndexError`.  The best option is
-            probably to catch both exceptions in your code::
-
-                try:
-                    cur.scroll(1000 * 1000)
-                except (ProgrammingError, IndexError), exc:
-                    deal_with_it(exc)
-
-        The method can be used both for client-side cursors and
-        :ref:`server-side cursors <server-side-cursors>`. Server-side cursors
-        can usually scroll backwards only if declared `~cursor.scrollable`.
-        Moving out-of-bound in a server-side cursor doesn't result in an
-        exception, if the backend doesn't raise any (Postgres doesn't tell us
-        in a reliable way if we went out of bound).
-
-
-    .. attribute:: arraysize
-
-        This read/write attribute specifies the number of rows to fetch at a
-        time with `~cursor.fetchmany()`. It defaults to 1 meaning to fetch
-        a single row at a time.
-
-
-    .. attribute:: itersize
-
-        Read/write attribute specifying the number of rows to fetch from the
-        backend at each network roundtrip during :ref:`iteration
-        <cursor-iterable>` on a :ref:`named cursor <server-side-cursors>`. The
-        default is 2000.
-
-        .. versionadded:: 2.4
-
-        .. extension::
-
-            The `itersize` attribute is a Psycopg extension to the |DBAPI|.
-
-
-    .. attribute:: rowcount
-
-        This read-only attribute specifies the number of rows that the last
-        |execute*|_ produced (for :abbr:`DQL (Data Query Language)` statements
-        like :sql:`SELECT`) or affected (for
-        :abbr:`DML (Data Manipulation Language)` statements like :sql:`UPDATE`
-        or :sql:`INSERT`).
-
-        The attribute is -1 in case no |execute*| has been performed on
-        the cursor or the row count of the last operation if it can't be
-        determined by the interface.
-
-        .. note::
-            The |DBAPI|_ interface reserves to redefine the latter case to
-            have the object return `!None` instead of -1 in future versions
-            of the specification.
-
-
-    .. attribute:: rownumber
-
-        This read-only attribute provides the current 0-based index of the
-        cursor in the result set or `!None` if the index cannot be
-        determined.
-
-        The index can be seen as index of the cursor in a sequence (the result
-        set). The next fetch operation will fetch the row indexed by
-        `rownumber` in that sequence.
-
-
-    .. index:: oid
-
-    .. attribute:: lastrowid
-
-        This read-only attribute provides the OID of the last row inserted
-        by the cursor. If the table wasn't created with OID support or the
-        last operation is not a single record insert, the attribute is set to
-        `!None`.
-
-        .. note::
-
-            PostgreSQL currently advices to not create OIDs on the tables and
-            the default for |CREATE-TABLE|__ is to not support them. The
-            |INSERT-RETURNING|__ syntax available from PostgreSQL 8.3 allows
-            more flexibility.
-
-        .. |CREATE-TABLE| replace:: :sql:`CREATE TABLE`
-        .. __: https://www.postgresql.org/docs/current/static/sql-createtable.html
-
-        .. |INSERT-RETURNING| replace:: :sql:`INSERT ... RETURNING`
-        .. __: https://www.postgresql.org/docs/current/static/sql-insert.html
-
-
-    .. attribute:: query
-
-        Read-only attribute containing the body of the last query sent to the
-        backend (including bound arguments) as bytes string. `!None` if no
-        query has been executed yet:
-
-            >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
-            >>> cur.query
-            "INSERT INTO test (num, data) VALUES (42, E'bar')"
-
-        .. extension::
-
-            The `query` attribute is a Psycopg extension to the |DBAPI|.
-
-
-    .. attribute:: statusmessage
-
-        Read-only attribute containing the message returned by the last
-        command:
-
-            >>> cur.execute("INSERT INTO test (num, data) VALUES (%s, %s)", (42, 'bar'))
-            >>> cur.statusmessage
-            'INSERT 0 1'
-
-        .. extension::
-
-            The `statusmessage` attribute is a Psycopg extension to the
-            |DBAPI|.
-
-
-    .. method:: cast(oid, s)
-
-        Convert a value from the PostgreSQL string representation to a Python
-        object.
-
-        Use the most specific of the typecasters registered by
-        `~psycopg2.extensions.register_type()`.
-
-        .. versionadded:: 2.4
-
-        .. extension::
-
-            The `cast()` method is a Psycopg extension to the |DBAPI|.
-
-
-    .. attribute:: tzinfo_factory
-
-        The time zone factory used to handle data types such as
-        :sql:`TIMESTAMP WITH TIME ZONE`.  It should be a `~datetime.tzinfo`
-        object.  Default is `datetime.timezone`.
-
-        .. versionchanged:: 2.9
-            previosly the default factory was `psycopg2.tz.FixedOffsetTimezone`.
-
-
-    .. method:: nextset()
-
-        This method is not supported (PostgreSQL does not have multiple data
-        sets) and will raise a `~psycopg2.NotSupportedError` exception.
-
-
-    .. method:: setoutputsize(size [, column])
-
-        This method is exposed in compliance with the |DBAPI|. It currently
-        does nothing but it is safe to call it.
-
-
-
-    .. rubric:: COPY-related methods
-
-    Efficiently copy data from file-like objects to the database and back. See
-    :ref:`copy` for an overview.
-
-    .. extension::
-
-        The :sql:`COPY` command is a PostgreSQL extension to the SQL standard.
-        As such, its support is a Psycopg extension to the |DBAPI|.
-
-    .. method:: copy_from(file, table, sep='\\t', null='\\\\N', size=8192, columns=None)
-
-        Read data *from* the file-like object *file* appending them to
-        the table named *table*.
-
-        :param file: file-like object to read data from.  It must have both
-            `!read()` and `!readline()` methods.
-        :param table: name of the table to copy data into.
-        :param sep: columns separator expected in the file. Defaults to a tab.
-        :param null: textual representation of :sql:`NULL` in the file.
-            The default is the two characters string ``\N``.
-        :param size: size of the buffer used to read from the file.
-        :param columns: iterable with name of the columns to import.
-            The length and types should match the content of the file to read.
-            If not specified, it is assumed that the entire table matches the
-            file structure.
-
-        Example::
-
-            >>> f = StringIO("42\tfoo\n74\tbar\n")
-            >>> cur.copy_from(f, 'test', columns=('num', 'data'))
-            >>> cur.execute("select * from test where id > 5;")
-            >>> cur.fetchall()
-            [(6, 42, 'foo'), (7, 74, 'bar')]
-
-        .. versionchanged:: 2.0.6
-            added the *columns* parameter.
-
-        .. versionchanged:: 2.4
-            data read from files implementing the `io.TextIOBase` interface
-            are encoded in the connection `~connection.encoding` when sent to
-            the backend.
-
-        .. versionchanged:: 2.9
-            the table and fields names are now quoted. If you need to specify
-            a schema-qualified table please use `copy_expert()`.
-
-
-    .. method:: copy_to(file, table, sep='\\t', null='\\\\N', columns=None)
-
-        Write the content of the table named *table* *to* the file-like
-        object *file*.  See :ref:`copy` for an overview.
-
-        :param file: file-like object to write data into.  It must have a
-            `!write()` method.
-        :param table: name of the table to copy data from.
-        :param sep: columns separator expected in the file. Defaults to a tab.
-        :param null: textual representation of :sql:`NULL` in the file.
-            The default is the two characters string ``\N``.
-        :param columns: iterable with name of the columns to export.
-            If not specified, export all the columns.
-
-        Example::
-
-            >>> cur.copy_to(sys.stdout, 'test', sep="|")
-            1|100|abc'def
-            2|\N|dada
-            ...
-
-        .. versionchanged:: 2.0.6
-            added the *columns* parameter.
-
-        .. versionchanged:: 2.4
-            data sent to files implementing the `io.TextIOBase` interface
-            are decoded in the connection `~connection.encoding` when read
-            from the backend.
-
-        .. versionchanged:: 2.9
-            the table and fields names are now quoted. If you need to specify
-            a schema-qualified table please use `copy_expert()`.
-
-
-    .. method:: copy_expert(sql, file, size=8192)
-
-        Submit a user-composed :sql:`COPY` statement. The method is useful to
-        handle all the parameters that PostgreSQL makes available (see
-        |COPY|__ command documentation).
-
-        :param sql: the :sql:`COPY` statement to execute.
-        :param file: a file-like object to read or write (according to *sql*).
-        :param size: size of the read buffer to be used in :sql:`COPY FROM`.
-
-        The *sql* statement should be in the form :samp:`COPY {table} TO
-        STDOUT` to export :samp:`{table}` to the *file* object passed as
-        argument or :samp:`COPY {table} FROM STDIN` to import the content of
-        the *file* object into :samp:`{table}`. If you need to compose a
-        :sql:`COPY` statement dynamically (because table, fields, or query
-        parameters are in Python variables) you may use the objects provided
-        by the `psycopg2.sql` module.
-
-        *file* must be a readable file-like object (as required by
-        `~cursor.copy_from()`) for *sql* statement :sql:`COPY ... FROM STDIN`
-        or a writable one (as required by `~cursor.copy_to()`) for :sql:`COPY
-        ... TO STDOUT`.
-
-        Example:
-
-            >>> cur.copy_expert("COPY test TO STDOUT WITH CSV HEADER", sys.stdout)
-            id,num,data
-            1,100,abc'def
-            2,,dada
-            ...
-
-        .. |COPY| replace:: :sql:`COPY`
-        .. __: https://www.postgresql.org/docs/current/static/sql-copy.html
-
-        .. versionadded:: 2.0.6
-
-        .. versionchanged:: 2.4
-            files implementing the `io.TextIOBase` interface are dealt with
-            using Unicode data instead of bytes.
-
-
-    .. rubric:: Interoperation with other C API modules
-
-    .. attribute:: pgresult_ptr
-
-        Return the cursor's internal `!PGresult*` as integer. Useful to pass
-        the libpq raw result structure to C functions, e.g. via `ctypes`::
-
-            >>> import ctypes
-            >>> libpq = ctypes.pydll.LoadLibrary(ctypes.util.find_library('pq'))
-            >>> libpq.PQcmdStatus.argtypes = [ctypes.c_void_p]
-            >>> libpq.PQcmdStatus.restype = ctypes.c_char_p
-
-            >>> curs.execute("select 'x'")
-            >>> libpq.PQcmdStatus(curs.pgresult_ptr)
-            b'SELECT 1'
-
-        .. versionadded:: 2.8
-
-.. testcode::
-    :hide:
-
-    conn.rollback()

doc/src/errorcodes.rst

@@ -1,76 +0,0 @@
-`psycopg2.errorcodes` -- Error codes defined by PostgreSQL
-===============================================================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. index::
-    single: Error; Codes
-
-.. module:: psycopg2.errorcodes
-
-.. testsetup:: *
-
-    from psycopg2 import errorcodes
-
-.. versionadded:: 2.0.6
-
-This module contains symbolic names for all PostgreSQL error codes and error
-classes codes.  Subclasses of `~psycopg2.Error` make the PostgreSQL error
-code available in the `~psycopg2.Error.pgcode` attribute.
-
-From PostgreSQL documentation:
-
-    All messages emitted by the PostgreSQL server are assigned five-character
-    error codes that follow the SQL standard's conventions for :sql:`SQLSTATE`
-    codes.  Applications that need to know which error condition has occurred
-    should usually test the error code, rather than looking at the textual
-    error message.  The error codes are less likely to change across
-    PostgreSQL releases, and also are not subject to change due to
-    localization of error messages. Note that some, but not all, of the error
-    codes produced by PostgreSQL are defined by the SQL standard; some
-    additional error codes for conditions not defined by the standard have
-    been invented or borrowed from other databases.
-
-    According to the standard, the first two characters of an error code
-    denote a class of errors, while the last three characters indicate a
-    specific condition within that class. Thus, an application that does not
-    recognize the specific error code can still be able to infer what to do
-    from the error class.
-
-.. seealso:: `PostgreSQL Error Codes table`__
-
-    .. __: https://www.postgresql.org/docs/current/static/errcodes-appendix.html#ERRCODES-TABLE
-
-
-An example of the available constants defined in the module:
-
-    >>> errorcodes.CLASS_SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION
-    '42'
-    >>> errorcodes.UNDEFINED_TABLE
-    '42P01'
-
-Constants representing all the error values defined by PostgreSQL versions
-between 8.1 and 15 are included in the module.
-
-
-.. autofunction:: lookup(code)
-
-    .. doctest::
-
-        >>> try:
-        ...     cur.execute("SELECT ouch FROM aargh;")
-        ... except Exception as e:
-        ...     pass
-        ...
-        >>> errorcodes.lookup(e.pgcode[:2])
-        'CLASS_SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION'
-        >>> errorcodes.lookup(e.pgcode)
-        'UNDEFINED_TABLE'
-
-    .. versionadded:: 2.0.14
-
-
-.. testcode::
-    :hide:
-
-    conn.rollback()

doc/src/errors.rst

@@ -1,89 +0,0 @@
-`psycopg2.errors` -- Exception classes mapping PostgreSQL errors
-================================================================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. index::
-    single: Error; Class
-
-.. module:: psycopg2.errors
-
-.. versionadded:: 2.8
-
-.. versionchanged:: 2.8.4 added errors introduced in PostgreSQL 12
-
-.. versionchanged:: 2.8.6 added errors introduced in PostgreSQL 13
-
-.. versionchanged:: 2.9.2 added errors introduced in PostgreSQL 14
-
-.. versionchanged:: 2.9.4 added errors introduced in PostgreSQL 15
-
-.. versionchanged:: 2.9.10 added errors introduced in PostgreSQL 17
-
-This module exposes the classes psycopg raises upon receiving an error from
-the database with a :sql:`SQLSTATE` value attached (available in the
-`~psycopg2.Error.pgcode` attribute). The content of the module is generated
-from the PostgreSQL source code and includes classes for every error defined
-by PostgreSQL in versions between 9.1 and 15.
-
-Every class in the module is named after what referred as "condition name" `in
-the documentation`__, converted to CamelCase: e.g. the error 22012,
-``division_by_zero`` is exposed by this module as the class `!DivisionByZero`.
-
-.. __: https://www.postgresql.org/docs/current/static/errcodes-appendix.html#ERRCODES-TABLE
-
-Every exception class is a subclass of one of the :ref:`standard DB-API
-exception <dbapi-exceptions>` and expose the `~psycopg2.Error` interface.
-Each class' superclass is what used to be raised by psycopg in versions before
-the introduction of this module, so everything should be compatible with
-previously written code catching one the DB-API class: if your code used to
-catch `!IntegrityError` to detect a duplicate entry, it will keep on working
-even if a more specialised subclass such as `UniqueViolation` is raised.
-
-The new classes allow a more idiomatic way to check and process a specific
-error among the many the database may return. For instance, in order to check
-that a table is locked, the following code could have been used previously:
-
-.. code-block:: python
-
-    try:
-        cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
-    except psycopg2.OperationalError as e:
-        if e.pgcode == psycopg2.errorcodes.LOCK_NOT_AVAILABLE:
-            locked = True
-        else:
-            raise
-
-While this method is still available, the specialised class allows for a more
-idiomatic error handler:
-
-.. code-block:: python
-
-    try:
-        cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
-    except psycopg2.errors.LockNotAvailable:
-        locked = True
-
-
-.. autofunction:: lookup
-
-    .. code-block:: python
-
-        try:
-            cur.execute("LOCK TABLE mytable IN ACCESS EXCLUSIVE MODE NOWAIT")
-        except psycopg2.errors.lookup("55P03"):
-            locked = True
-
-
-SQLSTATE exception classes
---------------------------
-
-The following table contains the list of all the SQLSTATE classes exposed by
-the module.
-
-Note that, for completeness, the module also exposes all the
-:ref:`DB-API-defined exceptions <dbapi-exceptions>` and :ref:`a few
-psycopg-specific ones <extension-exceptions>` exposed by the `!extensions`
-module, which are not listed here.
-
-.. include:: sqlstate_errors.rst

doc/src/faq.rst

@@ -1,382 +0,0 @@
-Frequently Asked Questions
-==========================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-Here are a few gotchas you may encounter using `psycopg2`.  Feel free to
-suggest new entries!
-
-
-Meta
-----
-
-.. _faq-question:
-.. cssclass:: faq
-
-How do I ask a question?
-    - Have you first checked if your question is answered already in the
-      documentation?
-
-    - If your question is about installing psycopg, have you checked the
-      :ref:`install FAQ <faq-compile>` and the :ref:`install docs
-      <installation>`?
-
-    - Have you googled for your error message?
-
-    - If you haven't found an answer yet, please write to the `Mailing List`_.
-
-    - If you haven't found a bug, DO NOT write to the bug tracker to ask
-      questions. You will only get piro grumpy.
-
-    .. _mailing list: https://www.postgresql.org/list/psycopg/
-
-
-.. _faq-transactions:
-
-Problems with transactions handling
------------------------------------
-
-.. _faq-idle-in-transaction:
-.. cssclass:: faq
-
-Why does `!psycopg2` leave database sessions "idle in transaction"?
-    Psycopg normally starts a new transaction the first time a query is
-    executed, e.g. calling `cursor.execute()`, even if the command is a
-    :sql:`SELECT`.  The transaction is not closed until an explicit
-    `~connection.commit()` or `~connection.rollback()`.
-
-    If you are writing a long-living program, you should probably make sure to
-    call one of the transaction closing methods before leaving the connection
-    unused for a long time (which may also be a few seconds, depending on the
-    concurrency level in your database).  Alternatively you can use a
-    connection in `~connection.autocommit` mode to avoid a new transaction to
-    be started at the first command.
-
-
-.. _faq-transaction-aborted:
-.. cssclass:: faq
-
-I receive the error *current transaction is aborted, commands ignored until end of transaction block* and can't do anything else!
-    There was a problem *in the previous* command to the database, which
-    resulted in an error.  The database will not recover automatically from
-    this condition: you must run a `~connection.rollback()` before sending
-    new commands to the session (if this seems too harsh, remember that
-    PostgreSQL supports nested transactions using the |SAVEPOINT|_ command).
-
-    .. |SAVEPOINT| replace:: :sql:`SAVEPOINT`
-    .. _SAVEPOINT: https://www.postgresql.org/docs/current/static/sql-savepoint.html
-
-
-.. _faq-transaction-aborted-multiprocess:
-.. cssclass:: faq
-
-Why do I get the error *current transaction is aborted, commands ignored until end of transaction block* when I use `!multiprocessing` (or any other forking system) and not when use `!threading`?
-    Psycopg's connections can't be shared across processes (but are thread
-    safe).  If you are forking the Python process make sure to create a new
-    connection in each forked child. See :ref:`thread-safety` for further
-    informations.
-
-
-.. _faq-types:
-
-Problems with type conversions
-------------------------------
-
-.. _faq-cant-adapt:
-.. cssclass:: faq
-
-Why does `!cursor.execute()` raise the exception *can't adapt*?
-    Psycopg converts Python objects in a SQL string representation by looking
-    at the object class.  The exception is raised when you are trying to pass
-    as query parameter an object for which there is no adapter registered for
-    its class.  See :ref:`adapting-new-types` for informations.
-
-
-.. _faq-number-required:
-.. cssclass:: faq
-
-I can't pass an integer or a float parameter to my query: it says *a number is required*, but *it is* a number!
-    In your query string, you always have to use ``%s``  placeholders,
-    even when passing a number.  All Python objects are converted by Psycopg
-    in their SQL representation, so they get passed to the query as strings.
-    See :ref:`query-parameters`. ::
-
-        >>> cur.execute("INSERT INTO numbers VALUES (%d)", (42,)) # WRONG
-        >>> cur.execute("INSERT INTO numbers VALUES (%s)", (42,)) # correct
-
-
-.. _faq-not-all-arguments-converted:
-.. cssclass:: faq
-
-I try to execute a query but it fails with the error *not all arguments converted during string formatting* (or *object does not support indexing*). Why?
-    Psycopg always require positional arguments to be passed as a sequence, even
-    when the query takes a single parameter.  And remember that to make a
-    single item tuple in Python you need a comma!  See :ref:`query-parameters`.
-    ::
-
-        >>> cur.execute("INSERT INTO foo VALUES (%s)", "bar")    # WRONG
-        >>> cur.execute("INSERT INTO foo VALUES (%s)", ("bar"))  # WRONG
-        >>> cur.execute("INSERT INTO foo VALUES (%s)", ("bar",)) # correct
-        >>> cur.execute("INSERT INTO foo VALUES (%s)", ["bar"])  # correct
-
-
-.. _faq-unicode:
-.. cssclass:: faq
-
-My database is Unicode, but I receive all the strings as UTF-8 `!str`. Can I receive `!unicode` objects instead?
-    The following magic formula will do the trick::
-
-        psycopg2.extensions.register_type(psycopg2.extensions.UNICODE)
-        psycopg2.extensions.register_type(psycopg2.extensions.UNICODEARRAY)
-
-    See :ref:`unicode-handling` for the gory details.
-
-
-.. _faq-bytes:
-.. cssclass:: faq
-
-My database is in mixed encoding. My program was working on Python 2 but Python 3 fails decoding the strings. How do I avoid decoding?
-    From psycopg 2.8 you can use the following adapters to always return bytes
-    from strings::
-
-        psycopg2.extensions.register_type(psycopg2.extensions.BYTES)
-        psycopg2.extensions.register_type(psycopg2.extensions.BYTESARRAY)
-
-    See :ref:`unicode-handling` for an example.
-
-
-.. _faq-float:
-.. cssclass:: faq
-
-Psycopg converts :sql:`decimal`\/\ :sql:`numeric` database types into Python `!Decimal` objects. Can I have `!float` instead?
-    You can register a customized adapter for PostgreSQL decimal type::
-
-        DEC2FLOAT = psycopg2.extensions.new_type(
-            psycopg2.extensions.DECIMAL.values,
-            'DEC2FLOAT',
-            lambda value, curs: float(value) if value is not None else None)
-        psycopg2.extensions.register_type(DEC2FLOAT)
-
-    See :ref:`type-casting-from-sql-to-python` to read the relevant
-    documentation. If you find `!psycopg2.extensions.DECIMAL` not available, use
-    `!psycopg2._psycopg.DECIMAL` instead.
-
-
-.. _faq-json-adapt:
-.. cssclass:: faq
-
-Psycopg automatically converts PostgreSQL :sql:`json` data into Python objects. How can I receive strings instead?
-    The easiest way to avoid JSON parsing is to register a no-op function with
-    `~psycopg2.extras.register_default_json()`::
-
-        psycopg2.extras.register_default_json(loads=lambda x: x)
-
-    See :ref:`adapt-json` for further details.
-
-
-.. _faq-jsonb-adapt:
-.. cssclass:: faq
-
-Psycopg converts :sql:`json` values into Python objects but :sql:`jsonb` values are returned as strings. Can :sql:`jsonb` be converted automatically?
-    Automatic conversion of :sql:`jsonb` values is supported from Psycopg
-    release 2.5.4. For previous versions you can register the :sql:`json`
-    typecaster on the :sql:`jsonb` oids (which are known and not supposed to
-    change in future PostgreSQL versions)::
-
-        psycopg2.extras.register_json(oid=3802, array_oid=3807, globally=True)
-
-    See :ref:`adapt-json` for further details.
-
-
-.. _faq-identifier:
-.. cssclass:: faq
-
-How can I pass field/table names to a query?
-    The arguments in the `~cursor.execute()` methods can only represent data
-    to pass to the query: they cannot represent a table or field name::
-
-        # This doesn't work
-        cur.execute("insert into %s values (%s)", ["my_table", 42])
-
-    If you want to build a query dynamically you can use the objects exposed
-    by the `psycopg2.sql` module::
-
-        cur.execute(
-            sql.SQL("insert into %s values (%%s)") % [sql.Identifier("my_table")],
-            [42])
-
-
-.. _faq-bytea-9.0:
-.. cssclass:: faq
-
-Transferring binary data from PostgreSQL 9.0 doesn't work.
-    PostgreSQL 9.0 uses by default `the "hex" format`__ to transfer
-    :sql:`bytea` data: the format can't be parsed by the libpq 8.4 and
-    earlier. The problem is solved in Psycopg 2.4.1, that uses its own parser
-    for the :sql:`bytea` format. For previous Psycopg releases, three options
-    to solve the problem are:
-
-    - set the bytea_output__ parameter to ``escape`` in the server;
-    - execute the database command ``SET bytea_output TO escape;`` in the
-      session before reading binary data;
-    - upgrade the libpq library on the client to at least 9.0.
-
-    .. __: https://www.postgresql.org/docs/current/static/datatype-binary.html
-    .. __: https://www.postgresql.org/docs/current/static/runtime-config-client.html#GUC-BYTEA-OUTPUT
-
-
-.. _faq-array:
-.. cssclass:: faq
-
-Arrays of *TYPE* are not casted to list.
-    Arrays are only casted to list when their oid is known, and an array
-    typecaster is registered for them. If there is no typecaster, the array is
-    returned unparsed from PostgreSQL (e.g. ``{a,b,c}``). It is easy to create
-    a generic arrays typecaster, returning a list of array: an example is
-    provided in the `~psycopg2.extensions.new_array_type()` documentation.
-
-
-.. _faq-best-practices:
-
-Best practices
---------------
-
-.. _faq-reuse-cursors:
-.. cssclass:: faq
-
-When should I save and re-use a cursor as opposed to creating a new one as needed?
-    Cursors are lightweight objects and creating lots of them should not pose
-    any kind of problem. But note that cursors used to fetch result sets will
-    cache the data and use memory in proportion to the result set size. Our
-    suggestion is to almost always create a new cursor and dispose old ones as
-    soon as the data is not required anymore (call `~cursor.close()` on
-    them.) The only exception are tight loops where one usually use the same
-    cursor for a whole bunch of :sql:`INSERT`\s or :sql:`UPDATE`\s.
-
-
-.. _faq-reuse-connections:
-.. cssclass:: faq
-
-When should I save and re-use a connection as opposed to creating a new one as needed?
-    Creating a connection can be slow (think of SSL over TCP) so the best
-    practice is to create a single connection and keep it open as long as
-    required. It is also good practice to rollback or commit frequently (even
-    after a single :sql:`SELECT` statement) to make sure the backend is never
-    left "idle in transaction".  See also `psycopg2.pool` for lightweight
-    connection pooling.
-
-
-.. _faq-named-cursors:
-.. cssclass:: faq
-
-What are the advantages or disadvantages of using named cursors?
-    The only disadvantages is that they use up resources on the server and
-    that there is a little overhead because at least two queries (one to
-    create the cursor and one to fetch the initial result set) are issued to
-    the backend. The advantage is that data is fetched one chunk at a time:
-    using small `~cursor.fetchmany()` values it is possible to use very
-    little memory on the client and to skip or discard parts of the result set.
-
-
-.. _faq-interrupt-query:
-.. cssclass:: faq
-
-How do I interrupt a long-running query in an interactive shell?
-    Normally the interactive shell becomes unresponsive to :kbd:`Ctrl-C` when
-    running a query. Using a connection in green mode allows Python to
-    receive and handle the interrupt, although it may leave the connection
-    broken, if the async callback doesn't handle the `!KeyboardInterrupt`
-    correctly.
-
-    Starting from psycopg 2.6.2, the `~psycopg2.extras.wait_select` callback
-    can handle a :kbd:`Ctrl-C` correctly. For previous versions, you can use
-    `this implementation`__.
-
-    .. __: https://www.psycopg.org/articles/2014/07/20/cancelling-postgresql-statements-python/
-
-    .. code-block:: pycon
-
-        >>> psycopg2.extensions.set_wait_callback(psycopg2.extras.wait_select)
-        >>> cnn = psycopg2.connect('')
-        >>> cur = cnn.cursor()
-        >>> cur.execute("select pg_sleep(10)")
-        ^C
-        Traceback (most recent call last):
-          File "<stdin>", line 1, in <module>
-          QueryCanceledError: canceling statement due to user request
-
-        >>> cnn.rollback()
-        >>> # You can use the connection and cursor again from here
-
-
-.. _faq-compile:
-
-Problems compiling and installing psycopg2
-------------------------------------------
-
-.. _faq-wheels:
-.. cssclass:: faq
-
-Psycopg 2.8 fails to install, Psycopg 2.7 was working fine.
-    With Psycopg 2.7 you were installing binary packages, but they have proven
-    unreliable so now you have to install them explicitly using the
-    ``psycopg2-binary`` package. See :ref:`binary-packages` for all the
-    details.
-
-.. _faq-python-h:
-.. cssclass:: faq
-
-I can't compile `!psycopg2`: the compiler says *error: Python.h: No such file or directory*. What am I missing?
-    You need to install a Python development package: it is usually called
-    ``python-dev`` or ``python3-dev`` according to your Python version.
-
-
-.. _faq-libpq-fe-h:
-.. cssclass:: faq
-
-I can't compile `!psycopg2`: the compiler says *error: libpq-fe.h: No such file or directory*. What am I missing?
-    You need to install the development version of the libpq: the package is
-    usually called ``libpq-dev``.
-
-
-.. _faq-lo_truncate:
-.. cssclass:: faq
-
-`!psycopg2` raises `!ImportError` with message *_psycopg.so: undefined symbol: lo_truncate* when imported.
-    This means that Psycopg was compiled with |lo_truncate|_ support (*i.e.*
-    the libpq used at compile time was version >= 8.3) but at runtime an older
-    libpq dynamic library is found.
-
-    Fast-forward several years, if the message reports *undefined symbol:
-    lo_truncate64* it means that Psycopg was built with large objects 64 bits
-    API support (*i.e.* the libpq used at compile time was at least 9.3) but
-    at runtime an older libpq dynamic library is found.
-
-    You can use:
-
-    .. code-block:: shell
-
-        $ ldd /path/to/packages/psycopg2/_psycopg.so | grep libpq
-
-    to find what is the libpq dynamic library used at runtime.
-
-    You can avoid the problem by using the same version of the
-    :program:`pg_config` at install time and the libpq at runtime.
-
-    .. |lo_truncate| replace:: `!lo_truncate()`
-    .. _lo_truncate: https://www.postgresql.org/docs/current/static/lo-interfaces.html#LO-TRUNCATE
-
-
-.. _faq-import-mod_wsgi:
-.. cssclass:: faq
-
-Psycopg raises *ImportError: cannot import name tz* on import in mod_wsgi / ASP, but it works fine otherwise.
-    If `!psycopg2` is installed in an egg_ (e.g. because installed by
-    :program:`easy_install`), the user running the program may be unable to
-    write in the `eggs cache`__. Set the env variable
-    :envvar:`PYTHON_EGG_CACHE` to a writable directory. With modwsgi you can
-    use the WSGIPythonEggs__ directive.
-
-    .. _egg: http://peak.telecommunity.com/DevCenter/PythonEggs
-    .. __: https://stackoverflow.com/questions/2192323/what-is-the-python-egg-cache-python-egg-cache
-    .. __: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIPythonEggs.html

doc/src/index.rst

@@ -1,70 +0,0 @@
-=================================================
-Psycopg -- PostgreSQL database adapter for Python
-=================================================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-Psycopg_ is the most popular PostgreSQL_ database adapter for the Python_
-programming language.  Its main features are the complete implementation of
-the Python |DBAPI|_ specification and the thread safety (several threads can
-share the same connection). It was designed for heavily multi-threaded
-applications that create and destroy lots of cursors and make a large number
-of concurrent :sql:`INSERT`\s or :sql:`UPDATE`\s.
-
-Psycopg 2 is mostly implemented in C as a libpq_ wrapper, resulting in being
-both efficient and secure. It features client-side and :ref:`server-side
-<server-side-cursors>` cursors, :ref:`asynchronous communication
-<async-support>` and :ref:`notifications <async-notify>`, :ref:`COPY <copy>`
-support.  Many Python types are supported out-of-the-box and :ref:`adapted to
-matching PostgreSQL data types <python-types-adaptation>`; adaptation can be
-extended and customized thanks to a flexible :ref:`objects adaptation system
-<adapting-new-types>`.
-
-Psycopg 2 is both Unicode and Python 3 friendly.
-
-
-.. _Psycopg: https://psycopg.org/
-.. _PostgreSQL: https://www.postgresql.org/
-.. _Python: https://www.python.org/
-.. _libpq: https://www.postgresql.org/docs/current/static/libpq.html
-
-
-.. rubric:: Contents
-
-.. toctree::
-   :maxdepth: 2
-
-   install
-   usage
-   module
-   connection
-   cursor
-   advanced
-   extensions
-   extras
-   errors
-   sql
-   tz
-   pool
-   errorcodes
-   faq
-   news
-   license
-
-
-.. ifconfig:: builder != 'text'
-
-    .. rubric:: Indices and tables
-
-    * :ref:`genindex`
-    * :ref:`modindex`
-    * :ref:`search`
-
-
-.. ifconfig:: todo_include_todos
-
-    .. note::
-
-        **To Do items in the documentation**
-
-        .. todolist::

doc/src/install.rst

@@ -1,364 +0,0 @@
-.. _installation:
-
-Installation
-============
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-Psycopg is a PostgreSQL_ adapter for the Python_ programming language. It is a
-wrapper for the libpq_, the official PostgreSQL client library.
-
-.. _PostgreSQL: https://www.postgresql.org/
-.. _Python: https://www.python.org/
-
-
-.. 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 use
-an up-to-date version of :program:`pip` (you can upgrade it using something
-like ``pip install -U pip``).
-
-You may then import the ``psycopg2`` package, as usual:
-
-.. code-block:: python
-
-    import psycopg2
-
-    # Connect to your postgres DB
-    conn = psycopg2.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: 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 <build-prerequisites>`.
-
-
-.. index::
-    single: Prerequisites
-
-Prerequisites
--------------
-
-The current `!psycopg2` implementation supports:
-
-..
-    NOTE: keep consistent with setup.py and the /features/ page.
-
-- Python versions from 3.8 to 3.13
-- PostgreSQL server versions from 7.4 to 17
-- PostgreSQL client library version from 9.1
-
-.. note::
-
-    Not all the psycopg2 versions support all the supported Python versions.
-
-    Please see the :ref:`release notes <news>` to verify when the support for
-    a new Python version was added and when the support for an old Python
-    version was removed.
-
-
-.. _build-prerequisites:
-
-Build prerequisites
-^^^^^^^^^^^^^^^^^^^
-
-The build prerequisites are to be met in order to install Psycopg from source
-code, from a source distribution package, GitHub_ or from PyPI.
-
-.. _GitHub: https://github.com/psycopg/psycopg2
-
-Psycopg is a C wrapper around 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** or **python3-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`:
-
-  .. code-block:: console
-
-    $ export PATH=/usr/lib/postgresql/X.Y/bin/:$PATH
-
-  You only need :program:`pg_config` to compile `!psycopg2`, not for its
-  regular usage.
-
-Once everything is in place it's just a matter of running the standard:
-
-.. code-block:: console
-
-    $ pip install psycopg2
-
-or, from the directory containing the source code:
-
-.. code-block:: console
-
-    $ python setup.py build
-    $ python setup.py install
-
-
-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 Psycopg how to find it,
-which is OS-dependent (for instance setting a suitable
-:envvar:`LD_LIBRARY_PATH` on Linux).
-
-.. 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``.
-
-.. 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: setup.py
-    single: setup.cfg
-
-Non-standard builds
--------------------
-
-If you have less standard requirements such as:
-
-- creating a :ref:`debug build <debug-build>`,
-- using :program:`pg_config` not in the :envvar:`PATH`,
-
-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` location using:
-
-.. code-block:: console
-
-    $ 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.
-
-
-.. 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* (the ``.tar.gz``
-  package).
-
-- Edit the ``setup.cfg`` file adding the ``PSYCOPG_DEBUG`` flag to the
-  ``define`` option.
-
-- :ref:`Compile and install <build-prerequisites>` the package.
-
-- Set the :envvar:`PSYCOPG_DEBUG` environment variable:
-
-.. code-block:: console
-
-    $ 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 stderr.
-
-.. __: 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
-
-.. _test-suite:
-
-Running the test suite
-----------------------
-
-Once `!psycopg2` is installed you can run the test suite to verify it is
-working correctly. From the source directory, you can run:
-
-.. code-block:: console
-
-    $ python -c "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
---------------------------
-
-Try the following. *In order:*
-
-- Read again the :ref:`build-prerequisites`.
-
-- Read the :ref:`FAQ <faq-compile>`.
-
-- Google for `!psycopg2` *your error message*. Especially useful the week
-  after the release of a new OS X version.
-
-- Write to the `Mailing List`_.
-
-- If you think that you have discovered a bug, test failure or missing feature
-  please raise a ticket in the `bug tracker`_.
-
-- 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.
-
-.. _mailing list: https://www.postgresql.org/list/psycopg/
-.. _bug tracker: https://github.com/psycopg/psycopg2/issues

doc/src/license.rst

@@ -1,7 +0,0 @@
-.. index::
-    single: License
-
-License
-=======
-
-.. include:: ../../LICENSE

doc/src/module.rst

@@ -1,388 +0,0 @@
-The `psycopg2` module content
-==================================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. module:: psycopg2
-
-The module interface respects the standard defined in the |DBAPI|_.
-
-.. index::
-    single: Connection string
-    double: Connection; Parameters
-    single: Username; Connection
-    single: Password; Connection
-    single: Host; Connection
-    single: Port; Connection
-    single: DSN (Database Source Name)
-
-.. function::
-    connect(dsn=None, connection_factory=None, cursor_factory=None, async=False, \*\*kwargs)
-
-    Create a new database session and return a new `connection` object.
-
-    The connection parameters can be specified as a `libpq connection
-    string`__ using the *dsn* parameter::
-
-        conn = psycopg2.connect("dbname=test user=postgres password=secret")
-
-    or using a set of keyword arguments::
-
-        conn = psycopg2.connect(dbname="test", user="postgres", password="secret")
-
-    or using a mix of both: if the same parameter name is specified in both
-    sources, the *kwargs* value will have precedence over the *dsn* value.
-    Note that either the *dsn* or at least one connection-related keyword
-    argument is required.
-
-    The basic connection parameters are:
-
-    - `!dbname` -- the database name (`!database` is a deprecated alias)
-    - `!user` -- user name used to authenticate
-    - `!password` -- password used to authenticate
-    - `!host` -- database host address (defaults to UNIX socket if not provided)
-    - `!port` -- connection port number (defaults to 5432 if not provided)
-
-    Any other connection parameter supported by the client library/server can
-    be passed either in the connection string or as a keyword. The PostgreSQL
-    documentation contains the complete list of the `supported parameters`__.
-    Also note that the same parameters can be passed to the client library
-    using `environment variables`__.
-
-    .. __:
-    .. _connstring: https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
-    .. __:
-    .. _connparams: https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PARAMKEYWORDS
-    .. __:
-    .. _connenvvars: https://www.postgresql.org/docs/current/static/libpq-envars.html
-
-    Using the *connection_factory* parameter a different class or
-    connections factory can be specified. It should be a callable object
-    taking a *dsn* string argument. See :ref:`subclassing-connection` for
-    details.  If a *cursor_factory* is specified, the connection's
-    `~connection.cursor_factory` is set to it. If you only need customized
-    cursors you can use this parameter instead of subclassing a connection.
-
-    Using *async*\=\ `!True` an asynchronous connection will be created: see
-    :ref:`async-support` to know about advantages and limitations. *async_* is
-    a valid alias for the Python version where ``async`` is a keyword.
-
-    .. versionchanged:: 2.4.3
-        any keyword argument is passed to the connection. Previously only the
-        basic parameters (plus `!sslmode`) were supported as keywords.
-
-    .. versionchanged:: 2.5
-        added the *cursor_factory* parameter.
-
-    .. versionchanged:: 2.7
-        both *dsn* and keyword arguments can be specified.
-
-    .. versionchanged:: 2.7
-        added *async_* alias.
-
-    .. seealso::
-
-        - `~psycopg2.extensions.parse_dsn`
-        - libpq `connection string syntax`__
-        - libpq supported `connection parameters`__
-        - libpq supported `environment variables`__
-
-        .. __: connstring_
-        .. __: connparams_
-        .. __: connenvvars_
-
-    .. extension::
-
-        The non-connection-related keyword parameters are Psycopg extensions
-        to the |DBAPI|_.
-
-.. data:: apilevel
-
-    String constant stating the supported DB API level.  For `psycopg2` is
-    ``2.0``.
-
-.. data:: threadsafety
-
-    Integer constant stating the level of thread safety the interface
-    supports.  For `psycopg2` is ``2``, i.e. threads can share the module
-    and the connection. See :ref:`thread-safety` for details.
-
-.. data:: paramstyle
-
-    String constant stating the type of parameter marker formatting expected
-    by the interface.  For `psycopg2` is ``pyformat``.  See also
-    :ref:`query-parameters`.
-
-.. data:: __libpq_version__
-
-   Integer constant reporting the version of the ``libpq`` library this
-   ``psycopg2`` module was compiled with (in the same format of
-   `~psycopg2.extensions.ConnectionInfo.server_version`).  If this value is
-   greater or equal than ``90100`` then you may query the version of the
-   actually loaded library using the `~psycopg2.extensions.libpq_version()`
-   function.
-
-
-.. index::
-    single: Exceptions; DB API
-
-.. _dbapi-exceptions:
-
-Exceptions
-----------
-
-In compliance with the |DBAPI|_, the module makes informations about errors
-available through the following exceptions:
-
-.. exception:: Warning
-
-    Exception raised for important warnings like data truncations while
-    inserting, etc. It is a subclass of the Python `StandardError`
-    (`Exception` on Python 3).
-
-.. exception:: Error
-
-    Exception that is the base class of all other error exceptions. You can
-    use this to catch all errors with one single `!except` statement. Warnings
-    are not considered errors and thus not use this class as base. It
-    is a subclass of the Python `StandardError` (`Exception` on Python 3).
-
-    .. attribute:: pgerror
-
-        String representing the error message returned by the backend,
-        `!None` if not available.
-
-    .. attribute:: pgcode
-
-        String representing the error code returned by the backend, `!None`
-        if not available.  The `~psycopg2.errorcodes` module contains
-        symbolic constants representing PostgreSQL error codes.
-
-    .. doctest::
-        :options: +NORMALIZE_WHITESPACE
-
-        >>> try:
-        ...     cur.execute("SELECT * FROM barf")
-        ... except psycopg2.Error as e:
-        ...     pass
-
-        >>> e.pgcode
-        '42P01'
-        >>> print(e.pgerror)
-        ERROR:  relation "barf" does not exist
-        LINE 1: SELECT * FROM barf
-                              ^
-
-    .. attribute:: cursor
-
-        The cursor the exception was raised from; `None` if not applicable.
-
-    .. attribute:: diag
-
-        A `~psycopg2.extensions.Diagnostics` object containing further
-        information about the error. ::
-
-            >>> try:
-            ...     cur.execute("SELECT * FROM barf")
-            ... except psycopg2.Error as e:
-            ...     pass
-
-            >>> e.diag.severity
-            'ERROR'
-            >>> e.diag.message_primary
-            'relation "barf" does not exist'
-
-        .. versionadded:: 2.5
-
-    .. extension::
-
-        The `~Error.pgerror`, `~Error.pgcode`, `~Error.cursor`, and
-        `~Error.diag` attributes are Psycopg extensions.
-
-
-.. exception:: InterfaceError
-
-    Exception raised for errors that are related to the database interface
-    rather than the database itself.  It is a subclass of `Error`.
-
-.. exception:: DatabaseError
-
-    Exception raised for errors that are related to the database.  It is a
-    subclass of `Error`.
-
-.. exception:: DataError
-
-    Exception raised for errors that are due to problems with the processed
-    data like division by zero, numeric value out of range, etc. It is a
-    subclass of `DatabaseError`.
-
-.. exception:: OperationalError
-
-    Exception raised for errors that are related to the database's operation
-    and not necessarily under the control of the programmer, e.g. an
-    unexpected disconnect occurs, the data source name is not found, a
-    transaction could not be processed, a memory allocation error occurred
-    during processing, etc.  It is a subclass of `DatabaseError`.
-
-.. exception:: IntegrityError
-
-    Exception raised when the relational integrity of the database is
-    affected, e.g. a foreign key check fails.  It is a subclass of
-    `DatabaseError`.
-
-.. exception:: InternalError
-
-    Exception raised when the database encounters an internal error, e.g. the
-    cursor is not valid anymore, the transaction is out of sync, etc.  It is a
-    subclass of `DatabaseError`.
-
-.. exception:: ProgrammingError
-
-    Exception raised for programming errors, e.g. table not found or already
-    exists, syntax error in the SQL statement, wrong number of parameters
-    specified, etc.  It is a subclass of `DatabaseError`.
-
-.. exception:: NotSupportedError
-
-    Exception raised in case a method or database API was used which is not
-    supported by the database, e.g. requesting a `!rollback()` on a
-    connection that does not support transaction or has transactions turned
-    off.  It is a subclass of `DatabaseError`.
-
-
-.. extension::
-
-    Psycopg actually raises a different exception for each :sql:`SQLSTATE`
-    error returned by the database: the classes are available in the
-    `psycopg2.errors` module.  Every exception class is a subclass of one of
-    the exception classes defined here though, so they don't need to be
-    trapped specifically: trapping `!Error` or `!DatabaseError` is usually
-    what needed to write a generic error handler; trapping a specific error
-    such as `!NotNullViolation` can be useful to write specific exception
-    handlers.
-
-
-This is the exception inheritance layout:
-
-.. parsed-literal::
-
-    `!StandardError`
-    \|__ `Warning`
-    \|__ `Error`
-        \|__ `InterfaceError`
-        \|__ `DatabaseError`
-            \|__ `DataError`
-            \|__ `OperationalError`
-            \|__ `IntegrityError`
-            \|__ `InternalError`
-            \|__ `ProgrammingError`
-            \|__ `NotSupportedError`
-
-
-
-.. _type-objects-and-constructors:
-
-Type Objects and Constructors
------------------------------
-
-.. note::
-
-    This section is mostly copied verbatim from the |DBAPI|_
-    specification.  While these objects are exposed in compliance to the
-    DB API, Psycopg offers very accurate tools to convert data between Python
-    and PostgreSQL formats.  See :ref:`adapting-new-types` and
-    :ref:`type-casting-from-sql-to-python`
-
-Many databases need to have the input in a particular format for
-binding to an operation's input parameters.  For example, if an
-input is destined for a DATE column, then it must be bound to the
-database in a particular string format.  Similar problems exist
-for "Row ID" columns or large binary items (e.g. blobs or RAW
-columns).  This presents problems for Python since the parameters
-to the .execute*() method are untyped.  When the database module
-sees a Python string object, it doesn't know if it should be bound
-as a simple CHAR column, as a raw BINARY item, or as a DATE.
-
-To overcome this problem, a module must provide the constructors
-defined below to create objects that can hold special values.
-When passed to the cursor methods, the module can then detect the
-proper type of the input parameter and bind it accordingly.
-
-A Cursor Object's description attribute returns information about
-each of the result columns of a query.  The type_code must compare
-equal to one of Type Objects defined below. Type Objects may be
-equal to more than one type code (e.g. DATETIME could be equal to
-the type codes for date, time and timestamp columns; see the
-Implementation Hints below for details).
-
-The module exports the following constructors and singletons:
-
-.. function:: Date(year,month,day)
-
-    This function constructs an object holding a date value.
-
-.. function:: Time(hour,minute,second)
-
-    This function constructs an object holding a time value.
-
-.. function:: Timestamp(year,month,day,hour,minute,second)
-
-    This function constructs an object holding a time stamp value.
-
-.. function:: DateFromTicks(ticks)
-
-    This function constructs an object holding a date value from the given
-    ticks value (number of seconds since the epoch; see the documentation of
-    the standard Python time module for details).
-
-.. function:: TimeFromTicks(ticks)
-
-    This function constructs an object holding a time value from the given
-    ticks value (number of seconds since the epoch; see the documentation of
-    the standard Python time module for details).
-
-.. function:: TimestampFromTicks(ticks)
-
-    This function constructs an object holding a time stamp value from the
-    given ticks value (number of seconds since the epoch; see the
-    documentation of the standard Python time module for details).
-
-.. function:: Binary(string)
-
-    This function constructs an object capable of holding a binary (long)
-    string value.
-
-.. note::
-
-    All the adapters returned by the module level factories (`!Binary`,
-    `!Date`, `!Time`, `!Timestamp` and the `!*FromTicks` variants) expose the
-    wrapped object (a regular Python object such as `!datetime`) in an
-    `!adapted` attribute.
-
-.. data:: STRING
-
-    This type object is used to describe columns in a database that are
-    string-based (e.g. CHAR).
-
-.. data:: BINARY
-
-    This type object is used to describe (long) binary columns in a database
-    (e.g. LONG, RAW, BLOBs).
-
-.. data:: NUMBER
-
-    This type object is used to describe numeric columns in a database.
-
-.. data:: DATETIME
-
-    This type object is used to describe date/time columns in a database.
-
-.. data:: ROWID
-
-    This type object is used to describe the "Row ID" column in a database.
-
-
-.. testcode::
-    :hide:
-
-    conn.rollback()

doc/src/news.rst

@@ -1,10 +0,0 @@
-.. index::
-    single: Release notes
-    single: News
-
-.. _news:
-
-Release notes
-=============
-
-.. include:: ../../NEWS

doc/src/pool.rst

@@ -1,60 +0,0 @@
-`psycopg2.pool` -- Connections pooling
-======================================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. index::
-    pair: Connection; Pooling
-
-.. module:: psycopg2.pool
-
-Creating new PostgreSQL connections can be an expensive operation.  This
-module offers a few pure Python classes implementing simple connection pooling
-directly in the client application.
-
-.. class:: AbstractConnectionPool(minconn, maxconn, \*args, \*\*kwargs)
-
-    Base class implementing generic key-based pooling code.
-
-    New *minconn* connections are created automatically. The pool will support
-    a maximum of about *maxconn* connections.  *\*args* and *\*\*kwargs* are
-    passed to the `~psycopg2.connect()` function.
-
-    The following methods are expected to be implemented by subclasses:
-
-    .. method:: getconn(key=None)
-
-        Get a free connection from the pool.
-
-        The *key* parameter is optional: if used, the connection will be
-        associated to the key and calling `!getconn()` with the same key again
-        will return the same connection.
-
-    .. method:: putconn(conn, key=None, close=False)
-
-        Put away a connection.
-
-        If *close* is `!True`, discard the connection from the pool.
-        *key* should be used consistently with `getconn()`.
-
-    .. method:: closeall
-
-        Close all the connections handled by the pool.
-
-        Note that all the connections are closed, including ones
-        eventually in use by the application.
-
-
-The following classes are `AbstractConnectionPool` subclasses ready to
-be used.
-
-.. autoclass:: SimpleConnectionPool
-
-    .. note:: This pool class is useful only for single-threaded applications.
-
-
-.. index:: Multithread; Connection pooling
-
-.. autoclass:: ThreadedConnectionPool
-
-    .. note:: This pool class can be safely used in multi-threaded applications.

doc/src/sql.rst

@@ -1,147 +0,0 @@
-`psycopg2.sql` -- SQL string composition
-========================================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. module:: psycopg2.sql
-
-.. versionadded:: 2.7
-
-The module contains objects and functions useful to generate SQL dynamically,
-in a convenient and safe way. SQL identifiers (e.g. names of tables and
-fields) cannot be passed to the `~cursor.execute()` method like query
-arguments::
-
-    # This will not work
-    table_name = 'my_table'
-    cur.execute("insert into %s values (%s, %s)", [table_name, 10, 20])
-
-The SQL query should be composed before the arguments are merged, for
-instance::
-
-    # This works, but it is not optimal
-    table_name = 'my_table'
-    cur.execute(
-        "insert into %s values (%%s, %%s)" % table_name,
-        [10, 20])
-
-This sort of works, but it is an accident waiting to happen: the table name
-may be an invalid SQL literal and need quoting; even more serious is the
-security problem in case the table name comes from an untrusted source. The
-name should be escaped using `~psycopg2.extensions.quote_ident()`::
-
-    # This works, but it is not optimal
-    table_name = 'my_table'
-    cur.execute(
-        "insert into %s values (%%s, %%s)" % ext.quote_ident(table_name, cur),
-        [10, 20])
-
-This is now safe, but it somewhat ad-hoc. In case, for some reason, it is
-necessary to include a value in the query string (as opposite as in a value)
-the merging rule is still different (`~psycopg2.extensions.adapt()` should be
-used...). It is also still relatively dangerous: if `!quote_ident()` is
-forgotten somewhere, the program will usually work, but will eventually crash
-in the presence of a table or field name with containing characters to escape,
-or will present a potentially exploitable weakness.
-
-The objects exposed by the `!psycopg2.sql` module allow generating SQL
-statements on the fly, separating clearly the variable parts of the statement
-from the query parameters::
-
-    from psycopg2 import sql
-
-    cur.execute(
-        sql.SQL("insert into {} values (%s, %s)")
-            .format(sql.Identifier('my_table')),
-        [10, 20])
-
-
-Module usage
-------------
-
-Usually you should express the template of your query as an `SQL` instance
-with `{}`\-style placeholders and use `~SQL.format()` to merge the variable
-parts into them, all of which must be `Composable` subclasses. You can still
-have `%s`\ -style placeholders in your query and pass values to
-`~cursor.execute()`: such value placeholders will be untouched by
-`!format()`::
-
-    query = sql.SQL("select {field} from {table} where {pkey} = %s").format(
-        field=sql.Identifier('my_name'),
-        table=sql.Identifier('some_table'),
-        pkey=sql.Identifier('id'))
-
-The resulting object is meant to be passed directly to cursor methods such as
-`~cursor.execute()`, `~cursor.executemany()`, `~cursor.copy_expert()`, but can
-also be used to compose a query as a Python string, using the
-`~Composable.as_string()` method::
-
-    cur.execute(query, (42,))
-
-If part of your query is a variable sequence of arguments, such as a
-comma-separated list of field names, you can use the `SQL.join()` method to
-pass them to the query::
-
-    query = sql.SQL("select {fields} from {table}").format(
-        fields=sql.SQL(',').join([
-            sql.Identifier('field1'),
-            sql.Identifier('field2'),
-            sql.Identifier('field3'),
-        ]),
-        table=sql.Identifier('some_table'))
-
-
-`!sql` objects
---------------
-
-The `!sql` objects are in the following inheritance hierarchy:
-
-|   `Composable`: the base class exposing the common interface
-|   ``|__`` `SQL`: a literal snippet of an SQL query
-|   ``|__`` `Identifier`: a PostgreSQL identifier or dot-separated sequence of identifiers
-|   ``|__`` `Literal`: a value hardcoded into a query
-|   ``|__`` `Placeholder`: a `%s`\ -style placeholder whose value will be added later e.g. by `~cursor.execute()`
-|   ``|__`` `Composed`: a sequence of `!Composable` instances.
-
-
-.. autoclass:: Composable
-
-    .. automethod:: as_string
-
-
-.. autoclass:: SQL
-
-    .. autoattribute:: string
-
-    .. automethod:: format
-
-    .. automethod:: join
-
-
-.. autoclass:: Identifier
-
-    .. versionchanged:: 2.8
-        added support for multiple strings.
-
-    .. autoattribute:: strings
-
-        .. versionadded:: 2.8
-            previous verions only had a `!string` attribute. The attribute
-            still exists but is deprecate and will only work if the
-            `!Identifier` wraps a single string.
-
-.. autoclass:: Literal
-
-    .. autoattribute:: wrapped
-
-
-.. autoclass:: Placeholder
-
-    .. autoattribute:: name
-
-
-.. autoclass:: Composed
-
-    .. autoattribute:: seq
-
-    .. automethod:: join

doc/src/tools/lib/dbapi_extension.py

@@ -1,50 +0,0 @@
-"""
-    extension
-    ~~~~~~~~~
-
-    A directive to create a box warning that a certain bit of Psycopg is an
-    extension to the DBAPI 2.0.
-
-    :copyright: Copyright 2010 by Daniele Varrazzo.
-"""
-
-from docutils import nodes
-
-from sphinx.locale import _
-from docutils.parsers.rst import Directive
-
-class extension_node(nodes.Admonition, nodes.Element): pass
-
-
-class Extension(Directive):
-    """
-    An extension entry, displayed as an admonition.
-    """
-
-    has_content = True
-    required_arguments = 0
-    optional_arguments = 0
-    final_argument_whitespace = False
-    option_spec = {}
-
-    def run(self):
-        node = extension_node('\n'.join(self.content))
-        node += nodes.title(_('DB API extension'), _('DB API extension'))
-        self.state.nested_parse(self.content, self.content_offset, node)
-        node['classes'].append('dbapi-extension')
-        return [node]
-
-
-def visit_extension_node(self, node):
-    self.visit_admonition(node)
-
-def depart_extension_node(self, node):
-    self.depart_admonition(node)
-
-def setup(app):
-    app.add_node(extension_node,
-                 html=(visit_extension_node, depart_extension_node),
-                 latex=(visit_extension_node, depart_extension_node),
-                 text=(visit_extension_node, depart_extension_node))
-
-    app.add_directive('extension', Extension)

doc/src/tools/lib/sql_role.py

@@ -1,19 +0,0 @@
-"""
-    sql role
-    ~~~~~~~~
-
-    An interpreted text role to style SQL syntax in Psycopg documentation.
-
-    :copyright: Copyright 2010 by Daniele Varrazzo.
-"""
-
-from docutils import nodes, utils
-from docutils.parsers.rst import roles
-
-def sql_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    text = utils.unescape(text)
-    options['classes'] = ['sql']
-    return [nodes.literal(rawtext, text, **options)], []
-
-def setup(app):
-    roles.register_local_role('sql', sql_role)

doc/src/tools/lib/ticket_role.py

@@ -1,57 +0,0 @@
-"""
-    ticket role
-    ~~~~~~~~~~~
-
-    An interpreted text role to link docs to tickets issues.
-
-    :copyright: Copyright 2013 by Daniele Varrazzo.
-"""
-
-import re
-from docutils import nodes, utils
-from docutils.parsers.rst import roles
-
-def ticket_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    cfg = inliner.document.settings.env.app.config
-    if cfg.ticket_url is None:
-        msg = inliner.reporter.warning(
-            "ticket not configured: please configure ticket_url in conf.py")
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
-
-    rv = [nodes.Text(name + ' ')]
-    tokens = re.findall(r'(#?\d+)|([^\d#]+)', text)
-    for ticket, noise in tokens:
-        if ticket:
-            num = int(ticket.replace('#', ''))
-
-            # Push numbers of the oldel tickets ahead.
-            # We moved the tickets from a different tracker to GitHub and the
-            # latter already had a few ticket numbers taken (as merge
-            # requests).
-            remap_until = cfg.ticket_remap_until
-            remap_offset = cfg.ticket_remap_offset
-            if remap_until and remap_offset:
-                if num <= remap_until:
-                    num += remap_offset
-
-            url = cfg.ticket_url % num
-            roles.set_classes(options)
-            node = nodes.reference(ticket, utils.unescape(ticket),
-                refuri=url, **options)
-
-            rv.append(node)
-
-        else:
-            assert noise
-            rv.append(nodes.Text(noise))
-
-    return rv, []
-
-
-def setup(app):
-    app.add_config_value('ticket_url', None, 'env')
-    app.add_config_value('ticket_remap_until', None, 'env')
-    app.add_config_value('ticket_remap_offset', None, 'env')
-    app.add_role('ticket', ticket_role)
-    app.add_role('tickets', ticket_role)

doc/src/tools/make_sqlstate_docs.py

@@ -1,57 +0,0 @@
-#!/usr/bin/env python
-"""Create the docs table of the sqlstate errors.
-"""
-
-
-import re
-import sys
-from collections import namedtuple
-
-from psycopg2._psycopg import sqlstate_errors
-
-
-def main():
-    sqlclasses = {}
-    clsfile = sys.argv[1]
-    with open(clsfile) as f:
-        for l in f:
-            m = re.match(r'/\* Class (..) - (.+) \*/', l)
-            if m is not None:
-                sqlclasses[m.group(1)] = m.group(2)
-
-    Line = namedtuple('Line', 'colstate colexc colbase sqlstate')
-
-    lines = [Line('SQLSTATE', 'Exception', 'Base exception', None)]
-    for k in sorted(sqlstate_errors):
-        exc = sqlstate_errors[k]
-        lines.append(Line(
-            f"``{k}``", f"`!{exc.__name__}`",
-            f"`!{get_base_exception(exc).__name__}`", k))
-
-    widths = [max(len(l[c]) for l in lines) for c in range(3)]
-    h = Line(*(['=' * w for w in widths] + [None]))
-    lines.insert(0, h)
-    lines.insert(2, h)
-    lines.append(h)
-
-    h1 = '-' * (sum(widths) + len(widths) - 1)
-    sqlclass = None
-    for l in lines:
-        cls = l.sqlstate[:2] if l.sqlstate else None
-        if cls and cls != sqlclass:
-            print(f"**Class {cls}**: {sqlclasses[cls]}")
-            print(h1)
-            sqlclass = cls
-
-        print("%-*s %-*s %-*s" % (
-            widths[0], l.colstate, widths[1], l.colexc, widths[2], l.colbase))
-
-
-def get_base_exception(exc):
-    for cls in exc.__mro__:
-        if cls.__module__ == 'psycopg2':
-            return cls
-
-
-if __name__ == '__main__':
-    sys.exit(main())

doc/src/tz.rst

@@ -1,19 +0,0 @@
-`psycopg2.tz` --  ``tzinfo`` implementations for Psycopg 2
-===============================================================
-
-.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
-
-.. module:: psycopg2.tz
-
-.. deprecated:: 2.9
-   The module will be dropped in psycopg 2.10. Use `datetime.timezone`
-   instead.
-
-This module holds two different tzinfo implementations that can be used as the
-`tzinfo` argument to `~datetime.datetime` constructors, directly passed to
-Psycopg functions or used to set the `cursor.tzinfo_factory` attribute in
-cursors.
-
-.. autoclass:: psycopg2.tz.FixedOffsetTimezone
-
-.. autoclass:: psycopg2.tz.LocalTimezone

examples/binary.py

@@ -0,0 +1,89 @@
+# binary.py - working with binary data
+#
+# Copyright (C) 2001-2004 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below tis line (except for experimenting)
+
+import sys
+import psycopg
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+print "Encoding for this connection is", conn.encoding
+
+curs = conn.cursor()
+try:
+    curs.execute("CREATE TABLE test_binary (id int4, name text, img bytea)")
+except:
+    conn.rollback()
+    curs.execute("DROP TABLE test_binary")
+    curs.execute("CREATE TABLE test_binary (id int4, name text, img bytea)")
+conn.commit()
+
+# first we try two inserts, one with an explicit Binary call and the other
+# using a buffer on a file object.
+
+data1 = {'id':1, 'name':'somehackers.jpg',
+         'img':psycopg.Binary(open('somehackers.jpg').read())}
+data2 = {'id':2, 'name':'whereareyou.jpg',
+         'img':buffer(open('whereareyou.jpg').read())}
+
+curs.execute("""INSERT INTO test_binary
+                  VALUES (%(id)s, %(name)s, %(img)s)""", data1)
+curs.execute("""INSERT INTO test_binary
+                  VALUES (%(id)s, %(name)s, %(img)s)""", data2)
+
+# now we try to extract the images as simple text strings
+
+print "Extracting the images as strings..."
+curs.execute("SELECT * FROM test_binary")
+
+for row in curs.fetchall():
+    name, ext = row[1].split('.')
+    new_name = name + '_S.' + ext
+    print "  writing %s to %s ..." % (name+'.'+ext, new_name),
+    open(new_name, 'wb').write(row[2])
+    print "done"
+    print "  python type of image data is", type(row[2])
+    
+# extract exactly the same data but using a binary cursor
+
+print "Extracting the images using a binary cursor:"
+
+curs.execute("""DECLARE zot CURSOR FOR
+                  SELECT img, name FROM test_binary FOR READ ONLY""")
+curs.execute("""FETCH ALL FROM zot""")
+
+for row in curs.fetchall():
+    name, ext = row[1].split('.')
+    new_name = name + '_B.' + ext
+    print "  writing %s to %s ..." % (name+'.'+ext, new_name),
+    open(new_name, 'wb').write(row[0])
+    print "done"
+    print "  python type of image data is", type(row[0])
+    
+# this rollback is requires because we can't drop a table with a binary cusor
+# declared and still open
+conn.rollback()
+
+curs.execute("DROP TABLE test_binary")
+conn.commit()
+
+print "\nNow try to load the new images, to check it worked!"

examples/copy_from.py

@@ -0,0 +1,178 @@
+# copy_from.py -- example about copy_from 
+#
+# Copyright (C) 2002 Tom Jenkins <tjenkins@devis.com>
+# Copyright (C) 2005 Federico Di Gregorio <fog@initd.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below tis line (except for experimenting)
+
+import sys
+import os
+import StringIO
+import psycopg
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+print "Encoding for this connection is", conn.encoding
+
+curs = conn.cursor()
+try:
+    curs.execute("CREATE TABLE test_copy (fld1 text, fld2 text, fld3 int4)")
+except:
+    conn.rollback()
+    curs.execute("DROP TABLE test_copy")
+    curs.execute("CREATE TABLE test_copy (fld1 text, fld2 text, fld3 int4)")
+conn.commit()
+
+# copy_from with default arguments, from open file
+
+io = open('copy_from.txt', 'wr')
+data = ['Tom\tJenkins\t37\n',
+        'Madonna\t\N\t45\n',
+        'Federico\tDi Gregorio\t\N\n']
+io.writelines(data)
+io.close()
+
+io = open('copy_from.txt', 'r')
+curs.copy_from(io, 'test_copy')
+print "1) Copy %d records from file object " % len(data) + \
+      "using defaults (sep: \\t and null = \\N)"
+io.close()
+
+curs.execute("SELECT * FROM test_copy")
+rows = curs.fetchall()
+print "   Select returned %d rows" % len(rows)
+
+for r in rows:
+    print "    %s %s\t%s" % (r[0], r[1], r[2])
+curs.execute("delete from test_copy")
+conn.commit()
+
+# copy_from using custom separator, from open file
+
+io = open('copy_from.txt', 'wr')
+data = ['Tom:Jenkins:37\n',
+        'Madonna:\N:45\n',
+        'Federico:Di Gregorio:\N\n']
+io.writelines(data)
+io.close()
+
+io = open('copy_from.txt', 'r')
+curs.copy_from(io, 'test_copy', ':')
+print "2) Copy %d records from file object using sep = :" % len(data)
+io.close()
+
+curs.execute("SELECT * FROM test_copy")
+rows = curs.fetchall()
+print "   Select returned %d rows" % len(rows)
+
+for r in rows:
+    print "    %s %s\t%s" % (r[0], r[1], r[2])
+curs.execute("delete from test_copy")
+conn.commit()
+
+# copy_from using custom null identifier, from open file
+
+io = open('copy_from.txt', 'wr')
+data = ['Tom\tJenkins\t37\n',
+        'Madonna\tNULL\t45\n',
+        'Federico\tDi Gregorio\tNULL\n']
+io.writelines(data)
+io.close()
+
+io = open('copy_from.txt', 'r')
+curs.copy_from(io, 'test_copy', null='NULL')
+print "3) Copy %d records from file object using null = NULL" % len(data)
+io.close()
+
+curs.execute("SELECT * FROM test_copy")
+rows = curs.fetchall()
+print "   Select using cursor returned %d rows" % len(rows)
+
+for r in rows:
+    print "    %s %s\t%s" % (r[0], r[1], r[2])
+curs.execute("delete from test_copy")
+conn.commit()
+
+# copy_from using custom separator and null identifier
+
+io = open('copy_from.txt', 'wr')
+data = ['Tom:Jenkins:37\n', 'Madonna:NULL:45\n', 'Federico:Di Gregorio:NULL\n']
+io.writelines(data)
+io.close()
+
+io = open('copy_from.txt', 'r')
+curs.copy_from(io, 'test_copy', ':', 'NULL')
+print "4) Copy %d records from file object " % len(data) + \
+      "using sep = : and null = NULL"
+io.close()
+
+curs.execute("SELECT * FROM test_copy")
+rows = curs.fetchall()
+print "   Select using cursor returned %d rows" % len(rows)
+
+for r in rows:
+    print "    %s %s\t%s" % (r[0], r[1], r[2])
+curs.execute("delete from test_copy")
+conn.commit()
+
+# anything can be used as a file if it has .read() and .readline() methods
+
+data = StringIO.StringIO()
+data.write('\n'.join(['Tom\tJenkins\t37',
+                      'Madonna\t\N\t45',
+                      'Federico\tDi Gregorio\t\N']))
+data.seek(0)
+
+curs.copy_from(data, 'test_copy')
+print "5) Copy 3 records from StringIO object using defaults"
+
+curs.execute("SELECT * FROM test_copy")
+rows = curs.fetchall()
+print "   Select using cursor returned %d rows" % len(rows)
+
+for r in rows:
+    print "    %s %s\t%s" % (r[0], r[1], r[2])
+curs.execute("delete from test_copy")
+conn.commit()
+
+# simple error test
+
+print "6) About to raise an error"
+data = StringIO.StringIO()
+data.write('\n'.join(['Tom\tJenkins\t37',
+                      'Madonna\t\N\t45',
+                      'Federico\tDi Gregorio\taaa']))
+data.seek(0)
+
+try:
+    curs.copy_from(data, 'test_copy')
+except StandardError, err:
+    conn.rollback()
+    print "   Catched error (as expected):\n", err
+
+conn.rollback()
+
+curs.execute("DROP TABLE test_copy")
+os.unlink('copy_from.txt')
+conn.commit()
+
+
+

examples/copy_to.py

@@ -0,0 +1,105 @@
+# copy_to.py -- example about copy_to 
+#
+# Copyright (C) 2002 Tom Jenkins <tjenkins@devis.com>
+# Copyright (C) 2005 Federico Di Gregorio <fog@initd.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below tis line (except for experimenting)
+
+import sys
+import os
+import StringIO
+import psycopg
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+print "Encoding for this connection is", conn.encoding
+
+curs = conn.cursor()
+try:
+    curs.execute("CREATE TABLE test_copy (fld1 text, fld2 text, fld3 int4)")
+except:
+    conn.rollback()
+    curs.execute("DROP TABLE test_copy")
+    curs.execute("CREATE TABLE test_copy (fld1 text, fld2 text, fld3 int4)")
+conn.commit()
+
+# demostrate copy_to functionality
+data = [('Tom', 'Jenkins', '37'),
+        ('Madonna', None, '45'),
+        ('Federico', 'Di Gregorio', None)]
+query = "INSERT INTO test_copy VALUES (%s, %s, %s)"
+for row in data:
+    curs.execute(query, row)
+conn.commit()
+
+# copy_to using defaults
+io = open('copy_to.txt', 'w')
+curs.copy_to(io, 'test_copy')
+print "1) Copy %d records into file object using defaults: " % len (data) + \
+      "sep = \\t and null = \\N"
+io.close()
+
+rows = open('copy_to.txt', 'r').readlines()
+print "   File has %d rows:" % len(rows)
+
+for r in rows:
+    print "   ", r,
+
+# copy_to using custom separator
+io = open('copy_to.txt', 'w')
+curs.copy_to(io, 'test_copy', ':')
+print "2) Copy %d records into file object using sep = :" % len(data)
+io.close()
+
+rows = open('copy_to.txt', 'r').readlines()
+print "   File has %d rows:" % len(rows)
+
+for r in rows:
+    print "   ", r,
+
+# copy_to using custom null identifier
+io = open('copy_to.txt', 'w')
+curs.copy_to(io, 'test_copy', null='NULL')
+print "3) Copy %d records into file object using null = NULL" % len(data)
+io.close()
+
+rows = open('copy_to.txt', 'r').readlines()
+print "   File has %d rows:" % len(rows)
+
+for r in rows:
+    print "   ", r,
+
+# copy_to using custom separator and null identifier
+io = open('copy_to.txt', 'w')
+curs.copy_to(io, 'test_copy', ':', 'NULL')
+print "4) Copy %d records into file object using sep = : and null ) NULL" % \
+      len(data)
+io.close()
+
+rows = open('copy_to.txt', 'r').readlines()
+print "   File has %d rows:" % len(rows)
+
+for r in rows:
+    print "   ", r,
+
+curs.execute("DROP TABLE test_copy")
+os.unlink('copy_to.txt')
+conn.commit()

examples/cursor.py

@@ -0,0 +1,64 @@
+# cursor.py - how to subclass the cursor type
+#
+# Copyright (C) 2004 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below this line (except for experimenting)
+
+import sys
+import psycopg
+import psycopg.extensions
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dsn:", DSN
+
+conn = psycopg.connect(DSN)
+print "Encoding for this connection is", conn.encoding
+
+
+class NoDataError(psycopg.ProgrammingError):
+    """Exception that will be raised by our cursor."""
+    pass
+
+class Cursor(psycopg.extensions.cursor):
+    """A custom cursor."""
+
+    def fetchone(self):
+        """Like fetchone but raise an exception if no data is available.
+
+        Note that to have .fetchmany() and .fetchall() to raise the same
+        exception we'll have to override them too; even if internally psycopg
+        uses the same function to fetch rows, the code path from Python is
+        different.
+        """
+        d = psycopg.extensions.cursor.fetchone(self)
+        if d is None:
+	    raise NoDataError("no more data")
+        return d
+    
+curs = conn.cursor(factory=Cursor)
+curs.execute("SELECT 1 AS foo")
+print "Result of fetchone():", curs.fetchone()
+
+# now let's raise the exception
+try:
+    curs.fetchone()
+except NoDataError, err:
+    print "Exception caugth:", err  
+
+conn.rollback()

examples/dialtone.py

@@ -0,0 +1,146 @@
+"""
+This example/recipe has been contributed by Valentino Volonghi (dialtone)
+
+Mapping arbitrary objects to a PostgreSQL database with psycopg2
+
+- Problem
+
+You need to store arbitrary objects in a PostgreSQL database without being
+intrusive for your classes (don't want inheritance from an 'Item' or 
+'Persistent' object).
+
+- Solution
+"""
+
+from datetime import datetime
+ 
+import psycopg
+from psycopg.extensions import adapt, register_adapter
+
+try: sorted()
+except NameError:
+    def sorted(seq):
+        seq.sort()
+        return seq
+
+# Here is the adapter for every object that we may ever need to 
+# insert in the database. It receives the original object and does
+# its job on that instance
+
+class ObjectMapper(object):
+    def __init__(self, orig, curs=None):
+        self.orig = orig
+        self.tmp = {}
+        self.items, self.fields = self._gatherState()
+ 
+    def _gatherState(self):
+        adaptee_name = self.orig.__class__.__name__
+        fields = sorted([(field, getattr(self.orig, field))
+                        for field in persistent_fields[adaptee_name]])
+        items = []
+        for item, value in fields:
+            items.append(item)
+        return items, fields
+ 
+    def getTableName(self):
+        return self.orig.__class__.__name__
+ 
+    def getMappedValues(self):
+        tmp = []
+        for i in self.items:
+            tmp.append("%%(%s)s"%i)
+        return ", ".join(tmp)
+ 
+    def getValuesDict(self):
+        return dict(self.fields)
+ 
+    def getFields(self):
+        return self.items
+
+    def generateInsert(self):
+        qry = "INSERT INTO"
+        qry += " " + self.getTableName() + " ("
+        qry += ", ".join(self.getFields()) + ") VALUES ("
+        qry += self.getMappedValues() + ")"
+        return qry, self.getValuesDict()
+
+# Here are the objects
+class Album(object):    
+    id = 0 
+    def __init__(self):
+        self.creation_time = datetime.now()
+        self.album_id = self.id
+        Album.id = Album.id + 1
+        self.binary_data = buffer('12312312312121')
+ 
+class Order(object):
+     id = 0
+     def __init__(self):
+        self.items = ['rice','chocolate']
+        self.price = 34
+        self.order_id = self.id
+        Order.id = Order.id + 1
+
+register_adapter(Album, ObjectMapper)
+register_adapter(Order, ObjectMapper)
+    
+# Describe what is needed to save on each object
+# This is actually just configuration, you can use xml with a parser if you
+# like to have plenty of wasted CPU cycles ;P.
+
+persistent_fields = {'Album': ['album_id', 'creation_time', 'binary_data'],
+                              'Order':  ['order_id', 'items', 'price']
+                            }
+ 
+print adapt(Album()).generateInsert()
+print adapt(Album()).generateInsert()
+print adapt(Album()).generateInsert()
+print adapt(Order()).generateInsert()
+print adapt(Order()).generateInsert()
+print adapt(Order()).generateInsert()
+
+"""
+- Discussion
+
+Psycopg 2 has a great new feature: adaptation. The big thing about 
+adaptation is that it enable the programmer to glue most of the 
+code out there without many difficulties.
+
+This recipe tries to focus the attention on a way to generate SQL queries to 
+insert  completely new objects inside a database. As you can see objects do 
+not know anything about the code that is handling them. We specify all the 
+fields that we need for each object through the persistent_fields dict.
+
+The most important line of this recipe is this one:
+    adapters.update({Album: ObjectMapper, Order: ObjectMapper})
+
+In this line we notify the system that when we call adapt with an Album instance 
+as an argument we want it to istantiate ObjectMapper passing the Album instance  
+as argument (self.orig in the ObjectMapper class).
+
+adapters is just a python dict with a Key that represents the type 
+we need to adapt from and a value that is the adapter 
+which will adapt to the wanted interface.
+
+The output is something like this (for each call to generateInsert):
+    
+('INSERT INTO Album (album_id, binary_data, creation_time) VALUES 
+   (%(album_id)s, %(binary_data)s, %(creation_time)s)', 
+      
+  {'binary_data': <read-only buffer for 0x402de070, ...>, 
+    'creation_time':   datetime.datetime(2004, 9, 10, 20, 48, 29, 633728), 
+    'album_id': 1}
+)
+
+This is a tuple of {SQL_QUERY, FILLING_DICT}, and all the quoting/converting 
+stuff (from python's datetime to postgres s and from python's buffer to 
+postgres' blob) is handled with the same adaptation process hunder the hood 
+by psycopg2.
+
+At last, just notice that ObjectMapper is working for both Album and Order 
+instances without any glitches at all, and both classes could have easily been 
+coming from closed source libraries or C coded ones (which are not easily 
+modified), whereas a common pattern in todays ORMs or OODBs is to provide 
+a basic 'Persistent' object that already knows how to store itself in the 
+database.
+"""

examples/dt.py

@@ -0,0 +1,91 @@
+# datetime.py -  example of using date and time types
+#
+# Copyright (C) 2001-2004 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below tis line (except for experimenting)
+
+import sys, psycopg
+import mx.DateTime
+import datetime
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+curs = conn.cursor()
+
+try:
+    curs.execute("""CREATE TABLE test_dt (k int4, d date, t time, dt timestamp,
+                                          z interval)""")
+except:
+    conn.rollback()
+    curs.execute("DROP TABLE test_dt")
+    curs.execute("""CREATE TABLE test_dt (k int4,
+                                          d date, t time, dt timestamp,
+                                          z interval)""")
+conn.commit()
+
+# build and insert some data using mx.DateTime
+mx1 = (
+    1,
+    mx.DateTime.Date(2004, 10, 19),
+    mx.DateTime.Time(0, 11, 17.015),
+    mx.DateTime.Timestamp(2004, 10, 19, 0, 11, 17.5),
+    mx.DateTime.DateTimeDelta(13, 15, 17, 59.9))
+
+print "Inserting mx.DateTime values..."
+curs.execute("INSERT INTO test_dt VALUES (%s, %s, %s, %s, %s)", mx1)
+
+# build and insert some values using the datetime adapters
+dt1 = (
+    2,
+    datetime.date(2004, 10, 19),
+    datetime.time(0, 11, 17, 15000),
+    datetime.datetime(2004, 10, 19, 0, 11, 17, 500000),
+    datetime.timedelta(13, 15*3600+17*60+59, 900000))
+
+print "Inserting Python datetime values..."
+curs.execute("INSERT INTO test_dt VALUES (%s, %s, %s, %s, %s)", dt1)
+
+# now extract the row from database and print them
+print "Extracting values inserted with mx.DateTime wrappers:"
+curs.execute("SELECT d, t, dt, z FROM test_dt WHERE k = 1")
+for n, x in zip(mx1[1:], curs.fetchone()):
+    try:
+        # this will work only is psycopg has been compiled with datetime
+        # as the default typecaster for date/time values
+        s = repr(n) + "\n -> " +  repr(x) + "\n -> " + x.isoformat()
+    except:
+        s = repr(n) + "\n -> " +  repr(x) + "\n -> " + str(x)
+    print s
+print
+
+print "Extracting values inserted with Python datetime wrappers:"
+curs.execute("SELECT d, t, dt, z FROM test_dt WHERE k = 2")
+for n, x in zip(dt1[1:], curs.fetchone()):
+    try:
+        # this will work only is psycopg has been compiled with datetime
+        # as the default typecaster for date/time values
+        s = repr(n) + "\n -> " +  repr(x) + "\n -> " + x.isoformat()
+    except:
+        s = repr(n) + "\n -> " +  repr(x) + "\n -> " + str(x)
+    print s
+print
+
+curs.execute("DROP TABLE test_dt")
+conn.commit()

examples/encoding.py

@@ -0,0 +1,102 @@
+# encoding.py - how to change client encoding (and test it works)
+# -*- encoding: latin-1 -*-
+#
+# Copyright (C) 2004 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below this line (except for experimenting)
+
+import sys, psycopg
+import psycopg.extensions
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+print "Initial encoding for this connection is", conn.encoding
+
+print "\n** This example is supposed to be run in a UNICODE terminal! **\n"
+
+print "Available encodings:"
+for a, b in psycopg.extensions.encodings.items():
+    print " ", a, "<->", b
+
+print "Using STRING typecaster"    
+print "Setting backend encoding to LATIN1 and executing queries:"
+conn.set_client_encoding('LATIN1')
+curs = conn.cursor()
+curs.execute("SELECT %s::TEXT AS foo", ('àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", unicode(x, 'latin-1').encode('utf-8'), type(x)
+curs.execute("SELECT %s::TEXT AS foo", (u'àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", unicode(x, 'latin-1').encode('utf-8'), type(x)
+
+print "Setting backend encoding to UTF8 and executing queries:"
+conn.set_client_encoding('UNICODE')
+curs = conn.cursor()
+curs.execute("SELECT %s::TEXT AS foo", (u'àèìòù'.encode('utf-8'),))
+x = curs.fetchone()[0]
+print "  ->", x, type(x)
+curs.execute("SELECT %s::TEXT AS foo", (u'àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", x, type(x)
+
+print "Using UNICODE typecaster"
+psycopg.extensions.register_type(psycopg.extensions.UNICODE)
+
+print "Setting backend encoding to LATIN1 and executing queries:"
+conn.set_client_encoding('LATIN1')
+curs = conn.cursor()
+curs.execute("SELECT %s::TEXT AS foo", ('àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", x.encode('utf-8'), ":", type(x)
+curs.execute("SELECT %s::TEXT AS foo", (u'àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", x.encode('utf-8'), ":", type(x)
+
+print "Setting backend encoding to UTF8 and executing queries:"
+conn.set_client_encoding('UNICODE')
+curs = conn.cursor()
+curs.execute("SELECT %s::TEXT AS foo", (u'àèìòù'.encode('utf-8'),))
+x = curs.fetchone()[0]
+print "  ->", x.encode('utf-8'), ":", type(x)
+curs.execute("SELECT %s::TEXT AS foo", (u'àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", x.encode('utf-8'), ":", type(x)
+
+print "Executing full UNICODE queries"
+
+print "Setting backend encoding to LATIN1 and executing queries:"
+conn.set_client_encoding('LATIN1')
+curs = conn.cursor()
+curs.execute(u"SELECT %s::TEXT AS foo", ('àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", x.encode('utf-8'), ":", type(x)
+curs.execute(u"SELECT %s::TEXT AS foo", (u'àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", x.encode('utf-8'), ":", type(x)
+
+print "Setting backend encoding to UTF8 and executing queries:"
+conn.set_client_encoding('UNICODE')
+curs = conn.cursor()
+curs.execute(u"SELECT %s::TEXT AS foo", (u'àèìòù'.encode('utf-8'),))
+x = curs.fetchone()[0]
+print "  ->", x.encode('utf-8'), ":", type(x)
+curs.execute(u"SELECT %s::TEXT AS foo", (u'àèìòù',))
+x = curs.fetchone()[0]
+print "  ->", x.encode('utf-8'), ":", type(x)

examples/lastrowid.py

@@ -0,0 +1,59 @@
+# lastrowid.py -  example of using .lastrowid attribute
+#
+# Copyright (C) 2001-2004 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below tis line (except for experimenting)
+
+import sys, psycopg
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+curs = conn.cursor()
+
+try:
+    curs.execute("CREATE TABLE test_oid (name text, surname text)")
+except:
+    conn.rollback()
+    curs.execute("DROP TABLE test_oid")
+    curs.execute("CREATE TABLE test_oid (name text, surname text)")
+conn.commit()
+
+data = ({'name':'Federico', 'surname':'Di Gregorio'},
+        {'name':'Pierluigi', 'surname':'Di Nunzio'})
+
+curs.execute("""INSERT INTO test_oid
+                VALUES (%(name)s, %(surname)s)""", data[0])
+
+foid = curs.lastrowid
+print "Oid for %(name)s %(surname)s" % data[0], "is", foid
+
+curs.execute("""INSERT INTO test_oid
+                VALUES (%(name)s, %(surname)s)""", data[1])
+moid = curs.lastrowid
+print "Oid for %(name)s %(surname)s" % data[1], "is", moid
+
+curs.execute("SELECT * FROM test_oid WHERE oid = %d", (foid,))
+print "Oid", foid, "selected %s %s" % curs.fetchone()
+
+curs.execute("SELECT * FROM test_oid WHERE oid = %d", (moid,))
+print "Oid", moid, "selected %s %s" % curs.fetchone()
+
+curs.execute("DROP TABLE test_oid")
+conn.commit()

examples/mogrify.py

@@ -0,0 +1,47 @@
+# mogrify.py - test all possible type mogrifications
+# -*- encoding: latin1 -*-
+#
+# Copyright (C) 2004 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below this line (except for experimenting)
+
+import sys, psycopg
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+
+conn = psycopg.connect(DSN)
+print "Encoding for this connection is", conn.encoding
+
+curs = conn.cursor()
+curs.execute("SELECT %(foo)s AS foo", {'foo':'bar'})
+curs.execute("SELECT %(foo)s AS foo", {'foo':None})
+curs.execute("SELECT %(foo)s AS foo", {'foo':True})
+curs.execute("SELECT %(foo)f AS foo", {'foo':42})
+curs.execute("SELECT %(foo)s AS foo", {'foo':u'yattà!'})
+curs.execute("SELECT %(foo)s AS foo", {'foo':u'bar'})
+
+print curs.mogrify("SELECT %(foo)s AS foo", {'foo':'bar'})
+print curs.mogrify("SELECT %(foo)s AS foo", {'foo':None})
+print curs.mogrify("SELECT %(foo)s AS foo", {'foo':True})
+print curs.mogrify("SELECT %(foo)f AS foo", {'foo':42})
+print curs.mogrify("SELECT %(foo)s AS foo", {'foo':u'yattà!'})
+print curs.mogrify("SELECT %(foo)s AS foo", {'foo':u'bar'})
+
+conn.rollback()

examples/myfirstrecipe.py

@@ -0,0 +1,122 @@
+"""
+Using a tuple as a bound variable in "SELECT ... IN (...)" clauses
+in PostgreSQL using psycopg 2
+
+Some time ago someone asked on the psycopg mailing list how to have a
+bound variable expand to the right SQL for an SELECT IN clause:
+
+    SELECT * FROM atable WHERE afield IN (value1, value2, value3)
+
+with the values to be used in the IN clause to be passed to the cursor
+.execute() method in a tuple as a bound variable, i.e.:
+
+    in_values = ("value1", "value2", "value3")
+    curs.execute("SELECT ... IN %s", (in_values,))
+
+psycopg 1 does support typecasting from Python to PostgreSQL (and back)
+only for simple types and this problem has no elegant solution (short or
+writing a wrapper class returning the pre-quoted text in an __str__
+method.
+
+But psycopg 2 offers a simple and elegant solution by partially
+implementing the Object Adaptation from PEP 246. psycopg 2 (still in
+beta and currently labeled as 1.99.9) moves the type-casting logic into
+external adapters and a somehow broken adapt() function.
+
+While the original adapt() takes 3 arguments, psycopg's one only takes
+1: the bound variable to be adapted. The result is an object supporting
+a not-yet well defined protocol that we can call IPsycopgSQLQuote:
+
+    class IPsycopgSQLQuote:
+
+        def getquoted(self):
+            "Returns a quoted string representing the bound variable."
+
+	def getbinary(self):
+	    "Returns a binary quoted string representing the bound variable."
+	    
+	def getbuffer(self):
+            "Returns the wrapped object itself."
+
+        __str__ = getquoted
+
+Then one of the functions (usually .getquoted()) is called by psycopg at
+the right time to obtain the right, sql-quoted representation for the
+corresponding bound variable.
+
+The nice part is that the default, built-in adapters, derived from
+psycopg 1 tyecasting code can be overridden by the programmer, simply
+replacing them in the psycopg.extensions.adapters dictionary.
+
+Then the solution to the original problem is now obvious: write an
+adapter that adapts tuple objects into the right SQL string, by calling
+recursively adapt() on each element.
+
+Note: psycopg 2 adapter code is still very young and will probably move
+to a more 'standard' (3 arguments) implementation for the adapt()
+function; as long as that does not slow down too much query execution.
+
+Psycopg 2 development can be tracked on the psycopg mailing list:
+
+   http://lists.initd.org/mailman/listinfo/psycopg
+
+and on the psycopg 2 wiki:
+
+   http://wiki.initd.org/Projects/Psycopg2
+
+"""
+
+import psycopg
+import psycopg.extensions
+from psycopg.extensions import adapt as psycoadapt
+from psycopg.extensions import register_adapter
+
+class AsIs(object):
+    """An adapter that just return the object 'as is'.
+
+    psycopg 1.99.9 has some optimizations that make impossible to call
+    adapt() without adding some basic adapters externally. This limitation
+    will be lifted in a future release.
+    """
+    def __init__(self, obj):
+        self.__obj = obj
+    def getquoted(self):
+        return self.__obj
+    
+class SQL_IN(object):
+    """Adapt a tuple to an SQL quotable object."""
+    
+    def __init__(self, seq):
+	self._seq = seq
+
+    def prepare(self, conn):
+        pass
+
+    def getquoted(self):
+        # this is the important line: note how every object in the
+        # list is adapted and then how getquoted() is called on it
+
+	qobjs = [str(psycoadapt(o).getquoted()) for o in self._seq]
+
+	return '(' + ', '.join(qobjs) + ')'
+	
+    __str__ = getquoted
+
+    
+# add our new adapter class to psycopg list of adapters
+register_adapter(tuple, SQL_IN)
+register_adapter(float, AsIs)
+register_adapter(int, AsIs)
+
+# usually we would call:
+#
+#     conn = psycopg.connect("...")
+#     curs = conn.cursor()
+#     curs.execute("SELECT ...", (("this", "is", "the", "tuple"),))
+#     
+# but we have no connection to a database right now, so we just check
+# the SQL_IN class by calling psycopg's adapt() directly:
+
+if __name__ == '__main__':
+    print "Note how the string will be SQL-quoted, but the number will not:"
+    print psycoadapt(("this is an 'sql quoted' str\\ing", 1, 2.0))

examples/simple.py

@@ -0,0 +1,52 @@
+# simple.py - very simple example of plain DBAPI-2.0 usage
+# currently used as test-me-stress-me script for psycopg 2.0
+#
+# Copyright (C) 2001-2003 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below this line (except for experimenting)
+
+class SimpleQuoter(object):
+    def sqlquote(x=None):
+        return "'bar'"
+
+import sys, psycopg
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+print "Encoding for this connection is", conn.encoding
+
+curs = conn.cursor()
+curs.execute("SELECT 1 AS foo")
+print curs.fetchone()
+curs.execute("SELECT 1 AS foo")
+print curs.fetchmany()
+curs.execute("SELECT 1 AS foo")
+print curs.fetchall()
+
+conn.rollback()
+
+sys.exit(0)
+
+curs.execute("SELECT 1 AS foo", async=1)
+
+curs.execute("SELECT %(foo)s AS foo", {'foo':'bar'})
+curs.execute("SELECT %(foo)s AS foo", {'foo':None})
+curs.execute("SELECT %(foo)f AS foo", {'foo':42})
+curs.execute("SELECT %(foo)s AS foo", {'foo':SimpleQuoter()})

examples/threads.py

@@ -0,0 +1,160 @@
+# threads.py -- example of multiple threads using psycopg
+# -*- encoding: latin1 -*-
+#
+# Copyright (C) 2001-2004 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## some others parameters
+INSERT_THREADS = ('A', 'B', 'C')
+SELECT_THREADS = ('1', '2')
+
+ROWS = 1000
+
+COMMIT_STEP = 20
+SELECT_SIZE = 10000
+SELECT_STEP = 500
+SELECT_DIV  = 250
+
+# the available modes are:
+# 0 - one connection for all insert and one for all select threads
+# 1 - connections generated using the connection pool
+
+MODE = 1
+
+## don't modify anything below tis line (except for experimenting)
+
+import sys, psycopg, threading
+from psycopg.pool import ThreadedConnectionPool
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+if len(sys.argv) > 2:
+    MODE = int(sys.argv[2])
+    
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+curs = conn.cursor()
+
+try:
+    curs.execute("""CREATE TABLE test_threads (
+                        name text, value1 int4, value2 float)""")
+except:
+    conn.rollback()
+    curs.execute("DROP TABLE test_threads")
+    curs.execute("""CREATE TABLE test_threads (
+                        name text, value1 int4, value2 float)""")
+conn.commit()
+
+
+## this function inserts a big number of rows and creates and destroys
+## a large number of cursors
+
+def insert_func(conn_or_pool, rows):
+    name = threading.currentThread().getName()
+
+    if MODE == 0:
+        conn = conn_or_pool
+    else:
+        conn = conn_or_pool.getconn()
+        
+    for i in range(rows):
+        if divmod(i, COMMIT_STEP)[1] == 0:
+            conn.commit()
+            if MODE == 1:
+                conn_or_pool.putconn(conn)
+            s = name + ": COMMIT STEP " + str(i)
+            print s
+            if MODE == 1:
+                conn = conn_or_pool.getconn()
+        c = conn.cursor()
+        try:
+            c.execute("INSERT INTO test_threads VALUES (%s, %d, %f)",
+                      (str(i), i, float(i)))
+        except psycopg.ProgrammingError, err:
+            print name, ": an error occurred; skipping this insert"
+            print err
+    conn.commit()
+
+## a nice select function that prints the current number of rows in the
+## database (and transefer them, putting some pressure on the network)
+    
+def select_func(conn_or_pool, z):
+    name = threading.currentThread().getName()
+
+    if MODE == 0:
+        conn = conn_or_pool
+        conn.set_isolation_level(0)
+    
+    for i in range(SELECT_SIZE):
+        if divmod(i, SELECT_STEP)[1] == 0:
+            try:
+                if MODE == 1:
+                    conn = conn_or_pool.getconn()
+                    conn.set_isolation_level(0)
+                c = conn.cursor()
+                c.execute("SELECT * FROM test_threads WHERE value2 < %s",
+                          (int(i/z),))
+                l = c.fetchall()
+                if MODE == 1:
+                    conn_or_pool.putconn(conn)
+                s = name + ": number of rows fetched: " + str(len(l))
+                print s
+            except psycopg.ProgrammingError, err:
+                print name, ": an error occurred; skipping this select"
+                print err
+
+## create the connection pool or the connections
+if MODE == 0:
+    conn_insert = psycopg.connect(DSN)
+    conn_select = psycopg.connect(DSN)
+else:
+    m = len(INSERT_THREADS) + len(SELECT_THREADS)
+    n = m/2
+    conn_insert = conn_select = ThreadedConnectionPool(n, m, DSN)
+    
+## create the threads
+threads = []
+
+print "Creating INSERT threads:"
+for name in INSERT_THREADS:
+    t = threading.Thread(None, insert_func, 'Thread-'+name,
+                         (conn_insert, ROWS))
+    t.setDaemon(0)
+    threads.append(t)
+
+print "Creating SELECT threads:"
+for name in SELECT_THREADS:
+    t = threading.Thread(None, select_func, 'Thread-'+name,
+                         (conn_select, SELECT_DIV))
+    t.setDaemon(0)
+    threads.append(t)
+
+## really start the threads now
+for t in threads:
+    t.start()
+
+# and wait for them to finish
+for t in threads:
+    t.join()
+    print t.getName(), "exited OK"
+
+
+conn.commit()
+curs.execute("SELECT count(name) FROM test_threads")
+print "Inserted", curs.fetchone()[0], "rows."
+
+curs.execute("DROP TABLE test_threads")
+conn.commit()

examples/tz.py

@@ -0,0 +1,62 @@
+# tz.py - example of datetime objects with time zones
+# -*- encoding: latin1 -*-
+#
+# Copyright (C) 2004 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below this line (except for experimenting)
+
+import sys, psycopg
+import datetime
+
+from psycopg.tz import ZERO, LOCAL, FixedOffsetTimezone
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+curs = conn.cursor()
+
+try:
+    curs.execute("CREATE TABLE test_tz (t timestamp with time zone)")
+except:
+    conn.rollback()
+    curs.execute("DROP TABLE test_tz")
+    curs.execute("CREATE TABLE test_tz (t timestamp with time zone)")
+conn.commit()
+
+d = datetime.datetime(1971, 10, 19, 22, 30, 0, tzinfo=LOCAL)
+curs.execute("INSERT INTO test_tz VALUES (%s)", (d,))
+print "Inserted timestamp with timezone:", d
+print "Time zone:", d.tzinfo.tzname(d), "offset:", d.tzinfo.utcoffset(d)
+
+tz = FixedOffsetTimezone(-5*60, "EST")
+d = datetime.datetime(1971, 10, 19, 22, 30, 0, tzinfo=tz)
+curs.execute("INSERT INTO test_tz VALUES (%s)", (d,))
+print "Inserted timestamp with timezone:", d
+print "Time zone:", d.tzinfo.tzname(d), "offset:", d.tzinfo.utcoffset(d)
+
+curs.tzinfo_factory = FixedOffsetTimezone
+curs.execute("SELECT * FROM test_tz")
+for d in curs:
+    u = d[0].utcoffset() or ZERO
+    print "UTC time:  ", d[0] - u 
+    print "Local time:", d[0]
+    print "Time zone:", d[0].tzinfo.tzname(d[0]), d[0].tzinfo.utcoffset(d[0])
+    
+curs.execute("DROP TABLE test_tz")
+conn.commit()

examples/usercast.py

@@ -0,0 +1,125 @@
+# usercast.py -- example of user defined typecasters
+# -*- encoding: latin-1 -*-
+#
+# Copyright (C) 2001-2005 Federico Di Gregorio  <fog@debian.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+
+## put in DSN your DSN string
+
+DSN = 'dbname=test'
+
+## don't modify anything below tis line (except for experimenting)
+
+import sys, psycopg
+import psycopg.extensions
+import whrandom
+
+# importing psycopg.extras will give us a nice tuple adapter: this is wrong
+# because the adapter is meant to be used in SQL IN clauses while we use
+# tuples to represent points but it works and the example is about Rect, not
+# "Point"
+import psycopg.extras
+
+if len(sys.argv) > 1:
+    DSN = sys.argv[1]
+
+print "Opening connection using dns:", DSN
+conn = psycopg.connect(DSN)
+print "Initial encoding for this connection is", conn.encoding
+
+curs = conn.cursor()
+try:
+    curs.execute("CREATE TABLE test_cast (p1 point, p2 point, b box)")
+except:
+    conn.rollback()
+    curs.execute("DROP TABLE test_cast")
+    curs.execute("CREATE TABLE test_cast (p1 point, p2 point, b box)")
+conn.commit()
+
+# this is the callable object we use as a typecast (the typecast is
+# usually a function, but we use a class, just to demonstrate the
+# flexibility of the psycopg casting system
+
+class Rect(object):
+    """Very simple rectangle.
+
+    Note that we use this type as a data holder, as an adapter of itself for
+    the ISQLQuote protocol used by psycopg's adapt() (see __confrom__ below)
+    and eventually as a type-caster for the data extracted from the database
+    (that's why __init__ takes the curs argument.)
+    """
+    
+    def __init__(self, s=None, curs=None):
+        """Init the rectangle from the optional string s."""
+        self.x = self.y = self.width = self.height = 0.0
+        if s: self.from_string(s)
+
+    def __conform__(self, proto):
+        """This is a terrible hack, just ignore proto and return self."""
+        if proto == psycopg.extensions.ISQLQuote:
+            return self
+    
+    def from_points(self, x0, y0, x1, y1):
+        """Init the rectangle from points."""
+        if x0 > x1: (x0, x1) = (x1, x0)
+        if y0 > y1: (y0, y1) = (y1, y0)
+        self.x = x0
+        self.y = y0
+        self.width = x1 - x0
+        self.height = y1 - y0
+
+    def from_string(self, s):
+        """Init the rectangle from a string."""
+        seq = eval(s)
+        self.from_points(seq[0][0], seq[0][1], seq[1][0], seq[1][1])
+
+    def getquoted(self):
+        """Format self as a string usable by the db to represent a box."""
+        s = "'((%d,%d),(%d,%d))'" % (
+            self.x, self.y, self.x + self.width, self.y + self.height)
+        return s
+
+    def show(self):
+        """Format a description of the box."""
+        s = "X: %d\tY: %d\tWidth: %d\tHeight: %d" % (
+            self.x, self.y, self.width, self.height)
+        return s
+    
+# here we select from the empty table, just to grab the description
+curs.execute("SELECT b FROM test_cast WHERE 0=1")
+boxoid = curs.description[0][1]
+print "Oid for the box datatype is", boxoid
+
+# and build the user cast object
+BOX = psycopg.extensions.new_type((boxoid,), "BOX", Rect)
+psycopg.extensions.register_type(BOX)
+
+# now insert 100 random data (2 points and a box in each row)
+for i in range(100):
+    p1 = (whrandom.randint(0,100), whrandom.randint(0,100))
+    p2 = (whrandom.randint(0,100), whrandom.randint(0,100))
+    b = Rect()
+    b.from_points(whrandom.randint(0,100), whrandom.randint(0,100),
+                  whrandom.randint(0,100), whrandom.randint(0,100))
+    curs.execute("INSERT INTO test_cast VALUES ('%(p1)s', '%(p2)s', %(box)s)",
+                 {'box':b, 'p1':p1, 'p2':p2})
+print "Added 100 boxed to the database"
+
+# select and print all boxes with at least one point inside
+curs.execute("SELECT b FROM test_cast WHERE p1 @ b OR p2 @ b")
+boxes = curs.fetchall()
+print "Found %d boxes with at least a point inside:" % len(boxes)
+for box in boxes:
+    print " ", box[0].show()
+
+curs.execute("DROP TABLE test_cast")
+conn.commit()

lib/__init__.py

@@ -1,126 +1,36 @@
 """A Python driver for PostgreSQL
 
-psycopg is a PostgreSQL_ database adapter for the Python_ programming
+psycopg is a PostgreSQL database adapter for the Python programming
 language. This is version 2, a complete rewrite of the original code to
 provide new-style classes for connection and cursor objects and other sweet
 candies. Like the original, psycopg 2 was written with the aim of being very
 small and fast, and stable as a rock.
-
-Homepage: https://psycopg.org/
-
-.. _PostgreSQL: https://www.postgresql.org/
-.. _Python: https://www.python.org/
-
-:Groups:
-  * `Connections creation`: connect
-  * `Value objects constructors`: Binary, Date, DateFromTicks, Time,
-    TimeFromTicks, Timestamp, TimestampFromTicks
 """
 # psycopg/__init__.py - initialization of the psycopg module
 #
-# Copyright (C) 2003-2019 Federico Di Gregorio  <fog@debian.org>
-# Copyright (C) 2020-2021 The Psycopg Team
+# Copyright (C) 2003-2004 Federico Di Gregorio  <fog@debian.org>
 #
-# psycopg2 is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2, or (at your option) any later
+# version.
 #
-# In addition, as a special exception, the copyright holders give
-# permission to link this program with the OpenSSL library (or with
-# modified versions of OpenSSL that use the same license as OpenSSL),
-# and distribute linked combinations including the two.
-#
-# You must obey the GNU Lesser General Public License in all respects for
-# all of the code used other than OpenSSL.
-#
-# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
-# License for more details.
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY
+# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
 
-# Import modules needed by _psycopg to allow tools like py2exe to do
-# their work without bothering about the module dependencies.
+__all__ = ['extensions', 'extras', 'tz', 'pool']
 
-# Note: the first internal import should be _psycopg, otherwise the real cause
-# of a failed loading of the C module may get hidden, see
-# https://archives.postgresql.org/psycopg/2011-02/msg00044.php
+# import the DBAPI-2.0 stuff into top-level module
+from _psycopg import BINARY, NUMBER, STRING, DATETIME, ROWID
 
-# Import the DBAPI-2.0 stuff into top-level module.
+from _psycopg import Binary, Date, Time, Timestamp
+from _psycopg import DateFromTicks, TimeFromTicks, TimestampFromTicks
 
-from psycopg2._psycopg import (                     # noqa
-    BINARY, NUMBER, STRING, DATETIME, ROWID,
+from _psycopg import Error, Warning, DataError, DatabaseError, ProgrammingError
+from _psycopg import IntegrityError, InterfaceError, InternalError
+from _psycopg import NotSupportedError, OperationalError
 
-    Binary, Date, Time, Timestamp,
-    DateFromTicks, TimeFromTicks, TimestampFromTicks,
-
-    Error, Warning, DataError, DatabaseError, ProgrammingError, IntegrityError,
-    InterfaceError, InternalError, NotSupportedError, OperationalError,
-
-    _connect, apilevel, threadsafety, paramstyle,
-    __version__, __libpq_version__,
-)
-
-
-# Register default adapters.
-
-from psycopg2 import extensions as _ext
-_ext.register_adapter(tuple, _ext.SQL_IN)
-_ext.register_adapter(type(None), _ext.NoneAdapter)
-
-# Register the Decimal adapter here instead of in the C layer.
-# This way a new class is registered for each sub-interpreter.
-# See ticket #52
-from decimal import Decimal                         # noqa
-from psycopg2._psycopg import Decimal as Adapter    # noqa
-_ext.register_adapter(Decimal, Adapter)
-del Decimal, Adapter
-
-
-def connect(dsn=None, connection_factory=None, cursor_factory=None, **kwargs):
-    """
-    Create a new database connection.
-
-    The connection parameters can be specified as a string:
-
-        conn = psycopg2.connect("dbname=test user=postgres password=secret")
-
-    or using a set of keyword arguments:
-
-        conn = psycopg2.connect(database="test", user="postgres", password="secret")
-
-    Or as a mix of both. The basic connection parameters are:
-
-    - *dbname*: the database name
-    - *database*: the database name (only as keyword argument)
-    - *user*: user name used to authenticate
-    - *password*: password used to authenticate
-    - *host*: database host address (defaults to UNIX socket if not provided)
-    - *port*: connection port number (defaults to 5432 if not provided)
-
-    Using the *connection_factory* parameter a different class or connections
-    factory can be specified. It should be a callable object taking a dsn
-    argument.
-
-    Using the *cursor_factory* parameter, a new default cursor factory will be
-    used by cursor().
-
-    Using *async*=True an asynchronous connection will be created. *async_* is
-    a valid alias (for Python versions where ``async`` is a keyword).
-
-    Any other keyword parameter will be passed to the underlying client
-    library: the list of supported parameters depends on the library version.
-
-    """
-    kwasync = {}
-    if 'async' in kwargs:
-        kwasync['async'] = kwargs.pop('async')
-    if 'async_' in kwargs:
-        kwasync['async_'] = kwargs.pop('async_')
-
-    dsn = _ext.make_dsn(dsn, **kwargs)
-    conn = _connect(dsn, connection_factory=connection_factory, **kwasync)
-    if cursor_factory is not None:
-        conn.cursor_factory = cursor_factory
-
-    return conn
+from _psycopg import connect, apilevel, threadsafety, paramstyle
+from _psycopg import __version__

lib/_ipaddress.py

@@ -1,90 +0,0 @@
-"""Implementation of the ipaddres-based network types adaptation
-"""
-
-# psycopg/_ipaddress.py - Ipaddres-based network types adaptation
-#
-# Copyright (C) 2016-2019 Daniele Varrazzo  <daniele.varrazzo@gmail.com>
-# Copyright (C) 2020-2021 The Psycopg Team
-#
-# psycopg2 is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# In addition, as a special exception, the copyright holders give
-# permission to link this program with the OpenSSL library (or with
-# modified versions of OpenSSL that use the same license as OpenSSL),
-# and distribute linked combinations including the two.
-#
-# You must obey the GNU Lesser General Public License in all respects for
-# all of the code used other than OpenSSL.
-#
-# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
-# License for more details.
-
-from psycopg2.extensions import (
-    new_type, new_array_type, register_type, register_adapter, QuotedString)
-
-# The module is imported on register_ipaddress
-ipaddress = None
-
-# The typecasters are created only once
-_casters = None
-
-
-def register_ipaddress(conn_or_curs=None):
-    """
-    Register conversion support between `ipaddress` objects and `network types`__.
-
-    :param conn_or_curs: the scope where to register the type casters.
-        If `!None` register them globally.
-
-    After the function is called, PostgreSQL :sql:`inet` values will be
-    converted into `~ipaddress.IPv4Interface` or `~ipaddress.IPv6Interface`
-    objects, :sql:`cidr` values into into `~ipaddress.IPv4Network` or
-    `~ipaddress.IPv6Network`.
-
-    .. __: https://www.postgresql.org/docs/current/static/datatype-net-types.html
-    """
-    global ipaddress
-    import ipaddress
-
-    global _casters
-    if _casters is None:
-        _casters = _make_casters()
-
-    for c in _casters:
-        register_type(c, conn_or_curs)
-
-    for t in [ipaddress.IPv4Interface, ipaddress.IPv6Interface,
-              ipaddress.IPv4Network, ipaddress.IPv6Network]:
-        register_adapter(t, adapt_ipaddress)
-
-
-def _make_casters():
-    inet = new_type((869,), 'INET', cast_interface)
-    ainet = new_array_type((1041,), 'INET[]', inet)
-
-    cidr = new_type((650,), 'CIDR', cast_network)
-    acidr = new_array_type((651,), 'CIDR[]', cidr)
-
-    return [inet, ainet, cidr, acidr]
-
-
-def cast_interface(s, cur=None):
-    if s is None:
-        return None
-    # Py2 version force the use of unicode. meh.
-    return ipaddress.ip_interface(str(s))
-
-
-def cast_network(s, cur=None):
-    if s is None:
-        return None
-    return ipaddress.ip_network(str(s))
-
-
-def adapt_ipaddress(obj):
-    return QuotedString(str(obj))

lib/_json.py

@@ -1,199 +0,0 @@
-"""Implementation of the JSON adaptation objects
-
-This module exists to avoid a circular import problem: pyscopg2.extras depends
-on psycopg2.extension, so I can't create the default JSON typecasters in
-extensions importing register_json from extras.
-"""
-
-# psycopg/_json.py - Implementation of the JSON adaptation objects
-#
-# Copyright (C) 2012-2019 Daniele Varrazzo  <daniele.varrazzo@gmail.com>
-# Copyright (C) 2020-2021 The Psycopg Team
-#
-# psycopg2 is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# In addition, as a special exception, the copyright holders give
-# permission to link this program with the OpenSSL library (or with
-# modified versions of OpenSSL that use the same license as OpenSSL),
-# and distribute linked combinations including the two.
-#
-# You must obey the GNU Lesser General Public License in all respects for
-# all of the code used other than OpenSSL.
-#
-# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
-# License for more details.
-
-import json
-
-from psycopg2._psycopg import ISQLQuote, QuotedString
-from psycopg2._psycopg import new_type, new_array_type, register_type
-
-
-# oids from PostgreSQL 9.2
-JSON_OID = 114
-JSONARRAY_OID = 199
-
-# oids from PostgreSQL 9.4
-JSONB_OID = 3802
-JSONBARRAY_OID = 3807
-
-
-class Json:
-    """
-    An `~psycopg2.extensions.ISQLQuote` wrapper to adapt a Python object to
-    :sql:`json` data type.
-
-    `!Json` can be used to wrap any object supported by the provided *dumps*
-    function. If none is provided, the standard :py:func:`json.dumps()` is
-    used.
-
-    """
-    def __init__(self, adapted, dumps=None):
-        self.adapted = adapted
-        self._conn = None
-        self._dumps = dumps or json.dumps
-
-    def __conform__(self, proto):
-        if proto is ISQLQuote:
-            return self
-
-    def dumps(self, obj):
-        """Serialize *obj* in JSON format.
-
-        The default is to call `!json.dumps()` or the *dumps* function
-        provided in the constructor. You can override this method to create a
-        customized JSON wrapper.
-        """
-        return self._dumps(obj)
-
-    def prepare(self, conn):
-        self._conn = conn
-
-    def getquoted(self):
-        s = self.dumps(self.adapted)
-        qs = QuotedString(s)
-        if self._conn is not None:
-            qs.prepare(self._conn)
-        return qs.getquoted()
-
-    def __str__(self):
-        # getquoted is binary
-        return self.getquoted().decode('ascii', 'replace')
-
-
-def register_json(conn_or_curs=None, globally=False, loads=None,
-                  oid=None, array_oid=None, name='json'):
-    """Create and register typecasters converting :sql:`json` type to Python objects.
-
-    :param conn_or_curs: a connection or cursor used to find the :sql:`json`
-        and :sql:`json[]` oids; the typecasters are registered in a scope
-        limited to this object, unless *globally* is set to `!True`. It can be
-        `!None` if the oids are provided
-    :param globally: if `!False` register the typecasters only on
-        *conn_or_curs*, otherwise register them globally
-    :param loads: the function used to parse the data into a Python object. If
-        `!None` use `!json.loads()`, where `!json` is the module chosen
-        according to the Python version (see above)
-    :param oid: the OID of the :sql:`json` type if known; If not, it will be
-        queried on *conn_or_curs*
-    :param array_oid: the OID of the :sql:`json[]` array type if known;
-        if not, it will be queried on *conn_or_curs*
-    :param name: the name of the data type to look for in *conn_or_curs*
-
-    The connection or cursor passed to the function will be used to query the
-    database and look for the OID of the :sql:`json` type (or an alternative
-    type if *name* if provided). No query is performed if *oid* and *array_oid*
-    are provided.  Raise `~psycopg2.ProgrammingError` if the type is not found.
-
-    """
-    if oid is None:
-        oid, array_oid = _get_json_oids(conn_or_curs, name)
-
-    JSON, JSONARRAY = _create_json_typecasters(
-        oid, array_oid, loads=loads, name=name.upper())
-
-    register_type(JSON, not globally and conn_or_curs or None)
-
-    if JSONARRAY is not None:
-        register_type(JSONARRAY, not globally and conn_or_curs or None)
-
-    return JSON, JSONARRAY
-
-
-def register_default_json(conn_or_curs=None, globally=False, loads=None):
-    """
-    Create and register :sql:`json` typecasters for PostgreSQL 9.2 and following.
-
-    Since PostgreSQL 9.2 :sql:`json` is a builtin type, hence its oid is known
-    and fixed. This function allows specifying a customized *loads* function
-    for the default :sql:`json` type without querying the database.
-    All the parameters have the same meaning of `register_json()`.
-    """
-    return register_json(conn_or_curs=conn_or_curs, globally=globally,
-        loads=loads, oid=JSON_OID, array_oid=JSONARRAY_OID)
-
-
-def register_default_jsonb(conn_or_curs=None, globally=False, loads=None):
-    """
-    Create and register :sql:`jsonb` typecasters for PostgreSQL 9.4 and following.
-
-    As in `register_default_json()`, the function allows to register a
-    customized *loads* function for the :sql:`jsonb` type at its known oid for
-    PostgreSQL 9.4 and following versions.  All the parameters have the same
-    meaning of `register_json()`.
-    """
-    return register_json(conn_or_curs=conn_or_curs, globally=globally,
-        loads=loads, oid=JSONB_OID, array_oid=JSONBARRAY_OID, name='jsonb')
-
-
-def _create_json_typecasters(oid, array_oid, loads=None, name='JSON'):
-    """Create typecasters for json data type."""
-    if loads is None:
-        loads = json.loads
-
-    def typecast_json(s, cur):
-        if s is None:
-            return None
-        return loads(s)
-
-    JSON = new_type((oid, ), name, typecast_json)
-    if array_oid is not None:
-        JSONARRAY = new_array_type((array_oid, ), f"{name}ARRAY", JSON)
-    else:
-        JSONARRAY = None
-
-    return JSON, JSONARRAY
-
-
-def _get_json_oids(conn_or_curs, name='json'):
-    # lazy imports
-    from psycopg2.extensions import STATUS_IN_TRANSACTION
-    from psycopg2.extras import _solve_conn_curs
-
-    conn, curs = _solve_conn_curs(conn_or_curs)
-
-    # Store the transaction status of the connection to revert it after use
-    conn_status = conn.status
-
-    # column typarray not available before PG 8.3
-    typarray = conn.info.server_version >= 80300 and "typarray" or "NULL"
-
-    # get the oid for the hstore
-    curs.execute(
-        "SELECT t.oid, %s FROM pg_type t WHERE t.typname = %%s;"
-        % typarray, (name,))
-    r = curs.fetchone()
-
-    # revert the status of the connection as before the command
-    if conn_status != STATUS_IN_TRANSACTION and not conn.autocommit:
-        conn.rollback()
-
-    if not r:
-        raise conn.ProgrammingError(f"{name} data type not found")
-
-    return r

lib/_range.py

@@ -1,554 +0,0 @@
-"""Implementation of the Range type and adaptation
-
-"""
-
-# psycopg/_range.py - Implementation of the Range type and adaptation
-#
-# Copyright (C) 2012-2019 Daniele Varrazzo  <daniele.varrazzo@gmail.com>
-# Copyright (C) 2020-2021 The Psycopg Team
-#
-# psycopg2 is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# In addition, as a special exception, the copyright holders give
-# permission to link this program with the OpenSSL library (or with
-# modified versions of OpenSSL that use the same license as OpenSSL),
-# and distribute linked combinations including the two.
-#
-# You must obey the GNU Lesser General Public License in all respects for
-# all of the code used other than OpenSSL.
-#
-# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
-# License for more details.
-
-import re
-
-from psycopg2._psycopg import ProgrammingError, InterfaceError
-from psycopg2.extensions import ISQLQuote, adapt, register_adapter
-from psycopg2.extensions import new_type, new_array_type, register_type
-
-
-class Range:
-    """Python representation for a PostgreSQL |range|_ type.
-
-    :param lower: lower bound for the range. `!None` means unbound
-    :param upper: upper bound for the range. `!None` means unbound
-    :param bounds: one of the literal strings ``()``, ``[)``, ``(]``, ``[]``,
-        representing whether the lower or upper bounds are included
-    :param empty: if `!True`, the range is empty
-
-    """
-    __slots__ = ('_lower', '_upper', '_bounds')
-
-    def __init__(self, lower=None, upper=None, bounds='[)', empty=False):
-        if not empty:
-            if bounds not in ('[)', '(]', '()', '[]'):
-                raise ValueError(f"bound flags not valid: {bounds!r}")
-
-            self._lower = lower
-            self._upper = upper
-            self._bounds = bounds
-        else:
-            self._lower = self._upper = self._bounds = None
-
-    def __repr__(self):
-        if self._bounds is None:
-            return f"{self.__class__.__name__}(empty=True)"
-        else:
-            return "{}({!r}, {!r}, {!r})".format(self.__class__.__name__,
-                self._lower, self._upper, self._bounds)
-
-    def __str__(self):
-        if self._bounds is None:
-            return 'empty'
-
-        items = [
-            self._bounds[0],
-            str(self._lower),
-            ', ',
-            str(self._upper),
-            self._bounds[1]
-        ]
-        return ''.join(items)
-
-    @property
-    def lower(self):
-        """The lower bound of the range. `!None` if empty or unbound."""
-        return self._lower
-
-    @property
-    def upper(self):
-        """The upper bound of the range. `!None` if empty or unbound."""
-        return self._upper
-
-    @property
-    def isempty(self):
-        """`!True` if the range is empty."""
-        return self._bounds is None
-
-    @property
-    def lower_inf(self):
-        """`!True` if the range doesn't have a lower bound."""
-        if self._bounds is None:
-            return False
-        return self._lower is None
-
-    @property
-    def upper_inf(self):
-        """`!True` if the range doesn't have an upper bound."""
-        if self._bounds is None:
-            return False
-        return self._upper is None
-
-    @property
-    def lower_inc(self):
-        """`!True` if the lower bound is included in the range."""
-        if self._bounds is None or self._lower is None:
-            return False
-        return self._bounds[0] == '['
-
-    @property
-    def upper_inc(self):
-        """`!True` if the upper bound is included in the range."""
-        if self._bounds is None or self._upper is None:
-            return False
-        return self._bounds[1] == ']'
-
-    def __contains__(self, x):
-        if self._bounds is None:
-            return False
-
-        if self._lower is not None:
-            if self._bounds[0] == '[':
-                if x < self._lower:
-                    return False
-            else:
-                if x <= self._lower:
-                    return False
-
-        if self._upper is not None:
-            if self._bounds[1] == ']':
-                if x > self._upper:
-                    return False
-            else:
-                if x >= self._upper:
-                    return False
-
-        return True
-
-    def __bool__(self):
-        return self._bounds is not None
-
-    def __eq__(self, other):
-        if not isinstance(other, Range):
-            return False
-        return (self._lower == other._lower
-            and self._upper == other._upper
-            and self._bounds == other._bounds)
-
-    def __ne__(self, other):
-        return not self.__eq__(other)
-
-    def __hash__(self):
-        return hash((self._lower, self._upper, self._bounds))
-
-    # as the postgres docs describe for the server-side stuff,
-    # ordering is rather arbitrary, but will remain stable
-    # and consistent.
-
-    def __lt__(self, other):
-        if not isinstance(other, Range):
-            return NotImplemented
-        for attr in ('_lower', '_upper', '_bounds'):
-            self_value = getattr(self, attr)
-            other_value = getattr(other, attr)
-            if self_value == other_value:
-                pass
-            elif self_value is None:
-                return True
-            elif other_value is None:
-                return False
-            else:
-                return self_value < other_value
-        return False
-
-    def __le__(self, other):
-        if self == other:
-            return True
-        else:
-            return self.__lt__(other)
-
-    def __gt__(self, other):
-        if isinstance(other, Range):
-            return other.__lt__(self)
-        else:
-            return NotImplemented
-
-    def __ge__(self, other):
-        if self == other:
-            return True
-        else:
-            return self.__gt__(other)
-
-    def __getstate__(self):
-        return {slot: getattr(self, slot)
-            for slot in self.__slots__ if hasattr(self, slot)}
-
-    def __setstate__(self, state):
-        for slot, value in state.items():
-            setattr(self, slot, value)
-
-
-def register_range(pgrange, pyrange, conn_or_curs, globally=False):
-    """Create and register an adapter and the typecasters to convert between
-    a PostgreSQL |range|_ type and a PostgreSQL `Range` subclass.
-
-    :param pgrange: the name of the PostgreSQL |range| type. Can be
-        schema-qualified
-    :param pyrange: a `Range` strict subclass, or just a name to give to a new
-        class
-    :param conn_or_curs: a connection or cursor used to find the oid of the
-        range and its subtype; the typecaster is registered in a scope limited
-        to this object, unless *globally* is set to `!True`
-    :param globally: if `!False` (default) register the typecaster only on
-        *conn_or_curs*, otherwise register it globally
-    :return: `RangeCaster` instance responsible for the conversion
-
-    If a string is passed to *pyrange*, a new `Range` subclass is created
-    with such name and will be available as the `~RangeCaster.range` attribute
-    of the returned `RangeCaster` object.
-
-    The function queries the database on *conn_or_curs* to inspect the
-    *pgrange* type and raises `~psycopg2.ProgrammingError` if the type is not
-    found.  If querying the database is not advisable, use directly the
-    `RangeCaster` class and register the adapter and typecasters using the
-    provided functions.
-
-    """
-    caster = RangeCaster._from_db(pgrange, pyrange, conn_or_curs)
-    caster._register(not globally and conn_or_curs or None)
-    return caster
-
-
-class RangeAdapter:
-    """`ISQLQuote` adapter for `Range` subclasses.
-
-    This is an abstract class: concrete classes must set a `name` class
-    attribute or override `getquoted()`.
-    """
-    name = None
-
-    def __init__(self, adapted):
-        self.adapted = adapted
-
-    def __conform__(self, proto):
-        if self._proto is ISQLQuote:
-            return self
-
-    def prepare(self, conn):
-        self._conn = conn
-
-    def getquoted(self):
-        if self.name is None:
-            raise NotImplementedError(
-                'RangeAdapter must be subclassed overriding its name '
-                'or the getquoted() method')
-
-        r = self.adapted
-        if r.isempty:
-            return b"'empty'::" + self.name.encode('utf8')
-
-        if r.lower is not None:
-            a = adapt(r.lower)
-            if hasattr(a, 'prepare'):
-                a.prepare(self._conn)
-            lower = a.getquoted()
-        else:
-            lower = b'NULL'
-
-        if r.upper is not None:
-            a = adapt(r.upper)
-            if hasattr(a, 'prepare'):
-                a.prepare(self._conn)
-            upper = a.getquoted()
-        else:
-            upper = b'NULL'
-
-        return self.name.encode('utf8') + b'(' + lower + b', ' + upper \
-            + b", '" + r._bounds.encode('utf8') + b"')"
-
-
-class RangeCaster:
-    """Helper class to convert between `Range` and PostgreSQL range types.
-
-    Objects of this class are usually created by `register_range()`. Manual
-    creation could be useful if querying the database is not advisable: in
-    this case the oids must be provided.
-    """
-    def __init__(self, pgrange, pyrange, oid, subtype_oid, array_oid=None):
-        self.subtype_oid = subtype_oid
-        self._create_ranges(pgrange, pyrange)
-
-        name = self.adapter.name or self.adapter.__class__.__name__
-
-        self.typecaster = new_type((oid,), name, self.parse)
-
-        if array_oid is not None:
-            self.array_typecaster = new_array_type(
-                (array_oid,), name + "ARRAY", self.typecaster)
-        else:
-            self.array_typecaster = None
-
-    def _create_ranges(self, pgrange, pyrange):
-        """Create Range and RangeAdapter classes if needed."""
-        # if got a string create a new RangeAdapter concrete type (with a name)
-        # else take it as an adapter. Passing an adapter should be considered
-        # an implementation detail and is not documented. It is currently used
-        # for the numeric ranges.
-        self.adapter = None
-        if isinstance(pgrange, str):
-            self.adapter = type(pgrange, (RangeAdapter,), {})
-            self.adapter.name = pgrange
-        else:
-            try:
-                if issubclass(pgrange, RangeAdapter) \
-                        and pgrange is not RangeAdapter:
-                    self.adapter = pgrange
-            except TypeError:
-                pass
-
-        if self.adapter is None:
-            raise TypeError(
-                'pgrange must be a string or a RangeAdapter strict subclass')
-
-        self.range = None
-        try:
-            if isinstance(pyrange, str):
-                self.range = type(pyrange, (Range,), {})
-            if issubclass(pyrange, Range) and pyrange is not Range:
-                self.range = pyrange
-        except TypeError:
-            pass
-
-        if self.range is None:
-            raise TypeError(
-                'pyrange must be a type or a Range strict subclass')
-
-    @classmethod
-    def _from_db(self, name, pyrange, conn_or_curs):
-        """Return a `RangeCaster` instance for the type *pgrange*.
-
-        Raise `ProgrammingError` if the type is not found.
-        """
-        from psycopg2.extensions import STATUS_IN_TRANSACTION
-        from psycopg2.extras import _solve_conn_curs
-        conn, curs = _solve_conn_curs(conn_or_curs)
-
-        if conn.info.server_version < 90200:
-            raise ProgrammingError("range types not available in version %s"
-                % conn.info.server_version)
-
-        # Store the transaction status of the connection to revert it after use
-        conn_status = conn.status
-
-        # Use the correct schema
-        if '.' in name:
-            schema, tname = name.split('.', 1)
-        else:
-            tname = name
-            schema = 'public'
-
-        # get the type oid and attributes
-        curs.execute("""\
-select rngtypid, rngsubtype, typarray
-from pg_range r
-join pg_type t on t.oid = rngtypid
-join pg_namespace ns on ns.oid = typnamespace
-where typname = %s and ns.nspname = %s;
-""", (tname, schema))
-        rec = curs.fetchone()
-
-        if not rec:
-            # The above algorithm doesn't work for customized seach_path
-            # (#1487) The implementation below works better, but, to guarantee
-            # backwards compatibility, use it only if the original one failed.
-            try:
-                savepoint = False
-                # Because we executed statements earlier, we are either INTRANS
-                # or we are IDLE only if the transaction is autocommit, in
-                # which case we don't need the savepoint anyway.
-                if conn.status == STATUS_IN_TRANSACTION:
-                    curs.execute("SAVEPOINT register_type")
-                    savepoint = True
-
-                curs.execute("""\
-SELECT rngtypid, rngsubtype, typarray, typname, nspname
-from pg_range r
-join pg_type t on t.oid = rngtypid
-join pg_namespace ns on ns.oid = typnamespace
-WHERE t.oid = %s::regtype
-""", (name, ))
-            except ProgrammingError:
-                pass
-            else:
-                rec = curs.fetchone()
-                if rec:
-                    tname, schema = rec[3:]
-            finally:
-                if savepoint:
-                    curs.execute("ROLLBACK TO SAVEPOINT register_type")
-
-        # revert the status of the connection as before the command
-        if conn_status != STATUS_IN_TRANSACTION and not conn.autocommit:
-            conn.rollback()
-
-        if not rec:
-            raise ProgrammingError(
-                f"PostgreSQL range '{name}' not found")
-
-        type, subtype, array = rec[:3]
-
-        return RangeCaster(name, pyrange,
-            oid=type, subtype_oid=subtype, array_oid=array)
-
-    _re_range = re.compile(r"""
-        ( \(|\[ )                   # lower bound flag
-        (?:                         # lower bound:
-          " ( (?: [^"] | "")* ) "   #   - a quoted string
-          | ( [^",]+ )              #   - or an unquoted string
-        )?                          #   - or empty (not catched)
-        ,
-        (?:                         # upper bound:
-          " ( (?: [^"] | "")* ) "   #   - a quoted string
-          | ( [^"\)\]]+ )           #   - or an unquoted string
-        )?                          #   - or empty (not catched)
-        ( \)|\] )                   # upper bound flag
-        """, re.VERBOSE)
-
-    _re_undouble = re.compile(r'(["\\])\1')
-
-    def parse(self, s, cur=None):
-        if s is None:
-            return None
-
-        if s == 'empty':
-            return self.range(empty=True)
-
-        m = self._re_range.match(s)
-        if m is None:
-            raise InterfaceError(f"failed to parse range: '{s}'")
-
-        lower = m.group(3)
-        if lower is None:
-            lower = m.group(2)
-            if lower is not None:
-                lower = self._re_undouble.sub(r"\1", lower)
-
-        upper = m.group(5)
-        if upper is None:
-            upper = m.group(4)
-            if upper is not None:
-                upper = self._re_undouble.sub(r"\1", upper)
-
-        if cur is not None:
-            lower = cur.cast(self.subtype_oid, lower)
-            upper = cur.cast(self.subtype_oid, upper)
-
-        bounds = m.group(1) + m.group(6)
-
-        return self.range(lower, upper, bounds)
-
-    def _register(self, scope=None):
-        register_type(self.typecaster, scope)
-        if self.array_typecaster is not None:
-            register_type(self.array_typecaster, scope)
-
-        register_adapter(self.range, self.adapter)
-
-
-class NumericRange(Range):
-    """A `Range` suitable to pass Python numeric types to a PostgreSQL range.
-
-    PostgreSQL types :sql:`int4range`, :sql:`int8range`, :sql:`numrange` are
-    casted into `!NumericRange` instances.
-    """
-    pass
-
-
-class DateRange(Range):
-    """Represents :sql:`daterange` values."""
-    pass
-
-
-class DateTimeRange(Range):
-    """Represents :sql:`tsrange` values."""
-    pass
-
-
-class DateTimeTZRange(Range):
-    """Represents :sql:`tstzrange` values."""
-    pass
-
-
-# Special adaptation for NumericRange. Allows to pass number range regardless
-# of whether they are ints, floats and what size of ints are, which are
-# pointless in Python world. On the way back, no numeric range is casted to
-# NumericRange, but only to their subclasses
-
-class NumberRangeAdapter(RangeAdapter):
-    """Adapt a range if the subtype doesn't need quotes."""
-    def getquoted(self):
-        r = self.adapted
-        if r.isempty:
-            return b"'empty'"
-
-        if not r.lower_inf:
-            # not exactly: we are relying that none of these object is really
-            # quoted (they are numbers). Also, I'm lazy and not preparing the
-            # adapter because I assume encoding doesn't matter for these
-            # objects.
-            lower = adapt(r.lower).getquoted().decode('ascii')
-        else:
-            lower = ''
-
-        if not r.upper_inf:
-            upper = adapt(r.upper).getquoted().decode('ascii')
-        else:
-            upper = ''
-
-        return (f"'{r._bounds[0]}{lower},{upper}{r._bounds[1]}'").encode('ascii')
-
-
-# TODO: probably won't work with infs, nans and other tricky cases.
-register_adapter(NumericRange, NumberRangeAdapter)
-
-# Register globally typecasters and adapters for builtin range types.
-
-# note: the adapter is registered more than once, but this is harmless.
-int4range_caster = RangeCaster(NumberRangeAdapter, NumericRange,
-    oid=3904, subtype_oid=23, array_oid=3905)
-int4range_caster._register()
-
-int8range_caster = RangeCaster(NumberRangeAdapter, NumericRange,
-    oid=3926, subtype_oid=20, array_oid=3927)
-int8range_caster._register()
-
-numrange_caster = RangeCaster(NumberRangeAdapter, NumericRange,
-    oid=3906, subtype_oid=1700, array_oid=3907)
-numrange_caster._register()
-
-daterange_caster = RangeCaster('daterange', DateRange,
-    oid=3912, subtype_oid=1082, array_oid=3913)
-daterange_caster._register()
-
-tsrange_caster = RangeCaster('tsrange', DateTimeRange,
-    oid=3908, subtype_oid=1114, array_oid=3909)
-tsrange_caster._register()
-
-tstzrange_caster = RangeCaster('tstzrange', DateTimeTZRange,
-    oid=3910, subtype_oid=1184, array_oid=3911)
-tstzrange_caster._register()

lib/errorcodes.py

@@ -1,450 +0,0 @@
-"""Error codes for PostgreSQL
-
-This module contains symbolic names for all PostgreSQL error codes.
-"""
-# psycopg2/errorcodes.py - PostgreSQL error codes
-#
-# Copyright (C) 2006-2019 Johan Dahlin  <jdahlin@async.com.br>
-# Copyright (C) 2020-2021 The Psycopg Team
-#
-# psycopg2 is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# In addition, as a special exception, the copyright holders give
-# permission to link this program with the OpenSSL library (or with
-# modified versions of OpenSSL that use the same license as OpenSSL),
-# and distribute linked combinations including the two.
-#
-# You must obey the GNU Lesser General Public License in all respects for
-# all of the code used other than OpenSSL.
-#
-# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
-# License for more details.
-#
-# Based on:
-#
-#   https://www.postgresql.org/docs/current/static/errcodes-appendix.html
-#
-
-
-def lookup(code, _cache={}):
-    """Lookup an error code or class code and return its symbolic name.
-
-    Raise `KeyError` if the code is not found.
-    """
-    if _cache:
-        return _cache[code]
-
-    # Generate the lookup map at first usage.
-    tmp = {}
-    for k, v in globals().items():
-        if isinstance(v, str) and len(v) in (2, 5):
-            # Strip trailing underscore used to disambiguate duplicate values
-            tmp[v] = k.rstrip("_")
-
-    assert tmp
-
-    # Atomic update, to avoid race condition on import (bug #382)
-    _cache.update(tmp)
-
-    return _cache[code]
-
-
-# autogenerated data: do not edit below this point.
-
-# Error classes
-CLASS_SUCCESSFUL_COMPLETION = '00'
-CLASS_WARNING = '01'
-CLASS_NO_DATA = '02'
-CLASS_SQL_STATEMENT_NOT_YET_COMPLETE = '03'
-CLASS_CONNECTION_EXCEPTION = '08'
-CLASS_TRIGGERED_ACTION_EXCEPTION = '09'
-CLASS_FEATURE_NOT_SUPPORTED = '0A'
-CLASS_INVALID_TRANSACTION_INITIATION = '0B'
-CLASS_LOCATOR_EXCEPTION = '0F'
-CLASS_INVALID_GRANTOR = '0L'
-CLASS_INVALID_ROLE_SPECIFICATION = '0P'
-CLASS_DIAGNOSTICS_EXCEPTION = '0Z'
-CLASS_CASE_NOT_FOUND = '20'
-CLASS_CARDINALITY_VIOLATION = '21'
-CLASS_DATA_EXCEPTION = '22'
-CLASS_INTEGRITY_CONSTRAINT_VIOLATION = '23'
-CLASS_INVALID_CURSOR_STATE = '24'
-CLASS_INVALID_TRANSACTION_STATE = '25'
-CLASS_INVALID_SQL_STATEMENT_NAME = '26'
-CLASS_TRIGGERED_DATA_CHANGE_VIOLATION = '27'
-CLASS_INVALID_AUTHORIZATION_SPECIFICATION = '28'
-CLASS_DEPENDENT_PRIVILEGE_DESCRIPTORS_STILL_EXIST = '2B'
-CLASS_INVALID_TRANSACTION_TERMINATION = '2D'
-CLASS_SQL_ROUTINE_EXCEPTION = '2F'
-CLASS_INVALID_CURSOR_NAME = '34'
-CLASS_EXTERNAL_ROUTINE_EXCEPTION = '38'
-CLASS_EXTERNAL_ROUTINE_INVOCATION_EXCEPTION = '39'
-CLASS_SAVEPOINT_EXCEPTION = '3B'
-CLASS_INVALID_CATALOG_NAME = '3D'
-CLASS_INVALID_SCHEMA_NAME = '3F'
-CLASS_TRANSACTION_ROLLBACK = '40'
-CLASS_SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION = '42'
-CLASS_WITH_CHECK_OPTION_VIOLATION = '44'
-CLASS_INSUFFICIENT_RESOURCES = '53'
-CLASS_PROGRAM_LIMIT_EXCEEDED = '54'
-CLASS_OBJECT_NOT_IN_PREREQUISITE_STATE = '55'
-CLASS_OPERATOR_INTERVENTION = '57'
-CLASS_SYSTEM_ERROR = '58'
-CLASS_SNAPSHOT_FAILURE = '72'
-CLASS_CONFIGURATION_FILE_ERROR = 'F0'
-CLASS_FOREIGN_DATA_WRAPPER_ERROR = 'HV'
-CLASS_PL_PGSQL_ERROR = 'P0'
-CLASS_INTERNAL_ERROR = 'XX'
-
-# Class 00 - Successful Completion
-SUCCESSFUL_COMPLETION = '00000'
-
-# Class 01 - Warning
-WARNING = '01000'
-NULL_VALUE_ELIMINATED_IN_SET_FUNCTION = '01003'
-STRING_DATA_RIGHT_TRUNCATION_ = '01004'
-PRIVILEGE_NOT_REVOKED = '01006'
-PRIVILEGE_NOT_GRANTED = '01007'
-IMPLICIT_ZERO_BIT_PADDING = '01008'
-DYNAMIC_RESULT_SETS_RETURNED = '0100C'
-DEPRECATED_FEATURE = '01P01'
-
-# Class 02 - No Data (this is also a warning class per the SQL standard)
-NO_DATA = '02000'
-NO_ADDITIONAL_DYNAMIC_RESULT_SETS_RETURNED = '02001'
-
-# Class 03 - SQL Statement Not Yet Complete
-SQL_STATEMENT_NOT_YET_COMPLETE = '03000'
-
-# Class 08 - Connection Exception
-CONNECTION_EXCEPTION = '08000'
-SQLCLIENT_UNABLE_TO_ESTABLISH_SQLCONNECTION = '08001'
-CONNECTION_DOES_NOT_EXIST = '08003'
-SQLSERVER_REJECTED_ESTABLISHMENT_OF_SQLCONNECTION = '08004'
-CONNECTION_FAILURE = '08006'
-TRANSACTION_RESOLUTION_UNKNOWN = '08007'
-PROTOCOL_VIOLATION = '08P01'
-
-# Class 09 - Triggered Action Exception
-TRIGGERED_ACTION_EXCEPTION = '09000'
-
-# Class 0A - Feature Not Supported
-FEATURE_NOT_SUPPORTED = '0A000'
-
-# Class 0B - Invalid Transaction Initiation
-INVALID_TRANSACTION_INITIATION = '0B000'
-
-# Class 0F - Locator Exception
-LOCATOR_EXCEPTION = '0F000'
-INVALID_LOCATOR_SPECIFICATION = '0F001'
-
-# Class 0L - Invalid Grantor
-INVALID_GRANTOR = '0L000'
-INVALID_GRANT_OPERATION = '0LP01'
-
-# Class 0P - Invalid Role Specification
-INVALID_ROLE_SPECIFICATION = '0P000'
-
-# Class 0Z - Diagnostics Exception
-DIAGNOSTICS_EXCEPTION = '0Z000'
-STACKED_DIAGNOSTICS_ACCESSED_WITHOUT_ACTIVE_HANDLER = '0Z002'
-
-# Class 20 - Case Not Found
-CASE_NOT_FOUND = '20000'
-
-# Class 21 - Cardinality Violation
-CARDINALITY_VIOLATION = '21000'
-
-# Class 22 - Data Exception
-DATA_EXCEPTION = '22000'
-STRING_DATA_RIGHT_TRUNCATION = '22001'
-NULL_VALUE_NO_INDICATOR_PARAMETER = '22002'
-NUMERIC_VALUE_OUT_OF_RANGE = '22003'
-NULL_VALUE_NOT_ALLOWED_ = '22004'
-ERROR_IN_ASSIGNMENT = '22005'
-INVALID_DATETIME_FORMAT = '22007'
-DATETIME_FIELD_OVERFLOW = '22008'
-INVALID_TIME_ZONE_DISPLACEMENT_VALUE = '22009'
-ESCAPE_CHARACTER_CONFLICT = '2200B'
-INVALID_USE_OF_ESCAPE_CHARACTER = '2200C'
-INVALID_ESCAPE_OCTET = '2200D'
-ZERO_LENGTH_CHARACTER_STRING = '2200F'
-MOST_SPECIFIC_TYPE_MISMATCH = '2200G'
-SEQUENCE_GENERATOR_LIMIT_EXCEEDED = '2200H'
-NOT_AN_XML_DOCUMENT = '2200L'
-INVALID_XML_DOCUMENT = '2200M'
-INVALID_XML_CONTENT = '2200N'
-INVALID_XML_COMMENT = '2200S'
-INVALID_XML_PROCESSING_INSTRUCTION = '2200T'
-INVALID_INDICATOR_PARAMETER_VALUE = '22010'
-SUBSTRING_ERROR = '22011'
-DIVISION_BY_ZERO = '22012'
-INVALID_PRECEDING_OR_FOLLOWING_SIZE = '22013'
-INVALID_ARGUMENT_FOR_NTILE_FUNCTION = '22014'
-INTERVAL_FIELD_OVERFLOW = '22015'
-INVALID_ARGUMENT_FOR_NTH_VALUE_FUNCTION = '22016'
-INVALID_CHARACTER_VALUE_FOR_CAST = '22018'
-INVALID_ESCAPE_CHARACTER = '22019'
-INVALID_REGULAR_EXPRESSION = '2201B'
-INVALID_ARGUMENT_FOR_LOGARITHM = '2201E'
-INVALID_ARGUMENT_FOR_POWER_FUNCTION = '2201F'
-INVALID_ARGUMENT_FOR_WIDTH_BUCKET_FUNCTION = '2201G'
-INVALID_ROW_COUNT_IN_LIMIT_CLAUSE = '2201W'
-INVALID_ROW_COUNT_IN_RESULT_OFFSET_CLAUSE = '2201X'
-INVALID_LIMIT_VALUE = '22020'
-CHARACTER_NOT_IN_REPERTOIRE = '22021'
-INDICATOR_OVERFLOW = '22022'
-INVALID_PARAMETER_VALUE = '22023'
-UNTERMINATED_C_STRING = '22024'
-INVALID_ESCAPE_SEQUENCE = '22025'
-STRING_DATA_LENGTH_MISMATCH = '22026'
-TRIM_ERROR = '22027'
-ARRAY_SUBSCRIPT_ERROR = '2202E'
-INVALID_TABLESAMPLE_REPEAT = '2202G'
-INVALID_TABLESAMPLE_ARGUMENT = '2202H'
-DUPLICATE_JSON_OBJECT_KEY_VALUE = '22030'
-INVALID_ARGUMENT_FOR_SQL_JSON_DATETIME_FUNCTION = '22031'
-INVALID_JSON_TEXT = '22032'
-INVALID_SQL_JSON_SUBSCRIPT = '22033'
-MORE_THAN_ONE_SQL_JSON_ITEM = '22034'
-NO_SQL_JSON_ITEM = '22035'
-NON_NUMERIC_SQL_JSON_ITEM = '22036'
-NON_UNIQUE_KEYS_IN_A_JSON_OBJECT = '22037'
-SINGLETON_SQL_JSON_ITEM_REQUIRED = '22038'
-SQL_JSON_ARRAY_NOT_FOUND = '22039'
-SQL_JSON_MEMBER_NOT_FOUND = '2203A'
-SQL_JSON_NUMBER_NOT_FOUND = '2203B'
-SQL_JSON_OBJECT_NOT_FOUND = '2203C'
-TOO_MANY_JSON_ARRAY_ELEMENTS = '2203D'
-TOO_MANY_JSON_OBJECT_MEMBERS = '2203E'
-SQL_JSON_SCALAR_REQUIRED = '2203F'
-SQL_JSON_ITEM_CANNOT_BE_CAST_TO_TARGET_TYPE = '2203G'
-FLOATING_POINT_EXCEPTION = '22P01'
-INVALID_TEXT_REPRESENTATION = '22P02'
-INVALID_BINARY_REPRESENTATION = '22P03'
-BAD_COPY_FILE_FORMAT = '22P04'
-UNTRANSLATABLE_CHARACTER = '22P05'
-NONSTANDARD_USE_OF_ESCAPE_CHARACTER = '22P06'
-
-# Class 23 - Integrity Constraint Violation
-INTEGRITY_CONSTRAINT_VIOLATION = '23000'
-RESTRICT_VIOLATION = '23001'
-NOT_NULL_VIOLATION = '23502'
-FOREIGN_KEY_VIOLATION = '23503'
-UNIQUE_VIOLATION = '23505'
-CHECK_VIOLATION = '23514'
-EXCLUSION_VIOLATION = '23P01'
-
-# Class 24 - Invalid Cursor State
-INVALID_CURSOR_STATE = '24000'
-
-# Class 25 - Invalid Transaction State
-INVALID_TRANSACTION_STATE = '25000'
-ACTIVE_SQL_TRANSACTION = '25001'
-BRANCH_TRANSACTION_ALREADY_ACTIVE = '25002'
-INAPPROPRIATE_ACCESS_MODE_FOR_BRANCH_TRANSACTION = '25003'
-INAPPROPRIATE_ISOLATION_LEVEL_FOR_BRANCH_TRANSACTION = '25004'
-NO_ACTIVE_SQL_TRANSACTION_FOR_BRANCH_TRANSACTION = '25005'
-READ_ONLY_SQL_TRANSACTION = '25006'
-SCHEMA_AND_DATA_STATEMENT_MIXING_NOT_SUPPORTED = '25007'
-HELD_CURSOR_REQUIRES_SAME_ISOLATION_LEVEL = '25008'
-NO_ACTIVE_SQL_TRANSACTION = '25P01'
-IN_FAILED_SQL_TRANSACTION = '25P02'
-IDLE_IN_TRANSACTION_SESSION_TIMEOUT = '25P03'
-TRANSACTION_TIMEOUT = '25P04'
-
-# Class 26 - Invalid SQL Statement Name
-INVALID_SQL_STATEMENT_NAME = '26000'
-
-# Class 27 - Triggered Data Change Violation
-TRIGGERED_DATA_CHANGE_VIOLATION = '27000'
-
-# Class 28 - Invalid Authorization Specification
-INVALID_AUTHORIZATION_SPECIFICATION = '28000'
-INVALID_PASSWORD = '28P01'
-
-# Class 2B - Dependent Privilege Descriptors Still Exist
-DEPENDENT_PRIVILEGE_DESCRIPTORS_STILL_EXIST = '2B000'
-DEPENDENT_OBJECTS_STILL_EXIST = '2BP01'
-
-# Class 2D - Invalid Transaction Termination
-INVALID_TRANSACTION_TERMINATION = '2D000'
-
-# Class 2F - SQL Routine Exception
-SQL_ROUTINE_EXCEPTION = '2F000'
-MODIFYING_SQL_DATA_NOT_PERMITTED_ = '2F002'
-PROHIBITED_SQL_STATEMENT_ATTEMPTED_ = '2F003'
-READING_SQL_DATA_NOT_PERMITTED_ = '2F004'
-FUNCTION_EXECUTED_NO_RETURN_STATEMENT = '2F005'
-
-# Class 34 - Invalid Cursor Name
-INVALID_CURSOR_NAME = '34000'
-
-# Class 38 - External Routine Exception
-EXTERNAL_ROUTINE_EXCEPTION = '38000'
-CONTAINING_SQL_NOT_PERMITTED = '38001'
-MODIFYING_SQL_DATA_NOT_PERMITTED = '38002'
-PROHIBITED_SQL_STATEMENT_ATTEMPTED = '38003'
-READING_SQL_DATA_NOT_PERMITTED = '38004'
-
-# Class 39 - External Routine Invocation Exception
-EXTERNAL_ROUTINE_INVOCATION_EXCEPTION = '39000'
-INVALID_SQLSTATE_RETURNED = '39001'
-NULL_VALUE_NOT_ALLOWED = '39004'
-TRIGGER_PROTOCOL_VIOLATED = '39P01'
-SRF_PROTOCOL_VIOLATED = '39P02'
-EVENT_TRIGGER_PROTOCOL_VIOLATED = '39P03'
-
-# Class 3B - Savepoint Exception
-SAVEPOINT_EXCEPTION = '3B000'
-INVALID_SAVEPOINT_SPECIFICATION = '3B001'
-
-# Class 3D - Invalid Catalog Name
-INVALID_CATALOG_NAME = '3D000'
-
-# Class 3F - Invalid Schema Name
-INVALID_SCHEMA_NAME = '3F000'
-
-# Class 40 - Transaction Rollback
-TRANSACTION_ROLLBACK = '40000'
-SERIALIZATION_FAILURE = '40001'
-TRANSACTION_INTEGRITY_CONSTRAINT_VIOLATION = '40002'
-STATEMENT_COMPLETION_UNKNOWN = '40003'
-DEADLOCK_DETECTED = '40P01'
-
-# Class 42 - Syntax Error or Access Rule Violation
-SYNTAX_ERROR_OR_ACCESS_RULE_VIOLATION = '42000'
-INSUFFICIENT_PRIVILEGE = '42501'
-SYNTAX_ERROR = '42601'
-INVALID_NAME = '42602'
-INVALID_COLUMN_DEFINITION = '42611'
-NAME_TOO_LONG = '42622'
-DUPLICATE_COLUMN = '42701'
-AMBIGUOUS_COLUMN = '42702'
-UNDEFINED_COLUMN = '42703'
-UNDEFINED_OBJECT = '42704'
-DUPLICATE_OBJECT = '42710'
-DUPLICATE_ALIAS = '42712'
-DUPLICATE_FUNCTION = '42723'
-AMBIGUOUS_FUNCTION = '42725'
-GROUPING_ERROR = '42803'
-DATATYPE_MISMATCH = '42804'
-WRONG_OBJECT_TYPE = '42809'
-INVALID_FOREIGN_KEY = '42830'
-CANNOT_COERCE = '42846'
-UNDEFINED_FUNCTION = '42883'
-GENERATED_ALWAYS = '428C9'
-RESERVED_NAME = '42939'
-UNDEFINED_TABLE = '42P01'
-UNDEFINED_PARAMETER = '42P02'
-DUPLICATE_CURSOR = '42P03'
-DUPLICATE_DATABASE = '42P04'
-DUPLICATE_PREPARED_STATEMENT = '42P05'
-DUPLICATE_SCHEMA = '42P06'
-DUPLICATE_TABLE = '42P07'
-AMBIGUOUS_PARAMETER = '42P08'
-AMBIGUOUS_ALIAS = '42P09'
-INVALID_COLUMN_REFERENCE = '42P10'
-INVALID_CURSOR_DEFINITION = '42P11'
-INVALID_DATABASE_DEFINITION = '42P12'
-INVALID_FUNCTION_DEFINITION = '42P13'
-INVALID_PREPARED_STATEMENT_DEFINITION = '42P14'
-INVALID_SCHEMA_DEFINITION = '42P15'
-INVALID_TABLE_DEFINITION = '42P16'
-INVALID_OBJECT_DEFINITION = '42P17'
-INDETERMINATE_DATATYPE = '42P18'
-INVALID_RECURSION = '42P19'
-WINDOWING_ERROR = '42P20'
-COLLATION_MISMATCH = '42P21'
-INDETERMINATE_COLLATION = '42P22'
-
-# Class 44 - WITH CHECK OPTION Violation
-WITH_CHECK_OPTION_VIOLATION = '44000'
-
-# Class 53 - Insufficient Resources
-INSUFFICIENT_RESOURCES = '53000'
-DISK_FULL = '53100'
-OUT_OF_MEMORY = '53200'
-TOO_MANY_CONNECTIONS = '53300'
-CONFIGURATION_LIMIT_EXCEEDED = '53400'
-
-# Class 54 - Program Limit Exceeded
-PROGRAM_LIMIT_EXCEEDED = '54000'
-STATEMENT_TOO_COMPLEX = '54001'
-TOO_MANY_COLUMNS = '54011'
-TOO_MANY_ARGUMENTS = '54023'
-
-# Class 55 - Object Not In Prerequisite State
-OBJECT_NOT_IN_PREREQUISITE_STATE = '55000'
-OBJECT_IN_USE = '55006'
-CANT_CHANGE_RUNTIME_PARAM = '55P02'
-LOCK_NOT_AVAILABLE = '55P03'
-UNSAFE_NEW_ENUM_VALUE_USAGE = '55P04'
-
-# Class 57 - Operator Intervention
-OPERATOR_INTERVENTION = '57000'
-QUERY_CANCELED = '57014'
-ADMIN_SHUTDOWN = '57P01'
-CRASH_SHUTDOWN = '57P02'
-CANNOT_CONNECT_NOW = '57P03'
-DATABASE_DROPPED = '57P04'
-IDLE_SESSION_TIMEOUT = '57P05'
-
-# Class 58 - System Error (errors external to PostgreSQL itself)
-SYSTEM_ERROR = '58000'
-IO_ERROR = '58030'
-UNDEFINED_FILE = '58P01'
-DUPLICATE_FILE = '58P02'
-
-# Class 72 - Snapshot Failure
-SNAPSHOT_TOO_OLD = '72000'
-
-# Class F0 - Configuration File Error
-CONFIG_FILE_ERROR = 'F0000'
-LOCK_FILE_EXISTS = 'F0001'
-
-# Class HV - Foreign Data Wrapper Error (SQL/MED)
-FDW_ERROR = 'HV000'
-FDW_OUT_OF_MEMORY = 'HV001'
-FDW_DYNAMIC_PARAMETER_VALUE_NEEDED = 'HV002'
-FDW_INVALID_DATA_TYPE = 'HV004'
-FDW_COLUMN_NAME_NOT_FOUND = 'HV005'
-FDW_INVALID_DATA_TYPE_DESCRIPTORS = 'HV006'
-FDW_INVALID_COLUMN_NAME = 'HV007'
-FDW_INVALID_COLUMN_NUMBER = 'HV008'
-FDW_INVALID_USE_OF_NULL_POINTER = 'HV009'
-FDW_INVALID_STRING_FORMAT = 'HV00A'
-FDW_INVALID_HANDLE = 'HV00B'
-FDW_INVALID_OPTION_INDEX = 'HV00C'
-FDW_INVALID_OPTION_NAME = 'HV00D'
-FDW_OPTION_NAME_NOT_FOUND = 'HV00J'
-FDW_REPLY_HANDLE = 'HV00K'
-FDW_UNABLE_TO_CREATE_EXECUTION = 'HV00L'
-FDW_UNABLE_TO_CREATE_REPLY = 'HV00M'
-FDW_UNABLE_TO_ESTABLISH_CONNECTION = 'HV00N'
-FDW_NO_SCHEMAS = 'HV00P'
-FDW_SCHEMA_NOT_FOUND = 'HV00Q'
-FDW_TABLE_NOT_FOUND = 'HV00R'
-FDW_FUNCTION_SEQUENCE_ERROR = 'HV010'
-FDW_TOO_MANY_HANDLES = 'HV014'
-FDW_INCONSISTENT_DESCRIPTOR_INFORMATION = 'HV021'
-FDW_INVALID_ATTRIBUTE_VALUE = 'HV024'
-FDW_INVALID_STRING_LENGTH_OR_BUFFER_LENGTH = 'HV090'
-FDW_INVALID_DESCRIPTOR_FIELD_IDENTIFIER = 'HV091'
-
-# Class P0 - PL/pgSQL Error
-PLPGSQL_ERROR = 'P0000'
-RAISE_EXCEPTION = 'P0001'
-NO_DATA_FOUND = 'P0002'
-TOO_MANY_ROWS = 'P0003'
-ASSERT_FAILURE = 'P0004'
-
-# Class XX - Internal Error
-INTERNAL_ERROR = 'XX000'
-DATA_CORRUPTED = 'XX001'
-INDEX_CORRUPTED = 'XX002'

lib/errors.py

@@ -1,38 +0,0 @@
-"""Error classes for PostgreSQL error codes
-"""
-
-# psycopg/errors.py - SQLSTATE and DB-API exceptions
-#
-# Copyright (C) 2018-2019 Daniele Varrazzo  <daniele.varrazzo@gmail.com>
-# Copyright (C) 2020-2021 The Psycopg Team
-#
-# psycopg2 is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published
-# by the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# In addition, as a special exception, the copyright holders give
-# permission to link this program with the OpenSSL library (or with
-# modified versions of OpenSSL that use the same license as OpenSSL),
-# and distribute linked combinations including the two.
-#
-# You must obey the GNU Lesser General Public License in all respects for
-# all of the code used other than OpenSSL.
-#
-# psycopg2 is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
-# License for more details.
-
-#
-# NOTE: the exceptions are injected into this module by the C extention.
-#
-
-
-def lookup(code):
-    """Lookup an error code and return its exception class.
-
-    Raise `!KeyError` if the code is not found.
-    """
-    from psycopg2._psycopg import sqlstate_errors   # avoid circular import
-    return sqlstate_errors[code]