Skip to content

Commit 807ed3e

Browse files
CitoCito
committed
deploy: 550305f 
0 parents  commit 807ed3e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

90 files changed

+25554
-0
lines changed

Diff for: ‎.buildinfo

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Sphinx build info version 1
2+
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: 0b41de128ce3b17b3c6ecf852a3396b9
4+
tags: 645f666f9bcd5a90fca523b33c5a78b7

Diff for: ‎.nojekyll

Whitespace-only changes.

Diff for: ‎CNAME

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pygresql.org

Diff for: ‎_sources/about.rst.txt

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
About PyGreSQL
2+
==============
3+
4+
**PyGreSQL** is an *open-source* `Python <http://www.python.org>`_ module
5+
that interfaces to a `PostgreSQL <http://www.postgresql.org>`_ database.
6+
It wraps the lower level C API library libpq to allow easy use of the
7+
powerful PostgreSQL features from Python.
8+
9+
| This software is copyright © 1995, Pascal Andre.
10+
| Further modifications are copyright © 1997-2008 by D'Arcy J.M. Cain.
11+
| Further modifications are copyright © 2009-2024 by the PyGreSQL team.
12+
| For licensing details, see the full :doc:`copyright`.
13+
14+
**PostgreSQL** is a highly scalable, SQL compliant, open source
15+
object-relational database management system. With more than 20 years
16+
of development history, it is quickly becoming the de facto database
17+
for enterprise level open source solutions.
18+
Best of all, PostgreSQL's source code is available under the most liberal
19+
open source license: the BSD license.
20+
21+
**Python** Python is an interpreted, interactive, object-oriented
22+
programming language. It is often compared to Tcl, Perl, Scheme or Java.
23+
Python combines remarkable power with very clear syntax. It has modules,
24+
classes, exceptions, very high level dynamic data types, and dynamic typing.
25+
There are interfaces to many system calls and libraries, as well as to
26+
various windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules
27+
are easily written in C or C++. Python is also usable as an extension
28+
language for applications that need a programmable interface.
29+
The Python implementation is copyrighted but freely usable and distributable,
30+
even for commercial use.
31+
32+
**PyGreSQL** is a Python module that interfaces to a PostgreSQL database.
33+
It wraps the lower level C API library libpq to allow easy use of the
34+
powerful PostgreSQL features from Python.
35+
36+
PyGreSQL is developed and tested on a NetBSD system, but it also runs on
37+
most other platforms where PostgreSQL and Python is running. It is based
38+
on the PyGres95 code written by Pascal Andre ([email protected]).
39+
D'Arcy ([email protected]) renamed it to PyGreSQL starting with
40+
version 2.0 and serves as the "BDFL" of PyGreSQL.
41+
42+
The current version PyGreSQL |version| needs PostgreSQL 10 to 17, and Python
43+
3.7 to 3.13. If you need to support older PostgreSQL or Python versions,
44+
you can resort to the PyGreSQL 5.x versions that still support them.

Diff for: ‎_sources/community/index.rst.txt

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
PyGreSQL Development and Support
2+
================================
3+
4+
PyGreSQL is an open-source project created by a group of volunteers.
5+
The project and the development infrastructure are currently maintained
6+
by D'Arcy J.M. Cain. We would be glad to welcome more contributors
7+
so that PyGreSQL can be further developed, modernized and improved.
8+
9+
.. include:: mailinglist.rst
10+
11+
.. include:: source.rst
12+
13+
.. include:: issues.rst
14+
15+
.. include:: support.rst
16+
17+
.. include:: homes.rst

Diff for: ‎_sources/contents/changelog.rst.txt

+732
Large diffs are not rendered by default.

