#summary The Person entity model
#labels Phase-Design,Contents-Draft,Design-Model

The Person entity stores a single [UserRoles#Person Person role] in the
[http://code.google.com/appengine/docs/datastore/ Datastore].  The Person
[http://code.google.com/appengine/docs/datastore/entitiesandmodels.html#The_Model_Interface Model]
contains a number of basic
[http://code.google.com/appengine/docs/datastore/propertyclass.html
Properties] common to all [UserRoles user roles]:

_*Eventually, this topic should be populated by the output of*_ `pydoc`.

{{{
class Person(db.Model):
  """Common data fields for all Roles.

  A Person can only participate in a single Program.  To avoid duplication of
  data entry, facilities will be available for selecting an existing Person
  associated with a particular User to be duplicated for participation in a
  new Program.

  Some details of a Person are considered "public" information, and nearly
  all of these are optional (except for givenname, surname, and email).
  Other details of a Person are kept "private" and are only provided to
  other Persons in roles that "need to know" this information.  How these
  fields are revealed is usually covered by Program terms of service.
  
  A Person entity participates in a number of relationships:

   user)  a required many:1 relationship that ties (possibly multiple
     entities of) Person details to a unique User.  A Person cannot exist
     unassociated from a login identity and credentials.  The
     back-reference in the User model is a Query named 'persons'.

   author)  a 1:1 relationship of Person details for a specific Author.
     This relation is implemented as the 'author' back-reference Query of
     the Author model 'person' reference.

   docs)  a 1:many relationship of documents (Documentation) associated
     with the Person by Administrators.  This relation is implemented as
     the 'docs' back-reference Query of the Documentation model 'person'
     reference.

  givenname, surname:  required db.StringProperty fields storing the
    parts of the Person's name corresponding to the field names;
    displayed publicly.

  nickname:  optional db.StringProperty storing a nickname; displayed
    publicly.

  email:  required db.EmailProperty used as the "public" contact mechanism
    for the Person (as opposed to the user.id email address which is kept
    secret).

  im:  db.IMProperty storing Instant Messaging network contact information;
    displayed publicly.

  homepage:  db.LinkProperty storing a home page URL; displayed publicly.

  blog:  db.LinkProperty storing a blog URL; displayed publicly.

  photo:  db.LinkProperty storing a URL to an image, expected to be a
    personal photo (or cartoon avatar, perhaps); displayed publicly.

  location:  db.GeoPtProperty storing the latitude and longitude provided
    by the Person; displayed publicly.

  residence:  required db.PostalAddressProperty containing residence
    address; kept private.

  shipping:  optional db.PostalAddressProperty containg a separate shipping
    address; kept private.

  phone:  required db.PhoneNumberProperty containing a phone number that
    will be supplied to shippers; kept private.

  birthdate:  required db.DateProperty containing the Person's birthdate
    (required for determining Program participation eligibility); kept
    private.

  tshirt_size:  optional db.StringProperty indicating choice of t-shirt
    size, from XXS to XXXL; kept private.

  tshirt_gender:  optional db.StringProperty indicating choice of male or
    female t-shirt fit; kept private.
  """
  user = db.ReferenceProperty(reference_class=User, required=True,
                              collection_name="persons")

  # (public) name
  givenname = db.StringProperty(required=True)  # first name
  surname = db.StringProperty(required=True)  # last name
  nickname = db.StringProperty()

  # (public) contact information
  email = db.EmailProperty(required=True)
  im = db.IMProperty()  # contains protocol (or URL) and handle
  homepage = db.LinkProperty()
  blog = db.LinkProperty()
  photo = db.LinkProperty()
  location = db.GeoPtProperty()

  # (private) contact information
  residence = db.PostalAddressProperty(required=True)
  shipping = db.PostalAddressProperty()
  phone = db.PhoneNumberProperty(required=True)

  # (private) personal information
  birthdate = db.DateProperty(required=True)
  tshirt_size = db.StringProperty(
    choices=set("XXS", "XS", "S", "M", "L", "XL", "XXL", "XXXL"))
  tshirt_gender = db.StringProperty(choices=set("male", "female"))
}}}

----
_Copyright 2008 Google Inc._
_This work is licensed under a_
[http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-attribution-2_5.html Creative Commons Attribution 2.5 License].
[http://creativecommons.org/licenses/by/2.5/ http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-2_5-88x31.png]