Add new "quickstart" samples

[jmdobry]

These are intended to be simple examples that explicitly show:

• Importing the client library
• Instantiating a client
• Making a single API call
• Printing the result

Products covered:

• BigQuery
  • - sample
  • - test
• Datastore
  • - sample
  • - test
• Language
  • - sample
  • - test
• Logging
  • - sample
  • - test
• Pub/Sub
  • - sample
  • - test
• Storage
  • - sample
  • - test
• Translate
  • - sample
  • - test
• Vision
  • - sample
  • - test

For reference, see the corresponding samples in other languages:

• GoogleCloudPlatform/nodejs-docs-samples (samples are on master in various quickstart.js files)
• Add new "quickstart" samples. golang-samples#131
• Add new "quickstart" samples. ruby-docs-samples#77
• Add new "quickstart" samples. php-docs-samples#174
• GoogleCloudPlatform/java-docs-samples (pending)
• GoogleCloudPlatform/dotnet-docs-samples (pending)

Thanks!

[theacodes]

It's sad to see that there are no tests for these, especially considering these will be the first samples users try out.

[jmdobry]

It's sad to see that there are no tests for these, especially considering these will be the first samples users try out.

I'm willing to write tests, but I need a crash course on testing python-docs-samples.

[theacodes]

I'm willing to write tests, but I need a how to test python-docs-samples crash course.

I can add them, they're just inherently hard to test. As soon as you import these modules they do stuff (side-effects), this is why all of samples are in functions - so that tests can setup fixtures to mock whatever is needed or setup environment variables before calling the function.

You've also hard-coded the project id, which means I have to do at least some mocking. It's also inconsistent with all of the parameters shown in other samples (which are just function args).

[jmdobry]

I recognize that they're harder to test (the tests for Node.js versions of these samples were a pain). Perhaps @omaray can concede some simplicity for more maintainable/testable samples? i.e. wrap in a function?

Hard-coding the project ID is a "product requirement" for these samples (these "quickstart" style samples will be the only ones that do so, all the rest can infer from the environment).

Also, I tried TESTING.md, but sudo pip install --upgrade nox-automation fails on my machine, and gcp-python-repo-tools gives me a 404.

[omaray]

@jonparrott happy to chat in person about this.

[theacodes]

@omaray @jmdobry I think it's fine, it's just very hard to test cleanly. Of course, the usability of our samples is outweighs test cleanliness.

I have no time to write tests for this PR this week, what is the timeline you guys want for this to be merged?

[omaray]

We were hoping this week if possible. But we can also check-in something for now that works (that we test manually to confirm) and then add the test next week. That wouldn't be a concern to me.

By the way, @jmdobry is using the "gcloud" module in his examples. Can we now switch to using the google-cloud-{api} one instead? So from google.cloud import pubsub and what not?

[jmdobry]

I can add them, they're just inherently hard to test. As soon as you import these modules they do stuff (side-effects), this is why all of samples are in functions - so that tests can setup fixtures to mock whatever is needed or setup environment variables before calling the function.

With python, can the test do the setup stuff before import the sample? (That's essentially what we do in Node.js.) Are imports required to be the first statements in a file?

[theacodes]

With python, can the test do the setup stuff before import the sample? (That's essentially what we do in Node.js.) Are imports required to be the first statements in a file?

We can do that, it's just pretty hacky.

We were hoping this week if possible. But we can also check-in something for now that works (that we test manually to confirm) and then add the test next week. That wouldn't be a concern to me.

That would be fine.

[theacodes]

@jmdobry if you rebase on master, you can use google-cloud (and tests should pass)

[jmdobry]

Done

[jmdobry]

I removed the explicit project IDs.

[jmdobry]

I wrapped each snippet in a method definition, does that make it easier for you to test? I also added snippets for Language and Vision. Speech is the only one missing (google-cloud-speech not published yet, but the docs for it have been published?)

[jmdobry]

Also, I ran all of the samples manually to make sure they work. Except for Speech, this PR now has "quickstart" sample parity with GoogleCloudPlatform/ruby-docs-samples#77 and the corresponding Node.js samples (which are already on master of nodejs-docs-samples).