From: Mike Bayer Date: Fri, 19 Oct 2012 23:20:18 +0000 (-0400) Subject: - rework the sphinx customizations into distinct modules X-Git-Tag: rel_0_8_0b1~45 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=675558bffb3c58647cde2605186dd7d7d7d9e593;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - rework the sphinx customizations into distinct modules - build a new Sphinx extension that allows dialect info to be entered as directives which is then rendered consistently throughout all dialect/dbapi sections - break out the "empty_strings" requirement for oracle test --- diff --git a/CHANGES b/CHANGES index 89f62ffd84..f1301ba281 100644 --- a/CHANGES +++ b/CHANGES @@ -288,9 +288,10 @@ underneath "0.7.xx". without producing history events. [ticket:2582] - [feature] ORM entities can be passed - to select() as well as the select_from(), + to the core select() construct as well + as to the select_from(), correlate(), and correlate_except() - methods, where they will be unwrapped + methods of select(), where they will be unwrapped into selectables. [ticket:2245] - [feature] Some support for auto-rendering of a diff --git a/doc/build/builder/__init__.py b/doc/build/builder/__init__.py index e69de29bb2..0e29e69c46 100644 --- a/doc/build/builder/__init__.py +++ b/doc/build/builder/__init__.py @@ -0,0 +1,12 @@ + + +from . import autodoc_mods, dialect_info, sqlformatter, mako + +def setup(app): + app.add_config_value('release_date', "", True) + app.add_config_value('site_base', "", True) + app.add_config_value('build_number', "", 1) + mako.setup(app) + autodoc_mods.setup(app) + dialect_info.setup(app) + sqlformatter.setup(app) diff --git a/doc/build/builder/autodoc_mods.py b/doc/build/builder/autodoc_mods.py new file mode 100644 index 0000000000..8c687fb3ae --- /dev/null +++ b/doc/build/builder/autodoc_mods.py @@ -0,0 +1,47 @@ +import re + +def autodoc_skip_member(app, what, name, obj, skip, options): + if what == 'class' and skip and \ + name in ('__init__', '__eq__', '__ne__', '__lt__', + '__le__', '__call__') and \ + obj.__doc__: + return False + else: + return skip + +# im sure this is in the app somewhere, but I don't really +# know where, so we're doing it here. +_track_autodoced = {} +def autodoc_process_docstring(app, what, name, obj, options, lines): + if what == "class": + _track_autodoced[name] = obj + elif what in ("attribute", "method") and \ + options.get("inherited-members"): + m = re.match(r'(.*?)\.([\w_]+)$', name) + if m: + clsname, attrname = m.group(1, 2) + if clsname in _track_autodoced: + cls = _track_autodoced[clsname] + for supercls in cls.__mro__: + if attrname in supercls.__dict__: + break + if supercls is not cls: + lines[:0] = [ + ".. container:: inherited_member", + "", + " *inherited from the* :%s:`.%s.%s` *%s of* :class:`.%s`" % ( + "attr" if what == "attribute" + else "meth", + supercls.__name__, + attrname, + what, + supercls.__name__ + ), + "" + ] + + +def setup(app): + app.connect('autodoc-skip-member', autodoc_skip_member) + app.connect('autodoc-process-docstring', autodoc_process_docstring) + diff --git a/doc/build/builder/builders.py b/doc/build/builder/builders.py deleted file mode 100644 index 0776bd475f..0000000000 --- a/doc/build/builder/builders.py +++ /dev/null @@ -1,244 +0,0 @@ -from sphinx.application import TemplateBridge -from sphinx.builders.html import StandaloneHTMLBuilder -from sphinx.highlighting import PygmentsBridge -from sphinx.jinja2glue import BuiltinTemplateLoader -from pygments import highlight -from pygments.lexer import RegexLexer, bygroups, using -from pygments.token import * -from pygments.filter import Filter, apply_filters -from pygments.lexers import PythonLexer, PythonConsoleLexer -from pygments.formatters import HtmlFormatter, LatexFormatter -import re -from mako.lookup import TemplateLookup -from mako.template import Template -from mako import __version__ -import os - -rtd = os.environ.get('READTHEDOCS', None) == 'True' - -class MakoBridge(TemplateBridge): - def init(self, builder, *args, **kw): - self.jinja2_fallback = BuiltinTemplateLoader() - self.jinja2_fallback.init(builder, *args, **kw) - - builder.config.html_context['release_date'] = builder.config['release_date'] - builder.config.html_context['site_base'] = builder.config['site_base'] - - self.lookup = TemplateLookup(directories=builder.config.templates_path, - #format_exceptions=True, - imports=[ - "from builder import util" - ] - ) - - if rtd: - import urllib2 - template_url = builder.config['site_base'] + "/docs_base.mako" - template = urllib2.urlopen(template_url).read() - self.lookup.put_string("/rtd_base.mako", template) - - def render(self, template, context): - template = template.replace(".html", ".mako") - context['prevtopic'] = context.pop('prev', None) - context['nexttopic'] = context.pop('next', None) - version = context['version'] - pathto = context['pathto'] - - # RTD layout - if rtd: - # add variables if not present, such - # as if local test of READTHEDOCS variable - if 'MEDIA_URL' not in context: - context['MEDIA_URL'] = "http://media.readthedocs.org/" - if 'slug' not in context: - context['slug'] = context['project'].lower() - if 'url' not in context: - context['url'] = "/some/test/url" - if 'current_version' not in context: - context['current_version'] = "latest" - - if 'name' not in context: - context['name'] = context['project'].lower() - - context['rtd'] = True - context['toolbar'] = True - context['layout'] = "rtd_layout.mako" - context['base'] = "rtd_base.mako" - context['pdf_url'] = "%spdf/%s/%s/%s.pdf" % ( - context['MEDIA_URL'], - context['slug'], - context['current_version'], - context['slug'] - ) - # local docs layout - else: - context['rtd'] = False - context['toolbar'] = False - context['layout'] = "layout.mako" - context['base'] = "static_base.mako" - - context.setdefault('_', lambda x:x) - return self.lookup.get_template(template).render_unicode(**context) - - def render_string(self, template, context): - # this is used for .js, .css etc. and we don't have - # local copies of that stuff here so use the jinja render. - return self.jinja2_fallback.render_string(template, context) - -class StripDocTestFilter(Filter): - def filter(self, lexer, stream): - for ttype, value in stream: - if ttype is Token.Comment and re.match(r'#\s*doctest:', value): - continue - yield ttype, value - -class PyConWithSQLLexer(RegexLexer): - name = 'PyCon+SQL' - aliases = ['pycon+sql'] - - flags = re.IGNORECASE | re.DOTALL - - tokens = { - 'root': [ - (r'{sql}', Token.Sql.Link, 'sqlpopup'), - (r'{opensql}', Token.Sql.Open, 'opensqlpopup'), - (r'.*?\n', using(PythonConsoleLexer)) - ], - 'sqlpopup':[ - ( - r'(.*?\n)((?:PRAGMA|BEGIN|SELECT|INSERT|DELETE|ROLLBACK|COMMIT|ALTER|UPDATE|CREATE|DROP|PRAGMA|DESCRIBE).*?(?:{stop}\n?|$))', - bygroups(using(PythonConsoleLexer), Token.Sql.Popup), - "#pop" - ) - ], - 'opensqlpopup':[ - ( - r'.*?(?:{stop}\n*|$)', - Token.Sql, - "#pop" - ) - ] - } - - -class PythonWithSQLLexer(RegexLexer): - name = 'Python+SQL' - aliases = ['pycon+sql'] - - flags = re.IGNORECASE | re.DOTALL - - tokens = { - 'root': [ - (r'{sql}', Token.Sql.Link, 'sqlpopup'), - (r'{opensql}', Token.Sql.Open, 'opensqlpopup'), - (r'.*?\n', using(PythonLexer)) - ], - 'sqlpopup':[ - ( - r'(.*?\n)((?:PRAGMA|BEGIN|SELECT|INSERT|DELETE|ROLLBACK|COMMIT|ALTER|UPDATE|CREATE|DROP|PRAGMA|DESCRIBE).*?(?:{stop}\n?|$))', - bygroups(using(PythonLexer), Token.Sql.Popup), - "#pop" - ) - ], - 'opensqlpopup':[ - ( - r'.*?(?:{stop}\n*|$)', - Token.Sql, - "#pop" - ) - ] - } - - -def _strip_trailing_whitespace(iter_): - buf = list(iter_) - if buf: - buf[-1] = (buf[-1][0], buf[-1][1].rstrip()) - for t, v in buf: - yield t, v - -class PopupSQLFormatter(HtmlFormatter): - def _format_lines(self, tokensource): - buf = [] - for ttype, value in apply_filters(tokensource, [StripDocTestFilter()]): - if ttype in Token.Sql: - for t, v in HtmlFormatter._format_lines(self, iter(buf)): - yield t, v - buf = [] - - if ttype is Token.Sql: - yield 1, "
%s
" % re.sub(r'(?:[{stop}|\n]*)$', '', value) - elif ttype is Token.Sql.Link: - yield 1, "sql" - elif ttype is Token.Sql.Popup: - yield 1, "
%s
" % re.sub(r'(?:[{stop}|\n]*)$', '', value) - else: - buf.append((ttype, value)) - - for t, v in _strip_trailing_whitespace(HtmlFormatter._format_lines(self, iter(buf))): - yield t, v - -class PopupLatexFormatter(LatexFormatter): - def _filter_tokens(self, tokensource): - for ttype, value in apply_filters(tokensource, [StripDocTestFilter()]): - if ttype in Token.Sql: - if ttype is not Token.Sql.Link and ttype is not Token.Sql.Open: - yield Token.Literal, re.sub(r'{stop}', '', value) - else: - continue - else: - yield ttype, value - - def format(self, tokensource, outfile): - LatexFormatter.format(self, self._filter_tokens(tokensource), outfile) - -def autodoc_skip_member(app, what, name, obj, skip, options): - if what == 'class' and skip and \ - name in ('__init__', '__eq__', '__ne__', '__lt__', '__le__', '__call__') and \ - obj.__doc__: - return False - else: - return skip - -# im sure this is in the app somewhere, but I don't really -# know where, so we're doing it here. -_track_autodoced = {} -def autodoc_process_docstring(app, what, name, obj, options, lines): - if what == "class": - _track_autodoced[name] = obj - elif what in ("attribute", "method") and \ - options.get("inherited-members"): - m = re.match(r'(.*?)\.([\w_]+)$', name) - if m: - clsname, attrname = m.group(1, 2) - if clsname in _track_autodoced: - cls = _track_autodoced[clsname] - for supercls in cls.__mro__: - if attrname in supercls.__dict__: - break - if supercls is not cls: - lines[:0] = [ - ".. container:: inherited_member", - "", - " *inherited from the* :%s:`.%s.%s` *%s of* :class:`.%s`" % ( - "attr" if what == "attribute" - else "meth", - supercls.__name__, - attrname, - what, - supercls.__name__ - ), - "" - ] - -def setup(app): - app.add_lexer('pycon+sql', PyConWithSQLLexer()) - app.add_lexer('python+sql', PythonWithSQLLexer()) - app.add_config_value('release_date', "", True) - app.add_config_value('site_base', "", True) - app.add_config_value('build_number', "", 1) - app.connect('autodoc-skip-member', autodoc_skip_member) - app.connect('autodoc-process-docstring', autodoc_process_docstring) - PygmentsBridge.html_formatter = PopupSQLFormatter - PygmentsBridge.latex_formatter = PopupLatexFormatter - diff --git a/doc/build/builder/dialect_info.py b/doc/build/builder/dialect_info.py new file mode 100644 index 0000000000..808b3cdf43 --- /dev/null +++ b/doc/build/builder/dialect_info.py @@ -0,0 +1,175 @@ +import re +from sphinx.util.compat import Directive +from docutils import nodes + +class DialectDirective(Directive): + has_content = True + + _dialects = {} + + def _parse_content(self): + d = {} + d['default'] = self.content[0] + d['text'] = [] + idx = 0 + for line in self.content[1:]: + idx += 1 + m = re.match(r'\:(.+?)\: +(.+)', line) + if m: + attrname, value = m.group(1, 2) + d[attrname] = value + else: + break + d["text"] = self.content[idx + 1:] + return d + + def _dbapi_node(self): + + dialect_name, dbapi_name = self.dialect_name.split("+") + + try: + dialect_directive = self._dialects[dialect_name] + except KeyError: + raise Exception("No .. dialect:: %s directive has been established" + % dialect_name) + + output = [] + + content = self._parse_content() + + parent_section_ref = self.state.parent.children[0]['ids'][0] + self._append_dbapi_bullet(dialect_name, dbapi_name, + content['name'], parent_section_ref) + + p = nodes.paragraph('', '', + nodes.Text( + "Support for the %s database via the %s driver." % ( + dialect_directive.database_name, + content['name'] + ), + "Support for the %s database via the %s driver." % ( + dialect_directive.database_name, + content['name'] + ) + ), + ) + + self.state.nested_parse(content['text'], 0, p) + output.append(p) + + if "url" in content or "driverurl" in content: + sec = nodes.section( + '', + nodes.title("DBAPI", "DBAPI"), + ids=["dialect-%s-%s-url" % (dialect_name, dbapi_name)] + ) + if "url" in content: + text = "%s is available at:\n" % dbapi_name + uri = content['url'] + sec.append( + nodes.paragraph('', '', + nodes.Text(text, text), + nodes.reference('', '', + nodes.Text(uri, uri), + refuri=uri, + ) + ) + ) + if "driverurl" in content: + text = "Drivers for this database are available at:\n" + sec.append( + nodes.paragraph('', '', + nodes.Text(text, text), + nodes.reference('', '', + nodes.Text(content['driverurl'], content['driverurl']), + refuri=content['driverurl'] + ) + ) + ) + output.append(sec) + + + if "connectstring" in content: + # TODO: wish I knew how to just embed RST here and parse it into + # nodes + sec = nodes.section( + '', + nodes.title("Connecting", "Connecting"), + nodes.paragraph('', '', + nodes.Text("Connect String:", "Connect String:"), + nodes.literal_block(content['connectstring'], + content['connectstring']) + ), + ids=["dialect-%s-%s-connect" % (dialect_name, dbapi_name)] + ) + output.append(sec) + + return output + + def _dialect_node(self): + self._dialects[self.dialect_name] = self + + content = self._parse_content() + self.database_name = content['name'] + + self.bullets = nodes.bullet_list() + text = "The following dialect/DBAPI options are available. "\ + "Please refer to individual DBAPI sections for connect information." + sec = nodes.section('', + nodes.paragraph('', '', + nodes.Text( + "Support for the %s database." % content['name'], + "Support for the %s database." % content['name'] + ), + ), + nodes.title("DBAPI Support", "DBAPI Support"), + nodes.paragraph('', '', + nodes.Text(text, text), + self.bullets + ), + ids=["dialect-%s" % self.dialect_name] + ) + + return [sec] + + def _append_dbapi_bullet(self, dialect_name, dbapi_name, name, idname): + env = self.state.document.settings.env + dialect_directive = self._dialects[dialect_name] + + list_node = nodes.list_item('', + nodes.paragraph('', '', + nodes.reference('', '', + nodes.Text(name, name), + refdocname=self.docname, + refuri=env.app.builder.get_relative_uri( + dialect_directive.docname, self.docname) + + "#" + idname + ), + #nodes.Text(" ", " "), + #nodes.reference('', '', + # nodes.Text("(connectstring)", "(connectstring)"), + # refdocname=self.docname, + # refuri=env.app.builder.get_relative_uri( + # dialect_directive.docname, self.docname) + + ## "#" + ("dialect-%s-%s-connect" % + # (dialect_name, dbapi_name)) + # ) + ) + ) + dialect_directive.bullets.append(list_node) + + def run(self): + env = self.state.document.settings.env + self.docname = env.docname + + self.dialect_name = dialect_name = self.content[0] + + has_dbapi = "+" in dialect_name + if has_dbapi: + return self._dbapi_node() + else: + return self._dialect_node() + +def setup(app): + app.add_directive('dialect', DialectDirective) + diff --git a/doc/build/builder/mako.py b/doc/build/builder/mako.py new file mode 100644 index 0000000000..0a69551882 --- /dev/null +++ b/doc/build/builder/mako.py @@ -0,0 +1,79 @@ +from __future__ import absolute_import + +from sphinx.application import TemplateBridge +from sphinx.jinja2glue import BuiltinTemplateLoader +from mako.lookup import TemplateLookup +import os + +rtd = os.environ.get('READTHEDOCS', None) == 'True' + +class MakoBridge(TemplateBridge): + def init(self, builder, *args, **kw): + self.jinja2_fallback = BuiltinTemplateLoader() + self.jinja2_fallback.init(builder, *args, **kw) + + builder.config.html_context['release_date'] = builder.config['release_date'] + builder.config.html_context['site_base'] = builder.config['site_base'] + + self.lookup = TemplateLookup(directories=builder.config.templates_path, + #format_exceptions=True, + imports=[ + "from builder import util" + ] + ) + + if rtd: + import urllib2 + template_url = builder.config['site_base'] + "/docs_base.mako" + template = urllib2.urlopen(template_url).read() + self.lookup.put_string("/rtd_base.mako", template) + + def render(self, template, context): + template = template.replace(".html", ".mako") + context['prevtopic'] = context.pop('prev', None) + context['nexttopic'] = context.pop('next', None) + + # RTD layout + if rtd: + # add variables if not present, such + # as if local test of READTHEDOCS variable + if 'MEDIA_URL' not in context: + context['MEDIA_URL'] = "http://media.readthedocs.org/" + if 'slug' not in context: + context['slug'] = context['project'].lower() + if 'url' not in context: + context['url'] = "/some/test/url" + if 'current_version' not in context: + context['current_version'] = "latest" + + if 'name' not in context: + context['name'] = context['project'].lower() + + context['rtd'] = True + context['toolbar'] = True + context['layout'] = "rtd_layout.mako" + context['base'] = "rtd_base.mako" + context['pdf_url'] = "%spdf/%s/%s/%s.pdf" % ( + context['MEDIA_URL'], + context['slug'], + context['current_version'], + context['slug'] + ) + # local docs layout + else: + context['rtd'] = False + context['toolbar'] = False + context['layout'] = "layout.mako" + context['base'] = "static_base.mako" + + context.setdefault('_', lambda x: x) + return self.lookup.get_template(template).render_unicode(**context) + + def render_string(self, template, context): + # this is used for .js, .css etc. and we don't have + # local copies of that stuff here so use the jinja render. + return self.jinja2_fallback.render_string(template, context) + +def setup(app): + app.config['template_bridge'] = "builder.mako.MakoBridge" + diff --git a/doc/build/builder/sqlformatter.py b/doc/build/builder/sqlformatter.py new file mode 100644 index 0000000000..2d80749000 --- /dev/null +++ b/doc/build/builder/sqlformatter.py @@ -0,0 +1,132 @@ +from pygments.lexer import RegexLexer, bygroups, using +from pygments.token import Token +from pygments.filter import Filter +from pygments.filter import apply_filters +from pygments.lexers import PythonLexer, PythonConsoleLexer +from sphinx.highlighting import PygmentsBridge +from pygments.formatters import HtmlFormatter, LatexFormatter + +import re + + +def _strip_trailing_whitespace(iter_): + buf = list(iter_) + if buf: + buf[-1] = (buf[-1][0], buf[-1][1].rstrip()) + for t, v in buf: + yield t, v + + +class StripDocTestFilter(Filter): + def filter(self, lexer, stream): + for ttype, value in stream: + if ttype is Token.Comment and re.match(r'#\s*doctest:', value): + continue + yield ttype, value + +class PyConWithSQLLexer(RegexLexer): + name = 'PyCon+SQL' + aliases = ['pycon+sql'] + + flags = re.IGNORECASE | re.DOTALL + + tokens = { + 'root': [ + (r'{sql}', Token.Sql.Link, 'sqlpopup'), + (r'{opensql}', Token.Sql.Open, 'opensqlpopup'), + (r'.*?\n', using(PythonConsoleLexer)) + ], + 'sqlpopup': [ + ( + r'(.*?\n)((?:PRAGMA|BEGIN|SELECT|INSERT|DELETE|ROLLBACK|' + 'COMMIT|ALTER|UPDATE|CREATE|DROP|PRAGMA' + '|DESCRIBE).*?(?:{stop}\n?|$))', + bygroups(using(PythonConsoleLexer), Token.Sql.Popup), + "#pop" + ) + ], + 'opensqlpopup': [ + ( + r'.*?(?:{stop}\n*|$)', + Token.Sql, + "#pop" + ) + ] + } + + +class PythonWithSQLLexer(RegexLexer): + name = 'Python+SQL' + aliases = ['pycon+sql'] + + flags = re.IGNORECASE | re.DOTALL + + tokens = { + 'root': [ + (r'{sql}', Token.Sql.Link, 'sqlpopup'), + (r'{opensql}', Token.Sql.Open, 'opensqlpopup'), + (r'.*?\n', using(PythonLexer)) + ], + 'sqlpopup': [ + ( + r'(.*?\n)((?:PRAGMA|BEGIN|SELECT|INSERT|DELETE|ROLLBACK' + '|COMMIT|ALTER|UPDATE|CREATE|DROP' + '|PRAGMA|DESCRIBE).*?(?:{stop}\n?|$))', + bygroups(using(PythonLexer), Token.Sql.Popup), + "#pop" + ) + ], + 'opensqlpopup': [ + ( + r'.*?(?:{stop}\n*|$)', + Token.Sql, + "#pop" + ) + ] + } + +class PopupSQLFormatter(HtmlFormatter): + def _format_lines(self, tokensource): + buf = [] + for ttype, value in apply_filters(tokensource, [StripDocTestFilter()]): + if ttype in Token.Sql: + for t, v in HtmlFormatter._format_lines(self, iter(buf)): + yield t, v + buf = [] + + if ttype is Token.Sql: + yield 1, "
%s
" % \ + re.sub(r'(?:[{stop}|\n]*)$', '', value) + elif ttype is Token.Sql.Link: + yield 1, "sql" + elif ttype is Token.Sql.Popup: + yield 1, "
%s
" % \ + re.sub(r'(?:[{stop}|\n]*)$', '', value) + else: + buf.append((ttype, value)) + + for t, v in _strip_trailing_whitespace( + HtmlFormatter._format_lines(self, iter(buf))): + yield t, v + +class PopupLatexFormatter(LatexFormatter): + def _filter_tokens(self, tokensource): + for ttype, value in apply_filters(tokensource, [StripDocTestFilter()]): + if ttype in Token.Sql: + if ttype is not Token.Sql.Link and ttype is not Token.Sql.Open: + yield Token.Literal, re.sub(r'{stop}', '', value) + else: + continue + else: + yield ttype, value + + def format(self, tokensource, outfile): + LatexFormatter.format(self, self._filter_tokens(tokensource), outfile) + +def setup(app): + app.add_lexer('pycon+sql', PyConWithSQLLexer()) + app.add_lexer('python+sql', PythonWithSQLLexer()) + + PygmentsBridge.html_formatter = PopupSQLFormatter + PygmentsBridge.latex_formatter = PopupLatexFormatter + diff --git a/doc/build/conf.py b/doc/build/conf.py index 9079232d51..73cd47e6be 100644 --- a/doc/build/conf.py +++ b/doc/build/conf.py @@ -30,10 +30,10 @@ import sqlalchemy # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. #extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', -# 'sphinx.ext.doctest', 'builder.builders'] +# 'sphinx.ext.doctest', 'builder'] extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.doctest', 'builder.builders'] + 'sphinx.ext.doctest', 'builder'] # Add any paths that contain templates here, relative to this directory. # not sure why abspath() is needed here, some users @@ -45,7 +45,6 @@ nitpicky = True # The suffix of source filenames. source_suffix = '.rst' -template_bridge = "builder.builders.MakoBridge" # The encoding of source files. #source_encoding = 'utf-8-sig' diff --git a/doc/build/dialects/drizzle.rst b/doc/build/dialects/drizzle.rst index ec0af93ce0..99ff596d7f 100644 --- a/doc/build/dialects/drizzle.rst +++ b/doc/build/dialects/drizzle.rst @@ -70,9 +70,7 @@ construction arguments, are as follows: :show-inheritance: -.. _drizzle_mysqldb: - -MySQL-Python Notes --------------------- +MySQL-Python +------------ .. automodule:: sqlalchemy.dialects.drizzle.mysqldb diff --git a/doc/build/dialects/firebird.rst b/doc/build/dialects/firebird.rst index 2ec0103eff..d5b6b2ffdd 100644 --- a/doc/build/dialects/firebird.rst +++ b/doc/build/dialects/firebird.rst @@ -5,8 +5,6 @@ Firebird .. automodule:: sqlalchemy.dialects.firebird.base -.. _kinterbasdb: - kinterbasdb ----------- diff --git a/doc/build/dialects/informix.rst b/doc/build/dialects/informix.rst index 12eaa04381..f37ae6cf56 100644 --- a/doc/build/dialects/informix.rst +++ b/doc/build/dialects/informix.rst @@ -5,7 +5,7 @@ Informix .. automodule:: sqlalchemy.dialects.informix.base -informixdb Notes --------------------- +informixdb +---------- .. automodule:: sqlalchemy.dialects.informix.informixdb \ No newline at end of file diff --git a/doc/build/dialects/mssql.rst b/doc/build/dialects/mssql.rst index f969983328..615d1a11dd 100644 --- a/doc/build/dialects/mssql.rst +++ b/doc/build/dialects/mssql.rst @@ -19,7 +19,7 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: SMALLINT, SMALLMONEY, SQL_VARIANT, TEXT, TIME, \ TIMESTAMP, TINYINT, UNIQUEIDENTIFIER, VARBINARY, VARCHAR -Types which are specific to SQL Server, or have SQL Server-specific +Types which are specific to SQL Server, or have SQL Server-specific construction arguments, are as follows: .. currentmodule:: sqlalchemy.dialects.mssql @@ -109,7 +109,7 @@ pymssql ------- .. automodule:: sqlalchemy.dialects.mssql.pymssql -zxjdbc Notes +zxjdbc -------------- .. automodule:: sqlalchemy.dialects.mssql.zxjdbc diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst index 2110e375af..b5119f23fb 100644 --- a/doc/build/dialects/mysql.rst +++ b/doc/build/dialects/mysql.rst @@ -155,50 +155,36 @@ construction arguments, are as follows: :members: __init__ :show-inheritance: -.. _mysqldb: - MySQL-Python -------------------- .. automodule:: sqlalchemy.dialects.mysql.mysqldb -.. _oursql: - OurSQL -------------- .. automodule:: sqlalchemy.dialects.mysql.oursql -.. _pymysql: - pymysql ------------- .. automodule:: sqlalchemy.dialects.mysql.pymysql -.. _mysqlconnector: - MySQL-Connector ---------------------- .. automodule:: sqlalchemy.dialects.mysql.mysqlconnector -.. _gaerdbms: - Google App Engine ----------------------- .. automodule:: sqlalchemy.dialects.mysql.gaerdbms -.. _mysql_pyodbc: - pyodbc --------------- +------ .. automodule:: sqlalchemy.dialects.mysql.pyodbc -.. _mysql_zxjdbc: - zxjdbc -------------- diff --git a/doc/build/dialects/oracle.rst b/doc/build/dialects/oracle.rst index 5e259ead76..4be8c5b513 100644 --- a/doc/build/dialects/oracle.rst +++ b/doc/build/dialects/oracle.rst @@ -18,7 +18,7 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: NUMBER, NVARCHAR, NVARCHAR2, RAW, TIMESTAMP, VARCHAR, \ VARCHAR2 -Types which are specific to Oracle, or have Oracle-specific +Types which are specific to Oracle, or have Oracle-specific construction arguments, are as follows: .. currentmodule:: sqlalchemy.dialects.oracle @@ -51,12 +51,12 @@ construction arguments, are as follows: :members: __init__ :show-inheritance: -cx_Oracle Notes ---------------- +cx_Oracle +---------- .. automodule:: sqlalchemy.dialects.oracle.cx_oracle -zxjdbc Notes --------------- +zxjdbc +------- .. automodule:: sqlalchemy.dialects.oracle.zxjdbc diff --git a/doc/build/dialects/postgresql.rst b/doc/build/dialects/postgresql.rst index cf6f277f56..55705a037a 100644 --- a/doc/build/dialects/postgresql.rst +++ b/doc/build/dialects/postgresql.rst @@ -76,23 +76,16 @@ psycopg2 .. automodule:: sqlalchemy.dialects.postgresql.psycopg2 - -.. _pypostgresql: - py-postgresql -------------------- .. automodule:: sqlalchemy.dialects.postgresql.pypostgresql -.. _pg8000: - pg8000 -------------- .. automodule:: sqlalchemy.dialects.postgresql.pg8000 -.. _zxjdbc: - zxjdbc -------------- diff --git a/doc/build/dialects/sybase.rst b/doc/build/dialects/sybase.rst index 8200f223dc..8e9695325a 100644 --- a/doc/build/dialects/sybase.rst +++ b/doc/build/dialects/sybase.rst @@ -5,17 +5,17 @@ Sybase .. automodule:: sqlalchemy.dialects.sybase.base -python-sybase notes +python-sybase ------------------- .. automodule:: sqlalchemy.dialects.sybase.pysybase -pyodbc notes +pyodbc ------------ .. automodule:: sqlalchemy.dialects.sybase.pyodbc -mxodbc notes +mxodbc ------------ .. automodule:: sqlalchemy.dialects.sybase.mxodbc diff --git a/lib/sqlalchemy/dialects/drizzle/base.py b/lib/sqlalchemy/dialects/drizzle/base.py index d32240c382..2b5df38601 100644 --- a/lib/sqlalchemy/dialects/drizzle/base.py +++ b/lib/sqlalchemy/dialects/drizzle/base.py @@ -6,7 +6,10 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the Drizzle database. +""" + +.. dialect:: drizzle + :name: Drizzle Drizzle is a variant of MySQL. Unlike MySQL, Drizzle's default storage engine is InnoDB (transactions, foreign-keys) rather than MyISAM. For more @@ -16,14 +19,6 @@ the `Drizzle Documentation `_. The SQLAlchemy Drizzle dialect leans heavily on the MySQL dialect, so much of the :doc:`SQLAlchemy MySQL ` documentation is also relevant. -DBAPI Support -------------- - -The following dialect/driver options are available: - -``drizzle://``- uses mysqldb_ - -``drizzle+mysqldb://`` - uses mysqldb_ """ diff --git a/lib/sqlalchemy/dialects/drizzle/mysqldb.py b/lib/sqlalchemy/dialects/drizzle/mysqldb.py index ce9518a811..7d91cc368b 100644 --- a/lib/sqlalchemy/dialects/drizzle/mysqldb.py +++ b/lib/sqlalchemy/dialects/drizzle/mysqldb.py @@ -1,15 +1,10 @@ -"""Support for the Drizzle database via the mysql-python adapter. - -MySQL-Python is available at: - - http://sourceforge.net/projects/mysql-python - -Connecting ------------ - -Connect string format:: +""" +.. dialect:: drizzle+mysqldb + :name: MySQL-Python + :dbapi: mysqldb + :connectstring: drizzle+mysqldb://:@[:]/ + :url: http://sourceforge.net/projects/mysql-python - drizzle+mysqldb://:@[:]/ """ diff --git a/lib/sqlalchemy/dialects/firebird/base.py b/lib/sqlalchemy/dialects/firebird/base.py index b990400389..df20060e58 100644 --- a/lib/sqlalchemy/dialects/firebird/base.py +++ b/lib/sqlalchemy/dialects/firebird/base.py @@ -5,18 +5,9 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -Support for the Firebird database. -DBAPI Support -------------- - -The following dialect/driver options are available: - -``firebird://``- uses kinterbasdb_ - -``firebird+kinterbasdb://`` - uses kinterbasdb_ - -``firebird+fdb://`` - uses fdb_ +.. dialect:: firebird + :name: Firebird Firebird Dialects ----------------- diff --git a/lib/sqlalchemy/dialects/firebird/fdb.py b/lib/sqlalchemy/dialects/firebird/fdb.py index 3601b391b1..aac3579d6f 100644 --- a/lib/sqlalchemy/dialects/firebird/fdb.py +++ b/lib/sqlalchemy/dialects/firebird/fdb.py @@ -5,21 +5,15 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -fdb is a kinterbasdb compatible DBAPI for Firebird. +.. dialect:: firebird+fdb + :name: fdb + :dbapi: pyodbc + :connectstring: firebird+fdb://user:password@host:port/path/to/db[?key=value&key=value...] + :url: http://pypi.python.org/pypi/fdb/ -.. versionadded:: 0.8 - Support for the fdb Firebird driver. + fdb is a kinterbasdb compatible DBAPI for Firebird. -DBAPI ------ - -http://pypi.python.org/pypi/fdb/ - -Connecting ------------ - -Connect string format:: - - firebird+fdb://user:password@host:port/path/to/db[?key=value&key=value...] + .. versionadded:: 0.8 - Support for the fdb Firebird driver. Status ------ diff --git a/lib/sqlalchemy/dialects/firebird/kinterbasdb.py b/lib/sqlalchemy/dialects/firebird/kinterbasdb.py index 78fffd6471..90fadde50b 100644 --- a/lib/sqlalchemy/dialects/firebird/kinterbasdb.py +++ b/lib/sqlalchemy/dialects/firebird/kinterbasdb.py @@ -5,18 +5,11 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ - -DBAPI ------ - -http://firebirdsql.org/index.php?op=devel&sub=python - -Connecting ------------ - -Connect string format:: - - firebird+kinterbasdb://user:password@host:port/path/to/db[?key=value&key=value...] +.. dialect:: firebird+kinterbasdb + :name: kinterbasdb + :dbapi: kinterbasdb + :connectstring: firebird+kinterbasdb://user:password@host:port/path/to/db[?key=value&key=value...] + :url: http://firebirdsql.org/index.php?op=devel&sub=python Arguments ---------- diff --git a/lib/sqlalchemy/dialects/informix/base.py b/lib/sqlalchemy/dialects/informix/base.py index eff563a1d1..f54bf6d37b 100644 --- a/lib/sqlalchemy/dialects/informix/base.py +++ b/lib/sqlalchemy/dialects/informix/base.py @@ -5,7 +5,9 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the Informix database. +""" +.. dialect:: informix + :name: Informix .. note:: diff --git a/lib/sqlalchemy/dialects/informix/informixdb.py b/lib/sqlalchemy/dialects/informix/informixdb.py index b771e15017..474bc5f11b 100644 --- a/lib/sqlalchemy/dialects/informix/informixdb.py +++ b/lib/sqlalchemy/dialects/informix/informixdb.py @@ -5,18 +5,12 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -Support for the informixdb DBAPI. -informixdb is available at: - - http://informixdb.sourceforge.net/ - -Connecting -^^^^^^^^^^ - -Sample informix connection:: - - engine = create_engine('informix+informixdb://user:password@host/dbname') +.. dialect:: informix+informixdb + :name: informixdb + :dbapi: informixdb + :connectstring: informix+informixdb://user:password@host/dbname + :url: http://informixdb.sourceforge.net/ """ diff --git a/lib/sqlalchemy/dialects/mssql/adodbapi.py b/lib/sqlalchemy/dialects/mssql/adodbapi.py index 5b23282692..747ea17db7 100644 --- a/lib/sqlalchemy/dialects/mssql/adodbapi.py +++ b/lib/sqlalchemy/dialects/mssql/adodbapi.py @@ -5,7 +5,16 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -The adodbapi dialect is not implemented for 0.6 at this time. +.. dialect:: mssql+adodbapi + :name: adodbapi + :dbapi: adodbapi + :connectstring: mssql+adodbapi://:@ + :url: http://adodbapi.sourceforge.net/ + +.. note:: + + The adodbapi dialect is not implemented SQLAlchemy versions 0.6 and + above at this time. """ import datetime diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py index e8f0385b4a..51884247f9 100644 --- a/lib/sqlalchemy/dialects/mssql/base.py +++ b/lib/sqlalchemy/dialects/mssql/base.py @@ -4,7 +4,9 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the Microsoft SQL Server database. +""" +.. dialect:: mssql + :name: Microsoft SQL Server Auto Increment Behavior diff --git a/lib/sqlalchemy/dialects/mssql/mxodbc.py b/lib/sqlalchemy/dialects/mssql/mxodbc.py index 4e0af2d396..91922a442a 100644 --- a/lib/sqlalchemy/dialects/mssql/mxodbc.py +++ b/lib/sqlalchemy/dialects/mssql/mxodbc.py @@ -5,24 +5,14 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -Support for MS-SQL via mxODBC. - -mxODBC is available at: - - http://www.egenix.com/ - -This was tested with mxODBC 3.1.2 and the SQL Server Native -Client connected to MSSQL 2005 and 2008 Express Editions. - -Connecting -~~~~~~~~~~ - -Connection is via DSN:: - - mssql+mxodbc://:@ +.. dialect:: mssql+mxodbc + :name: mxODBC + :dbapi: mxodbc + :connectstring: mssql+mxodbc://:@ + :url: http://www.egenix.com/ Execution Modes -~~~~~~~~~~~~~~~ +--------------- mxODBC features two styles of statement execution, using the ``cursor.execute()`` and ``cursor.executedirect()`` methods (the second being diff --git a/lib/sqlalchemy/dialects/mssql/pymssql.py b/lib/sqlalchemy/dialects/mssql/pymssql.py index 96b1511bd7..881893422b 100644 --- a/lib/sqlalchemy/dialects/mssql/pymssql.py +++ b/lib/sqlalchemy/dialects/mssql/pymssql.py @@ -5,28 +5,14 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -Support for the pymssql dialect. - -This dialect supports pymssql 1.0 and greater. - -pymssql is available at: - - http://pymssql.sourceforge.net/ - -Connecting -^^^^^^^^^^ - -Sample connect string:: - - mssql+pymssql://:@ - -Adding "?charset=utf8" or similar will cause pymssql to return -strings as Python unicode objects. This can potentially improve -performance in some scenarios as decoding of strings is -handled natively. +.. dialect:: mssql+pymssql + :name: pymssql + :dbapi: pymssql + :connectstring: mssql+pymssql://:@?charset=utf8 + :url: http://pymssql.sourceforge.net/ Limitations -^^^^^^^^^^^ +----------- pymssql inherits a lot of limitations from FreeTDS, including: diff --git a/lib/sqlalchemy/dialects/mssql/pyodbc.py b/lib/sqlalchemy/dialects/mssql/pyodbc.py index 10149689af..47a4851b00 100644 --- a/lib/sqlalchemy/dialects/mssql/pyodbc.py +++ b/lib/sqlalchemy/dialects/mssql/pyodbc.py @@ -5,14 +5,14 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -Support for MS-SQL via pyodbc. +.. dialect:: mssql+pyodbc + :name: PyODBC + :dbapi: pyodbc + :connectstring: mssql+pyodbc://:@ + :url: http://pypi.python.org/pypi/pyodbc/ -pyodbc is available at: - - http://pypi.python.org/pypi/pyodbc/ - -Connecting -^^^^^^^^^^ +Additional Connection Examples +------------------------------- Examples of pyodbc connection string URLs: @@ -81,7 +81,7 @@ the python shell. For example:: 'dsn%3Dmydsn%3BDatabase%3Ddb' Unicode Binds -^^^^^^^^^^^^^ +------------- The current state of PyODBC on a unix backend with FreeTDS and/or EasySoft is poor regarding unicode; different OS platforms and versions of UnixODBC diff --git a/lib/sqlalchemy/dialects/mssql/zxjdbc.py b/lib/sqlalchemy/dialects/mssql/zxjdbc.py index 38deacfd6b..1b36075b07 100644 --- a/lib/sqlalchemy/dialects/mssql/zxjdbc.py +++ b/lib/sqlalchemy/dialects/mssql/zxjdbc.py @@ -4,24 +4,13 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the Microsoft SQL Server database via the zxjdbc JDBC -connector. - -JDBC Driver ------------ - -Requires the jTDS driver, available from: http://jtds.sourceforge.net/ - -Connecting ----------- - -URLs are of the standard form of -``mssql+zxjdbc://user:pass@host:port/dbname[?key=value&key=value...]``. +""" +.. dialect:: mssql+zxjdbc + :name: zxJDBC for Jython + :dbapi: zxjdbc + :connectstring: mssql+zxjdbc://user:pass@host:port/dbname[?key=value&key=value...] + :driverurl: http://jtds.sourceforge.net/ -Additional arguments which may be specified either as query string -arguments on the URL, or as keyword arguments to -:func:`~sqlalchemy.create_engine()` will be passed as Connection -properties to the underlying JDBC driver. """ from ...connectors.zxJDBC import ZxJDBCConnector diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index 7f67d78261..92c6f58a0a 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -4,27 +4,10 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the MySQL database. - -DBAPI Support -------------- - -The following dialect/driver options are available: - -* :ref:`mysqldb` - -* :ref:`mysqlconnector` - -* :ref:`oursql` - -* :ref:`gaerdbms` - -* :ref:`pymysql` - -* :ref:`mysql_pyodbc` - -* :ref:`mysql_zxjdbc` +""" +.. dialect:: mysql + :name: MySQL Supported Versions and Features ------------------------------- @@ -55,11 +38,6 @@ Nested Transactions 5.0.3 See the official MySQL documentation for detailed information about features supported in any given server release. -Connecting ----------- - -See the API documentation on individual drivers for details on connecting. - Connection Timeouts ------------------- diff --git a/lib/sqlalchemy/dialects/mysql/gaerdbms.py b/lib/sqlalchemy/dialects/mysql/gaerdbms.py index 29a67a540b..66180e233a 100644 --- a/lib/sqlalchemy/dialects/mysql/gaerdbms.py +++ b/lib/sqlalchemy/dialects/mysql/gaerdbms.py @@ -3,29 +3,18 @@ # # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for Google Cloud SQL on Google App Engine. - -This dialect is based primarily on the :mod:`.mysql.mysqldb` dialect with minimal -changes. - -.. versionadded:: 0.7.8 - -DBAPI ------ - - https://developers.google.com/appengine/docs/python/cloud-sql/developers-guide - -Connecting ----------- - -Connect string format:: +""" +.. dialect:: mysql+gaerdbms + :name: Google Cloud SQL + :dbapi: rdbms + :connectstring: mysql+gaerdbms:///?instance=instancename + :url: https://developers.google.com/appengine/docs/python/cloud-sql/developers-guide - mysql+gaerdbms:/// + This dialect is based primarily on the :mod:`.mysql.mysqldb` dialect with minimal + changes. -E.g.:: + .. versionadded:: 0.7.8 - create_engine('mysql+gaerdbms:///mydb', - connect_args={"instance":"instancename"}) Pooling ------- diff --git a/lib/sqlalchemy/dialects/mysql/mysqlconnector.py b/lib/sqlalchemy/dialects/mysql/mysqlconnector.py index ea8d9322c0..82d9067855 100644 --- a/lib/sqlalchemy/dialects/mysql/mysqlconnector.py +++ b/lib/sqlalchemy/dialects/mysql/mysqlconnector.py @@ -4,21 +4,13 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the MySQL database via the MySQL Connector/Python adapter. - -DBAPI ------ - -MySQL Connector/Python is available at: - - https://launchpad.net/myconnpy - -Connecting ------------ - -Connect string format:: +""" +.. dialect:: mysql+mysqlconnector + :name: MySQL Connector/Python + :dbapi: myconnpy + :connectstring: mysql+mysqlconnector://:@[:]/ + :url: https://launchpad.net/myconnpy - mysql+mysqlconnector://:@[:]/ """ diff --git a/lib/sqlalchemy/dialects/mysql/mysqldb.py b/lib/sqlalchemy/dialects/mysql/mysqldb.py index add0c00ee8..7385f6e60d 100644 --- a/lib/sqlalchemy/dialects/mysql/mysqldb.py +++ b/lib/sqlalchemy/dialects/mysql/mysqldb.py @@ -4,21 +4,14 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the MySQL database via the MySQL-python adapter. - -DBAPI ------ - -MySQL-Python is available at: - - http://sourceforge.net/projects/mysql-python - -Connecting ------------ +""" -Connect string format:: +.. dialect:: mysql+mysqldb + :name: MySQL-Python + :dbapi: mysqldb + :connectstring: mysql+mysqldb://:@[:]/ + :url: http://sourceforge.net/projects/mysql-python - mysql+mysqldb://:@[:]/ Unicode ------- diff --git a/lib/sqlalchemy/dialects/mysql/oursql.py b/lib/sqlalchemy/dialects/mysql/oursql.py index ca713a068f..cc4e3b5f23 100644 --- a/lib/sqlalchemy/dialects/mysql/oursql.py +++ b/lib/sqlalchemy/dialects/mysql/oursql.py @@ -4,21 +4,13 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the MySQL database via the oursql adapter. - -DBAPI ------ - -OurSQL is available at: - - http://packages.python.org/oursql/ - -Connecting ------------ - -Connect string format:: +""" - mysql+oursql://:@[:]/ +.. dialect:: mysql+oursql + :name: OurSQL + :dbapi: oursql + :connectstring: mysql+oursql://:@[:]/ + :url: http://packages.python.org/oursql/ Unicode ------- diff --git a/lib/sqlalchemy/dialects/mysql/pymysql.py b/lib/sqlalchemy/dialects/mysql/pymysql.py index b6f2d4384f..36b49ba3b8 100644 --- a/lib/sqlalchemy/dialects/mysql/pymysql.py +++ b/lib/sqlalchemy/dialects/mysql/pymysql.py @@ -4,21 +4,13 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the MySQL database via the pymysql adapter. - -DBAPI ------ - -pymysql is available at: - - http://code.google.com/p/pymysql/ - -Connecting ----------- - -Connect string:: +""" - mysql+pymysql://:@/[?] +.. dialect:: mysql+pymysql + :name: PyMySQL + :dbapi: pymysql + :connectstring: mysql+pymysql://:@/[?] + :url: http://code.google.com/p/pymysql/ MySQL-Python Compatibility -------------------------- diff --git a/lib/sqlalchemy/dialects/mysql/pyodbc.py b/lib/sqlalchemy/dialects/mysql/pyodbc.py index 20cc53be7f..2736ef7a4b 100644 --- a/lib/sqlalchemy/dialects/mysql/pyodbc.py +++ b/lib/sqlalchemy/dialects/mysql/pyodbc.py @@ -4,21 +4,15 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the MySQL database via the pyodbc adapter. - -DBAPI ------ - -pyodbc is available at: - - http://pypi.python.org/pypi/pyodbc/ +""" -Connecting ----------- -Connect string:: +.. dialect:: mysql+pyodbc + :name: PyODBC + :dbapi: pyodbc + :connectstring: mysql+pyodbc://:@ + :url: http://pypi.python.org/pypi/pyodbc/ - mysql+pyodbc://:@ Limitations ----------- diff --git a/lib/sqlalchemy/dialects/mysql/zxjdbc.py b/lib/sqlalchemy/dialects/mysql/zxjdbc.py index 82e7dca8d0..955044a587 100644 --- a/lib/sqlalchemy/dialects/mysql/zxjdbc.py +++ b/lib/sqlalchemy/dialects/mysql/zxjdbc.py @@ -4,20 +4,13 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the MySQL database via Jython's zxjdbc JDBC connector. - -DBAPI ------ - -The official MySQL JDBC driver is at -http://dev.mysql.com/downloads/connector/j/. - -Connecting ----------- - -Connect string:: +""" - mysql+zxjdbc://:@[:]/ +.. dialect:: mysql+zxjdbc + :name: zxjdbc for Jython + :dbapi: zxjdbc + :connectstring: mysql+zxjdbc://:@[:]/ + :driverurl: http://dev.mysql.com/downloads/connector/j/ Character Sets -------------- diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py index ee4a82115c..7b1470f636 100644 --- a/lib/sqlalchemy/dialects/oracle/base.py +++ b/lib/sqlalchemy/dialects/oracle/base.py @@ -4,9 +4,11 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the Oracle database. +""" +.. dialect:: oracle + :name: Oracle -Oracle version 8 through current (11g at the time of this writing) are supported. + Oracle version 8 through current (11g at the time of this writing) are supported. Connect Arguments ----------------- diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py index ddd61e5a97..233f3cb271 100644 --- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py +++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py @@ -4,24 +4,19 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the Oracle database via the cx_oracle driver. - -Driver ------- +""" -The Oracle dialect uses the cx_oracle driver, available at -http://cx-oracle.sourceforge.net/ . The dialect has several behaviors -which are specifically tailored towards compatibility with this module. -Version 5.0 or greater is **strongly** recommended, as SQLAlchemy makes -extensive use of the cx_oracle output converters for numeric and -string conversions. +.. dialect:: oracle+cx_oracle + :name: cx-Oracle + :dbapi: cx_oracle + :connectstring: oracle+cx_oracle://user:pass@host:port/dbname[?key=value&key=value...] + :url: http://cx-oracle.sourceforge.net/ -Connecting ----------- +Additional Connect Arguments +---------------------------- -Connecting with create_engine() uses the standard URL approach of -``oracle://user:pass@host:port/dbname[?key=value&key=value...]``. If dbname is -present, the host, port, and dbname tokens are converted to a TNS name using +When connecting with ``dbname`` present, the host, port, and dbname tokens are +converted to a TNS name using the cx_oracle :func:`makedsn()` function. Otherwise, the host token is taken directly as a TNS name. diff --git a/lib/sqlalchemy/dialects/oracle/zxjdbc.py b/lib/sqlalchemy/dialects/oracle/zxjdbc.py index 3a0f456656..54608969bb 100644 --- a/lib/sqlalchemy/dialects/oracle/zxjdbc.py +++ b/lib/sqlalchemy/dialects/oracle/zxjdbc.py @@ -4,13 +4,12 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the Oracle database via the zxjdbc JDBC connector. - -JDBC Driver ------------ - -The official Oracle JDBC driver is at -http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html. +""" +.. dialect:: oracle+zxjdbc + :name: zxJDBC for Jython + :dbapi: zxjdbc + :connectstring: oracle+zxjdbc://user:pass@host/dbname + :driverurl: http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html. """ import decimal diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index 0d2cb3c8ff..625ece6a13 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -4,20 +4,10 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the PostgreSQL database. - -DBAPI Support -------------- - -The following dialect/driver options are available: - -* :ref:`psycopg2` - -* :ref:`pg8000` - -* :ref:`pypostgresql` +""" +.. dialect:: postgresql + :name: PostgreSQL -* :ref:`zxjdbc` Sequences/SERIAL ---------------- diff --git a/lib/sqlalchemy/dialects/postgresql/pg8000.py b/lib/sqlalchemy/dialects/postgresql/pg8000.py index e19d84b51a..6a7c5cecb7 100644 --- a/lib/sqlalchemy/dialects/postgresql/pg8000.py +++ b/lib/sqlalchemy/dialects/postgresql/pg8000.py @@ -4,19 +4,12 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the PostgreSQL database via the pg8000 driver. - -DBAPI ------- - - http://pybrary.net/pg8000/ - -Connecting ----------- - -Connect string format:: - - postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...] +""" +.. dialect:: postgresql+pg8000 + :name: pg8000 + :dbapi: pg8000 + :connectstring: postgresql+pg8000://user:password@host:port/dbname[?key=value&key=value...] + :url: http://pybrary.net/pg8000/ Unicode ------- diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py index 14fb354568..700f76793a 100644 --- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py @@ -4,23 +4,12 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the PostgreSQL database via the psycopg2 driver. - -DBAPI ------- - -The psycopg2 driver is available at http://pypi.python.org/pypi/psycopg2/ . -The dialect has several behaviors which are specifically tailored towards compatibility -with this module. - -Note that psycopg1 is **not** supported. - -Connecting ----------- - -Connect string format:: - - postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...] +""" +.. dialect:: postgresql+psycopg2 + :name: psycopg2 + :dbapi: psycopg2 + :connectstring: postgresql+psycopg2://user:password@host:port/dbname[?key=value&key=value...] + :url: http://pypi.python.org/pypi/psycopg2/ psycopg2 Connect Arguments ----------------------------------- diff --git a/lib/sqlalchemy/dialects/postgresql/pypostgresql.py b/lib/sqlalchemy/dialects/postgresql/pypostgresql.py index cf091b3115..e7023610be 100644 --- a/lib/sqlalchemy/dialects/postgresql/pypostgresql.py +++ b/lib/sqlalchemy/dialects/postgresql/pypostgresql.py @@ -4,19 +4,12 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the PostgreSQL database via py-postgresql. - -DBAPI ------ - - http://python.projects.pgfoundry.org/ - -Connecting ----------- - -Connect string format:: - - postgresql+pypostgresql://user:password@host:port/dbname[?key=value&key=value...] +""" +.. dialect:: postgresql+pypostgresql + :name: py-postgresql + :dbapi: pypostgresql + :connectstring: postgresql+pypostgresql://user:password@host:port/dbname[?key=value&key=value...] + :url: http://python.projects.pgfoundry.org/ """ diff --git a/lib/sqlalchemy/dialects/postgresql/zxjdbc.py b/lib/sqlalchemy/dialects/postgresql/zxjdbc.py index 381424c7f0..196d77aaaa 100644 --- a/lib/sqlalchemy/dialects/postgresql/zxjdbc.py +++ b/lib/sqlalchemy/dialects/postgresql/zxjdbc.py @@ -4,19 +4,12 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the PostgreSQL database via the zxjdbc JDBC connector. - -DBAPI ------------ - -The official Postgresql JDBC driver is at http://jdbc.postgresql.org/. - -Connecting ----------- - -Connect string format:: - - postgresql+zxjdbc://scott:tiger@localhost/db +""" +.. dialect:: postgresql+zxjdbc + :name: zxJDBC for Jython + :dbapi: zxjdbc + :connectstring: postgresql+zxjdbc://scott:tiger@localhost/db + :driverurl: http://jdbc.postgresql.org/ """ diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py index eb03a55c40..c7ac2bba43 100644 --- a/lib/sqlalchemy/dialects/sqlite/base.py +++ b/lib/sqlalchemy/dialects/sqlite/base.py @@ -4,7 +4,10 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the SQLite database. +""" +.. dialect:: sqlite + :name: SQLite + Date and Time Types ------------------- diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlite.py b/lib/sqlalchemy/dialects/sqlite/pysqlite.py index 648867094d..558f1016b3 100644 --- a/lib/sqlalchemy/dialects/sqlite/pysqlite.py +++ b/lib/sqlalchemy/dialects/sqlite/pysqlite.py @@ -4,10 +4,15 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for the SQLite database via pysqlite. +""" +.. dialect:: sqlite+pysqlite + :name: pysqlite + :dbapi: sqlite3 + :connectstring: sqlite+pysqlite:///file_path + :url: http://docs.python.org/library/sqlite3.html -Note that pysqlite is the same driver as the ``sqlite3`` -module included with the Python distribution. + Note that ``pysqlite`` is the same driver as the ``sqlite3`` + module included with the Python distribution. Driver ------ @@ -26,14 +31,12 @@ this explicitly:: from sqlite3 import dbapi2 as sqlite e = create_engine('sqlite+pysqlite:///file.db', module=sqlite) -Full documentation on pysqlite is available at: -``_ Connect Strings --------------- The file specification for the SQLite database is taken as the "database" portion of -the URL. Note that the format of a url is:: +the URL. Note that the format of a SQLAlchemy url is:: driver://user:pass@host/database diff --git a/lib/sqlalchemy/dialects/sybase/base.py b/lib/sqlalchemy/dialects/sybase/base.py index 9a1a5bdf38..2d213ed5b2 100644 --- a/lib/sqlalchemy/dialects/sybase/base.py +++ b/lib/sqlalchemy/dialects/sybase/base.py @@ -8,7 +8,10 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Support for Sybase Adaptive Server Enterprise (ASE). +""" + +.. dialect:: sybase + :name: Sybase .. note:: diff --git a/lib/sqlalchemy/dialects/sybase/mxodbc.py b/lib/sqlalchemy/dialects/sybase/mxodbc.py index f88b1ed3c6..2bf4071ddc 100644 --- a/lib/sqlalchemy/dialects/sybase/mxodbc.py +++ b/lib/sqlalchemy/dialects/sybase/mxodbc.py @@ -3,11 +3,17 @@ # # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php - """ -Support for Sybase via mxodbc. -This dialect is a stub only and is likely non functional at this time. +.. dialect:: sybase+mxodbc + :name: mxODBC + :dbapi: mxodbc + :connectstring: sybase+mxodbc://:@ + :url: http://www.egenix.com/ + +.. note:: + + This dialect is a stub only and is likely non functional at this time. """ diff --git a/lib/sqlalchemy/dialects/sybase/pyodbc.py b/lib/sqlalchemy/dialects/sybase/pyodbc.py index 70bdd71a26..c4badd3e5e 100644 --- a/lib/sqlalchemy/dialects/sybase/pyodbc.py +++ b/lib/sqlalchemy/dialects/sybase/pyodbc.py @@ -5,14 +5,12 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -Support for Sybase via pyodbc. +.. dialect:: sybase+pyodbc + :name: PyODBC + :dbapi: pyodbc + :connectstring: sybase+pyodbc://:@[/] + :url: http://pypi.python.org/pypi/pyodbc/ -http://pypi.python.org/pypi/pyodbc/ - -Connect strings are of the form:: - - sybase+pyodbc://:@/ - sybase+pyodbc://:@/ Unicode Support --------------- diff --git a/lib/sqlalchemy/dialects/sybase/pysybase.py b/lib/sqlalchemy/dialects/sybase/pysybase.py index bf8c2096b8..58a669be0e 100644 --- a/lib/sqlalchemy/dialects/sybase/pysybase.py +++ b/lib/sqlalchemy/dialects/sybase/pysybase.py @@ -5,13 +5,11 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -Support for Sybase via the python-sybase driver. - -http://python-sybase.sourceforge.net/ - -Connect strings are of the form:: - - sybase+pysybase://:@/[database name] +.. dialect:: sybase+pysybase + :name: Python-Sybase + :dbapi: Sybase + :connectstring: sybase+pysybase://:@/[database name] + :url: http://python-sybase.sourceforge.net/ Unicode Support --------------- diff --git a/lib/sqlalchemy/testing/requirements.py b/lib/sqlalchemy/testing/requirements.py index ade1fd241c..163e049470 100644 --- a/lib/sqlalchemy/testing/requirements.py +++ b/lib/sqlalchemy/testing/requirements.py @@ -186,8 +186,15 @@ class SuiteRequirements(Requirements): return exclusions.open() @property - def empty_strings(self): - """target database can persist/return an empty string.""" + def empty_strings_varchar(self): + """target database can persist/return an empty string with a varchar.""" + + return exclusions.open() + + @property + def empty_strings_text(self): + """target database can persist/return an empty string with an + unbounded text.""" return exclusions.open() diff --git a/lib/sqlalchemy/testing/suite/test_types.py b/lib/sqlalchemy/testing/suite/test_types.py index 361d784b8b..cd7b61f424 100644 --- a/lib/sqlalchemy/testing/suite/test_types.py +++ b/lib/sqlalchemy/testing/suite/test_types.py @@ -70,8 +70,7 @@ class _UnicodeFixture(object): assert isinstance(row[0], unicode) - @requirements.empty_strings - def test_empty_strings(self): + def _test_empty_strings(self): unicode_table = self.tables.unicode_table config.db.execute( @@ -89,9 +88,17 @@ class UnicodeVarcharTest(_UnicodeFixture, fixtures.TablesTest): datatype = Unicode(255) + @requirements.empty_strings_varchar + def test_empty_strings(self): + self._test_empty_strings() + class UnicodeTextTest(_UnicodeFixture, fixtures.TablesTest): __requires__ = 'unicode_data', 'text_type' datatype = UnicodeText() + @requirements.empty_strings_text + def test_empty_strings(self): + self._test_empty_strings() + __all__ = ('UnicodeVarcharTest', 'UnicodeTextTest') \ No newline at end of file diff --git a/test/requirements.py b/test/requirements.py index ca245eb307..b88b774322 100644 --- a/test/requirements.py +++ b/test/requirements.py @@ -290,8 +290,16 @@ class DefaultRequirements(SuiteRequirements): return skip_if("drizzle", "no VIEW support") @property - def empty_strings(self): - """target database can persist/return an empty string.""" + def empty_strings_varchar(self): + """target database can persist/return an empty string with a varchar.""" + + return fails_if("oracle", 'oracle converts empty ' + 'strings to a blank space') + + @property + def empty_strings_text(self): + """target database can persist/return an empty string with an + unbounded text.""" return fails_if("oracle", 'oracle converts empty ' 'strings to a blank space')