1"""
2libpq enum definitions for psycopg
3"""
4
5# Copyright (C) 2020-2021 The Psycopg Team
6
7from enum import IntEnum, auto
8
9
10class ConnStatus(IntEnum):
11    """
12    Current status of the connection.
13    """
14
15    __module__ = "psycopg.pq"
16
17    OK = 0
18    """The connection is in a working state."""
19    BAD = auto()
20    """The connection is closed."""
21
22    STARTED = auto()
23    MADE = auto()
24    AWAITING_RESPONSE = auto()
25    AUTH_OK = auto()
26    SETENV = auto()
27    SSL_STARTUP = auto()
28    NEEDED = auto()
29    CHECK_WRITABLE = auto()
30    CONSUME = auto()
31    GSS_STARTUP = auto()
32    CHECK_TARGET = auto()
33
34
35class PollingStatus(IntEnum):
36    """
37    The status of the socket during a connection.
38
39    If ``READING`` or ``WRITING`` you may select before polling again.
40    """
41
42    __module__ = "psycopg.pq"
43
44    FAILED = 0
45    """Connection attempt failed."""
46    READING = auto()
47    """Will have to wait before reading new data."""
48    WRITING = auto()
49    """Will have to wait before writing new data."""
50    OK = auto()
51    """Connection completed."""
52
53    ACTIVE = auto()
54
55
56class ExecStatus(IntEnum):
57    """
58    The status of a command.
59    """
60
61    __module__ = "psycopg.pq"
62
63    EMPTY_QUERY = 0
64    """The string sent to the server was empty."""
65
66    COMMAND_OK = auto()
67    """Successful completion of a command returning no data."""
68
69    TUPLES_OK = auto()
70    """
71    Successful completion of a command returning data (such as a SELECT or SHOW).
72    """
73
74    COPY_OUT = auto()
75    """Copy Out (from server) data transfer started."""
76
77    COPY_IN = auto()
78    """Copy In (to server) data transfer started."""
79
80    BAD_RESPONSE = auto()
81    """The server's response was not understood."""
82
83    NONFATAL_ERROR = auto()
84    """A nonfatal error (a notice or warning) occurred."""
85
86    FATAL_ERROR = auto()
87    """A fatal error occurred."""
88
89    COPY_BOTH = auto()
90    """
91    Copy In/Out (to and from server) data transfer started.
92
93    This feature is currently used only for streaming replication, so this
94    status should not occur in ordinary applications.
95    """
96
97    SINGLE_TUPLE = auto()
98    """
99    The PGresult contains a single result tuple from the current command.
100
101    This status occurs only when single-row mode has been selected for the
102    query.
103    """
104
105    PIPELINE_SYNC = auto()
106    """
107    The PGresult represents a synchronization point in pipeline mode,
108    requested by PQpipelineSync.
109
110    This status occurs only when pipeline mode has been selected.
111    """
112
113    PIPELINE_ABORTED = auto()
114    """
115    The PGresult represents a pipeline that has received an error from the server.
116
117    PQgetResult must be called repeatedly, and each time it will return this
118    status code until the end of the current pipeline, at which point it will
119    return PGRES_PIPELINE_SYNC and normal processing can resume.
120    """
121
122
123class TransactionStatus(IntEnum):
124    """
125    The transaction status of a connection.
126    """
127
128    __module__ = "psycopg.pq"
129
130    IDLE = 0
131    """Connection ready, no transaction active."""
132
133    ACTIVE = auto()
134    """A command is in progress."""
135
136    INTRANS = auto()
137    """Connection idle in an open transaction."""
138
139    INERROR = auto()
140    """An error happened in the current transaction."""
141
142    UNKNOWN = auto()
143    """Unknown connection state, broken connection."""
144
145
146class Ping(IntEnum):
147    """Response from a ping attempt."""
148
149    __module__ = "psycopg.pq"
150
151    OK = 0
152    """
153    The server is running and appears to be accepting connections.
154    """
155
156    REJECT = auto()
157    """
158    The server is running but is in a state that disallows connections.
159    """
160
161    NO_RESPONSE = auto()
162    """
163    The server could not be contacted.
164    """
165
166    NO_ATTEMPT = auto()
167    """
168    No attempt was made to contact the server.
169    """
170
171
172class PipelineStatus(IntEnum):
173    """Pipeline mode status of the libpq connection."""
174
175    __module__ = "psycopg.pq"
176
177    OFF = 0
178    """
179    The libpq connection is *not* in pipeline mode.
180    """
181    ON = auto()
182    """
183    The libpq connection is in pipeline mode.
184    """
185    ABORTED = auto()
186    """
187    The libpq connection is in pipeline mode and an error occurred while
188    processing the current pipeline. The aborted flag is cleared when
189    PQgetResult returns a result of type PGRES_PIPELINE_SYNC.
190    """
191
192
193class DiagnosticField(IntEnum):
194    """
195    Fields in an error report.
196    """
197
198    __module__ = "psycopg.pq"
199
200    # from postgres_ext.h
201    SEVERITY = ord("S")
202    SEVERITY_NONLOCALIZED = ord("V")
203    SQLSTATE = ord("C")
204    MESSAGE_PRIMARY = ord("M")
205    MESSAGE_DETAIL = ord("D")
206    MESSAGE_HINT = ord("H")
207    STATEMENT_POSITION = ord("P")
208    INTERNAL_POSITION = ord("p")
209    INTERNAL_QUERY = ord("q")
210    CONTEXT = ord("W")
211    SCHEMA_NAME = ord("s")
212    TABLE_NAME = ord("t")
213    COLUMN_NAME = ord("c")
214    DATATYPE_NAME = ord("d")
215    CONSTRAINT_NAME = ord("n")
216    SOURCE_FILE = ord("F")
217    SOURCE_LINE = ord("L")
218    SOURCE_FUNCTION = ord("R")
219
220
221class Format(IntEnum):
222    """
223    Enum representing the format of a query argument or return value.
224
225    These values are only the ones managed by the libpq. `~psycopg` may also
226    support automatically-chosen values: see `psycopg.adapt.PyFormat`.
227    """
228
229    __module__ = "psycopg.pq"
230
231    TEXT = 0
232    """Text parameter."""
233    BINARY = 1
234    """Binary parameter."""
235