# SQLAlchemy 0.6.0 Documentation

Search:
Version: 0.6.0 Last Updated: 04/18/2010 19:16:18

# Utilities

class `sqlalchemy.util.``IdentitySet`(iterable=None)

  A set that considers only object id() for uniqueness.

  This strategy has edge cases for builtin types- it’s possible to have two ‘foo’ strings in one of these sets, for example. Use sparingly.

  `__init__`(iterable=None)

class `sqlalchemy.util.``NamedTuple`

  tuple() subclass that adds labeled names.

  Is also pickleable.

class `sqlalchemy.util.``OrderedDict`(_OrderedDict____sequence=None, **kwargs)

  A dict that returns keys/values/items in the order they were added.

  `__init__`(_OrderedDict____sequence=None, **kwargs)

class `sqlalchemy.util.``OrderedProperties`

  An object that maintains the order in which attributes are set upon it.

  Also provides an iterator and a very basic getitem/setitem interface to those attributes.

  (Not really a dict, since it iterates over values, not keys. Not really a list, either, since each value must have a key associated; hence there is no append or extend.)

  `__init__`()

class `sqlalchemy.util.``PopulateDict`(creator)

  A dict which populates missing values via a creation function.

  Note the creation function takes a key, unlike collections.defaultdict.

  `__init__`(creator)

class `sqlalchemy.util.``ScopedRegistry`(createfunc, scopefunc)

  A Registry that can store one or multiple instances of a single class on a per-thread scoped basis, or on a customized scope.

  createfunc
    a callable that returns a new object to be placed in the registry
  scopefunc
    a callable that will return a key to store/retrieve an object.
  `__init__`(createfunc, scopefunc)

class `sqlalchemy.util.``UniqueAppender`(data, via=None)

  Appends items to a collection ensuring uniqueness.

  Additional appends() of the same object are ignored. Membership is determined by identity (`is a`) not equality (`==`).

  `__init__`(data, via=None)

class `sqlalchemy.util.``WeakIdentityMapping`

  A WeakKeyDictionary with an object identity index.

  Adds a .by_id dictionary to a regular WeakKeyDictionary. Trades performance during mutation operations for accelerated lookups by id().

  The usual cautions about weak dictionaries and iteration also apply to this subclass.

  `__init__`()

`sqlalchemy.util.``as_interface`(obj, cls=None, methods=None, required=None)

  Ensure basic interface compliance for an instance or dict of callables.

  Checks that `obj` implements public methods of `cls` or has members listed in `methods`. If `required` is not supplied, implementing at least one interface method is sufficient. Methods present on `obj` that are not in the interface are ignored.

  If `obj` is a dict and `dict` does not meet the interface requirements, the keys of the dictionary are inspected. Keys present in `obj` that are not in the interface will raise TypeErrors.

  Raises TypeError if `obj` does not meet the interface criteria.

  In all passing cases, an object with callable members is returned. In the simple case, `obj` is returned as-is; if dict processing kicks in then an anonymous class is returned.

  obj
    A type, instance, or dictionary of callables.
  cls
    Optional, a type. All public methods of cls are considered the interface. An `obj` instance of cls will always pass, ignoring `required`..
  methods
    Optional, a sequence of method names to consider as the interface.
  required
    Optional, a sequence of mandatory implementations. If omitted, an `obj` that provides at least one interface method is considered sufficient. As a convenience, required may be a type, in which case all public methods of the type are required.

`sqlalchemy.util.``class_hierarchy`(cls)

  Return an unordered sequence of all classes related to cls.

  Traverses diamond hierarchies.

  Fibs slightly: subclasses of builtin types are not returned. Thus class_hierarchy(class A(object)) returns (A, object), not A plus every class systemwide that derives from object.

  Old-style classes are discarded and hierarchies rooted on them will not be descended.

`sqlalchemy.util.``classproperty`

  A decorator that behaves like @property except that operates on classes rather than instances.

  This is helpful when you need to compute __table_args__ and/or __mapper_args__ when using declarative.

`sqlalchemy.util.``coerce_kw_type`(kw, key, type_, flexi_bool=True)
  If ‘key’ is present in dict ‘kw’, coerce its value to type ‘type_’ if necessary. If ‘flexi_bool’ is True, the string ‘0’ is considered false when coercing to boolean.

`sqlalchemy.util.``decode_slice`(slc)

  decode a slice object as sent to __getitem__.

  takes into account the 2.5 __index__() method, basically.

`sqlalchemy.util.``decorator`(target)
  A signature-matching decorator factory.

`sqlalchemy.util.``deprecated`(message=None, add_deprecation_to_docstring=True)

  Decorates a function and issues a deprecation warning on use.

  message
    If provided, issue message in the warning. A sensible default is used if not provided.
  add_deprecation_to_docstring
    Default True. If False, the wrapped function’s __doc__ is left as-is. If True, the ‘message’ is prepended to the docs if provided, or sensible default if message is omitted.

`sqlalchemy.util.``dictlike_iteritems`(dictlike)
  Return a (key, value) iterator for almost any dict-like object.

