Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Tidy up the docs a little

  • Loading branch information...
commit d2556caf9f815a88ddb47a4ea8ee808675637240 1 parent df3090e
authored July 18, 2012
105  README.rst
Source Rendered
... ...
@@ -1,7 +1,8 @@
1 1
 tw2.sqla
2 2
 ========
3 3
 
4  
-.. split here
  4
+.. tw2.sqla is a database layer for ToscaWidgets 2 and SQLAlchemy. It allows common database tasks to be achieved with minimal code.
  5
+
5 6
 
6 7
 Build Status
7 8
 ------------
@@ -21,105 +22,3 @@ Build Status
21 22
 +----------+-----------+
22 23
 | develop  | |develop| |
23 24
 +----------+-----------+
24  
-
25  
-
26  
-Introduction
27  
-------------
28  
-
29  
-tw2.sqla is a database layer for ToscaWidgets 2 and SQLAlchemy. It allows common database tasks to be achieved with minimal code.
30  
-
31  
-.. warning::
32  
-    tw2.sqla itself is in good shape, but this document is horribly out of date.
33  
-
34  
-
35  
-Features
36  
---------
37  
-
38  
-`Session and Transaction Management`
39  
-
40  
-    It is desirable to wrap individual HTTP requests in database transactions and ORM sessions. This ensures, for example, that if a web request fails part way through, no changes are made to the database. More advanced session management can retry a request if it fails due to a transitive error. Some also avoid the overhead of a database transaction for read-only requests.
41  
-
42  
-    Many web frameworks include session and transaction management. For example, TurboGears 2 uses `Repoze.tm <http://repoze.org/tmdemo.html>`_ and `zope.sqlalchemy <http://pypi.python.org/pypi/zope.sqlalchemy>`_ to support this.
43  
-
44  
-
45  
-`Loading and Saving Data`
46  
-
47  
-    For loading, data needs to be converted from the format loaded from the database into a format that can be displayed by the forms library. This conversion needs to be performed in reverse for saving. ToscaWidgets itself makes this relatively straightforward, but some conversion is still necessary. A database layer should aim to do all such conversion in a transparent manner.
48  
-
49  
-    Applications often contain quite repetitive code to initiate the act of loading and saving data. A database layer should aim to do this automatically.
50  
-
51  
-
52  
-`Populating Selection Fields`
53  
-
54  
-    Selection fields, such as dropdown lists, often have their options sourced from a database table. A database layer should load these automatically, and ideally support cacheing for efficiency.
55  
-
56  
-
57  
-`Generating Widget Definitions`
58  
-
59  
-    Many applications contain long widget definitions that closely match the underlying database models. The idea is to reduce application code by automatically generating these definitions. Some tools exist that automatically generate source code at design time, but tw2.sqla avoids that approach and generates the definitions at run time.
60  
-
61  
-    For flexibility it is very important to be able to override the automatic definitions. This needs to be possible on a per-field basis. It should also be possible to provide a customised policy, specifying the rules for generating widgets from model definitions. For example, an application may decide that all fields named "comment" should have a TextArea, instead of a TextField.
62  
-
63  
-
64  
-
65  
-Existing Technology
66  
--------------------
67  
-
68  
-Django has long had the `Django admin site <http://docs.djangoproject.com/en/dev/ref/contrib/admin/>`_, which is a key feature and receives much development attention. There have been several projects in the Python WSGI space to provide automatic form creation, or administrative interfaces. For example, TurboGears 1.0 had both `FastData <http://docs.turbogears.org/FastData>`_ and `Catwalk <http://docs.turbogears.org/1.0/Catwalk>`_. Such projects have tended to be relatively fragmented and unmaintained. A particular challenge was that FastData and Catwalk originally only worked with SQLObject and could not easily be changed to support SQLAlchemy.
69  
-
70  
-As of 2010, the leading efforts in the Python WSGI space are `Sprox <http://sprox.org/>`_ and `Rum <http://www.python-rum.org/>`_. Sprox helps automatically define forms and views from database models; it is a relatively thin layer that can be readily customised. Rum is a somewhat thicker layer, almost a web framework in itself, and is primarily aimed at producing automatic admin interfaces. Both work with SQLAlchemy and ToscaWidgets, while making efforts to abstract the dependencies.
71  
-
72  
-Sprox and Rum are the primary influences for tw2.sqla. One major difference is that tw2.sqla is only intended to work with SQLAlchemy and ToscaWidgets 2, and makes no attempt to abstract the dependencies. Here is a high-level comparison of their functionality:
73  
-
74  
-==================================  =======================================================  ==============================================  =======================================================
75  
-Feature                             Sprox                                                    Rum                                             tw2.sqla
76  
-==================================  =======================================================  ==============================================  =======================================================
77  
-Session and transaction management  None; relies on the containing framework                 Supported, same technique as TG2                Supported, same technique as TG2
78  
-Loading and saving data             None; responsibility of the application                  Supported, with both conversion and initiation  Supported, with both conversion and initiation
79  
-Generating widget definitions       Supported, with customisation of both fields and policy  Supported; Sprox can be used if desired         Supported, with customisation of both fields and policy
80  
-Populating selection fields         Supported; no cacheing                                   Supported; no cacheing                          Supported, with cacheing
81  
-==================================  =======================================================  ==============================================  =======================================================
82  
-
83  
-
84  
-Design
85  
-------
86  
-
87  
-`Session and Transaction Management`
88  
-
89  
-    The repoze.tm middleware needs to be installed in the stack. This can be done by passing ``repoze_tm=True`` to ``tw2.core.make_middleware`` or ``tw2.core.dev_server``. For example::
90  
-
91  
-        import tw2.core as twc
92  
-        twc.dev_server(host='127.0.0.1', repoze_tm=True)
93  
-
94  
-    For this to work correctly, ``ZopeTransactionExtension`` must be installed in the session; there is a convenience function for this ``tw2.sqla.transactional_session``
95  
-
96  
-    For example, to use this with Elixir, add the following to the model file::
97  
-
98  
-        import elixir as el, tw2.sqla as tws
99  
-        el.session = tws.transactional_session()
100  
-
101  
-
102  
-`Loading and Saving Data`
103  
-
104  
-    Check out ``tw2.sqla.RelatedValidator``
105  
-
106  
-    Efficiency consideration
107  
-    Say we have a ManyToOne relation, "status" using the column "status_id". We could have a SelectionField on "status" using RelatedValidator, or one on "status_id" using IntValidator. The former would do stronger validation, while the latter would be more efficient.
108  
-
109  
-    For now, lets go with "status"
110  
-
111  
-
112  
-`Generating Widget Definitions`
113  
-
114  
-    There is a policy class that defines the widget and its characteristics, based on:
115  
-
116  
-     * Database type
117  
-     * Field name (e.g. password, email)
118  
-     * Database details, e.g. nullable
119  
-
120  
-
121  
-    For relations:
122  
-
123  
-     * ManyToOne - SingleSelectField
124  
-     * ManyToMany - CheckBoxList
125  
-     * OneToMany - nothing
192  docs/conf.py
... ...
@@ -0,0 +1,192 @@
  1
