From: Mike Bayer Date: Mon, 4 Sep 2006 23:02:13 +0000 (+0000) Subject: revised section on quoting, semanticized headings and table of content lists X-Git-Tag: rel_0_2_8~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3a4f96e070118e8253f17312aab325ebab3e3e62;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git revised section on quoting, semanticized headings and table of content lists --- diff --git a/doc/build/components/formatting.myt b/doc/build/components/formatting.myt index 52928f539d..53575bf13e 100644 --- a/doc/build/components/formatting.myt +++ b/doc/build/components/formatting.myt @@ -6,6 +6,33 @@ +<%method printtoc> +<%args> + root + includefile + current = None + full = False + children = True + + +% header = False + +% +% header = True +

<% i.header %>

+ + + <%def printtocelement> <%doc>prints a TOCElement as a table of contents item and prints its immediate child items <%args> @@ -16,16 +43,14 @@ children = True -
- " href="<% item.get_link(includefile, anchor = (not includefile)) %>"><% item.description %> -
+
  • " href="<% item.get_link(includefile, anchor = (not includefile)) %>"><% item.description %>
    • % if children: -
    +
    + % @@ -35,48 +60,18 @@ includefile children = False -
    - -
    - <% item.description %> -
    +
  • <% item.description %>
    • % if children: + % -
    -<%method printtoc> -<%args> - root - includefile - current = None - full = False - children = True - - -% header = False -% for i in root.children: - -% if i.header: -% if header: - -% -% header = True - <% i.header %>
    -
    -% - <& printtocelement, item=i, includefile = includefile, bold = (i == current and includefile), full = full, children=children &> -% - -% if header: -
    -% - <%method printitem> @@ -99,7 +94,7 @@
    % if not omitheader: - <% item.description %> +

    <% item.description %>

    %
    diff --git a/doc/build/components/printsection.myt b/doc/build/components/printsection.myt index 006b890555..cd5a26ff36 100644 --- a/doc/build/components/printsection.myt +++ b/doc/build/components/printsection.myt @@ -128,7 +128,7 @@ Next: <& formatting.myt:itemlink, item=item.next, includefile=ispaged &> <& topnavcontrol, **ARGS &> - Table of Contents +

    Table of Contents

       (view full table)

    @@ -142,7 +142,7 @@ Next: <& formatting.myt:itemlink, item=item.next, includefile=ispaged &>
    - Table of Contents: Full +

    Table of Contents: Full

       (view brief table)

    diff --git a/doc/build/components/section_wrapper.myt b/doc/build/components/section_wrapper.myt index 8ed91f5ecd..b4e7c524e8 100644 --- a/doc/build/components/section_wrapper.myt +++ b/doc/build/components/section_wrapper.myt @@ -29,7 +29,7 @@
    -
    <% title %>
    +

    <% title %>

    % if version is not None:
    Version: <% version %> Last Updated: <% time.strftime('%x %X', time.localtime(last_updated)) %>
    % diff --git a/doc/build/content/metadata.txt b/doc/build/content/metadata.txt index 171b395941..a52cd4133a 100644 --- a/doc/build/content/metadata.txt +++ b/doc/build/content/metadata.txt @@ -233,24 +233,39 @@ Within the `MetaData` collection, this table will be identified by the combinati #### Enabling Table / Column Quoting {@name=quoting} -Many table, schema, or column names require quoting to be enabled. Reasons for this include names that are the same as a database reserved word, or for identifiers that use MixedCase, where the database would normally "fold" the case convention into lower or uppercase (such as Postgres). SQLAlchemy currently has no internal logic to automatically determine when quoting should be used; so its off unless explicitly enabled for a particular column or table. Turning on quoting for a column or table identifier is performed manually by the `quote=True` flag on `Column` or `Table`, as well as the `quote_schema=True` flag for `Table`. +Feature Status: [Alpha Implementation][alpha_implementation] + +Many table, schema, or column names require quoting to be enabled. Reasons for this include names that are the same as a database reserved word, or for identifiers that use MixedCase, where the database would normally "fold" the case convention into lower or uppercase (such as Postgres). SQLAlchemy as of version 0.2.8 will attempt to automatically determine when quoting should be used. It will determine a value for every identifier name called `case_sensitive`, which defaults to `False` if the identifer name uses no uppercase letters, or `True` otherwise. This flag may be explicitly set on any schema item as well (schema items include `Table`, `Column`, `MetaData`, `Sequence`, etc.) to override this default setting, where objects will inherit the setting from an enclosing object if not explicitly overridden. + +When `case_sensitive` is `True`, the dialect will do what it has to in order for the database to recognize the casing. For Postgres and Oracle, this means using quoted identifiers. + +Identifiers that match known SQL reserved words (such as "asc", "union", etc.) will also be quoted according to the dialect's quoting convention regardless of the `case_sensitive` setting. + +To force quoting for an identifier, set the "quote=True" flag on `Column` or `Table`, as well as the `quote_schema=True` flag for `Table`. {python} table2 = Table('WorstCase2', metadata, - # desc is a reserved word so quote this column - Column('desc', Integer, quote=True, primary_key=True), + # desc is a reserved word, which will be quoted. + Column('desc', Integer, primary_key=True), - # MixedCase uses a mixed case convention, so quote this column - Column('MixedCase', Integer, quote=True), + # if using a reserved word which SQLAlchemy doesn't know about, + # specify quote=True + Column('some_reserved_word', Integer, quote=True, primary_key=True), + + # MixedCase uses a mixed case convention. + # it will be automatically quoted since it is case sensitive + Column('MixedCase', Integer), # Union is both a reserved word and mixed case - Column('Union', Integer, quote=True), + Column('Union', Integer), # normal_column doesnt require quoting - Column('normal_column', String(30)), - - # the table name uses mixed case, so turn on quoting for the table ident - quote=True) + Column('normal_column', String(30))) + + # to use tables where case_sensitive is False by default regardless + # of idenfifier casings, set "case_sensitive" to false at any level + # (or true to force case sensitive for lowercase identifiers as well) + lowercase_metadata = MetaData(case_sensitive=False) #### Other Options {@name=options} diff --git a/doc/docs.css b/doc/docs.css index c86b6ded2f..753612557e 100644 --- a/doc/docs.css +++ b/doc/docs.css @@ -120,9 +120,25 @@ pre { margin: 0px 0px 0px 0px; } -.docheadertext { +h1, .docheadertext { font-size: 16px; font-weight: bold; + padding: 0px; + margin: 0px; +} + +h2 { + font-size: 16px; + font-weight: bold; + display: inline; + padding: 0px; + margin: 0px; +} + +h3, .sectionheadertext { + font-weight: bold; + font-size: 16px; + display: inline; } .docheader { @@ -139,10 +155,6 @@ pre { padding: 20px 0px 0px 0px; } -.sectionheadertext { - font-weight: bold; - font-size: 16px; -} .sectiontext { font-size: 12px; @@ -156,24 +168,26 @@ pre { margin: 0px 0px 10px 0px; } -.toclinkcontainer { - padding:0px 0px 0px 8px; - /*border:1px solid;*/ +.toc_list { + padding:0px; + margin: 0px; + } +.toc_list li { + font-size: 12px; + list-style-type: none; + padding:0px 0px 3px 8px; + margin: 0px; } - -.tocsection { - padding:2px 2px 2px 8px; +.small_toc_list { + padding: 0px 0px 0px 8px; +} +.small_toc_list li { + font-size: 11px; + list-style-type: none; } - .toclink { font-size: 12px; padding:0px 0px 3px 8px; - /*border:1px solid;*/ -} - -.smalltoclink { - font-size: 11px; - padding:0px 0px 3px 0px; } .docstring {