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 """Document (Model) query functions.

    18 """

    19 

    20 __authors__ = [

    21   '"Pawel Solyga" <pawel.solyga@gmail.com>',

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

    23   ]

    24 

    25 

    26 import re

    27 

    28 from google.appengine.ext import db

    29 

    30 from soc.logic import key_name

    31 from soc.logic import out_of_band

    32 from soc.logic.site import id_user

    33 

    34 from soc.logic import model

    35 

    36 import soc.models.document

    37 

    38 

    39 def getDocument(path, link_name=None):

    40   """Returns Document entity for a given path, or None if not found.  

    41     

    42   Args:

    43     path: a request path of the Document that uniquely identifies it

    44     link_name: optional link name to append to path (when supplied,

    45       path is actually a "partial path" that needs to link name appended

    46       to it)

    47   """

    48   # lookup by Doc:path key name

    49   name = key_name.nameDocument(path, link_name=link_name)

    50   

    51   if name:

    52     document = soc.models.document.Document.get_by_key_name(name)

    53   else:

    54     document = None

    55   

    56   return document

    57 

    58 

    59 def getDocumentIfPath(path, link_name=None):

    60   """Returns Document entity for supplied path if one exists.

    61   

    62   Args:

    63     path: path used in URLs to identify document

    64 

    65   Returns:

    66     * None if path is false.

    67     * Document entity that has supplied path

    68 

    69   Raises:

    70     out_of_band.ErrorResponse if path is not false, but no Document entity

    71     with the supplied path exists in the Datastore

    72   """

    73   if not path:

    74     # exit without error, to let view know that link_name was not supplied

    75     return None

    76 

    77   path_doc = getDocument(path, link_name=link_name)

    78     

    79   if path_doc:

    80     # a Document has this path, so return that corresponding Document entity

    81     return path_doc

    82 

    83   # else: a path was supplied, but there is no Document that has it

    84   raise out_of_band.ErrorResponse(

    85       'There is no document with a "path" of "%s".' % path, status=404)

    86 

    87 

    88 def updateOrCreateDocument(**document_properties):

    89   """Update existing Document entity, or create new one with supplied properties.

    90 

    91   Args:

    92     path: a request path of the Document that uniquely identifies it

    93     **document_properties: keyword arguments that correspond to Document entity

    94       properties and their values

    95 

    96   Returns:

    97     the Document entity corresponding to the path, with any supplied

    98     properties changed, or a new Document entity now associated with the 

    99     supplied path and properties.

   100   """

   101   # attempt to retrieve the existing Document

   102   document = getDocument(document_properties['partial_path'],

   103                          link_name=document_properties['link_name'])

   104 

   105   if not document:

   106     # document did not exist, so create one in a transaction

   107     name = key_name.nameDocument(document_properties['partial_path'],

   108                                  document_properties['link_name'])

   109     document = soc.models.document.Document.get_or_insert(

   110         name, **document_properties)

   111 

   112   # there is no way to be sure if get_or_insert() returned a new Document or

   113   # got an existing one due to a race, so update with document_properties anyway,

   114   # in a transaction

   115   return soc.logic.model.updateModelProperties(document, **document_properties)