Skip to content

Commit 94a1664

Browse files
author
James William Pye
committed
Use package_data with explicit txt files for docs.
1 parent bcdf454 commit 94a1664

18 files changed

Lines changed: 2797 additions & 2873 deletions

File tree

‎postgresql/documentation/admin.py‎

Lines changed: 2 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -2,83 +2,7 @@
22
# copyright 2009, James William Pye
33
# http://python.projects.postgresql.org
44
##
5-
r"""
6-
Administration
7-
==============
8-
9-
This chapter covers the administration of py-postgresql. This includes
10-
installation and other aspects of working with py-postgresql such as
11-
environment variables and configuration files.
12-
13-
14-
Installation
15-
------------
16-
17-
py-postgresql uses Python's standard distutils package to manage the
18-
build and installation process of the package. The normal entry point for
19-
this is the ``setup.py`` script contained in the root project directory.
20-
21-
After extracting the archive and changing the into the project's directory,
22-
installation is normally as simple as::
23-
24-
$ python3 ./setup.py install
25-
26-
However, if you need to install for use with a particular version of python,
27-
just use the path of the executable that should be used::
28-
29-
$ /usr/opt/bin/python3.0 ./setup.py install
30-
31-
Under most POSIX systems, the above should work without problem if the proper
32-
Python executable is referenced. However, if it does fail, it is likely due
33-
to a C extension's inability to compile.
34-
35-
The building of C extensions can be disable using the ``PY_BUILD_EXTENSIONS``
36-
environment variable::
37-
38-
$ env PY_BUILD_EXTENSIONS=0 python3 ./setup.py install
39-
40-
41-
Extension Modules under Windows
42-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
43-
44-
By default, a Python installation on Windows cannot build extension modules.
45-
py-postgresql provides optimizations for various key points, but can be
46-
installed and used without them. When a source installation is performed on
47-
'win32' systems, extension modules are *not* built by default.
48-
49-
In order to enable the compilation of extensions, set the environment variable
50-
``PY_BUILD_EXTENSIONS`` to '1' before executing the ``setup.py``
51-
script::
52-
53-
C:\-> setenv PY_BUILD_EXTENSIONS 1
54-
C:\-> c:\python30\python setup.py install
55-
56-
Or, more likely, compile using mingw32::
57-
58-
C:\-> setenv PY_BUILD_EXTENSIONS 1
59-
C:\-> c:\python30\python setup.py build_ext --compiler=mingw32
60-
C:\-> c:\python30\python setup.py install
61-
62-
See http://www.mingw.org/ to get the compiler.
63-
64-
65-
Environment
66-
-----------
67-
68-
These environment variables effect the operation of the package:
69-
70-
============== ===============================================================================
71-
PGINSTALLATION The path to the ``pg_config`` executable of the installation to use by default.
72-
============== ===============================================================================
73-
"""
74-
5+
__doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
756
__docformat__ = 'reStructuredText'
767
if __name__ == '__main__':
77-
import sys
78-
if (sys.argv + [None])[1] == 'dump':
79-
sys.stdout.write(__doc__)
80-
else:
81-
try:
82-
help(__package__ + '.admin')
83-
except NameError:
84-
help(__name__)
8+
help(__name__)

