Last modified: 13 December 2011
On Tue, Dec 13, 2011 at 11:47 AM, Ben Komalo <firstname.lastname@example.org> wrote:
Not silly questions. This is arguably the most convoluted part of the codebase, as a result of a history that's probably easier to explain in person. That being said:
"user - canonical reference to the user entity. This is what GAE uses to uniquely identify each user. This should never change once it's assigned to a user."
Pretty much. Right now, we're using it for our datastore "foreign key" for users. In an ideal world, these would just be the user_ids. Unfortunately, they're deeply tied in our existing data and we haven't been willing to go back and reconstruct all entities to fix this up. IMHO, App Engine should not have the UserProperty type, because it breaks when users change their email addresses. Bottom line: if .user is being used anywhere *other* than when directly putting something into or getting something out of the datastore, we want that code to go away. That is why you see all those variables with _user_data suffixes...I wanted to be sure we were moving away from passing Users around and into the world of only passing around UserData.
"current_user - a user entity that changes if the user changes e-mails via http://www.khanacademy.org/devadmin/emailchange"
This one can and should be removed. I just inspected again, and the only code remaining that touches it is maintenance code that, as you say, transfers user emails around. Again, can share the history if curious. If you pretend this entity doesn't exist, the rest make more sense.
"user_id - a non-human readable id that looks like http://googleid.khanacademy.org/<#> - not sure what it's for?"
This is the big one that's used in UserData.current(). When GAE acknowledges somebody as authenticated (users.get_current_user or whatever), the object has a user.user_id() that does not change when email addresses change. This is the correct unique identifier for Google-authenticated users. The only reason it has the prefix is b/c we use that prefix to differentiate b/w google unique IDs and facebook unique IDs. The only reason the prefix looks like a URL is b/c one of the original open source contributors briefly tried taking us in an OpenID direction...
"user_email - seems like a lot of the code relies on this being a unique identifier. This I guess refers to the e-mail of current_user, but can change for a given user?"
"@property email, and key_email - these just refer to user_email - is there a reason these abstractions exist? Do we intend to subclass for certain user types?"
Actually, email refers to user_email, and key_email refers to self.user.email(). In other words, I added these properties in the hopes that they would make things more clear to API users and such (I need to do a much better job documenting these issues), because .email() is what you'd expect for a UserData entity...and key_email is the database foreign key for that user, which happens to be an email. I realize I'm terrible at naming things and apologize for this code. I'm going to publish your questions and this email in the forge wiki thingie.