|
| 1 | +"""A Python driver for PostgreSQL |
| 2 | +
|
| 3 | +psycopg is a PostgreSQL_ database adapter for the Python_ programming |
| 4 | +language. This is version 2, a complete rewrite of the original code to |
| 5 | +provide new-style classes for connection and cursor objects and other sweet |
| 6 | +candies. Like the original, psycopg 2 was written with the aim of being very |
| 7 | +small and fast, and stable as a rock. |
| 8 | +
|
| 9 | +Homepage: https://psycopg.org/ |
| 10 | +
|
| 11 | +.. _PostgreSQL: https://www.postgresql.org/ |
| 12 | +.. _Python: https://www.python.org/ |
| 13 | +
|
| 14 | +:Groups: |
| 15 | + * `Connections creation`: connect |
| 16 | + * `Value objects constructors`: Binary, Date, DateFromTicks, Time, |
| 17 | + TimeFromTicks, Timestamp, TimestampFromTicks |
| 18 | +""" |
| 19 | +# psycopg/__init__.py - initialization of the psycopg module |
| 20 | +# |
| 21 | +# Copyright (C) 2003-2019 Federico Di Gregorio <[email protected]> |
| 22 | +# Copyright (C) 2020 The Psycopg Team |
| 23 | +# |
| 24 | +# psycopg2 is free software: you can redistribute it and/or modify it |
| 25 | +# under the terms of the GNU Lesser General Public License as published |
| 26 | +# by the Free Software Foundation, either version 3 of the License, or |
| 27 | +# (at your option) any later version. |
| 28 | +# |
| 29 | +# In addition, as a special exception, the copyright holders give |
| 30 | +# permission to link this program with the OpenSSL library (or with |
| 31 | +# modified versions of OpenSSL that use the same license as OpenSSL), |
| 32 | +# and distribute linked combinations including the two. |
| 33 | +# |
| 34 | +# You must obey the GNU Lesser General Public License in all respects for |
| 35 | +# all of the code used other than OpenSSL. |
| 36 | +# |
| 37 | +# psycopg2 is distributed in the hope that it will be useful, but WITHOUT |
| 38 | +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 39 | +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public |
| 40 | +# License for more details. |
| 41 | + |
| 42 | +# Import modules needed by _psycopg to allow tools like py2exe to do |
| 43 | +# their work without bothering about the module dependencies. |
| 44 | + |
| 45 | +# Note: the first internal import should be _psycopg, otherwise the real cause |
| 46 | +# of a failed loading of the C module may get hidden, see |
| 47 | +# https://archives.postgresql.org/psycopg/2011-02/msg00044.php |
| 48 | + |
| 49 | +# Import the DBAPI-2.0 stuff into top-level module. |
| 50 | + |
| 51 | +from psycopg2._psycopg import ( # noqa |
| 52 | + BINARY, NUMBER, STRING, DATETIME, ROWID, |
| 53 | + |
| 54 | + Binary, Date, Time, Timestamp, |
| 55 | + DateFromTicks, TimeFromTicks, TimestampFromTicks, |
| 56 | + |
| 57 | + Error, Warning, DataError, DatabaseError, ProgrammingError, IntegrityError, |
| 58 | + InterfaceError, InternalError, NotSupportedError, OperationalError, |
| 59 | + |
| 60 | + _connect, apilevel, threadsafety, paramstyle, |
| 61 | + __version__, __libpq_version__, |
| 62 | +) |
| 63 | + |
| 64 | +from psycopg2 import tz # noqa |
| 65 | + |
| 66 | + |
| 67 | +# Register default adapters. |
| 68 | + |
| 69 | +from psycopg2 import extensions as _ext |
| 70 | +_ext.register_adapter(tuple, _ext.SQL_IN) |
| 71 | +_ext.register_adapter(type(None), _ext.NoneAdapter) |
| 72 | + |
| 73 | +# Register the Decimal adapter here instead of in the C layer. |
| 74 | +# This way a new class is registered for each sub-interpreter. |
| 75 | +# See ticket #52 |
| 76 | +from decimal import Decimal # noqa |
| 77 | +from psycopg2._psycopg import Decimal as Adapter # noqa |
| 78 | +_ext.register_adapter(Decimal, Adapter) |
| 79 | +del Decimal, Adapter |
| 80 | + |
| 81 | + |
| 82 | +def connect(dsn=None, connection_factory=None, cursor_factory=None, **kwargs): |
| 83 | + """ |
| 84 | + Create a new database connection. |
| 85 | +
|
| 86 | + The connection parameters can be specified as a string: |
| 87 | +
|
| 88 | + conn = psycopg2.connect("dbname=test user=postgres password=secret") |
| 89 | +
|
| 90 | + or using a set of keyword arguments: |
| 91 | +
|
| 92 | + conn = psycopg2.connect(database="test", user="postgres", password="secret") |
| 93 | +
|
| 94 | + Or as a mix of both. The basic connection parameters are: |
| 95 | +
|
| 96 | + - *dbname*: the database name |
| 97 | + - *database*: the database name (only as keyword argument) |
| 98 | + - *user*: user name used to authenticate |
| 99 | + - *password*: password used to authenticate |
| 100 | + - *host*: database host address (defaults to UNIX socket if not provided) |
| 101 | + - *port*: connection port number (defaults to 5432 if not provided) |
| 102 | +
|
| 103 | + Using the *connection_factory* parameter a different class or connections |
| 104 | + factory can be specified. It should be a callable object taking a dsn |
| 105 | + argument. |
| 106 | +
|
| 107 | + Using the *cursor_factory* parameter, a new default cursor factory will be |
| 108 | + used by cursor(). |
| 109 | +
|
| 110 | + Using *async*=True an asynchronous connection will be created. *async_* is |
| 111 | + a valid alias (for Python versions where ``async`` is a keyword). |
| 112 | +
|
| 113 | + Any other keyword parameter will be passed to the underlying client |
| 114 | + library: the list of supported parameters depends on the library version. |
| 115 | +
|
| 116 | + """ |
| 117 | + kwasync = {} |
| 118 | + if 'async' in kwargs: |
| 119 | + kwasync['async'] = kwargs.pop('async') |
| 120 | + if 'async_' in kwargs: |
| 121 | + kwasync['async_'] = kwargs.pop('async_') |
| 122 | + |
| 123 | + if dsn is None and not kwargs: |
| 124 | + raise TypeError('missing dsn and no parameters') |
| 125 | + |
| 126 | + dsn = _ext.make_dsn(dsn, **kwargs) |
| 127 | + conn = _connect(dsn, connection_factory=connection_factory, **kwasync) |
| 128 | + if cursor_factory is not None: |
| 129 | + conn.cursor_factory = cursor_factory |
| 130 | + |
| 131 | + return conn |
0 commit comments