+# -*- coding: utf-8 -*-
  2
+#
  3
+# ToscaWidgets 2 documentation build configuration file, created by
  4
+# sphinx-quickstart on Tue Mar 10 11:38:11 2009.
  5
+#
  6
+# This file is execfile()d with the current directory set to its containing dir.
  7
+#
  8
+# The contents of this file are pickled, so don't put values in the namespace
  9
+# that aren't pickleable (module imports are okay, they're removed automatically).
  10
+#
  11
+# Note that not all possible configuration values are present in this
  12
+# autogenerated file.
  13
+#
  14
+# All configuration values have a default; values that are commented out
  15
+# serve to show the default.
  16
+
  17
+import sys, os
  18
+import pkg_resources
  19
+dist = pkg_resources.get_distribution('tw2.core')
  20
+
  21
+# If your extensions are in another directory, add it here. If the directory
  22
+# is relative to the documentation root, use os.path.abspath to make it
  23
+# absolute, like shown here.
  24
+#sys.path.append(os.path.abspath('.'))
  25
+
  26
+# General configuration
  27
+# ---------------------
  28
+
  29
+# Add any Sphinx extension module names here, as strings. They can be extensions
  30
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
  31
+extensions = ['sphinx.ext.autodoc']
  32
+
  33
+# Add any paths that contain templates here, relative to this directory.
  34
