cubicweb: comparison server/session.py

equal deleted inserted replaced

-:05aaa94c04f2
+:68744f5154c4
 pass
 class CnxSetTracker(object):
 """Keep track of which transaction use which cnxset.
-There should be one of this object per session plus one another for
+There should be one of these object per session (including internal sessions).
-internal session.
+Session objects are responsible of creating their CnxSetTracker object.
-Session object are responsible of creating their CnxSetTracker object.
+Transactions should use the :meth:`record` and :meth:`forget` to inform the
-Transaction should use the :meth:`record` and :meth:`forget` to inform the
+tracker of cnxsets they have acquired.
-tracker of cnxset they have acquired.
 .. automethod:: cubicweb.server.session.CnxSetTracker.record
 .. automethod:: cubicweb.server.session.CnxSetTracker.forget
-Session use the :meth:`close` and :meth:`wait` method when closing.
+Sessions use the :meth:`close` and :meth:`wait` methods when closing.
 .. automethod:: cubicweb.server.session.CnxSetTracker.close
 .. automethod:: cubicweb.server.session.CnxSetTracker.wait
 This object itself is threadsafe. It also requires caller to acquired its
 def __exit__(self, *args):
 return self._condition.__exit__(*args)
 def record(self, txid, cnxset):
-"""Inform the tracker that a txid have acquired a cnxset
+"""Inform the tracker that a txid has acquired a cnxset
-This methode is to be used by Transaction object.
+This method is to be used by Transaction objects.
 This method fails when:
-- The txid already have a recorded cnxset.
+- The txid already has a recorded cnxset.
 - The tracker is not active anymore.
 Notes about the caller:
 (1) It is responsible for retrieving a cnxset.
 (2) It must be prepared to release the cnxset if the
 `cnxsettracker.forget` call fails.
 (3) It should acquire the tracker lock until the very end of the operation.
-(4) However It take care to lock the CnxSetTracker object after having
+(4) However it must only lock the CnxSetTracker object after having
 retrieved the cnxset to prevent deadlock.
 A typical usage look like::
 cnxset = repo._get_cnxset() # (1)
 caller.cnxset = cnxset
 except Exception:
 repo._free_cnxset(cnxset) # (2)
 raise
 """
-# dubious since the caller is suppose to have acquired it anyway.
+# dubious since the caller is supposed to have acquired it anyway.
 with self._condition:
 if not self._active:
 raise SessionClosedError('Closed')
 old = self._record.get(txid)
 if old is not None:
-raise ValueError('"%s" already have a cnx_set (%r)'
+raise ValueError('transaction "%s" already has a cnx_set (%r)'
 % (txid, old))
 self._record[txid] = cnxset
 def forget(self, txid, cnxset):
 """Inform the tracker that a txid have release a cnxset
 self._condition.notify_all()
 def close(self):
 """Marks the tracker as inactive.
-This methode is to be used by Session object.
+This method is to be used by Session objects.
-Inactive tracker does not accept new record anymore.
+An inactive tracker does not accept new records anymore.
 """
 with self._condition:
 self._active = False
 def wait(self, timeout=10):
-"""Wait for all recorded cnxset to be released
+"""Wait for all recorded cnxsets to be released
-This methode is to be used by Session object.
+This method is to be used by Session objects.
-returns a tuple of transaction id that remains open.
+Returns a tuple of transaction ids that remain open.
 """
 with self._condition:
 if  self._active:
 raise RuntimeError('Cannot wait on active tracker.'
 ' Call tracker.close() first')
 class Transaction(object):
 """Repository Transaction
 Holds all transaction related data
-Database connections resource:
+Database connection resources:
 :attr:`running_dbapi_query`, boolean flag telling if the executing query
 is coming from a dbapi connection or is a query from within the repository
 :attr:`cnxset`, the connections set to use to execute queries on sources.
 If the transaction is read only, the connection set may be freed between
-actual query. This allows multiple transaction with a reasonable low
+actual queries. This allows multiple transactions with a reasonably low
-connection set pool size. control mechanism is detailed below
+connection set pool size.  Control mechanism is detailed below.
 .. automethod:: cubicweb.server.session.Transaction.set_cnxset
 .. automethod:: cubicweb.server.session.Transaction.free_cnxset
 :attr:`mode`, string telling the connections set handling mode, may be one
 'transaction' (we want to keep the connections set during all the
 transaction, with or without writing)
 Internal transaction data:
-:attr:`data`,is a dictionary containing some shared data
+:attr:`data` is a dictionary containing some shared data
 cleared at the end of the transaction. Hooks and operations may put
 arbitrary data in there, and this may also be used as a communication
 channel between the client and the repository.
 :attr:`pending_operations`, ordered list of operations to be processed on
 @property
 def transaction_data(self):
 return self.data
 def clear(self):
 """reset internal data"""
 self.data = {}
 #: ordered list of operations to be processed on commit/rollback
 self.pending_operations = []
 #: (None, 'precommit', 'postcommit', 'uncommitable')
 self.commit_state = None
 self.pruned_hooks_cache = {}
 # Connection Set Management ###############################################
 @property
 def cnxset(self):
 return self._cnxset
 self.repo._free_cnxset(cnxset)
 # Entity cache management #################################################
 #
-# The transaction entity cache as held in tx.data it is removed at end the
+# The transaction entity cache as held in tx.data is removed at the
 # end of the transaction (commit and rollback)
 #
 # XXX transaction level caching may be a pb with multiple repository
 # instances, but 1. this is probably not the only one :$ and 2. it may be
 # an acceptable risk. Anyway we could activate it or not according to a
 if eid is None:
 self.data.pop('ecache', None)
 else:
 del self.data['ecache'][eid]
-# Tracking of entity added of removed in the transaction ##################
+# Tracking of entities added of removed in the transaction ##################
-#
-# Those are function to  allows cheap call from client in other process.
 def deleted_in_transaction(self, eid):
 """return True if the entity of the given eid is being deleted in the
 current transaction
 """
 def transaction_inc_action_counter(self):
 num = self.data.setdefault('tx_action_count', 0) + 1
 self.data['tx_action_count'] = num
 return num
 # db-api like interface ###################################################
 def source_defs(self):
 return self.repo.source_defs()
 def describe(self, eid, asdict=False):
 """return a tuple (type, sourceuri, extid) for the entity with id <eid>"""
 metas = self.repo.type_and_source_from_eid(eid, self)
 if asdict:
 return dict(zip(('type', 'source', 'extid', 'asource'), metas))
 # XXX :-1 for cw compat, use asdict=True for full information
 return metas[:-1]
 def source_from_eid(self, eid):
 """return the source where the entity with id <eid> is located"""
 return self.repo.source_from_eid(eid, self)
 """return context manager to enter a transaction for the session: when
 exiting the `with` block on exception, call `session.rollback()`, else
 call `session.commit()` on normal exit.
 The `free_cnxset` will be given to rollback/commit methods to indicate
-wether the connections set should be freed or not.
+whether the connections set should be freed or not.
 """
 return transaction(self, free_cnxset)
 @deprecated('[3.17] do not use hijack_user. create new Session object')

branch	stable
changeset 9272	68744f5154c4
parent 9267	24d9b86dfa54
child 9274	b39ac464e3ac