Diff for: ‎_sources/contents/examples.rst.txt

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Examples
2+
========
3+
4+
I am starting to collect examples of applications that use PyGreSQL.
5+
So far I only have a few but if you have an example for me, you can
6+
either send me the files or the URL for me to point to.
7+
8+
The :doc:`postgres/index` that is part of the PyGreSQL distribution
9+
shows some examples of using PostgreSQL with PyGreSQL.
10+
11+
Here is a
12+
`list of motorcycle rides in Ontario <http://ontario.bikerides.ca>`_
13+
that uses a PostgreSQL database to store the rides.
14+
There is a link at the bottom of the page to view the source code.
15+
16+
Oleg Broytmann has written a simple example
17+
`RGB database demo <http://phdru.name/Software/Python/#rgb_example>`_

Diff for: ‎_sources/contents/general.rst.txt

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
General PyGreSQL programming information
2+
----------------------------------------
3+
4+
PyGreSQL consists of two parts: the "classic" PyGreSQL interface
5+
provided by the :mod:`pg` module and the newer
6+
DB-API 2.0 compliant interface provided by the :mod:`pgdb` module.
7+
8+
If you use only the standard features of the DB-API 2.0 interface,
9+
it will be easier to switch from PostgreSQL to another database
10+
for which a DB-API 2.0 compliant interface exists.
11+
12+
The "classic" interface may be easier to use for beginners, and it
13+
provides some higher-level and PostgreSQL specific convenience methods.
14+
15+
.. seealso::
16+
17+
**DB-API 2.0** (Python Database API Specification v2.0)
18+
is a specification for connecting to databases (not only PostgreSQL)
19+
from Python that has been developed by the Python DB-SIG in 1999.
20+
The authoritative programming information for the DB-API is :pep:`0249`.
21+
22+
Both Python modules utilize the same low-level C extension, which
23+
serves as a wrapper for the "libpq" library, the C API to PostgreSQL.
24+
25+
This means you must have the libpq library installed as a shared library
26+
on your client computer, in a version that is supported by PyGreSQL.
27+
Depending on the client platform, you may have to set environment variables
28+
like `PATH` or `LD_LIBRARY_PATH` so that PyGreSQL can find the library.
29+
30+
.. warning::
31+
32+
Note that PyGreSQL is not thread-safe on the connection level. Therefore
33+
we recommend using `DBUtils <http://www.webwareforpython.org/DBUtils>`_
34+
for multi-threaded environments, which supports both PyGreSQL interfaces.
35+
36+
Another option is using PyGreSQL indirectly as a database driver for the
37+
high-level `SQLAlchemy <http://www.sqlalchemy.org/>`_ SQL toolkit and ORM,
38+
which supports PyGreSQL starting with SQLAlchemy 1.1 and which provides a
39+
way to use PyGreSQL in a multi-threaded environment using the concept of
40+
"thread local storage". Database URLs for PyGreSQL take this form::
41+
42+
postgresql+pygresql://username:password@host:port/database

Diff for: ‎_sources/contents/index.rst.txt

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
The PyGreSQL documentation
2+
==========================
3+
4+
Contents
5+
--------
6+
7+
.. toctree::
8+
:maxdepth: 1
9+
10+
Installing PyGreSQL <install>
11+
What's New and History of Changes <changelog>
12+
General PyGreSQL Programming Information <general>
13+
First Steps with PyGreSQL <tutorial>
14+
The Classic PyGreSQL Interface <pg/index>
15+
The DB-API Compliant Interface <pgdb/index>
16+
A PostgreSQL Primer <postgres/index>
17+
Examples for using PyGreSQL <examples>
18+
19+
Indices and tables
20+
------------------
21+
22+
* :ref:`genindex`
23+
* :ref:`modindex`
24+
* :ref:`search`

Diff for: ‎_sources/contents/install.rst.txt

