openmedialibrary_platform/Darwin/lib/python3.4/site-packages/sqlalchemy/event/legacy.py

170 lines
5.7 KiB
Python
Raw Normal View History

2013-10-11 17:28:32 +00:00
# event/legacy.py
2014-09-30 16:15:32 +00:00
# Copyright (C) 2005-2014 the SQLAlchemy authors and contributors
# <see AUTHORS file>
2013-10-11 17:28:32 +00:00
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
"""Routines to handle adaption of legacy call signatures,
generation of deprecation notes and docstrings.
"""
from .. import util
2014-09-30 16:15:32 +00:00
2013-10-11 17:28:32 +00:00
def _legacy_signature(since, argnames, converter=None):
def leg(fn):
if not hasattr(fn, '_legacy_signatures'):
fn._legacy_signatures = []
fn._legacy_signatures.append((since, argnames, converter))
return fn
return leg
2014-09-30 16:15:32 +00:00
2013-10-11 17:28:32 +00:00
def _wrap_fn_for_legacy(dispatch_descriptor, fn, argspec):
for since, argnames, conv in dispatch_descriptor.legacy_signatures:
if argnames[-1] == "**kw":
has_kw = True
argnames = argnames[0:-1]
else:
has_kw = False
if len(argnames) == len(argspec.args) \
2014-09-30 16:15:32 +00:00
and has_kw is bool(argspec.keywords):
2013-10-11 17:28:32 +00:00
if conv:
assert not has_kw
2014-09-30 16:15:32 +00:00
2013-10-11 17:28:32 +00:00
def wrap_leg(*args):
return fn(*conv(*args))
else:
def wrap_leg(*args, **kw):
argdict = dict(zip(dispatch_descriptor.arg_names, args))
args = [argdict[name] for name in argnames]
if has_kw:
return fn(*args, **kw)
else:
return fn(*args)
return wrap_leg
else:
return fn
2014-09-30 16:15:32 +00:00
2013-10-11 17:28:32 +00:00
def _indent(text, indent):
return "\n".join(
2014-09-30 16:15:32 +00:00
indent + line
for line in text.split("\n")
)
2013-10-11 17:28:32 +00:00
def _standard_listen_example(dispatch_descriptor, sample_target, fn):
example_kw_arg = _indent(
2014-09-30 16:15:32 +00:00
"\n".join(
"%(arg)s = kw['%(arg)s']" % {"arg": arg}
for arg in dispatch_descriptor.arg_names[0:2]
),
" ")
2013-10-11 17:28:32 +00:00
if dispatch_descriptor.legacy_signatures:
current_since = max(since for since, args, conv
in dispatch_descriptor.legacy_signatures)
else:
current_since = None
text = (
2014-09-30 16:15:32 +00:00
"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"
2013-10-11 17:28:32 +00:00
)
if len(dispatch_descriptor.arg_names) > 3:
text += (
"\n# named argument style (new in 0.9)\n"
2014-09-30 16:15:32 +00:00
"@event.listens_for("
"%(sample_target)s, '%(event_name)s', named=True)\n"
2013-10-11 17:28:32 +00:00
"def receive_%(event_name)s(**kw):\n"
" \"listen for the '%(event_name)s' event\"\n"
"%(example_kw_arg)s\n"
"\n # ... (event handling logic) ...\n"
)
text %= {
2014-09-30 16:15:32 +00:00
"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
}
2013-10-11 17:28:32 +00:00
return text
2014-09-30 16:15:32 +00:00
2013-10-11 17:28:32 +00:00
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"
2014-09-30 16:15:32 +00:00
"def receive_%(event_name)s("
"%(named_event_arguments)s%(has_kw_arguments)s):\n"
2013-10-11 17:28:32 +00:00
" \"listen for the '%(event_name)s' event\"\n"
"\n # ... (event handling logic) ...\n" % {
"since": since,
"event_name": fn.__name__,
2014-09-30 16:15:32 +00:00
"has_kw_arguments": " **kw"
if dispatch_descriptor.has_kw else "",
2013-10-11 17:28:32 +00:00
"named_event_arguments": ", ".join(args),
"sample_target": sample_target
}
)
return text
2014-09-30 16:15:32 +00:00
2013-10-11 17:28:32 +00:00
def _version_signature_changes(dispatch_descriptor):
since, args, conv = dispatch_descriptor.legacy_signatures[0]
return (
2014-09-30 16:15:32 +00:00
"\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 ""
}
)
2013-10-11 17:28:32 +00:00
def _augment_fn_docs(dispatch_descriptor, parent_dispatch_cls, fn):
header = ".. container:: event_signatures\n\n"\
2014-09-30 16:15:32 +00:00
" Example argument forms::\n"\
"\n"
2013-10-11 17:28:32 +00:00
sample_target = getattr(parent_dispatch_cls, "_target_class_doc", "obj")
text = (
2014-09-30 16:15:32 +00:00
header +
_indent(
_standard_listen_example(
dispatch_descriptor, sample_target, fn),
" " * 8)
)
2013-10-11 17:28:32 +00:00
if dispatch_descriptor.legacy_signatures:
text += _indent(
2014-09-30 16:15:32 +00:00
_legacy_listen_examples(
dispatch_descriptor, sample_target, fn),
" " * 8)
2013-10-11 17:28:32 +00:00
text += _version_signature_changes(dispatch_descriptor)
return util.inject_docstring_text(fn.__doc__,
2014-09-30 16:15:32 +00:00
text,
1
)