+templates_path = ['.templates']
  35
+
  36
+# The suffix of source filenames.
  37
+source_suffix = '.rst'
  38
+
  39
+# The encoding of source files.
  40
+#source_encoding = 'utf-8'
  41
+
  42
+# The master toctree document.
  43
+master_doc = 'index'
  44
+
  45
+# General information about the project.
  46
+project = u'tw2.sqla'
  47
+copyright = u'2012, Paul Johnston, Alberto Valverde & Contributors'
  48
+
  49
+# The version info for the project you're documenting, acts as replacement for
  50
+# |version| and |release|, also used in various other places throughout the
  51
+# built documents.
  52
+#
  53
+# The short X.Y version.
  54
+version = '0.1'
  55
+# The full version, including alpha/beta/rc tags.
  56
+release = dist.version
  57
+
  58
+# The language for content autogenerated by Sphinx. Refer to documentation
  59
+# for a list of supported languages.
  60
+#language = None
  61
+
  62
+# There are two options for replacing |today|: either, you set today to some
  63
+# non-false value, then it is used:
  64
+#today = ''
  65
+# Else, today_fmt is used as the format for a strftime call.
  66
+#today_fmt = '%B %d, %Y'
  67
+
  68
+# List of documents that shouldn't be included in the build.
  69
+#unused_docs = []
  70
+
  71
+# List of directories, relative to source directory, that shouldn't be searched
  72
+# for source files.
  73
+exclude_trees = ['.build']
  74
+
  75
+# The reST default role (used for this markup: `text`) to use for all documents.
  76
+#default_role = None
  77
+
  78
+# If true, '()' will be appended to :func: etc. cross-reference text.
  79
+#add_function_parentheses = True
  80
+
  81
+# If true, the current module name will be prepended to all description
  82
+# unit titles (such as .. function::).
  83
+#add_module_names = True
  84
+
  85
+# If true, sectionauthor and moduleauthor directives will be shown in the
  86
+# output. They are ignored by default.
  87
+#show_authors = False
  88
+
  89
+# The name of the Pygments (syntax highlighting) style to use.
  90
+pygments_style = 'sphinx'
  91
+
  92
+
  93
+# Options for HTML output
  94
+# -----------------------
  95
+
  96
+# The style sheet to use for HTML and HTML Help pages. A file of that name
  97
+# must exist either in Sphinx' static/ path, or in one of the custom paths
  98
+# given in html_static_path.
  99
+html_style = 'default.css'
  100
+
  101
+# The name for this set of Sphinx documents.  If None, it defaults to
  102
+# "<project> v<release> documentation".
  103
+#html_title = None
  104
+
  105
+# A shorter title for the navigation bar.  Default is the same as html_title.
  106
+#html_short_title = None
  107
+
  108
+# The name of an image file (relative to this directory) to place at the top
  109
+# of the sidebar.
  110
+#html_logo = None
  111
+
  112
+# The name of an image file (within the static path) to use as favicon of the
  113
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
  114
+# pixels large.
  115
+#html_favicon = None
  116
+
  117
+# Add any paths that contain custom static files (such as style sheets) here,
  118
