feat: Comment/description support, bug fixes and better test coverage

.coveragerc

@@ -17,8 +17,6 @@
 # Generated by synthtool. DO NOT EDIT!
 [run]
 branch = True
-omit =
-  google/cloud/__init__.py
 
 [report]
 fail_under = 100
@@ -35,4 +33,4 @@ omit =
   */proto/*.py
   */core/*.py
   */site-packages/*.py
-  google/cloud/__init__.py
+  pybigquery/requirements.py

noxfile.py

@@ -28,17 +28,18 @@
 BLACK_PATHS = ["docs", "pybigquery", "tests", "noxfile.py", "setup.py"]
 
 DEFAULT_PYTHON_VERSION = "3.8"
-SYSTEM_TEST_PYTHON_VERSIONS = ["3.8"]
+SYSTEM_TEST_PYTHON_VERSIONS = ["3.9"]
 UNIT_TEST_PYTHON_VERSIONS = ["3.6", "3.7", "3.8", "3.9"]
 
 CURRENT_DIRECTORY = pathlib.Path(__file__).parent.absolute()
 
 # 'docfx' is excluded since it only needs to run in 'docs-presubmit'
 nox.options.sessions = [
+    "lint",
     "unit",
-    "system",
     "cover",
-    "lint",
+    "system",
+    "compliance",
     "lint_setup_py",
     "blacken",
     "docs",
@@ -169,6 +170,54 @@ def system(session):
         )
 
 
+@nox.session(python=SYSTEM_TEST_PYTHON_VERSIONS)
+def compliance(session):
+    """Run the system test suite."""
+    constraints_path = str(
+        CURRENT_DIRECTORY / "testing" / f"constraints-{session.python}.txt"
+    )
+    system_test_folder_path = os.path.join("tests", "sqlalchemy_dialect_compliance")
+
+    # Check the value of `RUN_SYSTEM_TESTS` env var. It defaults to true.
+    if os.environ.get("RUN_COMPLIANCE_TESTS", "true") == "false":
+        session.skip("RUN_COMPLIANCE_TESTS is set to false, skipping")
+    # Sanity check: Only run tests if the environment variable is set.
+    if not os.environ.get("GOOGLE_APPLICATION_CREDENTIALS", ""):
+        session.skip("Credentials must be set via environment variable")
+    # Install pyopenssl for mTLS testing.
+    if os.environ.get("GOOGLE_API_USE_CLIENT_CERTIFICATE", "false") == "true":
+        session.install("pyopenssl")
+    # Sanity check: only run tests if found.
+    if not os.path.exists(system_test_folder_path):
+        session.skip("Compliance tests were not found")
+
+    # Use pre-release gRPC for system tests.
+    session.install("--pre", "grpcio")
+
+    # Install all test dependencies, then install this package into the
+    # virtualenv's dist-packages.
+    session.install(
+        "mock",
+        "pytest",
+        "pytest-rerunfailures",
+        "google-cloud-testutils",
+        "-c",
+        constraints_path,
+    )
+    session.install("-e", ".", "-c", constraints_path)
+
+    session.run(
+        "py.test",
+        "-vv",
+        f"--junitxml=compliance_{session.python}_sponge_log.xml",
+        "--reruns=3",
+        "--reruns-delay=60",
+        "--only-rerun=403 Exceeded rate limits|409 Already Exists",
+        system_test_folder_path,
+        *session.posargs,
+    )
+
+
 @nox.session(python=DEFAULT_PYTHON_VERSION)
 def cover(session):
     """Run the final coverage report.
@@ -177,7 +226,7 @@ def cover(session):
     test runs (not system test runs), and then erases coverage data.
     """
     session.install("coverage", "pytest-cov")
-    session.run("coverage", "report", "--show-missing", "--fail-under=50")
+    session.run("coverage", "report", "--show-missing", "--fail-under=100")
 
     session.run("coverage", "erase")
 

pybigquery/requirements.py

@@ -0,0 +1,220 @@
+# Copyright (c) 2021 The PyBigQuery Authors
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+"""
+This module is used by the compliance tests to control which tests are run
+
+based on database capabilities.
+"""
+
+import sqlalchemy.testing.requirements
+import sqlalchemy.testing.exclusions
+
+supported = sqlalchemy.testing.exclusions.open
+unsupported = sqlalchemy.testing.exclusions.closed
+
+
+class Requirements(sqlalchemy.testing.requirements.SuiteRequirements):
+    @property
+    def index_reflection(self):
+        return unsupported()
+
+    @property
+    def indexes_with_ascdesc(self):
+        """target database supports CREATE INDEX with per-column ASC/DESC."""
+        return unsupported()
+
+    @property
+    def unique_constraint_reflection(self):
+        """target dialect supports reflection of unique constraints"""
+        return unsupported()
+
+    @property
+    def autoincrement_insert(self):
+        """target platform generates new surrogate integer primary key values
+        when insert() is executed, excluding the pk column."""
+        return unsupported()
+
+    @property
+    def primary_key_constraint_reflection(self):
+        return unsupported()
+
+    @property
+    def foreign_keys(self):
+        """Target database must support foreign keys."""
+
+        return unsupported()
+
+    @property
+    def foreign_key_constraint_reflection(self):
+        return unsupported()
+
+    @property
+    def on_update_cascade(self):
+        """target database must support ON UPDATE..CASCADE behavior in
+        foreign keys."""
+
+        return unsupported()
+
+    @property
+    def named_constraints(self):
+        """target database must support names for constraints."""
+
+        return unsupported()
+
+    @property
+    def temp_table_reflection(self):
+        return unsupported()
+
+    @property
+    def temporary_tables(self):
+        """target database supports temporary tables"""
+        return unsupported()  # Temporary tables require use of scripts.
+
+    @property
+    def duplicate_key_raises_integrity_error(self):
+        """target dialect raises IntegrityError when reporting an INSERT
+        with a primary key violation.  (hint: it should)
+
+        """
+        return unsupported()
+
+    @property
+    def precision_numerics_many_significant_digits(self):
+        """target backend supports values with many digits on both sides,
+        such as 319438950232418390.273596, 87673.594069654243
+
+        """
+        return supported()
+
+    @property
+    def date_coerces_from_datetime(self):
+        """target dialect accepts a datetime object as the target
+        of a date column."""
+
+        # BigQuery doesn't allow saving a datetime in a date:
+        # `TYPE_DATE`, Invalid date: '2012-10-15T12:57:18'
+
+        return unsupported()
+
+    @property
+    def window_functions(self):
+        """Target database must support window functions."""
+        return supported()  # There are no tests for this. <shrug>
+
+    @property
+    def ctes(self):
+        """Target database supports CTEs"""
+
+        return supported()
+
+    @property
+    def views(self):
+        """Target database must support VIEWs."""
+
+        return supported()
+
+    @property
+    def schemas(self):
+        """Target database must support external schemas, and have one
+        named 'test_schema'."""
+
+        return supported()
+
+    @property
+    def implicit_default_schema(self):
+        """target system has a strong concept of 'default' schema that can
+        be referred to implicitly.
+
+        basically, PostgreSQL.
+
+        """
+        return supported()
+
+    @property
+    def comment_reflection(self):
+        return supported()  # Well, probably not, but we'll try. :)
+
+    @property
+    def unicode_ddl(self):
+        """Target driver must support some degree of non-ascii symbol
+        names.
+        """
+        return supported()
+
+    @property
+    def datetime_literals(self):
+        """target dialect supports rendering of a date, time, or datetime as a
+        literal string, e.g. via the TypeEngine.literal_processor() method.
+
+        """
+
+        return supported()
+
+    @property
+    def timestamp_microseconds(self):
+        """target dialect supports representation of Python
+        datetime.datetime() with microsecond objects but only
+        if TIMESTAMP is used."""
+        return supported()
+
+    @property
+    def datetime_historic(self):
+        """target dialect supports representation of Python
+        datetime.datetime() objects with historic (pre 1970) values."""
+
+        return supported()
+
+    @property
+    def date_historic(self):
+        """target dialect supports representation of Python
+        datetime.datetime() objects with historic (pre 1970) values."""
+
+        return supported()
+
+    @property
+    def precision_numerics_enotation_small(self):
+        """target backend supports Decimal() objects using E notation
+        to represent very small values."""
+        return supported()
+
+    @property
+    def precision_numerics_enotation_large(self):
+        """target backend supports Decimal() objects using E notation
+        to represent very large values."""
+        return supported()
+
+    @property
+    def update_from(self):
+        """Target must support UPDATE..FROM syntax"""
+        return supported()
+
+    @property
+    def order_by_label_with_expression(self):
+        """target backend supports ORDER BY a column label within an
+        expression.
+
+        Basically this::
+
+            select data as foo from test order by foo || 'bar'
+
+        Lots of databases including PostgreSQL don't support this,
+        so this is off by default.
+
+        """
+        return supported()