‎postgresql/documentation/admin.txt‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Administration
2+
==============
3+
4+
This chapter covers the administration of py-postgresql. This includes
5+
installation and other aspects of working with py-postgresql such as
6+
environment variables and configuration files.
7+
8+
9+
Installation
10+
------------
11+
12+
py-postgresql uses Python's standard distutils package to manage the
13+
build and installation process of the package. The normal entry point for
14+
this is the ``setup.py`` script contained in the root project directory.
15+
16+
After extracting the archive and changing the into the project's directory,
17+
installation is normally as simple as::
18+
19+
$ python3 ./setup.py install
20+
21+
However, if you need to install for use with a particular version of python,
22+
just use the path of the executable that should be used::
23+
24+
$ /usr/opt/bin/python3.0 ./setup.py install
25+
26+
Under most POSIX systems, the above should work without problem if the proper
27+
Python executable is referenced. However, if it does fail, it is likely due
28+
to a C extension's inability to compile.
29+
30+
The building of C extensions can be disable using the ``PY_BUILD_EXTENSIONS``
31+
environment variable::
32+
33+
$ env PY_BUILD_EXTENSIONS=0 python3 ./setup.py install
34+
35+
36+
Extension Modules under Windows
37+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
38+
39+
By default, a Python installation on Windows cannot build extension modules.
40+
py-postgresql provides optimizations for various key points, but can be
41+
installed and used without them. When a source installation is performed on
42+
'win32' systems, extension modules are *not* built by default.
43+
44+
In order to enable the compilation of extensions, set the environment variable
45+
``PY_BUILD_EXTENSIONS`` to '1' before executing the ``setup.py``
46+
script::
47+
48+
C:\-> setenv PY_BUILD_EXTENSIONS 1
49+
C:\-> c:\python30\python setup.py install
50+
51+
Or, more likely, compile using mingw32::
52+
53+
C:\-> setenv PY_BUILD_EXTENSIONS 1
54+
C:\-> c:\python30\python setup.py build_ext --compiler=mingw32
55+
C:\-> c:\python30\python setup.py install
56+
57+
See http://www.mingw.org/ to get the compiler.
58+
59+
60+
Environment
61+
-----------
62+
63+
These environment variables effect the operation of the package:
64+
65+
============== ===============================================================================
66+
PGINSTALLATION The path to the ``pg_config`` executable of the installation to use by default.
67+
============== ===============================================================================

‎postgresql/documentation/bin.py‎

