diff options
Diffstat (limited to 'lib/sqlalchemy/event/legacy.py')
| -rw-r--r-- | lib/sqlalchemy/event/legacy.py | 116 |
1 files changed, 64 insertions, 52 deletions
diff --git a/lib/sqlalchemy/event/legacy.py b/lib/sqlalchemy/event/legacy.py index fc3aa288e..3b1519cb6 100644 --- a/lib/sqlalchemy/event/legacy.py +++ b/lib/sqlalchemy/event/legacy.py @@ -12,6 +12,7 @@ generation of deprecation notes and docstrings. from .. import util + def _legacy_signature(since, argnames, converter=None): def leg(fn): if not hasattr(fn, '_legacy_signatures'): @@ -20,6 +21,7 @@ def _legacy_signature(since, argnames, converter=None): return fn return leg + def _wrap_fn_for_legacy(dispatch_descriptor, fn, argspec): for since, argnames, conv in dispatch_descriptor.legacy_signatures: if argnames[-1] == "**kw": @@ -29,10 +31,11 @@ def _wrap_fn_for_legacy(dispatch_descriptor, fn, argspec): has_kw = False if len(argnames) == len(argspec.args) \ - and has_kw is bool(argspec.keywords): + and has_kw is bool(argspec.keywords): if conv: assert not has_kw + def wrap_leg(*args): return fn(*conv(*args)) else: @@ -47,38 +50,42 @@ def _wrap_fn_for_legacy(dispatch_descriptor, fn, argspec): else: return fn + def _indent(text, indent): return "\n".join( - indent + line - for line in text.split("\n") - ) + indent + line + for line in text.split("\n") + ) + def _standard_listen_example(dispatch_descriptor, sample_target, fn): example_kw_arg = _indent( - "\n".join( - "%(arg)s = kw['%(arg)s']" % {"arg": arg} - for arg in dispatch_descriptor.arg_names[0:2] - ), - " ") + "\n".join( + "%(arg)s = kw['%(arg)s']" % {"arg": arg} + for arg in dispatch_descriptor.arg_names[0:2] + ), + " ") if dispatch_descriptor.legacy_signatures: current_since = max(since for since, args, conv in dispatch_descriptor.legacy_signatures) else: current_since = None text = ( - "from sqlalchemy import event\n\n" - "# standard decorator style%(current_since)s\n" - "@event.listens_for(%(sample_target)s, '%(event_name)s')\n" - "def receive_%(event_name)s(%(named_event_arguments)s%(has_kw_arguments)s):\n" - " \"listen for the '%(event_name)s' event\"\n" - "\n # ... (event handling logic) ...\n" + "from sqlalchemy import event\n\n" + "# standard decorator style%(current_since)s\n" + "@event.listens_for(%(sample_target)s, '%(event_name)s')\n" + "def receive_%(event_name)s(" + "%(named_event_arguments)s%(has_kw_arguments)s):\n" + " \"listen for the '%(event_name)s' event\"\n" + "\n # ... (event handling logic) ...\n" ) if len(dispatch_descriptor.arg_names) > 3: text += ( "\n# named argument style (new in 0.9)\n" - "@event.listens_for(%(sample_target)s, '%(event_name)s', named=True)\n" + "@event.listens_for(" + "%(sample_target)s, '%(event_name)s', named=True)\n" "def receive_%(event_name)s(**kw):\n" " \"listen for the '%(event_name)s' event\"\n" "%(example_kw_arg)s\n" @@ -86,72 +93,77 @@ def _standard_listen_example(dispatch_descriptor, sample_target, fn): ) text %= { - "current_since": " (arguments as of %s)" % - current_since if current_since else "", - "event_name": fn.__name__, - "has_kw_arguments": ", **kw" if dispatch_descriptor.has_kw else "", - "named_event_arguments": ", ".join(dispatch_descriptor.arg_names), - "example_kw_arg": example_kw_arg, - "sample_target": sample_target - } + "current_since": " (arguments as of %s)" % + current_since if current_since else "", + "event_name": fn.__name__, + "has_kw_arguments": ", **kw" if dispatch_descriptor.has_kw else "", + "named_event_arguments": ", ".join(dispatch_descriptor.arg_names), + "example_kw_arg": example_kw_arg, + "sample_target": sample_target + } return text + def _legacy_listen_examples(dispatch_descriptor, sample_target, fn): text = "" for since, args, conv in dispatch_descriptor.legacy_signatures: text += ( "\n# legacy calling style (pre-%(since)s)\n" "@event.listens_for(%(sample_target)s, '%(event_name)s')\n" - "def receive_%(event_name)s(%(named_event_arguments)s%(has_kw_arguments)s):\n" + "def receive_%(event_name)s(" + "%(named_event_arguments)s%(has_kw_arguments)s):\n" " \"listen for the '%(event_name)s' event\"\n" "\n # ... (event handling logic) ...\n" % { "since": since, "event_name": fn.__name__, - "has_kw_arguments": " **kw" if dispatch_descriptor.has_kw else "", + "has_kw_arguments": " **kw" + if dispatch_descriptor.has_kw else "", "named_event_arguments": ", ".join(args), "sample_target": sample_target } ) return text + def _version_signature_changes(dispatch_descriptor): since, args, conv = dispatch_descriptor.legacy_signatures[0] return ( - "\n.. versionchanged:: %(since)s\n" - " The ``%(event_name)s`` event now accepts the \n" - " arguments ``%(named_event_arguments)s%(has_kw_arguments)s``.\n" - " Listener functions which accept the previous argument \n" - " signature(s) listed above will be automatically \n" - " adapted to the new signature." % { - "since": since, - "event_name": dispatch_descriptor.__name__, - "named_event_arguments": ", ".join(dispatch_descriptor.arg_names), - "has_kw_arguments": ", **kw" if dispatch_descriptor.has_kw else "" - } - ) + "\n.. versionchanged:: %(since)s\n" + " The ``%(event_name)s`` event now accepts the \n" + " arguments ``%(named_event_arguments)s%(has_kw_arguments)s``.\n" + " Listener functions which accept the previous argument \n" + " signature(s) listed above will be automatically \n" + " adapted to the new signature." % { + "since": since, + "event_name": dispatch_descriptor.__name__, + "named_event_arguments": ", ".join(dispatch_descriptor.arg_names), + "has_kw_arguments": ", **kw" if dispatch_descriptor.has_kw else "" + } + ) + def _augment_fn_docs(dispatch_descriptor, parent_dispatch_cls, fn): header = ".. container:: event_signatures\n\n"\ - " Example argument forms::\n"\ - "\n" + " Example argument forms::\n"\ + "\n" sample_target = getattr(parent_dispatch_cls, "_target_class_doc", "obj") text = ( - header + - _indent( - _standard_listen_example( - dispatch_descriptor, sample_target, fn), - " " * 8) - ) + header + + _indent( + _standard_listen_example( + dispatch_descriptor, sample_target, fn), + " " * 8) + ) if dispatch_descriptor.legacy_signatures: text += _indent( - _legacy_listen_examples( - dispatch_descriptor, sample_target, fn), - " " * 8) + _legacy_listen_examples( + dispatch_descriptor, sample_target, fn), + " " * 8) text += _version_signature_changes(dispatch_descriptor) return util.inject_docstring_text(fn.__doc__, - text, - 1 - ) + text, + 1 + ) |