docs/dbsession.readme

   1 As of Nov. 2013, when moving from 3.0 to 3.2
   2 --------------------------------------------
   3
   4 * driver-creation
   5 . expect an api instead of a config (and api.config is set)
   6
   7 * managers
   8 . cannot access their driver from self, but from the context (api is passed to methods)
   9
  10 * dbsession : implementation
  11 . storage.Alchemy still exports a global dbsession object, but named global_session(); together with close_global_session()
  12 . storage.Alchemy also exports a method called session(), that is *NOT* managed - caller is expected to close_session()
  13 . storage.Alchemy only exports global_session (as alchemy.global_session)
  14   so that any code that would still need adaptation will break at import time
  15
  16 * dbsession : usage
  17 . use api.dbsession() whenever possible
  18 . it's fair to have importers and sfaadmin use the global session (there won't be instances of api in their case)
  19 . there is one or 2 exceptions where dbsession is retrieved from an sqlalchemy object but this is deemed poor practice, please DO NOT do this as far as possible
  20
  21 ---
  22 OTHER NOTES:
  23
  24 * iotlab/cortexlab:
  25 . while browsing this code I noticed that the code for cortexlab seems very close to the one for iotlab
  26   I wonder if some inheritance would have allowed to reduce code duplication
  27   so I'll forget about cortexlab for now as all/most of the folowing comments probably apply as-is to cortex
  28
  29 * iotlab/iotlabapi
  30 . it's confusing that the class name here does not match the filename (class IotlabTestbedAPI in iotlabapi.py)
  31 . IIUC this could/should be renamed IotlabShell (in iotlabshell.py) instead, that's exactly what our notion of a shell is
  32 . regardless; in order to fetch dbsession() from the context api, I tried to tweak iotlabtestbedapi so that it also takes an api instead of a config in argument
  33   however I am puzzled at why most(all?) the IotlabTestbadAPI methods that actually use dbsession are labelled as methodstatic ?
  34   Is this a strong constraint ?
  35   It would help me a lot if this could be made a regular class, as opposed to what looks like a mere namespace, so we can retrieve dbsession() from an api object
  36
  37