Lines changed: 2 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -2,181 +2,7 @@
22
# copyright 2009, James William Pye
33
# http://python.projects.postgresql.org
44
##
5-
r'''
6-
Console Scripts
7-
***************
8-
9-
This chapter discusses the usage of the available console scripts.
10-
11-
12-
``pg_python``
13-
=============
14-
15-
The ``pg_python`` command provides a simple way to write Python scripts against a
16-
single target database. It acts like the regular Python console command, but
17-
takes standard PostgreSQL options as well to specify the client parameters
18-
to make establish connection with. The Python environment is then augmented
19-
with the following built-ins:
20-
21-
``db``
22-
The PG-API connection object.
23-
24-
``xact``
25-
``db.xact``, the transaction creator.
26-
27-
``settings``
28-
``db.settings``
29-
30-
``prepare``
31-
``db.prepare``, the statement creator.
32-
33-
``proc``
34-
``db.proc``
35-
36-
37-
pg_python Usage
38-
---------------
39-
40-
Usage: pg_python.py [connection options] [script] ...
41-
42-
Options:
43-
--unix=UNIX path to filesystem socket
44-
--ssl-mode=SSLMODE SSL requirement for connectivity: require, prefer,
45-
allow, disable
46-
-s SETTINGS, --setting=SETTINGS
47-
run-time parameters to set upon connecting
48-
-I PQ_IRI, --iri=PQ_IRI
49-
database locator string
50-
[pq://user:password@host:port/database?setting=value]
51-
-h HOST, --host=HOST database server host
52-
-p PORT, --port=PORT database server port
53-
-U USER, --username=USER
54-
user name to connect as
55-
-W, --password prompt for password
56-
-d DATABASE, --database=DATABASE
57-
database's name
58-
--pq-trace=PQ_TRACE trace PQ protocol transmissions
59-
-C PYTHON_CONTEXT, --context=PYTHON_CONTEXT
60-
Python context code to run[file://,module:,<code>]
61-
-m PYTHON_MAIN Python module to run as script(__main__)
62-
-c PYTHON_MAIN Python expression to run(__main__)
63-
--version show program's version number and exit
64-
--help show this help message and exit
65-
66-
67-
Interactive Console Backslash Commands
68-
--------------------------------------
69-
70-
Inspired by ``psql``::
71-
72-
>>> \?
73-
Backslash Commands:
74-
75-
\? Show this help message.
76-
\E Edit a file or a temporary script.
77-
\e Edit and Execute the file directly in the context.
78-
\i Execute a Python script within the interpreter's context.
79-
\set Configure environment variables. \set without arguments to show all
80-
\x Execute the Python command within this process.
81-
82-
83-
pg_python Examples
84-
------------------
85-
86-
Module execution taking advantage of the new built-ins::
87-
88-
$ pg_python -h localhost -W -m timeit "prepare('SELECT 1').first()"
89-
Password for pg_python[pq://jwp@localhost:5432]:
90-
1000 loops, best of 3: 1.35 msec per loop
91-
92-
$ pg_python -h localhost -W -m timeit -s "ps=prepare('SELECT 1')" "ps.first()"
93-
Password for pg_python[pq://jwp@localhost:5432]:
94-
1000 loops, best of 3: 442 usec per loop
95-
96-
Simple interactive usage::
97-
98-
$ pg_python -h localhost -W
99-
Password for pg_python[pq://jwp@localhost:5432]:
100-
>>> ps = prepare('select 1')
101-
>>> ps.first()
102-
1
103-
>>> c = ps()
104-
>>> c.read()
105-
[(1,)]
106-
>>> ps.close()
107-
>>> import sys
108-
>>> sys.exit(0)
109-
110-
111-
``pg_dotconf``
112-
==============
113-
114-
pg_dotconf is used to modify a PostgreSQL cluster's configuration file.
115-
It provides a means to apply settings specified from the command line and from a
116-
file referenced using the ``-f`` option.
117-
118-
.. warning::
119-
``include`` directives in configuration files are *completely* ignored. If
120-
modification of an included file is desired, the command must be applied to
121-
that specific file.
122-
123-
124-
pg_dotconf Usage
125-
----------------
126-
127-
Usage: pg_dotconf.py [--stdout] [-f filepath] postgresql.conf ([param=val]|[param])*
128-
129-
Options:
130-
--version show program's version number and exit
131-
-h, --help show this help message and exit
132-
-f SETTINGS, --file=SETTINGS
133-
A file of settings to *apply* to the given
134-
"postgresql.conf"
135-
--stdout Redirect the product to standard output instead of
136-
writing back to the "postgresql.conf" file
137-
138-
139-
Examples
140-
--------
141-
142-
Modifying a simple configuration file::
143-
144-
$ echo "setting = value" >pg.conf
145-
146-
# change 'setting'
147-
$ pg_dotconf pg.conf setting=newvalue
148-
149-
$ cat pg.conf
150-
setting = 'newvalue'
151-
152-
# new settings are appended to the file
153-
$ pg_dotconf pg.conf another_setting=value
154-
$ cat pg.conf
155-
setting = 'newvalue'
156-
another_setting = 'value'
157-
158-
# comment a setting
159-
$ pg_dotconf pg.conf another_setting
160-
161-
$ cat pg.conf
162-
setting = 'newvalue'
163-
#another_setting = 'value'
164-
165-
When a setting is given on the command line, it must been seen as one argument
166-
to the command, so it's *very* important to avoid invocations like::
167-
168-
$ pg_dotconf pg.conf setting = value
169-
ERROR: invalid setting, '=' after 'setting'
170-
HINT: Settings must take the form 'setting=value' or 'setting_name_to_comment'. Settings must also be received as a single argument.
171-
'''
172-
5+
__doc__ = open(__file__[:__file__.rfind('.')] + '.txt').read()
1736
__docformat__ = 'reStructuredText'
1747
if __name__ == '__main__':
175-
import sys
176-
if (sys.argv + [None])[1] == 'dump':
177-
sys.stdout.write(__doc__)
178-
else:
179-
try:
180-
help(__package__ + '.bin')
181-
except NameError:
182-
help(__name__)
8+
help(__name__)

0 commit comments

Comments
 (0)