Changes between Version 17 and Version 18 of AppEngine

Timestamp:

Aug 10, 2009, 6:47:26 AM (15 years ago)

Author:

Waldemar Kornewald

Comment:

reworked how key_name is handled

AppEngine

@@ -37 +37 @@
 == Keys, key_name, key id, parents ==
 
-In general, the "pk" field should never be assumed to be a number. If an entity uses a key_name the application should continue to work.
+In order to stay compatible with normal Django code the id should be emulated with an !AutoField and the key_name with a !CharField(primary_key=True). Since key_names may not start with a number the actual string is transparently prefixed with a string that can be specified in Meta.gae_key_name_prefix. The user won't notice this encoding when accessing the pk (or the !CharField). By default, this prefix is just 'k'.
 
-The key_name and parent could be emulated with a !CharField(primary_key=True) that automatically prefixes the given string with a character, internally. A special function could be provided for encoding a primary_key that consists of parents and a key_name or key id. This API would allow for reducing the key_name and parent into a single pk property and staying compatible with existing Django code which wouldn't work if we had separate pk and parent properties.
+With this setup most applications should work without any modifications and automatically use key_name in a natural way.
 
-The pk property should return an url-safe string that contains the key_name without the safety prefix (i.e., the value of the !CharField(primary_key=True)) and the parent pk. This is more portable than using the str(Key) because it doesn't contain the model and appid. Moreover, in case you specified a pk manually, the URLs will be much nicer. Even if you don't specify a key_name the URL is still shorter than the str(Key) version.
+Some applications might mix the use of ids and key_names within the same model. For these cases you can set the prefix to an empty string. This allows for working directly with raw ids and key_names (for simplicity, the pk will always be a string, even if it's an id).
+
+Parents are a special App Engine feature which can't be mapped transparently to Django features, so they should be simulated with a separate gae_parent field that is automatically added to every model. The pk itself only contains the id or key_name (without the prefix) and thus stays clean and doesn't have to be encoded in a special format. A special function allows for constructing parent paths: make_parent_path(ModelA, 23, ModelB, 'kname'). This function returns a human-readable string (e.g.: "ModelA|23|ModelB|kname") representing the path.
+
+Code should never assume that the "pk" field is a number. If an entity uses a string pk (key_name) the application should continue to work.
 
 Queries should support ancestor conditions.
 
-Every model should provide properties for: key, key_name, key_id, parent, parent_key
+Every model should provide properties for: key, key_name, key_id, parent, parent_key (all prefixed with "gae_" to reduce name conflicts)
 
 == Transactions ==