mediagoblin/db/__init__.py

   1 # GNU MediaGoblin -- federated, autonomous media hosting
   2 # Copyright (C) 2011, 2012 MediaGoblin contributors.  See AUTHORS.
   3 #
   4 # This program is free software: you can redistribute it and/or modify
   5 # it under the terms of the GNU Affero General Public License as published by
   6 # the Free Software Foundation, either version 3 of the License, or
   7 # (at your option) any later version.
   8 #
   9 # This program is distributed in the hope that it will be useful,
  10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 # GNU Affero General Public License for more details.
  13 #
  14 # You should have received a copy of the GNU Affero General Public License
  15 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 """
  18 Database Abstraction/Wrapper Layer
  19 ==================================
  20
  21   **NOTE from Chris Webber:** I asked Elrond to explain why he put
  22   ASCENDING and DESCENDING in db/util.py when we could just import from
  23   pymongo.  Read beow for why, but note that nobody is actually doing
  24   this and there's no proof that we'll ever support more than
  25   MongoDB... it would be a huge amount of work to do so.
  26
  27   If you really want to prove that possible, jump on IRC and talk to
  28   us about making such a branch.  In the meanwhile, it doesn't hurt to
  29   have things as they are... if it ever makes it hard for us to
  30   actually do things, we might revisit or remove this.  But for more
  31   information, read below.
  32
  33 This submodule is for most of the db specific stuff.
  34
  35 There are two main ideas here:
  36
  37 1. Open up a small possibility to replace mongo by another
  38    db.  This means, that all direct mongo accesses should
  39    happen in the db submodule.  While all the rest uses an
  40    API defined by this submodule.
  41
  42    Currently this API happens to be basicly mongo.
  43    Which means, that the abstraction/wrapper layer is
  44    extremely thin.
  45
  46 2. Give the rest of the app a simple and easy way to get most of
  47    their db needs. Which often means some simple import
  48    from db.util.
  49
  50 What does that mean?
  51
  52 * Never import mongo directly outside of this submodule.
  53
  54 * Inside this submodule you can do whatever is needed. The
  55   API border is exactly at the submodule layer. Nowhere
  56   else.
  57
  58 * helper functions can be moved in here. They become part
  59   of the db.* API
  60
  61 """