Permalink
Browse files

Tidy up the docs a little

  • Loading branch information...
unknown unknown
unknown authored and unknown committed Jul 18, 2012
1 parent df3090e commit d2556caf9f815a88ddb47a4ea8ee808675637240
Showing with 357 additions and 103 deletions.
  1. +2 −103 README.rst
  2. +192 −0 docs/conf.py
  3. +61 −0 docs/design.rst
  4. +102 −0 docs/index.rst
View
@@ -1,7 +1,8 @@
tw2.sqla
========
-.. split here
+.. tw2.sqla is a database layer for ToscaWidgets 2 and SQLAlchemy. It allows common database tasks to be achieved with minimal code.
+
Build Status
------------
@@ -21,105 +22,3 @@ Build Status
+----------+-----------+
| develop | |develop| |
+----------+-----------+
-
-
-Introduction
-------------
-
-tw2.sqla is a database layer for ToscaWidgets 2 and SQLAlchemy. It allows common database tasks to be achieved with minimal code.
-
-.. warning::
- tw2.sqla itself is in good shape, but this document is horribly out of date.
-
-
-Features
---------
-
-`Session and Transaction Management`
-
- 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.
-
- 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.
-
-
-`Loading and Saving Data`
-
- 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.
-
- Applications often contain quite repetitive code to initiate the act of loading and saving data. A database layer should aim to do this automatically.
-
-
-`Populating Selection Fields`
-
- 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.
-
-
-`Generating Widget Definitions`
-
- 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.
-
- 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.
-
-
-
-Existing Technology
--------------------
-
-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.
-
-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.
-
-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:
-
-================================== ======================================================= ============================================== =======================================================
-Feature Sprox Rum tw2.sqla
-================================== ======================================================= ============================================== =======================================================
-Session and transaction management None; relies on the containing framework Supported, same technique as TG2 Supported, same technique as TG2
-Loading and saving data None; responsibility of the application Supported, with both conversion and initiation Supported, with both conversion and initiation
-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
-Populating selection fields Supported; no cacheing Supported; no cacheing Supported, with cacheing
-================================== ======================================================= ============================================== =======================================================
-
-
-Design
-------
-
-`Session and Transaction Management`
-
- 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::
-
- import tw2.core as twc
- twc.dev_server(host='127.0.0.1', repoze_tm=True)
-
- For this to work correctly, ``ZopeTransactionExtension`` must be installed in the session; there is a convenience function for this ``tw2.sqla.transactional_session``
-
- For example, to use this with Elixir, add the following to the model file::
-
- import elixir as el, tw2.sqla as tws
- el.session = tws.transactional_session()
-
-
-`Loading and Saving Data`
-
- Check out ``tw2.sqla.RelatedValidator``
-
- 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.
-
- For now, lets go with "status"
-
-
-`Generating Widget Definitions`
-
- There is a policy class that defines the widget and its characteristics, based on:
-
- * Database type
- * Field name (e.g. password, email)
- * Database details, e.g. nullable
-
-
- For relations:
-
- * ManyToOne - SingleSelectField
- * ManyToMany - CheckBoxList
- * OneToMany - nothing
View
@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+#
+# ToscaWidgets 2 documentation build configuration file, created by
+# sphinx-quickstart on Tue Mar 10 11:38:11 2009.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+import pkg_resources
+dist = pkg_resources.get_distribution('tw2.core')
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# General configuration
+# ---------------------
+
+# 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']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'tw2.sqla'
+copyright = u'2012, Paul Johnston, Alberto Valverde & Contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = dist.version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['.build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ToscaWidgets2doc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+ ('index', 'ToscaWidgets2.tex', ur'ToscaWidgets 2 Documentation',
+ ur'Paul Johnston, Alberto Valverde & Contributors', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
View
@@ -0,0 +1,61 @@
+.. _design:
+
+Design
+======
+
+
+Features
+--------
+
+`Session and Transaction Management`
+
+ 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.
+
+ 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.
+
+
+`Loading and Saving Data`
+
+ 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.
+
+ Applications often contain quite repetitive code to initiate the act of loading and saving data. A database layer should aim to do this automatically.
+
+
+`Populating Selection Fields`
+
+ 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.
+
+
+`Generating Widget Definitions`
+
+ 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.
+
+ 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.
+
+
+
+Existing Technology
+-------------------
+
+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.
+
+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.
+
+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:
+
+================================== ======================================================= ============================================== =======================================================
+Feature Sprox Rum tw2.sqla
+================================== ======================================================= ============================================== =======================================================
+Session and transaction management None; relies on the containing framework Supported, same technique as TG2 Supported, same technique as TG2
+Loading and saving data None; responsibility of the application Supported, with both conversion and initiation Supported, with both conversion and initiation
+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
+Populating selection fields Supported; no cacheing Supported; no cacheing Supported, with cacheing
+================================== ======================================================= ============================================== =======================================================
+
+
+
+Open issues
+-----------
+
+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.
+
Oops, something went wrong.

0 comments on commit d2556ca

Please sign in to comment.