[Documentation Issue]

[joeholley]

Page Name: index
Release: 0.12.0

I'm just trying to get the example code on the gcloud-python homepage (http://googlecloudplatform.github.io/gcloud-python/) or getting started page (http://googlecloudplatform.github.io/gcloud-python/stable/index.html) to work.

Setup:
I created an n1-standard-1 machine in us-central1-f using the latest ubuntu 1510 image and including the datastore scope. All I've run on it (as root):

apt-get update
apt-get installed python-pip python-crypto python-openssl 
pip install gcloud

I then logged in via my usual user account and ran the interactive python interpreter. First, I tried the homepage example code:

Python 2.7.10 (default, Oct 14 2015, 16:09:02)
[GCC 5.2.1 20151010] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from gcloud import datastore
>>>
>>> client = datastore.Client()
>>> product_key = client.key('Product', 123)
>>> print(client.get(product_key))
None

then, the getting started example code:

Python 2.7.10 (default, Oct 14 2015, 16:09:02)
[GCC 5.2.1 20151010] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from gcloud import datastore
>>>
>>> client = datastore.Client()
>>> key = client.key('Person')
>>>
>>> entity = datastore.Entity(key=key)
>>> entity['name'] = 'Your name'
>>> entity['age'] = 25
>>> client.put(entity)

This pauses, like it has successfully put, but I can't retrieve?

>>> client.get(key)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/client.py", line 250, in get
    deferred=deferred)
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/client.py", line 291, in get_multi
    transaction_id=transaction and transaction.id,
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/client.py", line 123, in _extended_lookup
    transaction_id=transaction_id,
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/connection.py", line 199, in lookup
    _datastore_pb2.LookupResponse)
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/connection.py", line 117, in _rpc
    data=request_pb.SerializeToString())
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/connection.py", line 94, in _request
    raise make_exception(headers, error_status.message, use_json=False)
gcloud.exceptions.BadRequest: 400 Key path element must not be incomplete: [Person: ]

However, if I combine the two code examples, it works:

Python 2.7.10 (default, Oct 14 2015, 16:09:02) 
[GCC 5.2.1 20151010] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from gcloud import datastore
>>> 
>>> client = datastore.Client()
>>> key = client.key('Person', 123)
>>> 
>>> entity = datastore.Entity(key=key)
>>> entity['name'] = 'Your name'
>>> entity['age'] = 25
>>> client.put(entity)
>>> print(client.get(key))
<Entity[{'kind': u'Person', 'id': 123L}] {u'age': 25L, u'name': 'Your name'}>

So, probably need to update one/both of these to be functional for new users?

[dhermes]

Thanks for filing @joeholley! When you say

This pauses, like it has successfully put, but I can't retrieve?

are you waiting until the .put() call completes?

As for why you can't retrieve it, the error message explains the issue. Your key client.key('Person') is incomplete. After the entity is saved, the key attribute gets updated because the backend completes the partial key from ('Person',) to ('Person', 5675684525506560). For example:

>>> from gcloud import datastore
>>> client = datastore.Client(project='YOUR-PROJECT')
>>> key = client.key('Person')
>>> key
<Key[{'kind': 'Person'}], project=YOUR-PROJECT>
>>> id(key)
140413770314320
>>> entity = datastore.Entity(key=key)
>>> entity['name'] = 'Steph Curry'
>>> entity.key
<Key[{'kind': 'Person'}], project=YOUR-PROJECT>
>>> id(entity.key)
140413770314320
>>> client.put(entity)
>>> entity.key
<Key[{'kind': 'Person', 'id': 5675684525506560L}], project=YOUR-PROJECT>
>>> id(entity.key)
140413770315536
>>> id(key)
140413770314320

[joeholley]

Right; this issue here isn't that I couldn't figure it out. The issue is that the example code on the homepage and the gettting started pages doesn't work!

Your key client.key('Person') is incomplete.

It's not "my key"; this is literally cut/paste example code from the getting started page. If additional code is needed to make it work, the code should be included in the getting started example, IMO. Basically, just add:

print(client.get(entity.key))

to the end of the example code. Then the homepage code should be similarly updated to either put an entity under the product_key in question, or print the product_key itself rather than the return of client.get(product_key), either of which product meaningful output (rather than 'None'):

