feat: add Database.list_tables method

[tswast]

Adds Table-management methods required by PSO data validation tool.

Fixes #156 🦕

[larkee]

LG, just a couple design details to work out regarding the Table methods 👍

[larkee]

I think instead of having get_schema, it would make more sense to match the rest of the library and the BigQuery implementation by having this as a property. What do you think?

[tswast]

That would be more consistent. My main worry with a property is it might be less clear that table.schema makes an API call compared to table.get_schema().

[larkee]

That is a good point. For the other resource objects (i.e. Instance, Backup, Database) we store local copies of properties and have a reload() method to make an RPC call to update them. I think it may make sense to stick to this design, especially if we decide to support create, update, and delete on the Table object.

I would initialize a private schema attribute as None and then call reload in schema if it is None. This means the property would make one API call at most. Then, if the user is expecting the schema to change frequently, they can all reload themselves to ensure the schema remains in sync with production. WDYT?

[tswast]

I would initialize a private schema attribute as None and then call reload in schema if it is None. This means the property would make one API call at most. Then, if the user is expecting the schema to change frequently, they can all reload themselves to ensure the schema remains in sync with production. WDYT?

I think that's a good approach. In BigQuery we didn't have this logic, so customers would surprisingly get None values, which caused all sorts of issues. I'll make this a property and add a reload method.

[tswast]

Updated. Also added a exists() method to match Database.reload()'s NotFound exception behavior.

[tswast]

I'm marking this as ready for review, though I suspect I'll need to add some unit tests for coverage.

[larkee]

The new Table type will also need documentation similar to database-api and database-usage so that documentation for the type and how to use it can be generated.

[tswast]

Docs added:

[larkee]

Please add a table() method on the Database object which creates the Table object to be consistent with the other classes e.g.

client = spanner.Client()
instance = client.instance(instance_id)
database = instance.database(database_id)
table = database.table(table_id)

[tswast]

Done! Thanks for your patience while I was OOO.

Edit: added in the following commit: 1250d8a

[tswast]

@larkee I've made the requested changes and synced with latest master branch. Should be ready for another round of review.

[tswast]

Test failure

______________________ TestBackupAPI.test_backup_workflow ______________________

self = <tests.system.test_system.TestBackupAPI testMethod=test_backup_workflow>

    def test_backup_workflow(self):
        from datetime import datetime
        from datetime import timedelta
        from pytz import UTC

        instance = Config.INSTANCE
        backup_id = "backup_id" + unique_resource_id("_")
        expire_time = datetime.utcnow() + timedelta(days=3)
        expire_time = expire_time.replace(tzinfo=UTC)

        # Create backup.
        backup = instance.backup(
            backup_id,
            database=self._db,
            expire_time=expire_time,
            version_time=self.database_version_time,
        )
        operation = backup.create()
        self.to_delete.append(backup)

        # Check metadata.
        metadata = operation.metadata
        self.assertEqual(backup.name, metadata.name)
        self.assertEqual(self._db.name, metadata.database)
        operation.result()

        # Check backup object.
        backup.reload()
        self.assertEqual(self._db.name, backup._database)
        self.assertEqual(expire_time, backup.expire_time)
        self.assertIsNotNone(backup.create_time)
        self.assertEqual(self.database_version_time, backup.version_time)
        self.assertIsNotNone(backup.size_bytes)
        self.assertIsNotNone(backup.state)

        # Update with valid argument.
        valid_expire_time = datetime.utcnow() + timedelta(days=7)
        valid_expire_time = valid_expire_time.replace(tzinfo=UTC)
        backup.update_expire_time(valid_expire_time)
        self.assertEqual(valid_expire_time, backup.expire_time)

        # Restore database to same instance.
        restored_id = "restored_db" + unique_resource_id("_")
        database = instance.database(restored_id)
        self.to_drop.append(database)
        operation = database.restore(source=backup)
        restored_db = operation.result()
>       self.assertEqual(
            self.database_version_time, restored_db.restore_info.backup_info.create_time
        )
E       AssertionError: datetime.datetime(2021, 2, 22, 21, 31, 33[16 chars]UTC>) != DatetimeWithNanoseconds(2021, 2, 22, 21, [40 chars].utc)

appears to be a problem with master branch. I'll try merging from upstream again.

[larkee]

LGTM other than a minor docs fix 👍