# HG changeset patch
# User Thierry Florac <thierry.florac@onf.fr>
# Date 1515688268 -3600
# Node ID 35db50b263751cf2e2d7373361a5cb140d4e7874
# Parent  c33dfe243afc221260e54901409756c8170ae494
Use DocFieldProperty to generate Sphinx documentation based on fields description

diff -r c33dfe243afc -r 35db50b26375 src/pyams_alchemy/engine.py
--- a/src/pyams_alchemy/engine.py	Thu Jan 11 17:30:29 2018 +0100
+++ b/src/pyams_alchemy/engine.py	Thu Jan 11 17:31:08 2018 +0100
@@ -34,6 +34,7 @@
 # import packages
 from persistent import Persistent
 from persistent.dict import PersistentDict
+from pyams_utils.property import DocFieldProperty
 from pyams_utils.registry import query_utility
 from pyams_utils.request import check_request, get_request_data, set_request_data
 from pyams_utils.vocabulary import vocabulary_config
@@ -41,7 +42,6 @@
 from zope.componentvocabulary.vocabulary import UtilityVocabulary
 from zope.container.contained import Contained
 from zope.interface import implementer
-from zope.schema.fieldproperty import FieldProperty
 from zope.sqlalchemy.datamanager import _SESSION_STATE, STATUS_READONLY, STATUS_ACTIVE, \
     ZopeTransactionExtension, join_transaction
 
@@ -79,7 +79,7 @@
 class ConnectionCleanerThread(Thread):
     """Background thread used to clean unused database connections
 
-    Each connection is referenced in CONNECTION_TIMESTAMPS on checkin and is invalidated
+    Each connection is referenced in CONNECTION_TIMESTAMPS mapping on checkin and is invalidated
     if not being used after 5 minutes
     """
     timeout = 300
@@ -106,15 +106,15 @@
 class AlchemyEngineUtility(object):
     """SQLAlchemy engine utility"""
 
-    name = FieldProperty(IAlchemyEngineUtility['name'])
-    dsn = FieldProperty(IAlchemyEngineUtility['dsn'])
-    echo = FieldProperty(IAlchemyEngineUtility['echo'])
-    use_pool = FieldProperty(IAlchemyEngineUtility['use_pool'])
-    pool_size = FieldProperty(IAlchemyEngineUtility['pool_size'])
-    pool_recycle = FieldProperty(IAlchemyEngineUtility['pool_recycle'])
-    echo_pool = FieldProperty(IAlchemyEngineUtility['echo_pool'])
-    encoding = FieldProperty(IAlchemyEngineUtility['encoding'])
-    convert_unicode = FieldProperty(IAlchemyEngineUtility['convert_unicode'])
+    name = DocFieldProperty(IAlchemyEngineUtility['name'])
+    dsn = DocFieldProperty(IAlchemyEngineUtility['dsn'])
+    echo = DocFieldProperty(IAlchemyEngineUtility['echo'])
+    use_pool = DocFieldProperty(IAlchemyEngineUtility['use_pool'])
+    pool_size = DocFieldProperty(IAlchemyEngineUtility['pool_size'])
+    pool_recycle = DocFieldProperty(IAlchemyEngineUtility['pool_recycle'])
+    echo_pool = DocFieldProperty(IAlchemyEngineUtility['echo_pool'])
+    encoding = DocFieldProperty(IAlchemyEngineUtility['encoding'])
+    convert_unicode = DocFieldProperty(IAlchemyEngineUtility['convert_unicode'])
 
     def __init__(self, name='', dsn='', echo=False, use_pool=True, pool_size=25, pool_recycle=-1, echo_pool=False,
                  encoding='utf-8', convert_unicode=False, **kwargs):
@@ -203,7 +203,8 @@
                 twophase=True, use_zope_extension=True, use_pool=True):
     """Get a new SQLALchemy session
 
-    Session is stored in request and in session storage
+    Session is stored in request and in session storage.
+    See :func:`get_user_session` function to get arguments documentation.
     """
     if request is None:
         request = check_request()
@@ -234,8 +235,15 @@
                      twophase=True, use_zope_extension=True, use_pool=True):
     """Get a new SQLAlchemy session
 
-    `engine` can be a session name or an already created session (in which case it's
-    returned as-is).
+    :param str engine: name of an SQLAlchemy engine session utility; if *engine* is not given as a string, it is
+        returned as-is.
+    :param bool join: if *True*, session is joined to the current Pyramid transaction
+    :param str status: status of the new session; can be STATUS_ACTIVE or STATUS_READONLY
+    :param request: currently running request
+    :param str alias: alias to use in connections mapping for this session
+    :param bool twophase: if *False*, session will be isolated and not included into two-phase transactions mechanism
+    :param bool use_zope_extension: if *True*, use ZopeTransactionExtension scoped session
+    :param bool use_pool: if *True*, this session will use a pool
     """
     if isinstance(engine, str):
         session = get_session(engine, join, status, request, alias, twophase, use_zope_extension, use_pool)