# Example code from http://googlecloudplatform.github.io/gcloud-python/
from gcloud import datastore

client = datastore.Client()
product_key = client.key('Product', 123)
# This does not generate meaningful output (when key doesn't already exist)
print(client.get(product_key))
### END OF EXAMPLE CODE ###

# Additional code that could be added to generate meaningful output
entity = datastore.Entity(key=product_key)
entity['name'] = 'Widget'
client.put(entity)

# This now produces meaningful output
print(client.get(product_key))

output:

None                                                          
<Entity[{'kind': u'Product', 'id': 123L}] {u'name': 'Widget'}>

[dhermes]

They work for me.

From: http://googlecloudplatform.github.io/gcloud-python/

>>> from gcloud import datastore
>>>
>>> client = datastore.Client()
>>> product_key = client.key('Product', 123)
>>> print(client.get(product_key))
None
>>>

From http://googlecloudplatform.github.io/gcloud-python/stable/index.html

>>> from gcloud import datastore
>>> 
>>> client = datastore.Client()
>>> key = client.key('Person')
>>> 
>>> entity = datastore.Entity(key=key)
>>> entity['name'] = 'Your name'
>>> entity['age'] = 25
>>> client.put(entity)
>>> 
>>> 
>>> # Extra after the example
... 
>>> client.get(entity.key)
<Entity[{'kind': u'Person', 'id': 5701829602050048L}] {u'age': 25L, u'name': 'Your name'}>
>>> client.get(key)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/client.py", line 250, in get
    deferred=deferred)
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/client.py", line 291, in get_multi
    transaction_id=transaction and transaction.id,
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/client.py", line 123, in _extended_lookup
    transaction_id=transaction_id,
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/connection.py", line 199, in lookup
    _datastore_pb2.LookupResponse)
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/connection.py", line 117, in _rpc
    data=request_pb.SerializeToString())
  File "/usr/local/lib/python2.7/dist-packages/gcloud/datastore/connection.py", line 94, in _request
    raise make_exception(headers, error_status.message, use_json=False)
gcloud.exceptions.BadRequest: 400 Key path element must not be incomplete: [Person: ]

The only "issue" is the distinction between key and entity.key, but our examples don't have any snippets which incorrectly refer to one or the other.

What would you like to see changed?

[joeholley]

Okay, technically you are correct. The codes examples as they exist do "work". But they are unintentionally misleading. The example on the homepage prints an empty value, and the one on the getting started page does not show you how to retrieve the value you've placed in datastore... in fact, after having come from the homepage, the print method most people would try first (print(client.get(key)), from the previous example) produces an exception.

My suggestions for additions/changes still stand from the previous post.

• To the datastore code example on the getting started page, add:
  print(client.get(entity.key))
  at the end.
• To the datastore code example on the homepage, add:

entity = datastore.Entity(key=product_key)
entity['name'] = 'Widget'
client.put(entity)

before the line
print(client.get(product_key))

[dhermes]

Those two snippets were not intended to be consumed together, so much of the confusion is linked to thinking that they should work together.

However, we haven't put much thought into them in general, so I'll dive in and revamp.

[ptone]

I'll weigh in and say that on any one page - I believe should have enough context in the snippet to make functional sense when put in the shell. A peev of mine (and I don't believe this project is guilty of) is when a given example assumes you have the correct imports that may have been covered somewhere else in the docs.

So to me it makes sense to combine the put and get in both places, with a comment over whatever is needed to clarify that this is just helping set context, like dummy data for a unit test.

[lukesneeringer]

Hello,
One of the challenges of maintaining a large open source project is that sometimes, you can bite off more than you can chew. As the lead maintainer of google-cloud-python, I can definitely say that I have let the issues here pile up.

As part of trying to get things under control (as well as to empower us to provide better customer service in the future), I am declaring a "bankruptcy" of sorts on many of the old issues, especially those likely to have been addressed or made obsolete by more recent updates.

My goal is to close stale issues whose relevance or solution is no longer immediately evident, and which appear to be of lower importance. I believe in good faith that this is one of those issues, but I am scanning quickly and may occasionally be wrong. If this is an issue of high importance, please comment here and we will reconsider. If this is an issue whose solution is trivial, please consider providing a pull request.

Thank you!