+214
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
Installation
2+
============
3+
4+
General
5+
-------
6+
7+
You must first install Python and PostgreSQL on your system.
8+
If you want to access remote databases only, you don't need to install
9+
the full PostgreSQL server, but only the libpq C-interface library.
10+
On Windows, this library is called ``libpq.dll`` and is for instance contained
11+
in the PostgreSQL ODBC driver (search for "psqlodbc"). On Linux, it is called
12+
``libpq.so`` and usually provided in a package called "libpq" or "libpq5".
13+
On Windows, you also need to make sure that the directory that contains
14+
``libpq.dll`` is part of your ``PATH`` environment variable.
15+
16+
The current version of PyGreSQL has been tested with Python versions
17+
3.7 to 3.13, and PostgreSQL versions 10 to 17.
18+
19+
PyGreSQL will be installed as two packages named ``pg`` (for the classic
20+
interface) and ``pgdb`` (for the DB API 2 compliant interface). The former
21+
also contains a shared library called ``_pg.so`` (on Linux) or a DLL called
22+
``_pg.pyd`` (on Windows) and a stub file ``_pg.pyi`` for this library.
23+
24+
25+
Installing with Pip
26+
-------------------
27+
28+
This is the most easy way to install PyGreSQL if you have "pip" installed.
29+
Just run the following command in your terminal::
30+
31+
pip install PyGreSQL
32+
33+
This will automatically try to find and download a distribution on the
34+
`Python Package Index <https://pypi.python.org/>`_ that matches your operating
35+
system and Python version and install it.
36+
37+
Note that you still need to have the libpq interface installed on your system
38+
(see the general remarks above).
39+
40+
41+
Installing from a Binary Distribution
42+
-------------------------------------
43+
44+
If you don't want to use "pip", or "pip" doesn't find an appropriate
45+
distribution for your computer, you can also try to manually download
46+
and install a distribution.
47+
48+
When you download the source distribution, you will need to compile the
49+
C extension, for which you need a C compiler installed.
50+
If you don't want to install a C compiler or avoid possible problems
51+
with the compilation, you can search for a pre-compiled binary distribution
52+
of PyGreSQL on the Python Package Index or the PyGreSQL homepage.
53+
54+
You can currently download PyGreSQL as Linux RPM, NetBSD package and Windows
55+
installer. Make sure the required Python version of the binary package matches
56+
the Python version you have installed.
57+
58+
Install the package as usual on your system.
59+
60+
Note that the documentation is currently only included in the source package.
61+
62+
63+
Installing from Source
64+
----------------------
65+
66+
If you want to install PyGreSQL from Source, or there is no binary
67+
package available for your platform, follow these instructions.
68+
69+
Make sure the Python header files and PostgreSQL client and server header
70+
files are installed. These come usually with the "devel" packages on Unix
71+
systems and the installer executables on Windows systems.
72+
73+
If you are using a precompiled PostgreSQL, you will also need the pg_config
74+
tool. This is usually also part of the "devel" package on Unix, and will be
75+
installed as part of the database server feature on Windows systems.
76+
77+
Building and installing with Distutils
78+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79+
80+
You can build and install PyGreSQL using
81+
`Distutils <http://docs.python.org/install/>`_.
82+
83+
Download and unpack the PyGreSQL source tarball if you haven't already done so.
84+
85+
Type the following commands to build and install PyGreSQL::
86+
87+
python setup.py install
88+
89+
Now you should be ready to use PyGreSQL.
90+
91+
You can also run the build step separately if you want to create a distribution
92+
to be installed on a different system or explicitly enable or disable certain
93+
features. For instance, in order to build PyGreSQL without support for the
94+
memory size functions, run::
95+
96+
python setup.py build_ext --no-memory-size
97+
98+
By default, PyGreSQL is compiled with support for all features available in the
99+
installed PostgreSQL version, and you will get warnings for the features that
100+
are not supported in this version. You can also explicitly require a feature in
101+
order to get an error if it is not available, for instance:
102+
103+
python setup.py build_ext --memory-size
104+
105+
You can find out all possible build options with::
106+
107+
python setup.py build_ext --help
108+
109+
Alternatively, you can also use the corresponding C preprocessor macros like
110+
``MEMORY_SIZE`` directly (see the next section).
111+
112+
Note that if you build PyGreSQL with support for newer features that are not
113+
available in the PQLib installed on the runtime system, you may get an error
114+
when importing PyGreSQL, since these features are missing in the shared library
115+
which will prevent Python from loading it.
116+
117+
Compiling Manually
118+
~~~~~~~~~~~~~~~~~~
119+
120+
The source file for compiling the C extension module is pgmodule.c.
121+
You have two options. You can compile PyGreSQL as a stand-alone module
122+
or you can build it into the Python interpreter.
123+
124+
Stand-Alone
125+
^^^^^^^^^^^
126+
127+
* In the directory containing ``pgmodule.c``, run the following command::
128+
129+
cc -fpic -shared -o _pg.so -I$PYINC -I$PGINC -I$PSINC -L$PGLIB -lpq pgmodule.c
130+
131+
where you have to set::
132+
133+
PYINC = path to the Python include files
134+
(usually something like /usr/include/python)
135+
PGINC = path to the PostgreSQL client include files
136+
(something like /usr/include/pgsql or /usr/include/postgresql)
137+
PSINC = path to the PostgreSQL server include files
138+
(like /usr/include/pgsql/server or /usr/include/postgresql/server)
139+
PGLIB = path to the PostgreSQL object code libraries (usually /usr/lib)
140+
141+
If you are not sure about the above paths, try something like::
142+
143+
PYINC=`find /usr -name Python.h`
144+
PGINC=`find /usr -name libpq-fe.h`
145+
PSINC=`find /usr -name postgres.h`
146+
PGLIB=`find /usr -name libpq.so`
147+
148+
If you have the ``pg_config`` tool installed, you can set::
149+
150+
PGINC=`pg_config --includedir`
151+
PSINC=`pg_config --includedir-server`
152+
PGLIB=`pg_config --libdir`
153+
154+
Some options may be added to this line::
155+
156+
-DMEMORY_SIZE = support memory size function (PostgreSQL 12 or newer)
157+
158+
On some systems you may need to include ``-lcrypt`` in the list of libraries
159+
to make it compile.
160+
161+
* Test the new module. Something like the following should work::
162+
163+
$ python
164+
165+
>>> import _pg
166+
>>> db = _pg.connect('thilo','localhost')
167+
>>> db.query("INSERT INTO test VALUES ('ping','pong')")
168+
18304
169+
>>> db.query("SELECT * FROM test")
170+
eins|zwei
171+
----+----
172+
ping|pong
173+
(1 row)
174+
175+
* Finally, move the ``_pg.so``, ``pg.py``, and ``pgdb.py`` to a directory in
176+
your ``PYTHONPATH``. A good place would be ``/usr/lib/python/site-packages``
177+
if your Python modules are in ``/usr/lib/python``.
178+
179+
Built-in to Python interpreter
180+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
181+
182+
* Find the directory where your ``Setup`` file lives (usually in the ``Modules``
183+
subdirectory) in the Python source hierarchy and copy or symlink the
184+
``pgmodule.c`` file there.
185+
186+
* Add the following line to your 'Setup' file::
187+
188+
_pg pgmodule.c -I$PGINC -I$PSINC -L$PGLIB -lpq
189+
190+
where::
191+
192+
PGINC = path to the PostgreSQL client include files (see above)
193+
PSINC = path to the PostgreSQL server include files (see above)
194+
PGLIB = path to the PostgreSQL object code libraries (see above)
195+
196+
Some options may be added to this line::
197+
198+
-DMEMORY_SIZE = support memory size function (PostgreSQL 12 or newer)
199+
200+
On some systems you may need to include ``-lcrypt`` in the list of libraries
201+
to make it compile.
202+
203+
* If you want a shared module, make sure that the ``shared`` keyword is
204+
uncommented and add the above line below it. You used to need to install
205+
your shared modules with ``make sharedinstall`` but this no longer seems
206+
to be true.
207+
208+
* Copy ``pg.py`` to the lib directory where the rest of your modules are.
209+
For example, that's ``/usr/local/lib/Python`` on my system.
210+
211+
* Rebuild Python from the root directory of the Python source hierarchy by
212+
running ``make -f Makefile.pre.in boot`` and ``make && make install``.
213+
214+
* For more details read the documentation at the top of ``Makefile.pre.in``.

0 commit comments

Comments
 (0)