BQ: Make snippets.py run as system tests.

Converts snippet function names to pytest conventions (shouldn't affect
the docs, as the docs use region tags to grab sub-sections to include.

I had to make some minor changes to ensure that the samples work on both
Python 2 and Python 3, which is why I didn't try to bulk update the
snippets for all the other products.

Author: tswast

bigquery/nox.py

@@ -87,6 +87,39 @@ def system_tests(session, python_version):
     )
 
 
+@nox.session
+@nox.parametrize('python_version', ['2.7', '3.6'])
+def snippets_tests(session, python_version):
+    """Run the system test suite."""
+
+    # Sanity check: Only run system tests if the environment variable is set.
+    if not os.environ.get('GOOGLE_APPLICATION_CREDENTIALS', ''):
+        session.skip('Credentials must be set via environment variable.')
+
+    # Run the system tests against latest Python 2 and Python 3 only.
+    session.interpreter = 'python{}'.format(python_version)
+
+    # Set the virtualenv dirname.
+    session.virtualenv_dirname = 'snip-' + python_version
+
+    # Install all test dependencies, then install this package into the
+    # virtualenv's dist-packages.
+    session.install('mock', 'pytest', *LOCAL_DEPS)
+    session.install(
+        os.path.join('..', 'storage'),
+        os.path.join('..', 'test_utils'),
+    )
+    session.install('.')
+
+    # Run py.test against the system tests.
+    session.run(
+        'py.test',
+        '--quiet',
+        os.path.join(os.pardir, 'docs', 'bigquery', 'snippets.py'),
+        *session.posargs
+    )
+
+
 @nox.session
 def lint(session):
     """Run linters.
@@ -100,6 +133,8 @@ def lint(session):
     session.install('.')
     session.run('flake8', os.path.join('google', 'cloud', 'bigquery'))
     session.run('flake8', 'tests')
+    session.run(
+        'flake8', os.path.join(os.pardir, 'docs', 'bigquery', 'snippets.py'))
     session.run(
         'gcp-devrel-py-tools', 'run-pylint',
         '--config', 'pylint.config.py',

docs/bigquery/snippets.py

@@ -26,6 +26,7 @@
 import operator
 import time
 
+import pytest
 import six
 
 from google.cloud.bigquery import SchemaField
@@ -50,10 +51,17 @@
     'WHERE state = "TX"')
 
 
-def snippet(func):
-    """Mark ``func`` as a snippet example function."""
-    func._snippet = True
-    return func
+@pytest.fixture(scope='module')
+def client():
+    return Client()
+
+
+@pytest.fixture
+def to_delete():
+    doomed = []
+    yield doomed
+    for item in doomed:
+        item.delete()
 
 
 def _millis():
@@ -69,8 +77,7 @@ def delete(self):
         self._wrapped.close()
 
 
-@snippet
-def client_list_datasets(client, _):
+def test_client_list_datasets(client):
     """List datasets for a project."""
 
     def do_something_with(_):
@@ -82,8 +89,7 @@ def do_something_with(_):
     # [END client_list_datasets]
 
 
-@snippet
-def dataset_create(client, to_delete):
+def test_dataset_create(client, to_delete):
     """Create a dataset."""
     DATASET_NAME = 'dataset_create_%d' % (_millis(),)
 
@@ -95,8 +101,7 @@ def dataset_create(client, to_delete):
     to_delete.append(dataset)
 
 
-@snippet
-def dataset_exists(client, to_delete):
+def test_dataset_exists(client, to_delete):
     """Test existence of a dataset."""
     DATASET_NAME = 'dataset_exists_%d' % (_millis(),)
     dataset = client.dataset(DATASET_NAME)
@@ -109,8 +114,7 @@ def dataset_exists(client, to_delete):
     # [END dataset_exists]
 
 
-@snippet
-def dataset_reload(client, to_delete):
+def test_dataset_reload(client, to_delete):
     """Reload a dataset's metadata."""
     DATASET_NAME = 'dataset_reload_%d' % (_millis(),)
     dataset = client.dataset(DATASET_NAME)
@@ -127,8 +131,7 @@ def dataset_reload(client, to_delete):
     # [END dataset_reload]
 
 
-@snippet
-def dataset_patch(client, to_delete):
+def test_dataset_patch(client, to_delete):
     """Patch a dataset's metadata."""
     DATASET_NAME = 'dataset_patch_%d' % (_millis(),)
     dataset = client.dataset(DATASET_NAME)
@@ -148,8 +151,7 @@ def dataset_patch(client, to_delete):
     # [END dataset_patch]
 
 