+# relative to this directory. They are copied after the builtin static files,
  119
+# so a file named "default.css" will overwrite the builtin "default.css".
  120
+html_static_path = ['.static']
  121
+
  122
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
  123
+# using the given strftime format.
  124
+#html_last_updated_fmt = '%b %d, %Y'
  125
+
  126
+# If true, SmartyPants will be used to convert quotes and dashes to
  127
+# typographically correct entities.
  128
+#html_use_smartypants = True
  129
+
  130
+# Custom sidebar templates, maps document names to template names.
  131
+#html_sidebars = {}
  132
+
  133
+# Additional templates that should be rendered to pages, maps page names to
  134
+# template names.
  135
+#html_additional_pages = {}
  136
+
  137
+# If false, no module index is generated.
  138
+#html_use_modindex = True
  139
+
  140
+# If false, no index is generated.
  141
+#html_use_index = True
  142
+
  143
+# If true, the index is split into individual pages for each letter.
  144
+#html_split_index = False
  145
+
  146
+# If true, the reST sources are included in the HTML build as _sources/<name>.
  147
+#html_copy_source = True
  148
+
  149
+# If true, an OpenSearch description file will be output, and all pages will
  150
+# contain a <link> tag referring to it.  The value of this option must be the
  151
+# base URL from which the finished HTML is served.
  152
+#html_use_opensearch = ''
  153
+
  154
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
  155
+#html_file_suffix = ''
  156
+
  157
+# Output file base name for HTML help builder.
  158
+htmlhelp_basename = 'ToscaWidgets2doc'
  159
+
  160
+
  161
+# Options for LaTeX output
  162
+# ------------------------
  163
+
  164
+# The paper size ('letter' or 'a4').
  165
+#latex_paper_size = 'letter'
  166
+
  167
+# The font size ('10pt', '11pt' or '12pt').
  168
+#latex_font_size = '10pt'
  169
+
  170
+# Grouping the document tree into LaTeX files. List of tuples
  171
+# (source start file, target name, title, author, document class [howto/manual]).
  172
+latex_documents = [
  173
+  ('index', 'ToscaWidgets2.tex', ur'ToscaWidgets 2 Documentation',
  174
+   ur'Paul Johnston, Alberto Valverde & Contributors', 'manual'),
  175
+]
  176
+
  177
+# The name of an image file (relative to this directory) to place at the top of
  178
+# the title page.
  179
+#latex_logo = None
  180
+
  181
+# For "manual" documents, if this is true, then toplevel headings are parts,
  182
+# not chapters.
  183
+#latex_use_parts = False
  184
+
  185
+# Additional stuff for the LaTeX preamble.
  186
+#latex_preamble = ''
  187
+
  188
+# Documents to append as an appendix to all manuals.
  189
+#latex_appendices = []
  190
+
  191
+# If false, no module index is generated.
  192
+#latex_use_modindex = True
61  docs/design.rst
Source Rendered
... ...
@@ -0,0 +1,61 @@
  1
+.. _design:
  2
+
  3
+Design
  4
+======
  5
+
  6
+
  7
+Features
  8
+--------
  9
+
  10
+`Session and Transaction Management`
  11
+
  12
+    It is desirable to wrap individual HTTP requests in database transactions and ORM sessions. This ensures, for example, that if a web request fails part way through, no changes are made to the database. More advanced session management can retry a request if it fails due to a transitive error. Some also avoid the overhead of a database transaction for read-only requests.
  13
+
  14
+    Many web frameworks include session and transaction management. For example, TurboGears 2 uses `Repoze.tm <http://repoze.org/tmdemo.html>`_ and `zope.sqlalchemy <http://pypi.python.org/pypi/zope.sqlalchemy>`_ to support this.
  15
+
  16
+
  17
+`Loading and Saving Data`
  18
+
  19
