gdZddlZddlZddlmZgdZGddeZGdd eZGd d eejej Z Gd d eejej Z Gddej Z Gddeejej Ze eeZGddeejZGddeZGddeejZGddeZGddeZGddeZGdd eZGd!d"eZGd#d$eZGd%d&eZGd'd(eZGd)d*eZd+Z e!d,kre"e#d-zdSdS).a Application Programmer Interfaces for PostgreSQL. ``postgresql.api`` is a collection of Python APIs for the PostgreSQL DBMS. It is designed to take full advantage of PostgreSQL's features to provide the Python programmer with substantial convenience. This module is used to define "PG-API". It creates a set of ABCs that makes up the basic interfaces used to work with a PostgreSQL server. N)Element)Message StatementChunksCursor ConnectorCategoryDatabaseTypeIO Connection TransactionSettingsStoredProcedureDriver InstallationClusterceZdZdZdZdZdZeej de fdZ eej de fdZ eej de fdZ eej defd Zej defd Zd S) rzS A message emitted by PostgreSQL. A message being a NOTICE, WARNING, INFO, etc. MESSAGE)DEBUGINFONOTICEWARNINGERRORFATALPANIC)SERVERCLIENTreturncdS)zV Where the message originated from. Normally, 'SERVER', but sometimes 'CLIENT'. Nselfs D/granary/edev/quantum/lib/python3.11/site-packages/postgresql/api.pysourcezMessage.source:cdS)z( The SQL state code of the message. Nr!r"s r$codez Message.codeBr&r'cdS)z! The primary message string. Nr!r"s r$messagezMessage.messageIr&r'cdS)z The additional details given with the message. Common keys *should* be the following: * 'severity' * 'context' * 'detail' * 'hint' * 'file' * 'line' * 'function' * 'position' * 'internal_position' * 'internal_query' Nr!r"s r$detailszMessage.detailsPr&r'cdS)at Whether the fields of the `other` Message object is consistent with the fields of `self`. This *must* return the result of the comparison of code, source, message, and details. This method is provided as the alternative to overriding equality; often, pointer equality is the desirable means for comparison, but equality of the fields is also necessary. Nr!)r#others r$ isconsistentzMessage.isconsistentcr&r'N)__name__ __module__ __qualname____doc___e_label severitiessourcespropertyabcabstractmethodstrr%r)r+dictr-boolr0r!r'r$rr%s2    S (  3 (  c (  d (" $      r'rceZdZdZdZdZejddZe ejde fdZ e ejde gfdZ e ejde gfd Ze ejde gfd Ze ejde gfd Ze ejdedffd Ze ejddZdS)Resulta A result is an object managing the results of a prepared statement. These objects represent a binding of parameters to a given statement object. For results that were constructed on the server and a reference passed back to the client, statement and parameters may be None. RESULT) statement parameters cursor_idrNcdS)z Close the Result handle. Nr!r"s r$closez Result.close}r&r'cdS)z The cursor's identifier. Nr!r"s r$rCzResult.cursor_idr&r'cdS)z The type of the columns produced by the cursor. A sequence of `str` objects stating the SQL type name:: ['INTEGER', 'CHARACTER VARYING', 'INTERVAL'] Nr!r"s r$sql_column_typeszResult.sql_column_typesr&r'cdS)z The type Oids of the columns produced by the cursor. A sequence of `int` objects stating the SQL type name:: [27, 28] Nr!r"s r$pg_column_typeszResult.pg_column_typesr&r'cdS)z The attribute names of the columns produced by the cursor. A sequence of `str` objects stating the column name:: ['column1', 'column2', 'emp_name'] Nr!r"s r$ column_nameszResult.column_namesr&r'cdS)z The Python types of the columns produced by the cursor. A sequence of type objects:: [, ] Nr!r"s r$ column_typeszResult.column_typesr&r'cdS)a: The parameters bound to the cursor. `None`, if unknown and an empty tuple `()`, if no parameters were given. These should be the *original* parameters given to the invoked statement. This should only be `None` when the cursor is created from an identifier, `postgresql.api.Database.cursor_from_id`. Nr!r"s r$rBzResult.parametersr&r'rNcdS)z The query object used to create the cursor. `None`, if unknown. This should only be `None` when the cursor is created from an identifier, `postgresql.api.Database.cursor_from_id`. Nr!r"s r$rAzResult.statementr&r'rN)rrP)r1r2r3r4r5 _e_factorsr9r:rEr8r;rCrHintrJrLrNtuplerBrAr!r'r$r?r?qs 6   (  u ( se ( C5 ( C5 (  %    (   (r'r?ceZdZdS)rN)r1r2r3r!r'r$rrs r'rceZdZdZdZddddddZddd Zejdd Z d Z e ejd e fd Z ej dddddd dgfdZejddZejddZdS)raV A `Cursor` object is an interface to a sequence of tuples(rows). A result set. Cursors publish a file-like interface for reading tuples from a cursor declared on the database. `Cursor` objects are created by invoking the `Statement.declare` method or by opening a cursor using an identifier via the `Database.cursor_from_id` method. CURSORABSOLUTERELATIVEFROM_ENDFORWARDBACKWARD)rr)TFrcdS)z; Create a new cursor using the same factors as `self`. Nr!r"s r$clonez Cursor.cloner&r'c|SNr!r"s r$__iter__zCursor.__iter__s +r'cdS)z The default `direction` argument for read(). When `True` reads are FORWARD. When `False` reads are BACKWARD. Cursor operation option. Nr!r"s r$ directionzCursor.directionr&r'NquantityzNumber of rows to readrgz3Direction to fetch in, defaults to `self.direction`RowcdS)ag Read, fetch, the specified number of rows and return them in a list. If quantity is `None`, all records will be fetched. `direction` can be used to override the default configured direction. This alters the cursor's position. Read does not directly correlate to FETCH. If zero is given as the quantity, an empty sequence *must* be returned. Nr!)r#rhrgs r$readz Cursor.readr&r'cdS)zN Get the next tuple in the cursor. Advances the cursor position by one. Nr!r"s r$__next__zCursor.__next__r&r'cdS)a/ Set the cursor's position to the given offset with respect to the whence parameter and the configured direction. Whence values: ``0`` or ``"ABSOLUTE"`` Absolute. ``1`` or ``"RELATIVE"`` Relative. ``2`` or ``"FROM_END"`` Absolute from end. ``3`` or ``"FORWARD"`` Relative forward. ``4`` or ``"BACKWARD"`` Relative backward. Direction effects whence. If direction is BACKWARD, ABSOLUTE positioning will effectively be FROM_END, RELATIVE's position will be negated, and FROM_END will effectively be ABSOLUTE. Nr!)r#offsetwhences r$seekz Cursor.seekr&r')rrNN)rri)rY)r1r2r3r4r5_seek_whence_map_direction_mapr9r:rbrer8r=rgrkrmrqr!r'r$rrsR         ((,FJ %C g  r'rceZdZdZejddddgfdZejdejfdZ ejdejfdZ ejdejfd Z ejdejfd Z ejde fd Z ejdd Zej ddZej ddZdS) Executionz, The abstract class of execution methods. rBzPositional ParametersrricdS)z Execute the prepared statement with the given arguments as parameters. Usage: >>> p=db.prepare("SELECT column FROM ttable WHERE key = $1") >>> p('identifier') [...] Nr!r#rBs r$__call__zExecution.__call__:r&r'cdS)a  Return an iterator producing the values of first column of the rows produced by the cursor created from the statement bound with the given parameters. Column iterators are never scrollable. Supporting cursors will be WITH HOLD when outside of a transaction to allow cross-transaction access. `column` is designed for the situations involving large data sets. Each iteration returns a single value. column expressed in sibling terms:: return map(operator.itemgetter(0), self.rows(*parameters)) Nr!rxs r$columnzExecution.columnFr&r'cdS)a Return an iterator producing sequences of rows produced by the cursor created from the statement bound with the given parameters. Chunking iterators are *never* scrollable. Supporting cursors will be WITH HOLD when outside of a transaction. `chunks` is designed for moving large data sets efficiently. Each iteration returns sequences of rows *normally* of length(seq) == chunksize. If chunksize is unspecified, a default, positive integer will be filled in. The rows contained in the sequences are only required to support the basic `collections.Sequence` interfaces; simple and quick sequence types should be used. Nr!rxs r$chunkszExecution.chunks[r&r'cdS)a Return an iterator producing rows produced by the cursor created from the statement bound with the given parameters. Row iterators are never scrollable. Supporting cursors will be WITH HOLD when outside of a transaction to allow cross-transaction access. `rows` is designed for the situations involving large data sets. Each iteration returns a single row. Arguably, best implemented:: return itertools.chain.from_iterable(self.chunks(*parameters)) Nr!rxs r$rowszExecution.rowsnr&r'cdS)a Return an iterator producing the values of the first column in the cursor created from the statement bound with the given parameters. Column iterators are never scrollable. Supporting cursors will be WITH HOLD when outside of a transaction to allow cross-transaction access. `column` is designed for the situations involving large data sets. Each iteration returns a single value. `column` is equivalent to:: return map(operator.itemgetter(0), self.rows(*parameters)) Nr!rxs r$r{zExecution.columnr&r'cdS)za Return a scrollable cursor with hold using the statement bound with the given parameters. Nr!rxs r$declarezExecution.declarer&r','First' object that is returned by the querycdS)aT Execute the prepared statement with the given arguments as parameters. If the statement returns rows with multiple columns, return the first row. If the statement returns rows with a single column, return the first column in the first row. If the query does not return rows at all, return the count or `None` if no count exists in the completion message. Usage: >>> db.prepare("SELECT * FROM ttable WHERE key = $1").first("somekey") ('somekey', 'somevalue') >>> db.prepare("SELECT 'foo'").first() 'foo' >>> db.prepare("INSERT INTO atable (col) VALUES (1)").first() 1 Nr!rxs r$firstzExecution.firstr&r'iterable2A iterable of tuples to execute the statement withcdS)a Given an iterable, `iterable`, feed the produced parameters to the query. This is a bulk-loading interface for parameterized queries. Effectively, it is equivalent to: >>> q = db.prepare(sql) >>> for i in iterable: ... q(*i) Its purpose is to allow the implementation to take advantage of the knowledge that a series of parameters are to be loaded so that the operation can be optimized. Nr!r#rs r$ load_rowszExecution.load_rowsr&r'>> ps = db.prepare(...) >>> for c in iterable: ... for i in c: ... q(*i) Its purpose is to allow the implementation to take advantage of the knowledge that a series of chunks of parameters are to be loaded so that the operation can be optimized. Nr!rs r$ load_chunkszExecution.load_chunksr&r'N)rr)rr)rr)r1r2r3r4r9r:ry collectionsIterabler{r}rrrrrrr!r'r$rvrv5s "9 ug    +"6(+"6$ 4"+"6"6 $ A$ Kr'rv) metaclasscReZdZdZdZdZeejde fdZ eejde fdZ eejde gfdZ eejde gfdZeejdegfd Zeejdegfd Zeejde gfd Zeejdegfd Zeejdegfd ZejddZejddZdS)ra5 Instances of `Statement` are returned by the `prepare` method of `Database` instances. A Statement is an Iterable as well as Callable. The Iterable interface is supported for queries that take no arguments at all. It allows the syntax:: >>> for x in db.prepare('select * FROM table'): ... pass STATEMENT)database statement_idstringrcdS)z The statment's identifier. Nr!r"s r$rzStatement.statement_idr&r'cdS)a! The SQL string of the prepared statement. `None` if not available. This can happen in cases where a statement is prepared on the server and a reference to the statement is sent to the client which subsequently uses the statement via the `Database`'s `statement` constructor. Nr!r"s r$rzStatement.stringr&r'cdS)z The type of the parameters required by the statement. A sequence of `str` objects stating the SQL type name:: ['INTEGER', 'VARCHAR', 'INTERVAL'] Nr!r"s r$sql_parameter_typeszStatement.sql_parameter_typesr&r'cdS)z The type of the columns produced by the statement. A sequence of `str` objects stating the SQL type name:: ['INTEGER', 'VARCHAR', 'INTERVAL'] Nr!r"s r$rHzStatement.sql_column_typesr&r'cdS)z The type Oids of the parameters required by the statement. A sequence of `int` objects stating the PostgreSQL type Oid:: [27, 28] Nr!r"s r$pg_parameter_typeszStatement.pg_parameter_typesr&r'cdS)z The type Oids of the columns produced by the statement. A sequence of `int` objects stating the SQL type name:: [27, 28] Nr!r"s r$rJzStatement.pg_column_typesr&r'cdS)z The attribute names of the columns produced by the statement. A sequence of `str` objects stating the column name:: ['column1', 'column2', 'emp_name'] Nr!r"s r$rLzStatement.column_names'r&r'cdS)z The Python types of the columns produced by the statement. A sequence of type objects:: [, ] Nr!r"s r$rNzStatement.column_types2r&r'cdS)z The Python types expected of parameters given to the statement. A sequence of type objects:: [, ] Nr!r"s r$parameter_typeszStatement.parameter_types=r&r'cdS)z Create a new statement object using the same factors as `self`. When used for refreshing plans, the new clone should replace references to the original. Nr!r"s r$rbzStatement.cloneHr&r'NcdS)zJ Close the prepared statement releasing resources associated with it. Nr!r"s r$rEzStatement.closeQr&r')rrrR)r1r2r3r4r5rSr8r9r:r;robjectrrrHrTrrJrLtyperNrrbrEr!r'r$rrs[   5 3 (  V ( 3% ( u ( # ( se ( C5 ( D6 ( tf (r'rcPeZdZdZdZdZejdee e j ffdZ dS)rz& A function stored on the database. FUNCTIONrrcdS)a Execute the procedure with the given arguments. If keyword arguments are passed they must be mapped to the argument whose name matches the key. If any positional arguments are given, they must fill in gaps created by the stated keyword arguments. If too few or too many arguments are given, a TypeError must be raised. If a keyword argument is passed where the procedure does not have a corresponding argument name, then, likewise, a TypeError must be raised. In the case where the `StoredProcedure` references a set returning function(SRF), the result *must* be an iterable. SRFs that return single columns *must* return an iterable of that column; not row data. If the SRF returns a composite(OUT parameters), it *should* return a `Cursor`. Nr!r#argskws r$ryzStoredProcedure.__call__cr&r'N) r1r2r3r4r5rSr9r:rrrrryr!r'r$rrYs] VV[5I$Jr'rc<eZdZdZdZdZeejdde ffdZ eejdde ffdZ ejd dZ e Z ejd d Zejd d ZeZejd Zejd ZdS)ra A `Tranaction` is an element that represents a transaction in the session. Once created, it's ready to be started, and subsequently committed or rolled back. Read-only transaction: >>> with db.xact(mode = 'read only'): ... ... Read committed isolation: >>> with db.xact(isolation = 'READ COMMITTED'): ... ... Savepoints are created if inside a transaction block: >>> with db.xact(): ... with db.xact(): ... ... XACTrrNcdS)z The mode of the transaction block: START TRANSACTION [ISOLATION] ; The `mode` property is a string and will be directly interpolated into the START TRANSACTION statement. Nr!r"s r$modezTransaction.moder&r'cdS)z The isolation level of the transaction block: START TRANSACTION [MODE]; The `isolation` property is a string and will be directly interpolated into the START TRANSACTION statement. Nr!r"s r$ isolationzTransaction.isolationr&r'cdS)a Start the transaction. If the database is in a transaction block, the transaction should be configured as a savepoint. If any transaction block configuration was applied to the transaction, raise a `postgresql.exceptions.OperationError`. If the database is not in a transaction block, start one using the configuration where: `self.isolation` specifies the ``ISOLATION LEVEL``. Normally, ``READ COMMITTED``, ``SERIALIZABLE``, or ``READ UNCOMMITTED``. `self.mode` specifies the mode of the transaction. Normally, ``READ ONLY`` or ``READ WRITE``. If the transaction is already open, do nothing. If the transaction has been committed or aborted, raise an `postgresql.exceptions.OperationError`. Nr!r"s r$startzTransaction.startr&r'cdS)a% Commit the transaction. If the transaction is a block, issue a COMMIT statement. If the transaction was started inside a transaction block, it should be identified as a savepoint, and the savepoint should be released. If the transaction has already been committed, do nothing. Nr!r"s r$commitzTransaction.commitr&r'cdS)z Abort the transaction. If the transaction is a savepoint, ROLLBACK TO the savepoint identifier. If the transaction is a transaction block, issue an ABORT. If the transaction has already been aborted, do nothing. Nr!r"s r$rollbackzTransaction.rollbackr&r'cdS)z- Run the `start` method and return self. Nr!r"s r$ __enter__zTransaction.__enter__r&r'cdS)a# If an exception is indicated by the parameters, run the transaction's `rollback` method iff the database is still available(not closed), and return a `False` value. If an exception is not indicated, but the database's transaction state is in error, run the transaction's `rollback` method and raise a `postgresql.exceptions.InFailedTransactionError`. If the database is unavailable, the `rollback` method should cause a `postgresql.exceptions.ConnectionDoesNotExistError` exception to occur. Otherwise, run the transaction's `commit` method. When the `commit` is ultimately unsuccessful or not ran at all, the purpose of __exit__ is to resolve the error state of the database iff the database is available(not closed) so that more commands can be after the block's exit. Nr!r#typobjtbs r$__exit__zTransaction.__exit__r&r'rR)r1r2r3r4r5rSr8r9r:r;rrrbeginrrabortrrr!r'r$rr{sN*  D#; ( s  (,           r'rc8eZdZdZdZejdZejdZejdZ ejd dZ ejdZ ejd Z ejd Z ejd Zejd ZdS)rz A mapping interface to the session's settings. This provides a direct interface to ``SHOW`` or ``SET`` commands. Identifiers and values need not be quoted specially as the implementation must do that work for the user. SETTINGScdS)z Return the setting corresponding to the given key. The result should be consistent with what the ``SHOW`` command returns. If the key does not exist, raise a KeyError. Nr!)r#keys r$ __getitem__zSettings.__getitem__r&r'cdS)z Set the setting with the given key to the given value. The action should be consistent with the effect of the ``SET`` command. Nr!)r#rvalues r$ __setitem__zSettings.__setitem__r&r'c dS)z Create a context manager applying the given settings on __enter__ and restoring the old values on __exit__. >>> with db.settings(search_path = 'local,public'): ... ... Nr!)r#rs r$ryzSettings.__call__r&r'NcdS)zh Get the setting with the corresponding key. If the setting does not exist, return the `default`. Nr!)r#rdefaults r$getz Settings.getr&r'cdS)z Return a dictionary containing the key-value pairs of the requested settings. If *any* of the keys do not exist, a `KeyError` must be raised with the set of keys that did not exist. Nr!)r#keyss r$getsetzSettings.getset&r&r'cdS)zL For each key-value pair, incur the effect of the `__setitem__` method. Nr!)r#mappings r$updatezSettings.update.r&r'cdS)z6 Return an iterator to all of the settings' keys. Nr!r"s r$rz Settings.keys4r&r'cdS)z8 Return an iterator to all of the settings' values. Nr!r"s r$valueszSettings.values:r&r'cdS)z; Return an iterator to all of the setting value pairs. Nr!r"s r$itemszSettings.items@r&r'rd)r1r2r3r4r5r9r:rrryrrrrrrr!r'r$rrs?      r'rc HeZdZdZdZeejdedffdZ eejde fdZ eejde dffdZ eejdedffdZeej d$d d d d defd ZeejdefdZejd%dZejd%dZejde defdZejdddefdZejdddefdZejdddefdZejd%dZejdefdZejd%dZejd%dZejdd d!gfd"Z ejd&de!j"fd#Z#dS)'r zT The interface to an individual database. `Connection` objects inherit from this DATABASErNcdS)z' The backend's process identifier. Nr!r"s r$ backend_idzDatabase.backend_idMr&r'cdS)z} A version tuple of the database software similar Python's `sys.version_info`. >>> db.version_info (8, 1, 3, '', 0) Nr!r"s r$ version_infozDatabase.version_infoTr&r'cdS)z The client address that the server sees. This is obtainable by querying the ``pg_catalog.pg_stat_activity`` relation. `None` if unavailable. Nr!r"s r$client_addresszDatabase.client_address^r&r'cdS)z The client port that the server sees. This is obtainable by querying the ``pg_catalog.pg_stat_activity`` relation. `None` if unavailable. Nr!r"s r$ client_portzDatabase.client_porthr&r'rz+ISOLATION LEVEL to use with the transactionrz0Mode of the transaction, READ ONLY or READ WRITEcdS)z] Create a `Transaction` object using the given keyword arguments as its configuration. Nr!)r#rrs r$xactz Database.xactrr&r'cdS)z4 A `Settings` instance bound to the `Database`. Nr!r"s r$settingszDatabase.settings}r&r'cdS)z Execute a DO statement using the given language and source. Always returns `None`. Likely to be a function of Connection.execute. Nr!)languager%s r$doz Database.dor&r'cdS)za Execute an arbitrary block of SQL. Always returns `None` and raise an exception on error. Nr!)sqls r$executezDatabase.executer&r'rcdS)z Create a new `Statement` instance bound to the connection using the given SQL. >>> s = db.prepare("SELECT 1") >>> c = s() >>> c.next() (1,) Nr!)r#rs r$preparezDatabase.preparer&r'rz&The statement's identification string.cdS)a" Create a `Statement` object that was already prepared on the server. The distinction between this and a regular query is that it must be explicitly closed if it is no longer desired, and it is instantiated using the statement identifier as opposed to the SQL statement itself. Nr!)r#rs r$statement_from_idzDatabase.statement_from_idr&r'rCz#The cursor's identification string.cdS)a Create a `Cursor` object from the given `cursor_id` that was already declared on the server. `Cursor` objects created this way must *not* be closed when the object is garbage collected. Rather, the user must explicitly close it for the server resources to be released. This is in contrast to `Cursor` objects that are created by invoking a `Statement` or a SRF `StoredProcedure`. Nr!)r#rCs r$cursor_from_idzDatabase.cursor_from_idr&r' procedure_idz:The procedure identifier; a valid ``regprocedure`` or Oid.cdS)a Create a `StoredProcedure` instance using the given identifier. The `proc_id` given can be either an ``Oid``, or a ``regprocedure`` that identifies the stored procedure to create the interface for. >>> p = db.proc('version()') >>> p() 'PostgreSQL 8.3.0' >>> qstr = "select oid from pg_proc where proname = 'generate_series'" >>> db.prepare(qstr).first() 1069 >>> generate_series = db.proc(1069) >>> list(generate_series(1,5)) [1, 2, 3, 4, 5] Nr!)r#rs r$procz Database.procr&r'cdS)a Reset the connection into it's original state. Issues a ``RESET ALL`` to the database. If the database supports removing temporary tables created in the session, then remove them. Reapply initial configuration settings such as path. The purpose behind this method is to provide a soft-reconnect method that re-initializes the connection into its original state. One obvious use of this would be in a connection pool where the connection is being recycled. Nr!r"s r$resetzDatabase.resetr&r'cdS)a NOTIFY the channels with the given payload. Equivalent to issuing "NOTIFY " or "NOTIFY , " for each item in `channels` and `channel_and_payload`. All NOTIFYs issued *must* occur in the same transaction. The items in `channels` can either be a string or a tuple. If a string, no payload is given, but if an item is a `builtins.tuple`, the second item will be given as the payload. `channels` offers a means to issue NOTIFYs in guaranteed order. The items in `channel_and_payload` are all payloaded NOTIFYs where the keys are the channels and the values are the payloads. Order is undefined. Nr!)r#channelschannel_and_payloads r$notifyzDatabase.notifyr&r'cdS)ze Start listening to the given channels. Equivalent to issuing "LISTEN " for x in channels. Nr!r#rs r$listenzDatabase.listenr&r'cdS)zf Stop listening to the given channels. Equivalent to issuing "UNLISTEN " for x in channels. Nr!rs r$unlistenzDatabase.unlistenr&r'z channel name.cdS)zK Return an *iterator* to all the channels currently being listened to. Nr!r"s r$listening_channelszDatabase.listening_channelsr&r'cdS)a) Return an iterator to the notifications received by the connection. The iterator *must* produce triples in the form ``(channel, payload, pid)``. If timeout is not `None`, `None` *must* be emitted at the specified timeout interval. If the timeout is zero, all the pending notifications *must* be yielded by the iterator and then `StopIteration` *must* be raised. If the connection is closed for any reason, the iterator *must* silently stop by raising `StopIteration`. Further error control is then the responsibility of the user. Nr!r#timeouts r$ iternotifieszDatabase.iternotifiesr&r'rrrRrd)$r1r2r3r4r5r8r9r:rTrrUrr;rrrrrrrrrrrrrrrrrrrrrIteratorrr!r'r$r r Fs  #t (  5 ( c4[ ( 3+ ( >B>B; ; ( x (         9      3      ?*    s".#!6   ;+?      r'r ceZdZdZdZdS)r TYPIOcdS)Nr!r!r"s r$_e_metaszTypeIO._e_metass r'N)r1r2r3r5r r!r'r$r r s(      r'r cleZdZeejdefdZeejdefdZeejdefdZ eejdede fdZ ejdede dffdZ ejdd Zejdejgfd ZdS) SocketFactoryrcdS)z The exception that is raised by sockets that indicate a fatal error. The exception can be a base exception as the `fatal_error_message` will indicate if that particular exception is actually fatal. Nr!r"s r$fatal_exceptionzSocketFactory.fatal_exceptionr&r'cdS)zx The exception raised by the socket when an operation could not be completed due to a configured time constraint. Nr!r"s r$timeout_exceptionzSocketFactory.timeout_exception)r&r'cdS)zh The exception raised by the socket when an operation was interrupted, but should be tried again. Nr!r"s r$tryagain_exceptionz SocketFactory.tryagain_exception1r&r'errcdS)zH Whether or not `err` suggests the operation should be tried again. Nr!r#rs r$tryagainzSocketFactory.tryagain9r&r'NcdS)a A function returning a string describing the failure, this string will be given to the `postgresql.exceptions.ConnectionFailure` instance that will subsequently be raised by the `Connection` object. Returns `None` when `err` is not actually fatal. Nr!rs r$fatal_exception_messagez%SocketFactory.fatal_exception_message@r&r'socket socket objectsecured socketcdS)z Return a reference to the secured socket using the given parameters. If securing the socket for the connector is impossible, the user should never be able to instantiate the connector with parameters requesting security. Nr!)r#rs r$ socket_securezSocketFactory.socket_secureJr&r'cdS)zm Return a sequence of `SocketCreator`s that `Connection` objects will use to create the socket object. Nr!r"s r$socket_factory_sequencez%SocketFactory.socket_factory_sequenceTr&r')rrrr)r1r2r3r8r9r: Exceptionrrrr=rr;rrrCallabler!r!r'r$rrsx i (   (   (  ) ( T{{';&<r'rc:eZdZdZdZdZejdZdS)r z A category is an object that initializes the subject connection for a specific purpose. Arguably, a runtime class for use with connections. CATEGORYr!cdS)zJ Initialize the given connection in order to conform to the category. Nr!)r# connections r$ryzCategory.__call__er&r'N) r1r2r3r4r5rSr9r:ryr!r'r$r r [sG r'r c ReZdZdZdZdZdZ d ddded ed eeefgfd e f d Z dS)r z A connector is an object providing the necessary information to establish a connection. This includes credentials, database settings, and many times addressing information. CONNECTOR)drivercategoryc.|jj|g|Ri|S)zd Create and connect. Arguments will be given to the `Connection` instance's `connect` method. )r*r'rs r$ryzConnector.__call__ts)   2t 2 2 2r 2 22r'Nuserz.required keyword specifying the user name(str)passwordrrr+c|td||_||_||_||_||_|$t |tstddSdS)Nz'user' is a required keywordz8'category' must a be `None` or `postgresql.api.Category`) TypeErrorr-r.rrr+ isinstancer )r#r-r.rrr+s r$__init__zConnector.__init__{sm \ 1 2 22$)$-$-$-$- *Xx"@"@ M N NNr')NNNNN) r1r2r3r4r5rSryr;r<r r2r!r'r$r r ks $333=A#' OO 9O OOc#YK O  OOOOOOr'r cbeZdZdZdZdZeejde fdZ eejde fdZ eejde fdZejddZejdd Zejdd Zejd Zejd Zd S)r z The interface to a connection to a PostgreSQL database. This is a `Database` interface with the additional connection management tools that are particular to using a remote database. CONNECTION) connectorrcdS)zs The :py:class:`Connector` instance facilitating the `Connection` object's communication and initialization. Nr!r"s r$r5zConnection.connectorr&r'cdS)z The :py:class:`Execution` instance providing a one-shot query interface:: connection.query.(sql, *parameters) == connection.prepare(sql).(*parameters) Nr!r"s r$queryzConnection.queryr&r'cdS)zj `True` if the `Connection` is closed, `False` if the `Connection` is open. >>> db.closed True Nr!r"s r$closedzConnection.closedr&r'cdS)zy Create another connection using the same factors as `self`. The returned object should be open and ready for use. Nr!r"s r$rbzConnection.cloner&r'Nc<|jj}| ||dSdS)z Establish the connection to the server and initialize the category. Does nothing if the connection is already established. N)r5r+)r#cats r$connectzConnection.connects+ #_3t99999_r'cdS)zP Close the connection. Does nothing if the connection is already closed. Nr!r"s r$rEzConnection.closer&r'cdS)z/ Establish the connection and return self. Nr!r"s r$rzConnection.__enter__r&r'cdS)ze Closes the connection and returns `False` when an exception is passed in, `True` when `None`. Nr!rs r$rzConnection.__exit__r&r')rr rR)r1r2r3r4r5rSr8r9r:r r5rvr8r=r:rbr>rErrr!r'r$r r sq    (  I ( T (      r'r c:eZdZdZdZdZejdZdS)rz The `Driver` element provides the `Connector` and other information pertaining to the implementation of the driver. Information about what the driver supports is available in instances. DRIVERr!c dS)zG Create a connection using the given parameters for the Connector. Nr!)rs r$r>zDriver.connectr&r'N) r1r2r3r4r5rSr9r:r>r!r'r$rrsG r'rceZdZdZdZdZeejdZ eejdZ eejdZ eejde fdZ d S) rz Interface to a PostgreSQL installation. Instances would provide various information about an installation of PostgreSQL accessible by the Python INSTALLATIONr!cdS)zL A version string consistent with what `SELECT version()` would output. Nr!r"s r$versionzInstallation.versionr&r'cdS)z A tuple specifying the version in a form similar to Python's sys.version_info. (8, 3, 3, 'final', 0) See `postgresql.versionstring`. Nr!r"s r$rzInstallation.version_infor&r'cdS)zd The "type" of PostgreSQL. Normally, the first component of the string returned by pg_config. Nr!r"s r$rzInstallation.typer&r'rcdS)z, Whether the installation supports SSL. Nr!r"s r$sslzInstallation.ssl r&r'N)r1r2r3r4r5rSr8r9r:rHrrr=rLr!r'r$rrs   (   (  (  $ (r'rcPeZdZdZdZdZeejde fdZ eejde fdZ ej d. d/d Z ejd!Zejd"Zejd#Zejd$Zejd%Zej d0 d1d)Zej d0 d1d*Zeejd+Zejd,Zejd-ZdS)2rzy Interface to a PostgreSQL cluster--a data directory. An implementation of this provides a means to control a server. CLUSTER) installationdata_directoryrcdS)z+ The installation used by the cluster. Nr!r"s r$rOzCluster.installationr&r'cdS)z4 The path to the data directory of the cluster. Nr!r"s r$rPzCluster.data_directoryr&r'Ninitdbpath to the initdb to user-name of the cluster's superuserr.superuser's passwordencoding#the encoding to use for the clusterlocale!the locale to use for the clustercollate$the collation to use for the clusterctype the ctype to use for the clustermonetary#the monetary to use for the clusternumeric"the numeric to use for the clustertimethe time to use for the clustertext_search_config!default text search configurationxlogdir*location for the transaction log directoryc dS)zX Create the cluster at the `data_directory` associated with the Cluster instance. Nr!) r#rSr-r.rWrYr[r]r_rarcrergs r$initz Cluster.init&r&r'cdS)z? Kill the server and completely remove the data directory. Nr!r"s r$dropz Cluster.drop:r&r'cdS)z Start the cluster. Nr!r"s r$rz Cluster.start@r&r'cdS)z$ Signal the server to shutdown. Nr!r"s r$stopz Cluster.stopFr&r'cdS)z Kill the server. Nr!r"s r$killz Cluster.killLr&r'cdS)z Restart the cluster. Nr!r"s r$restartzCluster.restartRr&r' rmaximum time to waitcdS)a After the start() method is ran, the database may not be ready for use. This method provides a mechanism to block until the cluster is ready for use. If the `timeout` is reached, the method *must* throw a `postgresql.exceptions.ClusterTimeoutError`. Nr!rs r$wait_until_startedzCluster.wait_until_startedXr&r'cdS)a  After the stop() method is ran, the database may still be running. This method provides a mechanism to block until the cluster is completely shutdown. If the `timeout` is reached, the method *must* throw a `postgresql.exceptions.ClusterTimeoutError`. Nr!rs r$wait_until_stoppedzCluster.wait_until_stoppeder&r'cdS)z[ A `Settings` interface to the ``postgresql.conf`` file associated with the cluster. Nr!r"s r$rzCluster.settingsrr&r'cdS)zU Start the cluster if it's not already running, and wait for it to be readied. Nr!r"s r$rzCluster.__enter__zr&r'cdS)ze Stop the cluster and wait for it to shutdown *iff* it was started by the corresponding enter. Nr!)r#excvalrs r$rzCluster.__exit__r&r') NNNNNNNNNNNN)rSrTr-rUr.rVrWrXrYrZr[r\r]r^r_r`rarbrcrdrerfrgrh)rt)rru)r1r2r3r4r5rSr8r9r:rrOr;rPrjrlrrorqrsrwryrrrr!r'r$rrs 0 < (  S ( )--1&*591559/35937-1=A;? & *$3  /  3  -3 1 +; 9&     %'  "    %'  "      (  r'rreStructuredText__main__z.api)$r4rr9python.elementr__all__rr?rrrrABCMetarvr#rregisterPreparedStatementrrMutableMappingrr r rrr r r rrr __docformat__r1help __package__r!r'r$rs1   ######   $JJJJJgJJJXZZZZZWZZZx  _____  ___B]]]]]CK]]]]~AAAAA  AAAD 9 D}}}}}'}}}~JJJJJ JJJXPPPPPwPPPd     W   ;;;;;F;;;zw O O O O O O O ODJJJJJJJJX     W   &&&&&7&&&Pvvvvvgvvvp#  zkFr'