-@snippet
-def dataset_update(client, to_delete):
+def test_dataset_update(client, to_delete):
     """Update a dataset's metadata."""
     DATASET_NAME = 'dataset_update_%d' % (_millis(),)
     dataset = client.dataset(DATASET_NAME)
@@ -178,8 +180,7 @@ def dataset_update(client, to_delete):
     # [END dataset_update]
 
 
-@snippet
-def dataset_delete(client, _):
+def test_dataset_delete(client):
     """Delete a dataset."""
     DATASET_NAME = 'dataset_delete_%d' % (_millis(),)
     dataset = client.dataset(DATASET_NAME)
@@ -192,8 +193,7 @@ def dataset_delete(client, _):
     # [END dataset_delete]
 
 
-@snippet
-def dataset_list_tables(client, to_delete):
+def test_dataset_list_tables(client, to_delete):
     """List tables within a dataset."""
     DATASET_NAME = 'dataset_list_tables_dataset_%d' % (_millis(),)
     TABLE_NAME = 'dataset_list_tables_table_%d' % (_millis(),)
@@ -214,8 +214,7 @@ def dataset_list_tables(client, to_delete):
     to_delete.insert(0, table)
 
 
-@snippet
-def table_create(client, to_delete):
+def test_table_create(client, to_delete):
     """Create a table."""
     DATASET_NAME = 'table_create_dataset_%d' % (_millis(),)
     TABLE_NAME = 'table_create_table_%d' % (_millis(),)
@@ -231,8 +230,7 @@ def table_create(client, to_delete):
     to_delete.insert(0, table)
 
 
-@snippet
-def table_exists(client, to_delete):
+def test_table_exists(client, to_delete):
     """Test existence of a table."""
     DATASET_NAME = 'table_exists_dataset_%d' % (_millis(),)
     TABLE_NAME = 'table_exists_table_%d' % (_millis(),)
@@ -250,8 +248,7 @@ def table_exists(client, to_delete):
     to_delete.insert(0, table)
 
 
-@snippet
-def table_reload(client, to_delete):
+def test_table_reload(client, to_delete):
     """Reload a table's metadata."""
     DATASET_NAME = 'table_reload_dataset_%d' % (_millis(),)
     TABLE_NAME = 'table_reload_table_%d' % (_millis(),)
@@ -276,8 +273,7 @@ def table_reload(client, to_delete):
     # [END table_reload]
 
 
-@snippet
-def table_patch(client, to_delete):
+def test_table_patch(client, to_delete):
     """Patch a table's metadata."""
     DATASET_NAME = 'table_patch_dataset_%d' % (_millis(),)
     TABLE_NAME = 'table_patch_table_%d' % (_millis(),)
@@ -304,8 +300,7 @@ def table_patch(client, to_delete):
     # [END table_patch]
 
 
-@snippet
-def table_update(client, to_delete):
+def test_table_update(client, to_delete):
     """Update a table's metadata."""
     DATASET_NAME = 'table_update_dataset_%d' % (_millis(),)
     TABLE_NAME = 'table_update_table_%d' % (_millis(),)
@@ -350,8 +345,7 @@ def _warm_up_inserted_table_data(table):
             time.sleep(5)
 
 
-@snippet
-def table_insert_fetch_data(client, to_delete):
+def test_table_insert_fetch_data(client, to_delete):
     """Insert / fetch table data."""
     DATASET_NAME = 'table_insert_fetch_data_dataset_%d' % (_millis(),)
     TABLE_NAME = 'table_insert_fetch_data_table_%d' % (_millis(),)
@@ -391,11 +385,8 @@ def do_something(row):
         assert found == to_insert
 
 
-@snippet
-def table_upload_from_file(client, to_delete):
+def test_table_upload_from_file(client, to_delete):
     """Upload table data from a CSV file."""
-    import csv
-    import tempfile
     DATASET_NAME = 'table_upload_from_file_dataset_%d' % (_millis(),)
     TABLE_NAME = 'table_upload_from_file_table_%d' % (_millis(),)
     dataset = client.dataset(DATASET_NAME)
@@ -406,19 +397,15 @@ def table_upload_from_file(client, to_delete):
     table.create()
     to_delete.insert(0, table)
 
-    csv_file = tempfile.NamedTemporaryFile(suffix='.csv')
-    to_delete.append(_CloseOnDelete(csv_file))
-
     # [START table_upload_from_file]
