stymied by the pydocs

[Graham Charles]

Am I the only one that finds the client library documentation
impossible to use?

Example: I am retrieving a UserEntry object. Where do I find its
members? Well, I grep the pydocs and find the UserEntry class
documented at

http://gdata-python-client.googlecode.com/svn/trunk/pydocs/gdata.apps.html#UserEntry

There's a method list, but no property list. I can step back through
the parent classes up at the top of that docs page (why are they in a
different place?) and find UserEntry's properties, but they're listed
there without their types. The "Name" element is in fact a class also
derived from AtomBase (members include given_name and family_name),
but I can only discover its properties from the __init__ method --
again, there's no property list anywhere.

I've imported inspect and am using getmembers liberally to figure out
all these properties, but that's a little weird, isn't it?

The pydocs seem entirely unsuitable for a method reference.

So... sorry to be such an idiot, but what am I missing?

Thanks,

g.

[David Carter-Tod]

Printing an entry object would lead me to believe that the given name was accessed using givenName, but it's not.

So, yeah, completely obscure to a python beginner as far as I'm concerned.  I'm the only one writing python in my organization.  I couldn't possibly guess how to do half this stuff.  I have the same problem with Java though :-)

David

On Tue, Oct 6, 2009 at 1:48 PM, Tim Garthwaite <t...@appirio.com> wrote:

Hi Charles,

It was really frustrating to me (and I still wish there were better published docs on this), but a colleague pointed me towards the "Pythonic" way of doing things... Fire up the Python prompt, connect with a service, grab a feed, then an entry, and pass it into print():

dir(entry)

another useful one, for methods, is help(method_name)

For constructors, it's help(class_name.__init__)

Hope this helps,

Tim Garthwaite
+1 401-405-1513
Appirio: Accelerating Enterprise Adoption of the Cloud
www.appirio.com

[Graham Charles]

Do you mean to say that it's not obscure to a python expert? Where do
they find the property list?

I'm a 20+ year programmer, and though I'm newish to python, I'm not
new to the concept of class documentation.

g.

On Oct 6, 10:54 am, David Carter-Tod <dct...@gmail.com> wrote:
> Printing an entry object would lead me to believe that the given name was
> accessed using givenName, but it's not.
>
> So, yeah, completely obscure to a python beginner as far as I'm concerned.
> I'm the only one writing python in my organization.  I couldn't possibly
> guess how to do half this stuff.  I have the same problem with Java though
> :-)
>
> David
>
>
>
> On Tue, Oct 6, 2009 at 1:48 PM, Tim Garthwaite <t...@appirio.com> wrote:
>
> > Hi Charles,
>
> > It was really frustrating to me (and I still wish there were better
> > published docs on this), but a colleague pointed me towards the "Pythonic"
> > way of doing things... Fire up the Python prompt, connect with a service,
> > grab a feed, then an entry, and pass it into print():
>
> > dir(entry)
>
> > another useful one, for methods, is help(method_name)
>
> > For constructors, it's help(class_name.__init__)
>
> > Hope this helps,
>
> > Tim Garthwaite
> > +1 401-405-1513
> > Appirio: Accelerating Enterprise Adoption of the Cloud
> >www.appirio.com
>

> > On Mon, Oct 5, 2009 at 7:40 PM, Graham Charles <grahampchar...@gmail.com>wrote:
>
> >> Am I the only one that finds the client library documentation
> >> impossible to use?
>
> >> Example: I am retrieving a UserEntry object. Where do I find its
> >> members? Well, I grep the pydocs and find the UserEntry class
> >> documented at
>

> >>http://gdata-python-client.googlecode.com/svn/trunk/pydocs/gdata.apps...

[David Carter-Tod]

I'm more of a neophyte and find class documentation obscure and confusing, but your observation is obviously true for experts too.

David

[Sam]

The command-line environment and source code are both your friends.

Most of the members of the python API classes can be discovered by
looking at the __init__ methods of the objects. i.e. help
(gdata.apps.UserEntry.__init__) gives:

Help on method __init__ in module gdata.apps:

__init__(self, author=None, category=None, content=None,
atom_id=None,
link=None, published=None, title=None, updated=None,
login=None,
name=None, quota=None, who=None, feed_link=None,
extended_property=None, extension_elements=None,
extension_attributes=None, text=None) unbound
gdata.apps.UserEntry method

"name" looks interesting. Looking at the source of the gdata.apps
module shows that each object contains a list of valid members which
looks like it they get magic'd into the real structures. i.e.

class UserEntry(gdata.GDataEntry):
...
_children['{%s}name' % APPS_NAMESPACE] = ('name', Name)

That's a reference to the class Name which seems to have the
attributes you want:

class Name(atom.AtomBase):
...
_attributes['familyName'] = 'family_name'
_attributes['givenName'] = 'given_name'

So to change the given name of a user entry, you'll need to do
something like:

>>> user = client.RetrieveUser('username')
>>> user.name.given_name = 'Given Name'
>>> client.UpdateUser('username', user)

Admittedly there is a fair bit of magic in the Python implementation
of the Google APIs which makes it difficult to dissect in a
traditional Pythonic way. Magic is great but begs better
documentation.

My main advice would be: look at the source. It should at least hint
at what you want, then tease out the details in the command-line
environment, or your favourite introspecting IDE i.e. Eclipse.

Sam.

On Oct 9, 9:53 pm, David Carter-Tod <dct...@gmail.com> wrote:
> I'm more of a neophyte and find class documentation obscure and confusing,
> but your observation is obviously true for experts too.
>
> David
>

[eric.truett]

Try this and if you have any improvements please let me know!

def UpdateUser(self, userName, setting, value):
'''
Method allow you to change following settings:
familyName, givenName, userName, password, suspended,
quotaLimit, hashFunctionName, admin

The google documentation of this is weak, you have to inspect
UserEntry object and figure out properties
user.name properties: family_name, given_name
user.login properties: admin, agreed_to_terms, change_password,
hash_function_name, ip_whitelisted, password, suspended, text,
user_name
user.quota properties: limit, text
'''

# get UserEntry object
user = self.service.RetrieveUser(userName)

# change UserEntry object
if setting == 'familyName':
#admin.UpdateUser('bbb222', 'familyName', 'Jones')
user.name.family_name = value
elif setting == 'givenName':
#admin.UpdateUser('bbb222', 'givenName', 'Jim')
user.name.given_name = value
elif setting == 'userName':
#admin.UpdateUser('bbb222', 'userName', 'ccc333')
user.login.user_name = value
elif setting == 'password':
#admin.UpdateUser('bbb222', 'password', 'p@ssw0rd')
user.login.password = value
elif setting == 'suspended':
#admin.UpdateUser('bbb222', 'suspended', 'true')
user.login.suspended = value
elif setting == 'quotaLimit':
#admin.UpdateUser('bbb222', 'quotaLimit', '1024')
user.quota.limit = value
elif setting == 'hashFunctionName':
#admin.UpdateUser('bbb222', 'hashFunctionName', 'MD5')
user.login.hash_function_name = value
elif setting == 'admin':
#admin.UpdateUser('bbb222', 'admin', 'true')
user.login.admin = value

# submit modified UserEntry object
self.service.UpdateUser(userName, user)

On Oct 9, 8:53 am, David Carter-Tod <dct...@gmail.com> wrote:
> I'm more of a neophyte and find class documentation obscure and confusing,
> but your observation is obviously true for experts too.
>
> David
>