1 #!/usr/bin/python2.5

     2 #

     3 # Copyright 2008 the Melange authors.

     4 #

     5 # Licensed under the Apache License, Version 2.0 (the "License");

     6 # you may not use this file except in compliance with the License.

     7 # You may obtain a copy of the License at

     8 #

     9 #   http://www.apache.org/licenses/LICENSE-2.0

    10 #

    11 # Unless required by applicable law or agreed to in writing, software

    12 # distributed under the License is distributed on an "AS IS" BASIS,

    13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    14 # See the License for the specific language governing permissions and

    15 # limitations under the License.

    16 

    17 """This module contains the Person Model."""

    18 

    19 __authors__ = [

    20   '"Todd Larsen" <tlarsen@google.com>',

    21   '"Sverre Rabbelier" <sverre@rabbelier.nl>',

    22 ]

    23 

    24 from google.appengine.ext import db

    25 from django.utils.translation import ugettext_lazy

    26 

    27 from soc import models

    28 import soc.models.user

    29 

    30 from soc.models import countries

    31 

    32 

    33 class Person(db.Model):

    34   """Common data fields for all Roles.

    35 

    36   A Person can only participate in a single Program.  To avoid duplication of

    37   data entry, facilities will be available for selecting an existing Person

    38   associated with a particular User to be duplicated for participation in a

    39   new Program.

    40 

    41   Some details of a Person are considered "public" information, and nearly

    42   all of these are optional (except for given_name, surname, and email).

    43   Other details of a Person are kept "private" and are only provided to

    44   other Persons in roles that "need to know" this information.  How these

    45   fields are revealed is usually covered by Program terms of service.

    46 

    47   A Person entity participates in the following relationships implemented

    48   as a db.ReferenceProperty elsewhere in another db.Model:

    49 

    50    author)  a 1:1 relationship of Person details for a specific Author.

    51      This relation is implemented as the 'author' back-reference Query of

    52      the Author model 'person' reference.

    53 

    54    docs)  a 1:many relationship of documents (Documentation) associated

    55      with the Person by Administrators.  This relation is implemented as

    56      the 'docs' back-reference Query of the Documentation model 'person'

    57      reference.

    58   """

    59 

    60   #: A required many:1 relationship that ties (possibly multiple

    61   #: entities of) Person details to a unique User.  A Person cannot

    62   #: exist unassociated from a login identity and credentials.  The

    63   #: back-reference in the User model is a Query named 'persons'.

    64   user = db.ReferenceProperty(reference_class=models.user.User,

    65                               required=True, collection_name='persons')

    66 

    67   #====================================================================

    68   #  (public) name information

    69   #====================================================================

    70 

    71   #: Required field storing the parts of the Person's name

    72   #: corresponding to the field names; displayed publicly.

    73   #: given_name can only be lower ASCII, not UTF-8 text, because it is

    74   #: used, for example, as part of the shipping (mailing) address.

    75   given_name = db.StringProperty(required=True,

    76       verbose_name=ugettext_lazy('First (given) name'))

    77   given_name.help_text = ugettext_lazy('lower ASCII characters only')

    78 

    79   #: Required field storing the parts of the Person's name

    80   #: corresponding to the field names; displayed publicly.

    81   #: Surname can only be lower ASCII, not UTF-8 text, because it is

    82   #: used, for example, as part of the shipping (mailing) address.

    83   surname = db.StringProperty(

    84       required=True,

    85       verbose_name=ugettext_lazy('Last (family) name'))

    86   surname.help_text = ugettext_lazy('lower ASCII characters only')

    87 

    88   #: Optional field storing a nickname; displayed publicly.

    89   #: Nicknames can be any valid UTF-8 text.

    90   nickname = db.StringProperty(

    91       verbose_name=ugettext_lazy('Nick name'))

    92 

    93   #: Optional field used as a display name, such as for awards

    94   #: certificates. Should be the entire display name in the format

    95   #: the Person would like it displayed (could be surname followed by

    96   #: given name in some cultures, for example). Display names can be

    97   #: any valid UTF-8 text.

    98   display_name = db.StringProperty(

    99       verbose_name=ugettext_lazy('Display Name'))

   100   display_name.help_text = ugettext_lazy(

   101       'Optional field used as a display name, such as for awards '

   102       'certificates. Should be the entire display name in the format '

   103       'the person would like it displayed (could be family name followed '

   104       'by given name in some cultures, for example). Display names can be '

   105       'any valid UTF-8 text.')

   106 

   107   #====================================================================

   108   #  (public) contact information

   109   #====================================================================

   110 

   111   #: Required field used as the 'public' contact mechanism for the

   112   #: Person (as opposed to the user.id email address which is

   113   #: kept secret).

   114   email = db.EmailProperty(

   115       required=True,

   116       verbose_name=ugettext_lazy('Email Address'))

   117 

   118   #: Optional field storing Instant Messaging network; displayed publicly.

   119   im_network = db.StringProperty(

   120       verbose_name=ugettext_lazy('IM Network'))

   121   im_network.help_text=ugettext_lazy(

   122       'examples: irc:irc.freenode.org xmpp:gmail.com/Home')

   123 

   124   #: Optional field storing Instant Messaging handle; displayed publicly.

   125   im_handle = db.StringProperty(

   126       verbose_name=ugettext_lazy('IM Handle'))

   127   im_handle.help_text=ugettext_lazy(

   128       'personal identifier, such as: screen name, IRC nick, user name')

   129 

   130   #: Optional field storing a home page URL; displayed publicly.

   131   home_page = db.LinkProperty(

   132       verbose_name=ugettext_lazy('Home Page URL'))

   133 

   134   #: Optional field storing a blog URL; displayed publicly.

   135   blog = db.LinkProperty(

   136       verbose_name=ugettext_lazy('Blog URL'))

   137 

   138   #: Optional field storing a URL to an image, expected to be a

   139   #: personal photo (or cartoon avatar, perhaps); displayed publicly.

   140   photo_url = db.LinkProperty(

   141       verbose_name=ugettext_lazy('Thumbnail Photo URL'))

   142   photo_url.help_text = ugettext_lazy(

   143       'URL of 64x64 pixel thumbnail image')

   144 

   145   #: Optional field storing the latitude provided by the Person; displayed

   146   #: publicly.

   147   latitude = db.FloatProperty(

   148       verbose_name=ugettext_lazy('Latitude'))

   149   latitude.help_text = ugettext_lazy(

   150       'decimal degrees northerly (N), use minus sign (-) for southerly (S)')

   151 

   152   #: Optional field storing the longitude provided by the Person; displayed

   153   #: publicly.

   154   longitude = db.FloatProperty(

   155       verbose_name=ugettext_lazy('Longitude'))

   156   longitude.help_text = ugettext_lazy(

   157       'decimal degrees easterly (E), use minus sign (-) for westerly (W)')

   158 

   159   #====================================================================

   160   # (private) contact information

   161   #====================================================================

   162 

   163   #: Required field containing residence street address; kept private.

   164   #: Residence street address can only be lower ASCII, not UTF-8 text, because

   165   #: it may be used as a shipping address.

   166   res_street = db.StringProperty(required=True,

   167       verbose_name=ugettext_lazy('Street address'))

   168   res_street.help_text = ugettext_lazy(

   169       'street number and name, lower ASCII characters only')

   170 

   171   #: Required field containing residence address city; kept private.

   172   #: Residence city can only be lower ASCII, not UTF-8 text, because it

   173   #: may be used as a shipping address.

   174   res_city = db.StringProperty(required=True,

   175       verbose_name=ugettext_lazy('City'))

   176   res_city.help_text = ugettext_lazy('lower ASCII characters only')

   177 

   178   #: Required field containing residence address state or province; kept

   179   #: private.  Residence state/province can only be lower ASCII, not UTF-8

   180   #: text, because it may be used as a shipping address.

   181   res_state = db.StringProperty(

   182       verbose_name=ugettext_lazy('State/Province'))

   183   res_state.help_text = ugettext_lazy(

   184       'optional if country/territory does not have states or provinces, '

   185       'lower ASCII characters only')

   186 

   187   #: Required field containing residence address country or territory; kept

   188   #: private.

   189   res_country = db.StringProperty(required=True,

   190       verbose_name=ugettext_lazy('Country/Territory'),

   191       choices=countries.COUNTRIES_AND_TERRITORIES)

   192 

   193   #: Required field containing residence address postal code (ZIP code in

   194   #: the United States); kept private.  Residence postal code can only be

   195   #: lower ASCII, not UTF-8 text, because it may be used as a shipping address.

   196   res_postalcode = db.StringProperty(required=True,

   197       verbose_name=ugettext_lazy('ZIP/Postal Code'))

   198   res_postalcode.help_text=ugettext_lazy('lower ASCII characters only')

   199 

   200   #: Optional field containing a separate shipping street address; kept

   201   #: private.  If shipping address is not present in its entirety, the

   202   #: residence address will be used instead.  Shipping street address can only

   203   #: be lower ASCII, not UTF-8 text, because, if supplied, it is used as a

   204   #: shipping address.

   205   ship_street = db.StringProperty(

   206       verbose_name=ugettext_lazy('Street address'))

   207   ship_street.help_text = ugettext_lazy(

   208       'street number and name, lower ASCII characters only')

   209 

   210   #: Optional field containing shipping address city; kept private.

   211   #: Shipping city can only be lower ASCII, not UTF-8 text, because, if

   212   #: supplied, it is used as a shipping address.

   213   ship_city = db.StringProperty(

   214       verbose_name=ugettext_lazy('City'))

   215   ship_city.help_text = ugettext_lazy('lower ASCII characters only')

   216 

   217   #: Optional field containing shipping address state or province; kept

   218   #: private.  Shipping state/province can only be lower ASCII, not UTF-8

   219   #: text, because, if supplied, it is used as a shipping address.

   220   ship_state = db.StringProperty(

   221       verbose_name=ugettext_lazy('State/Province'))

   222   ship_state.help_text = ugettext_lazy(

   223       'optional if country/territory does not have states or provinces, '

   224       'lower ASCII characters only')

   225 

   226   #: Optional field containing shipping address country or territory; kept

   227   #: private.

   228   ship_country = db.StringProperty(

   229       verbose_name=ugettext_lazy('Country/Territory'),

   230       choices=countries.COUNTRIES_AND_TERRITORIES)

   231 

   232   #: Optional field containing shipping address postal code (ZIP code in

   233   #: the United States); kept private.  Shipping postal code can only be

   234   #: lower ASCII, not UTF-8 text, because, if supplied, it is used as a

   235   #: shipping address.

   236   ship_postalcode = db.StringProperty(

   237       verbose_name=ugettext_lazy('ZIP/Postal Code'))

   238   ship_postalcode.help_text=ugettext_lazy('lower ASCII characters only')

   239 

   240   #: Required field containing a phone number that will be supplied

   241   #: to shippers; kept private.

   242   phone = db.PhoneNumberProperty(

   243       required=True,

   244       verbose_name=ugettext_lazy('Phone Number'))

   245   phone.help_text = ugettext_lazy(

   246       'include complete international calling number with country code')

   247 

   248   #====================================================================

   249   # (private) personal information

   250   #====================================================================

   251 

   252   #: Required field containing the Person's birthdate (for

   253   #: determining Program participation eligibility); kept private.

   254   birth_date = db.DateProperty(

   255       required=True,

   256       verbose_name=ugettext_lazy('Birth Date'))

   257   birth_date.help_text = ugettext_lazy(

   258       'required for determining program eligibility')

   259 

   260   #: Optional field indicating choice of t-shirt, from XXS to XXXL;

   261   #: kept private.

   262   tshirt_size = db.StringProperty(

   263       verbose_name=ugettext_lazy('T-shirt Size'),

   264       choices=('XXS', 'XS', 'S', 'M', 'L', 'XL', 'XXL', 'XXXL'))

   265 

   266   #: Optional field indicating choice of t-shirt fit; kept private.

   267   tshirt_style = db.StringProperty(

   268       verbose_name=ugettext_lazy('T-shirt Style'),

   269       choices=('male', 'female'))