`sqlalchemy.util.``duck_type_collection`(specimen, default=None)
  Given an instance or class, guess if it is or is acting as one of the basic collection types: list, set and dict. If the __emulates__ property is present, return that preferentially.

`sqlalchemy.util.``flatten_iterator`(x)
  Given an iterator of which further sub-elements may also be iterators, flatten the sub-elements into a single iterator.

`sqlalchemy.util.``format_argspec_init`(method, grouped=True)

  format_argspec_plus with considerations for typical __init__ methods

  Wraps format_argspec_plus with error handling strategies for typical __init__ cases:

      object.__init__ -> (self)
      other unreflectable (usually C) -> (self, *args, **kwargs)

`sqlalchemy.util.``format_argspec_plus`(fn, grouped=True)

  Returns a dictionary of formatted, introspected function arguments.

  A enhanced variant of inspect.formatargspec to support code generation.

  fn
    An inspectable callable or tuple of inspect getargspec() results.
  grouped
    Defaults to True; include (parens, around, argument) lists

  Returns:

  args
    Full inspect.formatargspec for fn
  self_arg
    The name of the first positional argument, varargs[0], or None if the function defines no positional arguments.
  apply_pos
    args, re-written in calling rather than receiving syntax. Arguments are passed positionally.
  apply_kw
    Like apply_pos, except keyword-ish args are passed as keywords.

  Example:

      >>> format_argspec_plus(lambda self, a, b, c=3, **d: 123)
      {'args': '(self, a, b, c=3, **d)',
       'self_arg': 'self',
       'apply_kw': '(self, a, b, c=c, **d)',
       'apply_pos': '(self, a, b, c, **d)'}

`sqlalchemy.util.``function_named`(fn, name)

  Return a function with a given __name__.

  Will assign to __name__ and return the original function if possible on the Python implementation, otherwise a new function will be constructed.

`sqlalchemy.util.``get_cls_kwargs`(cls)

  Return the full set of inherited kwargs for the given cls.

  Probes a class’s __init__ method, collecting all named arguments. If the __init__ defines a **kwargs catch-all, then the constructor is presumed to pass along unrecognized keywords to it’s base classes, and the collection process is repeated recursively on each of the bases.

`sqlalchemy.util.``get_func_kwargs`(func)
  Return the full set of legal kwargs for the given func.

`sqlalchemy.util.``getargspec_init`(method)

  inspect.getargspec with considerations for typical __init__ methods

  Wraps inspect.getargspec with error handling for typical __init__ cases:

      object.__init__ -> (self)
      other unreflectable (usually C) -> (self, *args, **kwargs)

`sqlalchemy.util.``iterate_attributes`(cls)

  iterate all the keys and attributes associated with a class, without using getattr().

  Does not use getattr() so that class-sensitive descriptors (i.e. property.__get__()) are not called.

`sqlalchemy.util.``memoized_instancemethod`

  Decorate a method memoize its return value.

  Best applied to no-arg methods: memoization is not sensitive to argument values, and will always return the same value even when called with different arguments.

`sqlalchemy.util.``memoized_property`
  A read-only @property that is only evaluated once.

`sqlalchemy.util.``monkeypatch_proxied_specials`(into_cls, from_cls, skip=None, only=None, name='self.proxy', from_instance=None)
  Automates delegation of __specials__ for a proxying type.

`sqlalchemy.util.``pending_deprecation`(version, message=None, add_deprecation_to_docstring=True)

  Decorates a function and issues a pending deprecation warning on use.

  version
    An approximate future version at which point the pending deprecation will become deprecated. Not used in messaging.
  message
    If provided, issue message in the warning. A sensible default is used if not provided.
  add_deprecation_to_docstring
    Default True. If False, the wrapped function’s __doc__ is left as-is. If True, the ‘message’ is prepended to the docs if provided, or sensible default if message is omitted.

`sqlalchemy.util.``populate_column_dict`
  alias of `PopulateDict`

class `sqlalchemy.util.``portable_instancemethod`(meth)

  Turn an instancemethod into a (parent, name) pair to produce a serializable callable.

  `__init__`(meth)

`sqlalchemy.util.``set_creation_order`(instance)

  Assign a ‘_creation_order’ sequence to the given instance.

  This allows multiple instances to be sorted in order of creation (typically within a single thread; the counter is not particularly threadsafe).

class `sqlalchemy.util.``symbol`

  A constant symbol.

      >>> symbol('foo') is symbol('foo')
      True
      >>> symbol('foo')
      <symbol 'foo>

  A slight refinement of the MAGICCOOKIE=object() pattern. The primary advantage of symbol() is its repr(). They are also singletons.

  Repeated calls of symbol(‘name’) will all return the same instance.

`sqlalchemy.util.``unbound_method_to_callable`(func_or_cls)
  Adjust the incoming callable such that a ‘self’ argument is not required.

`sqlalchemy.util.``update_copy`(d, _new=None, **kw)
  Copy the given dict and update with the given values.

`sqlalchemy.util.``warn_exception`(func, *args, **kwargs)
  executes the given function, catches all exceptions and converts to a warning.