Skip to content

Commit 4502741

Browse files
tswasttswast
authored
Implementation of DB-API for BigQuery. (#2921)
The `google.cloud.bigquery.dbapi` package covers all of the required implementation details in the PEP-249 DB-API specification.
1 parent 91246a4 commit 4502741

11 files changed

Lines changed: 1432 additions & 19 deletions

File tree

‎google/cloud/bigquery/dbapi/__init__.py‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Copyright 2017 Google Inc.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""Google BigQuery implementation of the Database API Specification v2.0.
16+
17+
This module implements the `Python Database API Specification v2.0 (DB-API)`_
18+
for Google BigQuery.
19+
20+
.. _Python Database API Specification v2.0 (DB-API):
21+
https://www.python.org/dev/peps/pep-0249/
22+
23+
.. warning::
24+
The ``dbapi`` module is **alpha**. The implementation is not complete. It
25+
might be changed in backward-incompatible ways and is not subject to any SLA
26+
or deprecation policy.
27+
"""
28+
29+
from google.cloud.bigquery.dbapi.connection import connect
30+
from google.cloud.bigquery.dbapi.connection import Connection
31+
from google.cloud.bigquery.dbapi.cursor import Cursor
32+
from google.cloud.bigquery.dbapi.exceptions import Warning
33+
from google.cloud.bigquery.dbapi.exceptions import Error
34+
from google.cloud.bigquery.dbapi.exceptions import InterfaceError
35+
from google.cloud.bigquery.dbapi.exceptions import DatabaseError
36+
from google.cloud.bigquery.dbapi.exceptions import DataError
37+
from google.cloud.bigquery.dbapi.exceptions import OperationalError
38+
from google.cloud.bigquery.dbapi.exceptions import IntegrityError
39+
from google.cloud.bigquery.dbapi.exceptions import InternalError
40+
from google.cloud.bigquery.dbapi.exceptions import ProgrammingError
41+
from google.cloud.bigquery.dbapi.exceptions import NotSupportedError
42+
from google.cloud.bigquery.dbapi.types import Binary
43+
from google.cloud.bigquery.dbapi.types import Date
44+
from google.cloud.bigquery.dbapi.types import DateFromTicks
45+
from google.cloud.bigquery.dbapi.types import Time
46+
from google.cloud.bigquery.dbapi.types import TimeFromTicks
47+
from google.cloud.bigquery.dbapi.types import Timestamp
48+
from google.cloud.bigquery.dbapi.types import TimestampFromTicks
49+
from google.cloud.bigquery.dbapi.types import BINARY
50+
from google.cloud.bigquery.dbapi.types import DATETIME
51+
from google.cloud.bigquery.dbapi.types import NUMBER
52+
from google.cloud.bigquery.dbapi.types import ROWID
53+
from google.cloud.bigquery.dbapi.types import STRING
54+
55+
56+
apilevel = '2.0'
57+
58+
# Threads may share the module, but not connections.
59+
threadsafety = 1
60+
61+
paramstyle = 'pyformat'
62+
63+
__all__ = [
64+
'apilevel', 'threadsafety', 'paramstyle', 'connect', 'Connection',
65+
'Cursor', 'Warning', 'Error', 'InterfaceError', 'DatabaseError',
66+
'DataError', 'OperationalError', 'IntegrityError', 'InternalError',
67+
'ProgrammingError', 'NotSupportedError', 'Binary', 'Date', 'DateFromTicks',
68+
'Time', 'TimeFromTicks', 'Timestamp', 'TimestampFromTicks', 'BINARY',
69+
'DATETIME', 'NUMBER', 'ROWID', 'STRING',
70+
]

‎google/cloud/bigquery/dbapi/_helpers.py‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Copyright 2017 Google Inc.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import collections
16+
import datetime
17+
import numbers
18+
import time
19+
20+
import six
21+
22+
from google.cloud import bigquery
23+
from google.cloud.bigquery.dbapi import exceptions
24+
25+
26+
def wait_for_job(job):
27+
"""Waits for a job to complete by polling until the state is `DONE`.
28+
29+
Sleeps 1 second between calls to the BigQuery API.
30+
31+
:type job: :class:`~google.cloud.bigquery.job._AsyncJob`
32+
:param job: Wait for this job to finish.
33+
34+
:raises: :class:`~google.cloud.bigquery.dbapi.exceptions.DatabaseError`
35+
if the job fails.
36+
"""
37+
while True:
38+
job.reload()
39+
if job.state == 'DONE':
40+
if job.error_result:
41+
raise exceptions.DatabaseError(job.errors)
42+
return
43+
time.sleep(1)
44+
45+
46+
def scalar_to_query_parameter(value, name=None):
47+
"""Convert a scalar value into a query parameter.
48+
49+
:type value: any
50+
:param value: A scalar value to convert into a query parameter.
51+
52+
:type name: str
53+
:param name: (Optional) Name of the query parameter.
54+
55+
:rtype: :class:`~google.cloud.bigquery.ScalarQueryParameter`
56+
:returns:
57+
A query parameter corresponding with the type and value of the plain
58+
Python object.
59+
:raises: :class:`~google.cloud.bigquery.dbapi.exceptions.ProgrammingError`
60+
if the type cannot be determined.
61+
"""
62+
parameter_type = None
63+
64+
if isinstance(value, bool):
65+
parameter_type = 'BOOL'
66+
elif isinstance(value, numbers.Integral):
67+
parameter_type = 'INT64'
68+
elif isinstance(value, numbers.Real):
69+
parameter_type = 'FLOAT64'
70+
elif isinstance(value, six.text_type):
71+
parameter_type = 'STRING'
72+
elif isinstance(value, six.binary_type):
73+
parameter_type = 'BYTES'
74+
elif isinstance(value, datetime.datetime):
75+
parameter_type = 'DATETIME' if value.tzinfo is None else 'TIMESTAMP'
76+
elif isinstance(value, datetime.date):
77+
parameter_type = 'DATE'
78+
elif isinstance(value, datetime.time):
79+
parameter_type = 'TIME'
80+
else:
81+
raise exceptions.ProgrammingError(
82+
'encountered parameter {} with value {} of unexpected type'.format(
83+
name, value))
84+
return bigquery.ScalarQueryParameter(name, parameter_type, value)
85+
86+
87+
def to_query_parameters_list(parameters):
88+
"""Converts a sequence of parameter values into query parameters.
89+
90+
:type parameters: Sequence[Any]
91+
:param parameters: Sequence of query parameter values.
92+
93+
:rtype: List[google.cloud.bigquery._helpers.AbstractQueryParameter]
94+
:returns: A list of query parameters.
95+
"""
96+
return [scalar_to_query_parameter(value) for value in parameters]
97+
98+
99+
def to_query_parameters_dict(parameters):
100+
"""Converts a dictionary of parameter values into query parameters.
101+
102+
:type parameters: Mapping[str, Any]
103+
:param parameters: Dictionary of query parameter values.
104+
105+
:rtype: List[google.cloud.bigquery._helpers.AbstractQueryParameter]
106+
:returns: A list of named query parameters.
107+
"""
108+
return [
109+
scalar_to_query_parameter(value, name=name)
110+
for name, value
111+
in six.iteritems(parameters)]
112+
113+
114+
def to_query_parameters(parameters):
115+
"""Converts DB-API parameter values into query parameters.
116+
117+
:type parameters: Mapping[str, Any] or Sequence[Any]
118+
:param parameters: A dictionary or sequence of query parameter values.
119+
120+
:rtype: List[google.cloud.bigquery._helpers.AbstractQueryParameter]
121+
:returns: A list of query parameters.
122+
"""
123+
if parameters is None:
124+
return []
125+
126+
if isinstance(parameters, collections.Mapping):
127+
return to_query_parameters_dict(parameters)
128+
129+
return to_query_parameters_list(parameters)

‎google/cloud/bigquery/dbapi/connection.py‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Copyright 2017 Google Inc.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""Connection for the Google BigQuery DB-API."""
16+
17+
from google.cloud import bigquery
18+
from google.cloud.bigquery.dbapi import cursor
19+
20+
21+
class Connection(object):
22+
"""DB-API Connection to Google BigQuery.
23+
24+
:type client: :class:`~google.cloud.bigquery.Client`
25+
:param client: A client used to connect to BigQuery.
26+
"""
27+
def __init__(self, client):
28+
self._client = client
29+
30+
def close(self):
31+
"""No-op."""
32+
33+
def commit(self):
34+
"""No-op."""
35+
36+
def cursor(self):
37+
"""Return a new cursor object.
38+
39+
:rtype: :class:`~google.cloud.bigquery.dbapi.Cursor`
40+
:returns: A DB-API cursor that uses this connection.
41+
"""
42+
return cursor.Cursor(self)
43+
44+
45+
def connect(client=None):
46+
"""Construct a DB-API connection to Google BigQuery.
47+
48+
:type client: :class:`~google.cloud.bigquery.Client`
49+
:param client:
50+
(Optional) A client used to connect to BigQuery. If not passed, a
51+
client is created using default options inferred from the environment.
52+
53+
:rtype: :class:`~google.cloud.bigquery.dbapi.Connection`
54+
:returns: A new DB-API connection to BigQuery.
55+
"""
56+
if client is None:
57+
client = bigquery.Client()
58+
return Connection(client)

0 commit comments

Comments
 (0)