Skip to content

Commit 228b0cd

Browse files
author
James William Pye
committed
More documentation.
 - Modify transactions for new APIs - Add stored procedure section - Isolate clientparmeters into its own document
1 parent 450bd61 commit 228b0cd

1 file changed

Lines changed: 133 additions & 0 deletions

File tree

‎postgresql/documentation/clientparameters.py‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
##
2+
# copyright 2009, James William Pye
3+
# http://python.projects.postgresql.org
4+
##
5+
"""
6+
Client Parameters
7+
=================
8+
9+
Connection creation interfaces in `postgresql.driver` are purposefully simple.
10+
All parameters are keywords, and are taken literally. libpq-based drivers
11+
tend differ as they inherit default client parameters from the environment.
12+
Doing this by default is undesirable as it can cause trivial failures due to
13+
unexpected parameter inheritance. However, using these parameters from the
14+
environment and other sources are simply expected in *some* cases--
15+
`postgresql.open`. The `postgresql.clientparameters` module provides a means
16+
to collect them into one dictionary-object for subsequent application to a
17+
connection creation interface.
18+
19+
`postgresql.clientparameters` is primarily useful to script authors that want to
20+
provide an interface consistent with PostgreSQL commands like ``psql``.
21+
22+
The primary entry points are `postgresql.clientparameters` is
23+
24+
`postgresql.clientparameters.standard`
25+
26+
Build a client parameter dictionary from the environment and parsed command
27+
line options.
28+
29+
``co``
30+
Options parsed by `postgresql.clientparameters.StandardParser` or
31+
`postgresql.clientparameters.DefaultParser` instances.
32+
``no_defaults``
33+
Don't include defaults like ``pgpassfile`` and ``user``. Defaults to `False`.
34+
``environ``
35+
Environment variables to extract client parameter variables from.
36+
Defaults to `os.environ` and expects a `collections.Mapping` interface.
37+
``environ_prefix``
38+
Environment variable prefix to use. Defaults to "PG". This allows the
39+
collection of non-standard environment variables whose keys are partially
40+
consistent with the standard variants. e.g. "PG_SRC_USER", "PG_SRC_HOST",
41+
etc.
42+
``default_pg_sysconfdir``
43+
The location of the pg_service.conf file. The ``PGSYSCONFDIR`` environment
44+
variable will override this.
45+
``pg_service_file``
46+
Explicit location of the service file. This will override the "sysconfdir"
47+
based path.
48+
``prompt_title``
49+
Descriptive title to use if a password prompt is needed. `None` to disable
50+
password resolution--disables pgpassfile lookups.
51+
``parameters``
52+
Base client parameters to use. These are set after the defaults are
53+
collected.
54+
(The defaults that can be disabled by ``no_defaults``).
55+
56+
`postgresql.clientparameters.resolve_password`
57+
58+
Resolve the password for the given client parameters dictionary returned by
59+
``standard``. By default, this function need not be used as ``standard`` will
60+
resolve the password by default. However, password resolution
61+
can be turned off by passing ``prompt_title`` keyword argument as `None`.
62+
``resolve_password`` will use the configured ``pgpassfile`` keyword.
63+
64+
``parameters``
65+
First positional argument. Normalized client parameters dictionary to update
66+
in-place with the resolved password. If the 'prompt_password' key is in
67+
``parameters``, it will prompt regardless(normally comes from ``-W``).
68+
``getpass``
69+
Function to call to prompt for the password. Defaults to `getpass.getpass`.
70+
``prompt_title``
71+
Additional title to use if a prompt is requested. This can also be specified
72+
in the ``parameters`` as the ``prompt_title`` key.
73+
74+
Example usage:
75+
76+
>>> import postgresql.clientparameters as pg_param
77+
>>> p = pg_param.DefaultParser()
78+
>>> co, ca = p.parse_args(...)
79+
>>> cp = pg_param.standard(co = co)
80+
>>> print(cp)
81+
82+
The `postgresql.clientparameters` module is executable, so you can see the
83+
results of the above snippet by::
84+
85+
$ python -m postgresql.clientparameters -h localhost -U a_db_user -ssearch_path=public
86+
{'host': 'localhost',
87+
'password': None,
88+
'port': 5432,
89+
'settings': {'search_path': 'public'},
90+
'user': 'a_db_user'}
91+
92+
Environment Variables
93+
=====================
94+
95+
The following is a list of environment variables that will be collected by the
96+
`postgresql.clientparameter.standard` function using the "PG" ``environ_prefix``:
97+
98+
===================== ======================================
99+
Environment Variable Connection Creation Keyword
100+
===================== ======================================
101+
``PGUSER`` ``'user'``
102+
``PGDATABASE`` ``'database'``
103+
``PGHOST`` ``'host'``
104+
``PGPORT`` ``'port'``
105+
``PGPASSWORD`` ``'password'``
106+
``PGSSLMODE`` ``'sslmode'``
107+
``PGSSLKEY`` ``'sslkey'``
108+
``PGCONNECT_TIMEOUT`` ``'connect_timeout'``
109+
``PGREALM`` ``'kerberos4_realm'``
110+
``PGKRBSRVNAME`` ``'kerberos5_service'``
111+
``PGROLE`` ``'role'``
112+
``PGPASSFILE`` ``'pgpassfile'``
113+
``PGTZ`` ``'settings' = {'timezone': }``
114+
``PGDATESTYLE`` ``'settings' = {'datestyle': }``
115+
``PGCLIENTENCODING`` ``'settings' = {'client_encoding': }``
116+
``PGGEQO`` ``'settings' = {'geqo': }``
117+
===================== ======================================
118+
119+
The "PG" prefix is adjustable using the ``environ_prefix`` keyword.
120+
This is useful in cases where multiple connections are being established by a
121+
single script.
122+
"""
123+
124+
__docformat__ = 'reStructuredText'
125+
if __name__ == '__main__':
126+
import sys
127+
if (sys.argv + [None])[1] == 'dump':
128+
sys.stdout.write(__doc__)
129+
else:
130+
try:
131+
help(__package__ + '.clientparameters')
132+
except NameError:
133+
help(__name__)

0 commit comments

Comments
 (0)