-    writer = csv.writer(csv_file)
-    writer.writerow((b'full_name', b'age'))
-    writer.writerow((b'Phred Phlyntstone', b'32'))
-    writer.writerow((b'Wylma Phlyntstone', b'29'))
-    csv_file.flush()
-
-    with open(csv_file.name, 'rb') as readable:
-        table.upload_from_file(
-            readable, source_format='CSV', skip_leading_rows=1)
+    csv_file = six.BytesIO(b"""full_name,age
+Phred Phlyntstone,32
+Wylma Phlyntstone,29
+""")
+
+    load_job = table.upload_from_file(
+        csv_file, source_format='CSV', skip_leading_rows=1)
+    load_job.result()  # Wait for table load to complete.
     # [END table_upload_from_file]
 
     _warm_up_inserted_table_data(table)
@@ -431,12 +418,11 @@ def table_upload_from_file(client, to_delete):
 
     assert len(rows) == total == 2
     assert token is None
-    assert rows[0] == (u'Phred Phlyntstone', 32)
-    assert rows[1] == (u'Wylma Phlyntstone', 29)
+    assert (u'Phred Phlyntstone', 32) in rows
+    assert (u'Wylma Phlyntstone', 29) in rows
 
 
-@snippet
-def table_delete(client, to_delete):
+def test_table_delete(client, to_delete):
     """Delete a table."""
     DATASET_NAME = 'table_delete_dataset_%d' % (_millis(),)
     TABLE_NAME = 'table_create_table_%d' % (_millis(),)
@@ -454,8 +440,7 @@ def table_delete(client, to_delete):
     # [END table_delete]
 
 
-@snippet
-def client_list_jobs(client, _):
+def test_client_list_jobs(client):
     """List jobs for a project."""
 
     def do_something_with(_):
@@ -468,12 +453,11 @@ def do_something_with(_):
     # [END client_list_jobs]
 
 
-@snippet
-def client_run_sync_query(client, _):
+def test_client_run_sync_query(client):
     """Run a synchronous query."""
     LIMIT = 100
     LIMITED = '%s LIMIT %d' % (QUERY, LIMIT)
-    TIMEOUT_MS = 1000
+    TIMEOUT_MS = 10000
 
     # [START client_run_sync_query]
     query = client.run_sync_query(LIMITED)
@@ -486,15 +470,14 @@ def client_run_sync_query(client, _):
     # [END client_run_sync_query]
 
 
-@snippet
-def client_run_sync_query_w_param(client, _):
+def test_client_run_sync_query_w_param(client):
     """Run a synchronous query using a query parameter"""
     QUERY_W_PARAM = (
         'SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` '
         'WHERE state = @state')
     LIMIT = 100
     LIMITED = '%s LIMIT %d' % (QUERY_W_PARAM, LIMIT)
-    TIMEOUT_MS = 1000
+    TIMEOUT_MS = 10000
 
     # [START client_run_sync_query_w_param]
     from google.cloud.bigquery import ScalarQueryParameter
@@ -510,10 +493,9 @@ def client_run_sync_query_w_param(client, _):
     # [END client_run_sync_query_w_param]
 
 
-@snippet
-def client_run_sync_query_paged(client, _):
+def test_client_run_sync_query_paged(client):
     """Run a synchronous query with paged results."""
-    TIMEOUT_MS = 1000
+    TIMEOUT_MS = 10000
     PAGE_SIZE = 100
     LIMIT = 1000
     LIMITED = '%s LIMIT %d' % (QUERY, LIMIT)
@@ -543,8 +525,7 @@ def do_something_with(row):
     assert len(all_rows) == LIMIT
 
 
-@snippet
-def client_run_sync_query_timeout(client, _):
+def test_client_run_sync_query_timeout(client):
     """Run a synchronous query w/ timeout"""
     TIMEOUT_MS = 10
 
@@ -580,28 +561,5 @@ def do_something_with(row):
     assert len(all_rows) == iterator.total_rows
 
 
-def _find_examples():
-    funcs = [obj for obj in globals().values()
-             if getattr(obj, '_snippet', False)]
-    for func in sorted(funcs, key=lambda f: f.func_code.co_firstlineno):
-        yield func
-
-
-def main():
-    client = Client()
-    for example in _find_examples():
-        to_delete = []
-        print('%-30s: %s' % (
-            example.func_name, example.func_doc))
-        try:
-            example(client, to_delete)
-        except AssertionError as e:
-            print('   FAIL: %s' % (e,))
-        except Exception as e:  # pylint: disable=broad-except
-            print('  ERROR: %r' % (e,))
-        for item in to_delete:
-            item.delete()
-
-
 if __name__ == '__main__':
-    main()
+    pytest.main()