+    For loading, data needs to be converted from the format loaded from the database into a format that can be displayed by the forms library. This conversion needs to be performed in reverse for saving. ToscaWidgets itself makes this relatively straightforward, but some conversion is still necessary. A database layer should aim to do all such conversion in a transparent manner.
  20
+
  21
+    Applications often contain quite repetitive code to initiate the act of loading and saving data. A database layer should aim to do this automatically.
  22
+
  23
+
  24
+`Populating Selection Fields`
  25
+
  26
+    Selection fields, such as dropdown lists, often have their options sourced from a database table. A database layer should load these automatically, and ideally support cacheing for efficiency.
  27
+
  28
+
  29
+`Generating Widget Definitions`
  30
+
  31
+    Many applications contain long widget definitions that closely match the underlying database models. The idea is to reduce application code by automatically generating these definitions. Some tools exist that automatically generate source code at design time, but tw2.sqla avoids that approach and generates the definitions at run time.
  32
+
  33
+    For flexibility it is very important to be able to override the automatic definitions. This needs to be possible on a per-field basis. It should also be possible to provide a customised policy, specifying the rules for generating widgets from model definitions. For example, an application may decide that all fields named "comment" should have a TextArea, instead of a TextField.
  34
+
  35
+
  36
+
  37
+Existing Technology
  38
+-------------------
  39
+
  40
+Django has long had the `Django admin site <http://docs.djangoproject.com/en/dev/ref/contrib/admin/>`_, which is a key feature and receives much development attention. There have been several projects in the Python WSGI space to provide automatic form creation, or administrative interfaces. For example, TurboGears 1.0 had both `FastData <http://docs.turbogears.org/FastData>`_ and `Catwalk <http://docs.turbogears.org/1.0/Catwalk>`_. Such projects have tended to be relatively fragmented and unmaintained. A particular challenge was that FastData and Catwalk originally only worked with SQLObject and could not easily be changed to support SQLAlchemy.
  41
+
  42
+As of 2010, the leading efforts in the Python WSGI space are `Sprox <http://sprox.org/>`_ and `Rum <http://www.python-rum.org/>`_. Sprox helps automatically define forms and views from database models; it is a relatively thin layer that can be readily customised. Rum is a somewhat thicker layer, almost a web framework in itself, and is primarily aimed at producing automatic admin interfaces. Both work with SQLAlchemy and ToscaWidgets, while making efforts to abstract the dependencies.
  43
+
  44
+Sprox and Rum are the primary influences for tw2.sqla. One major difference is that tw2.sqla is only intended to work with SQLAlchemy and ToscaWidgets 2, and makes no attempt to abstract the dependencies. Here is a high-level comparison of their functionality:
  45
+
  46
+==================================  =======================================================  ==============================================  =======================================================
  47
+Feature                             Sprox                                                    Rum                                             tw2.sqla
  48
+==================================  =======================================================  ==============================================  =======================================================
  49
+Session and transaction management  None; relies on the containing framework                 Supported, same technique as TG2                Supported, same technique as TG2
  50
+Loading and saving data             None; responsibility of the application                  Supported, with both conversion and initiation  Supported, with both conversion and initiation
  51
+Generating widget definitions       Supported, with customisation of both fields and policy  Supported; Sprox can be used if desired         Supported, with customisation of both fields and policy
  52
+Populating selection fields         Supported; no cacheing                                   Supported; no cacheing                          Supported, with cacheing
  53
+==================================  =======================================================  ==============================================  =======================================================
  54
+
  55
+
  56
+
  57
+Open issues
  58
+-----------
  59
+
  60
+RelativeValidator, efficiency consideration: Say we have a ManyToOne relation, "status" using the column "status_id". We could have a SelectionField on "status" using RelatedValidator, or one on "status_id" using IntValidator. The former would do stronger validation, while the latter would be more efficient.
  61
+
102  docs/index.rst
Source Rendered
... ...
@@ -0,0 +1,102 @@
  1
