From c0f391af951ab75a1c486d4179216d31997a0f83 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 29 Apr 2007 16:08:36 +0000 Subject: [PATCH] - fixed textual select elements that got broke the other day - docstring work --- doc/build/genhtml.py | 33 ++++++++++++++++++++------------- doc/build/lib/docstring.py | 5 ++++- doc/build/templates/pydoc.html | 6 +++--- lib/sqlalchemy/engine/base.py | 7 ++----- lib/sqlalchemy/sql.py | 14 ++++++++++++-- lib/sqlalchemy/util.py | 18 ++++++++++++++++++ 6 files changed, 59 insertions(+), 24 deletions(-) diff --git a/doc/build/genhtml.py b/doc/build/genhtml.py index 4f7e2d00ee..6ebedff1c9 100644 --- a/doc/build/genhtml.py +++ b/doc/build/genhtml.py @@ -8,10 +8,11 @@ import gen_docstrings, read_markdown, toc from mako.lookup import TemplateLookup from mako import exceptions, runtime import time +import optparse files = [ 'index', - 'documentation', +# 'documentation', 'tutorial', 'dbengine', 'metadata', @@ -25,10 +26,14 @@ files = [ 'docstrings' ] -argfile = len(sys.argv) > 1 and sys.argv[1] -if argfile: - files = [argfile] - +parser = optparse.OptionParser(usage = "usage: %prog [options] [tests...]") +parser.add_option("--file", action="store", dest="file", help="only generate file ") +parser.add_option("--docstrings", action="store_true", dest="docstrings", help="only generate docstrings") + +(options, args) = parser.parse_args() +if options.file: + files = [file] + title='SQLAlchemy 0.3 Documentation' version = '0.3.6' @@ -38,9 +43,10 @@ shutil.copy('./content/index.html', './output/index.html') shutil.copy('./content/docstrings.html', './output/docstrings.html') shutil.copy('./content/documentation.html', './output/documentation.html') -read_markdown.parse_markdown_files(root, files) +if not options.docstrings: + read_markdown.parse_markdown_files(root, files) -if not argfile: +if not options.file or options.docstrings: docstrings = gen_docstrings.make_all_docs() doc_files = gen_docstrings.create_docstring_toc(docstrings, root) @@ -60,13 +66,14 @@ def genfile(name, outname): t = lookup.get_template(infile) outfile.write(t.render(attributes={})) -for filename in files: - try: - genfile(filename, os.path.join(os.getcwd(), '../', filename + ".html")) - except: - print exceptions.text_error_template().render() +if not options.docstrings: + for filename in files: + try: + genfile(filename, os.path.join(os.getcwd(), '../', filename + ".html")) + except: + print exceptions.text_error_template().render() -if not argfile: +if not options.file or options.docstrings: for filename in doc_files: try: genfile(filename, os.path.join(os.getcwd(), '../', os.path.basename(filename) + ".html")) diff --git a/doc/build/lib/docstring.py b/doc/build/lib/docstring.py index e878aa9b27..f0aebe92ba 100644 --- a/doc/build/lib/docstring.py +++ b/doc/build/lib/docstring.py @@ -55,7 +55,7 @@ class ObjectDoc(AbstractDoc): and (getattr(obj, x).__name__ == '__init__' or not getattr(obj,x).__name__[0] == '_') ] + - [(x, getattr(obj, x)) for x in obj.__dict__.keys() if isinstance(getattr(obj,x), property) + [(x, getattr(obj, x)) for x in obj.__dict__.keys() if _is_property(getattr(obj,x)) and not x[0] == '_' ] @@ -111,6 +111,9 @@ class ObjectDoc(AbstractDoc): def accept_visitor(self, visitor): visitor.visit_object(self) +def _is_property(elem): + return isinstance(elem, property) or (hasattr(elem, '__get__') and hasattr(elem, '__set__')) + class FunctionDoc(AbstractDoc): def __init__(self, func): super(FunctionDoc, self).__init__(func) diff --git a/doc/build/templates/pydoc.html b/doc/build/templates/pydoc.html index 4fa6e5ca96..34bb5e7bc3 100644 --- a/doc/build/templates/pydoc.html +++ b/doc/build/templates/pydoc.html @@ -83,7 +83,7 @@ def formatdocstring(content): % if isinstance(func, docstring.FunctionDoc): ${function_doc(func=func, toc=toc, extension=extension, paged=paged)} % elif isinstance(func, docstring.PropertyDoc): - ${property_doc(prop=func)} + ${property_doc(prop=func, toc=toc, extension=extension, paged=paged)} % endif % endfor % endif @@ -113,12 +113,12 @@ def formatdocstring(content): -<%def name="property_doc(prop)"> +<%def name="property_doc(prop, toc, extension, paged)">
${prop.name} = property()
- ${prop.doc or '' | formatdocstring} + ${prop.doc or '' | formatdocstring, inline_links(toc, extension, paged)}
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 5083b1cff9..1cea9ffc35 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -399,11 +399,8 @@ class Connectable(sql.Executor): def execute(self, object, *multiparams, **params): raise NotImplementedError() - def _not_impl(self): - raise NotImplementedError() - - engine = property(_not_impl, doc="The Engine which this Connectable is associated with.") - dialect = property(_not_impl, doc="Dialect which this Connectable is associated with.") + engine = util.NotImplProperty("The Engine which this Connectable is associated with.") + dialect = util.NotImplProperty("Dialect which this Connectable is associated with.") class Connection(Connectable): """Represent a single DBAPI connection returned from the underlying connection pool. diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py index f4ece3d6b5..9c327bd53d 100644 --- a/lib/sqlalchemy/sql.py +++ b/lib/sqlalchemy/sql.py @@ -1342,7 +1342,17 @@ class _CompareMixin(object): return obj.type class Selectable(ClauseElement): - """Represent a column list-holding object.""" + """Represent a column list-holding object. + + this is the common base class of [sqlalchemy.sql#ColumnElement] + and [sqlalchemy.sql#FromClause]. The reason ``ColumnElement`` + is marked as a "list-holding" object is so that it can be treated + similarly to ``FromClause`` in column-selection scenarios; it + contains a list of columns consisting of itself. + + """ + + columns = util.NotImplProperty("""a [sqlalchemy.sql#ColumnCollection] containing ``ColumnElement`` instances.""") def _selectable(self): return self @@ -2792,7 +2802,7 @@ class Select(_SelectBaseMixin, FromClause): def append_column(self, column): if _is_literal(column): - column = literal_column(str(column), table=self) + column = literal_column(str(column)) self._raw_columns.append(column) diff --git a/lib/sqlalchemy/util.py b/lib/sqlalchemy/util.py index 08b281684c..d4627974b5 100644 --- a/lib/sqlalchemy/util.py +++ b/lib/sqlalchemy/util.py @@ -127,6 +127,24 @@ class SimpleProperty(object): else: return getattr(obj, self.key) +class NotImplProperty(object): + """a property that raises ``NotImplementedError``.""" + + def __init__(self, doc): + self.__doc__ = doc + + def __set__(self, obj, value): + raise NotImplementedError() + + def __delete__(self, obj): + raise NotImplementedError() + + def __get__(self, obj, owner): + if obj is None: + return self + else: + raise NotImplementedError() + class OrderedProperties(object): """An object that maintains the order in which attributes are set upon it. -- 2.47.2