From: Mike Bayer Date: Sat, 14 Apr 2007 01:28:45 +0000 (+0000) Subject: some docstrings to provide more detail in the sql package X-Git-Tag: rel_0_3_7~73 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bb1ec10f3a6b0932d8d6aa92027b40374db9943f;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git some docstrings to provide more detail in the sql package --- diff --git a/doc/build/content/docstrings.html b/doc/build/content/docstrings.html index 1fdde37e21..c0a9e1ac27 100644 --- a/doc/build/content/docstrings.html +++ b/doc/build/content/docstrings.html @@ -9,3 +9,4 @@ <%! filename = 'docstrings' %> + diff --git a/doc/build/gen_docstrings.py b/doc/build/gen_docstrings.py index ced16af24f..c9b9df09ed 100644 --- a/doc/build/gen_docstrings.py +++ b/doc/build/gen_docstrings.py @@ -16,16 +16,16 @@ import sqlalchemy.mods.threadlocal as threadlocal import sqlalchemy.ext.selectresults as selectresults import sqlalchemy.databases as databases -def make_doc(obj, classes=None, functions=None): +def make_doc(obj, classes=None, functions=None, **kwargs): """generate a docstring.ObjectDoc structure for an individual module, list of classes, and list of functions.""" - obj = docstring.ObjectDoc(obj, classes=classes, functions=functions) + obj = docstring.ObjectDoc(obj, classes=classes, functions=functions, **kwargs) return (obj.name, obj) def make_all_docs(): """generate a docstring.AbstractDoc structure.""" print "generating docstrings" objects = [ - make_doc(obj=sql), + make_doc(obj=sql,include_all_classes=True), make_doc(obj=schema), make_doc(obj=types), make_doc(obj=engine), diff --git a/doc/build/lib/docstring.py b/doc/build/lib/docstring.py index d234414bda..e878aa9b27 100644 --- a/doc/build/lib/docstring.py +++ b/doc/build/lib/docstring.py @@ -14,15 +14,16 @@ class AbstractDoc(object): self.toc_path = None class ObjectDoc(AbstractDoc): - def __init__(self, obj, functions=None, classes=None): + def __init__(self, obj, functions=None, classes=None, include_all_classes=False): super(ObjectDoc, self).__init__(obj) self.isclass = isinstance(obj, types.ClassType) or isinstance(obj, types.TypeType) self.name= obj.__name__ + self.include_all_classes = include_all_classes functions = functions classes= classes if not self.isclass: - if hasattr(obj, '__all__'): + if not include_all_classes and hasattr(obj, '__all__'): objects = obj.__all__ sort = True else: @@ -42,10 +43,11 @@ class ObjectDoc(AbstractDoc): if getattr(obj,x,None) is not None and (isinstance(getattr(obj,x), types.TypeType) or isinstance(getattr(obj,x), types.ClassType)) - and not getattr(obj,x).__name__[0] == '_' + and (self.include_all_classes or not getattr(obj,x).__name__[0] == '_') ] + classes = list(set(classes)) if sort: - classes.sort(lambda a, b: cmp(a.__name__, b.__name__)) + classes.sort(lambda a, b: cmp(a.__name__.replace('_', ''), b.__name__.replace('_', ''))) else: if functions is None: functions = ( diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py index 2388ecc3e0..450653e39a 100644 --- a/lib/sqlalchemy/sql.py +++ b/lib/sqlalchemy/sql.py @@ -326,6 +326,8 @@ def label(name, obj): def column(text, type=None): """Return a textual column clause, relative to a table. + + The object returned is an instance of ``sqlalchemy.sql._ColumnClause``. This is also the primitive version of a ``schema.Column`` which is a subclass. @@ -869,7 +871,21 @@ class ClauseElement(object): return _BooleanExpression(_TextClause("NOT"), self, None) class _CompareMixin(object): - """Define comparison operations for ClauseElements.""" + """Defines comparison operations for ``ClauseElement`` instances. + + This is a mixin class that adds the capability to produce ``ClauseElement`` + instances based on regular Python operators. + These operations are achieved using Python's operator overload methods + (i.e. ``__eq__()``, ``__ne__()``, etc. + + Overridden operators include all comparison operators (i.e. '==', '!=', '<'), + math operators ('+', '-', '*', etc), the '&' and '|' operators which evaluate + to ``AND`` and ``OR`` respectively. + + Other methods exist to create additional SQL clauses such as ``IN``, ``LIKE``, + ``DISTINCT``, etc. + + """ def __lt__(self, other): return self._compare('<', other) @@ -890,9 +906,11 @@ class _CompareMixin(object): return self._compare('>=', other) def like(self, other): + """produce a ``LIKE`` clause.""" return self._compare('LIKE', other) def in_(self, *other): + """produce an ``IN`` clause.""" if len(other) == 0: return self.__eq__(None) elif len(other) == 1 and not hasattr(other[0], '_selectable'): @@ -908,21 +926,42 @@ class _CompareMixin(object): return self._compare('IN', other[0], negate='NOT IN') def startswith(self, other): + """produce the clause ``LIKE '%'``""" return self._compare('LIKE', other + "%") def endswith(self, other): + """produce the clause ``LIKE '%'``""" return self._compare('LIKE', "%" + other) def label(self, name): + """produce a column label, i.e. `` AS ``""" return _Label(name, self, self.type) def distinct(self): + """produce a DISTINCT clause, i.e. ``DISTINCT ``""" return _CompoundClause(None,"DISTINCT", self) def between(self, cleft, cright): + """produce a BETWEEN clause, i.e. `` BETWEEN AND ``""" return _BooleanExpression(self, and_(self._check_literal(cleft), self._check_literal(cright)), 'BETWEEN') def op(self, operator): + """produce a generic operator function. + + e.g. + + somecolumn.op("*")(5) + + produces + + somecolumn * 5 + + operator + a string which will be output as the infix operator + between this ``ClauseElement`` and the expression + passed to the generated function. + + """ return lambda other: self._operate(operator, other) # and here come the math operators: @@ -1008,15 +1047,24 @@ class Selectable(ClauseElement): return True class ColumnElement(Selectable, _CompareMixin): - """Represent a column element within the list of a Selectable's columns. - - A ``ColumnElement`` can either be directly associated with a - ``TableClause``, or a free-standing textual column with no table, - or is a *proxy* column, indicating it is placed on a - ``Selectable`` such as an ``Alias`` or ``Select`` statement and - ultimately corresponds to a ``TableClause``-attached column (or in - the case of a ``CompositeSelect``, a proxy ``ColumnElement`` may - correspond to several ``TableClause``-attached columns). + """Represent an element that is useable within the + "column clause" portion of a ``SELECT`` statement. + + This includes columns associated with tables, aliases, + and subqueries, expressions, function calls, SQL keywords + such as ``NULL``, literals, etc. ``ColumnElement`` is the + ultimate base class for all such elements. + + ``ColumnElement`` supports the ability to be a *proxy* element, + which indicates that the ``ColumnElement`` may be associated with + a ``Selectable`` which was derived from another ``Selectable``. + An example of a "derived" ``Selectable`` is an ``Alias`` of + a ``Table``. + + a ``ColumnElement``, by subclassing the ``_CompareMixin`` mixin + class, provides the ability to generate new ``ClauseElement`` + objects using Python expressions. See the ``_CompareMixin`` + docstring for more details. """ primary_key = property(lambda self:getattr(self, '_primary_key', False), @@ -1962,9 +2010,34 @@ class _Label(ColumnElement): legal_characters = util.Set(string.ascii_letters + string.digits + '_') class _ColumnClause(ColumnElement): - """Represent a textual column clause in a SQL statement. - - May or may not be bound to an underlying ``Selectable``. + """Represents a generic column expression from any textual string. + This includes columns associated with tables, aliases and select + statements, but also any arbitrary text. May or may not be bound + to an underlying ``Selectable``. ``_ColumnClause`` is usually + created publically via the ``column()`` function or the + ``column_literal()`` function. + + text + the text of the element. + + selectable + parent selectable. + + type + ``TypeEngine`` object which can associate this ``_ColumnClause`` + with a type. + + case_sensitive + defines whether identifier quoting rules will be applied to the + generated text of this ``_ColumnClause`` so that it is identified in + a case-sensitive manner. + + is_literal + if True, the ``_ColumnClause`` is assumed to be an exact expression + that will be delivered to the output with no quoting rules applied + regardless of case sensitive settings. the ``column_literal()`` function is + usually used to create such a ``_ColumnClause``. + """ def __init__(self, text, selectable=None, type=None, _is_oid=False, case_sensitive=True, is_literal=False):