+tw2.sqla
  2
+========
  3
+
  4
+
  5
+Introduction
  6
+------------
  7
+
  8
+tw2.sqla is a database layer for ToscaWidgets 2 and SQLAlchemy. It allows common database tasks to be achieved with minimal code. There are four main features:
  9
+
  10
+ * Session and transaction management
  11
+ * Loading and saving data
  12
+ * Populating selection fields
  13
+ * Generating widget definitions
  14
+
  15
+See the :ref:`design` document for a more detailed description of these. tw2.sqla is designed to work fully however you define your model objects - traditional, declarative base, or Elixir.
  16
+
  17
+
  18
+.. warning::
  19
+    tw2.sqla itself is in good shape, but this document is out of date.
  20
+
  21
+
  22
+
  23
+Getting started
  24
+---------------
  25
+
  26
+If you are using tw2.sqla with another framework (e.g. Pyramid), the framework will already be providing session management. You do not need to use the session management within tw2.sqla.
  27
+
  28
+Any database objects used with tw2.sqla must have a ``query`` property. This is automatically present with Elixir. For declarative base, you must use the following::
  29
+
  30
+    Base = declarative_base()
  31
+    Base.query = tws.transactional_session().query_property()
  32
+
  33
+
  34
+Session and Transaction Management
  35
+----------------------------------
  36
+
  37
+The repoze.tm middleware needs to be installed in the stack. This can be done by passing ``repoze_tm=True`` to ``tw2.core.make_middleware`` or ``tw2.devtools.dev_server``. For example::
  38
+
  39
+    tw2.devtools.dev_server(host='127.0.0.1', repoze_tm=True)
  40
+
  41
+For this to work correctly, ``ZopeTransactionExtension`` must be installed in the session; there is a convenience function for this ``tw2.sqla.transactional_session``
  42
+
  43
+To use this with Elixir, add the following to the model file::
  44
+
  45
+    import elixir as el, tw2.sqla as tws
  46
+    el.session = tws.transactional_session()
  47
+
  48
+With declarative base, if the query property is setup as above, no further configuration is necessary.
  49
+
  50
+
  51
+Loading and Saving Data
  52
+-----------------------
  53
+
  54
+The main classes to use are:
  55
+
  56
+`tw2.sqla.DbListPage`
  57
+    
  58
+    This presents a list of items.
  59
+    
  60
+`tw2.sqla.DbFormPage`
  61
+
  62
+    This allows editing of a single item. The item is loaded based on primary key columns in the query string. When the form is posted, the data is saved back to the database.
  63
+    
  64
+Internally, ``tw2.sqla.RelatedValidator`` is key - it converts IDs to objects. Other classes to use: `DbListForm` and `DbLinkField`.
  65
+
  66
+
  67
+Populating selection fields
  68
+---------------------------
  69
+
  70
+Main classes:
  71
+
  72
+ * DbSingleSelectField
  73
+ * DbRadioList
  74
+ * DbCheckBoxList
  75
+ * DbCheckBoxTable
  76
+
  77
+Note: composite primary keys are NOT supported by these fields.
  78
+
  79
+
  80
+Generating Widget Definitions
  81
+-----------------------------
  82
+
  83
+There is a policy class that defines the widget and its characteristics, based on:
  84
+
  85
+ * Database type
  86
+ * Field name (e.g. password, email)
  87
+ * Database details, e.g. nullable
  88
+
  89
+For relations:
  90
+
  91
+ * ManyToOne - SingleSelectField
  92
+ * ManyToMany - CheckBoxList
  93
+ * OneToMany - nothing
  94
+
  95
+
  96
+
  97
+**Contents**
  98
+
  99
+.. toctree::
  100
+   :maxdepth: 2
  101
+
  102
+   design

0 notes on commit d2556ca

Please sign in to comment.
Something went wrong with that request. Please try again.