1. diana clarke
  2. sqlalchemy-2422

Commits

Mike Bayer  committed d8d7bc3

revised section on quoting, semanticized headings and table of content lists

  • Participants
  • Parent commits 28a7d93
  • Branches default

Comments (0)

Files changed (5)

File doc/build/components/formatting.myt

View file
 </%global>
 
 
+<%method printtoc>
+<%args> 
+    root
+    includefile
+    current = None
+    full = False
+    children = True
+</%args>
+
+% header = False
+<ul class="toc_list">
+% for i in root.children:
+
+%   if i.header:
+%       if header:
+    </ul>
+%
+%   header = True
+    <h3><% i.header %></h3>
+    <ul class="toc_list">
+%
+    <& printtocelement, item=i, includefile = includefile, bold = (i == current and includefile), full = full, children=children &>
+%
+
+</ul>
+</%method>
+
 <%def printtocelement>
 <%doc>prints a TOCElement as a table of contents item and prints its immediate child items</%doc>
     <%args>
         children = True
     </%args>
 
-    <div class="toclink">
-        <A style="<% bold and "font-weight:bold;" or "" %>" href="<% item.get_link(includefile, anchor = (not includefile)) %>"><% item.description %></a>
-    </div>
+        <li><A style="<% bold and "font-weight:bold;" or "" %>" href="<% item.get_link(includefile, anchor = (not includefile)) %>"><% item.description %></a></li>
     
 % if children:  
-    <div class="toclinkcontainer">
+    <ul class="small_toc_list">
 %   for i in item.children:
         <& printsmtocelem, item=i, includefile = includefile, children=full &>
 %
-    </div>
+    </ul>
 %
 </%def>
 
         includefile
         children = False
     </%args>    
-    <div class="toclinkcontainer">
-    
-    <div class="smalltoclink">
-    <A href="<% item.get_link(includefile) %>"><% item.description %></a>
-    </div>
+    <li><A href="<% item.get_link(includefile) %>"><% item.description %></a></li>
 
 % if children:
+    <ul class="small_toc_list">
 %   for i in item.children:
         <& printsmtocelem, item = i, includefile = includefile &>
 %
+    </ul>
 %
-    </div>
 
 </%def>
 
-<%method printtoc>
-<%args> 
-    root
-    includefile
-    current = None
-    full = False
-    children = True
-</%args>
-
-% header = False
-% for i in root.children:
-
-%   if i.header:
-%       if header:
-    </div>
-%
-%   header = True
-    <b><% i.header %></b><br/>
-    <div class="tocsection">
-%
-    <& printtocelement, item=i, includefile = includefile, bold = (i == current and includefile), full = full, children=children &>
-%
-
-%   if header:
-    </div>
-%
-</%method>
 
 
 <%method printitem>
 <div class="subsection" style="margin-left:<% repr(10 + indentlevel * 10) %>px;">
 
 % if not omitheader:
-    <span class="sectionheadertext"><% item.description %></span>
+    <h3><% item.description %></h3>
 %
     <div class="sectiontext">
 

File doc/build/components/printsection.myt

View file
 	<& topnavcontrol, **ARGS &>
 
 	<a name="table_of_contents"></a>
-	<span class="docheadertext">Table of Contents</span>
+	<h2>Table of Contents</h2>
 	&nbsp;&nbsp;
 	<a href="#full_index">(view full table)</a>
 	<br/><br/>
 
 	<div class="maintoc">
 	<a name="full_index"></a>
-	<span class="docheadertext">Table of Contents: Full</span>
+	<h2>Table of Contents: Full</h2>
 	&nbsp;&nbsp;
 	<a href="#table_of_contents">(view brief table)</a>
 	<br/><br/>

File doc/build/components/section_wrapper.myt

View file
 
 <div class="docheader">
 
-<div class="docheadertext" ><% title %></div>
+<h1><% title %></h1>
 % if version is not None:
 <div class="">Version: <% version %>   Last Updated: <% time.strftime('%x %X', time.localtime(last_updated)) %></div>
 %

File doc/build/content/metadata.txt

View file
 
 #### 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}
 

File doc/docs.css

View file
 	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 {
 	padding: 20px 0px 0px 0px;
 }
 
-.sectionheadertext {
-	font-weight: bold;
-	font-size: 16px;
-}
 
 .sectiontext {
 	font-size: 12px;
 	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 {