From b65d8eacda1da9105b027e8e02e95be13854061a Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 21 Dec 2008 20:49:45 +0000 Subject: - Updated paster template "ez_setup.py" to one that requires setuptools 0.6c9. - Turn ``view_execution_permitted`` from the :mod:`repoze.bfg.view` module into a documented API. - Doc cleanups. --- docs/api/view.rst | 3 +++ docs/glossary.rst | 8 ++++---- docs/narr/MyProject/MyProject.ini | 1 + docs/narr/MyProject/ez_setup.py | 12 ++++++++---- docs/narr/install.rst | 7 ++++--- docs/narr/introduction.rst | 5 ++++- docs/narr/project.rst | 11 ++++++++--- docs/narr/startup.rst | 19 ++++++++++--------- docs/narr/templates.rst | 10 +++++----- 9 files changed, 47 insertions(+), 29 deletions(-) (limited to 'docs') diff --git a/docs/api/view.rst b/docs/api/view.rst index 02810471c..b57ea97c4 100644 --- a/docs/api/view.rst +++ b/docs/api/view.rst @@ -12,3 +12,6 @@ .. autofunction:: render_view .. autofunction:: is_response + + .. autofunction:: view_execution_permitted + diff --git a/docs/glossary.rst b/docs/glossary.rst index c15f94883..4c59db0e7 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -305,9 +305,9 @@ Glossary CA-and-ZODB-based applications useful within bfg applications. repoze.catalog An indexing and search facility (fielded and full-text) based on - `zope.index `_. It is - available from `repoze.org SVN - `_. + `zope.index `_. See + `the documentation `_ for more + information. repoze.who `Authentication middleware `_ for :term:`WSGI` applications. It can be used by @@ -318,6 +318,6 @@ Glossary :mod:`repoze.bfg` to form a workflow system. repoze.bfg.convention `An add-on for repoze.bfg - `_ which provides + `_ which provides alternative mechanisms for common :mod:`repoze.bfg` application configuration tasks. Useful for the :term:`ZCML` -allergic. diff --git a/docs/narr/MyProject/MyProject.ini b/docs/narr/MyProject/MyProject.ini index c1ff50547..f5d094dff 100644 --- a/docs/narr/MyProject/MyProject.ini +++ b/docs/narr/MyProject/MyProject.ini @@ -5,6 +5,7 @@ debug = true use = egg:MyProject#app reload_templates = true debug_authorization = false +debug_notfound = false [server:main] use = egg:Paste#http diff --git a/docs/narr/MyProject/ez_setup.py b/docs/narr/MyProject/ez_setup.py index 89cf056d9..d24e845e5 100644 --- a/docs/narr/MyProject/ez_setup.py +++ b/docs/narr/MyProject/ez_setup.py @@ -14,7 +14,7 @@ the appropriate options to ``use_setuptools()``. This file can also be run as a script to install or upgrade setuptools. """ import sys -DEFAULT_VERSION = "0.6c8" +DEFAULT_VERSION = "0.6c9" DEFAULT_URL = "http://pypi.python.org/packages/%s/s/setuptools/" % sys.version[:3] md5_data = { @@ -48,13 +48,18 @@ md5_data = { 'setuptools-0.6c8-py2.3.egg': '50759d29b349db8cfd807ba8303f1902', 'setuptools-0.6c8-py2.4.egg': 'cba38d74f7d483c06e9daa6070cce6de', 'setuptools-0.6c8-py2.5.egg': '1721747ee329dc150590a58b3e1ac95b', + 'setuptools-0.6c9-py2.3.egg': 'a83c4020414807b496e4cfbe08507c03', + 'setuptools-0.6c9-py2.4.egg': '260a2be2e5388d66bdaee06abec6342a', + 'setuptools-0.6c9-py2.5.egg': 'fe67c3e5a17b12c0e7c541b7ea43a8e6', + 'setuptools-0.6c9-py2.6.egg': 'ca37b1ff16fa2ede6e19383e7b59245a', } import sys, os +try: from hashlib import md5 +except ImportError: from md5 import md5 def _validate_md5(egg_name, data): if egg_name in md5_data: - from md5 import md5 digest = md5(data).hexdigest() if digest != md5_data[egg_name]: print >>sys.stderr, ( @@ -64,7 +69,6 @@ def _validate_md5(egg_name, data): sys.exit(2) return data - def use_setuptools( version=DEFAULT_VERSION, download_base=DEFAULT_URL, to_dir=os.curdir, download_delay=15 @@ -233,7 +237,6 @@ def update_md5(filenames): """Update our built-in md5 registry""" import re - from md5 import md5 for name in filenames: base = os.path.basename(name) @@ -270,3 +273,4 @@ if __name__=='__main__': + diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 57ce8a700..2eb391ce3 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -8,9 +8,10 @@ How To Install You will need `Python `_ version 2.4 or better to run :mod:`repoze.bfg`. It has been tested under Python 2.4.5, Python -2.5.2 and Python 2.6. Development of :mod:`repoze.bfg` is done -primarily under Python 2.4. :mod:`repoze.bfg` does *not* run under -any version of Python before 2.4, and does *not* run under Python 3.X. +2.5.2 and Python 2.6. Development of :mod:`repoze.bfg` is currently +done primarily under Python 2.4. :mod:`repoze.bfg` does *not* run +under any version of Python before 2.4, and does *not* run under +Python 3.X. .. warning:: To succesfully install :mod:`repoze.bfg`, you will need an environment capable of compiling C code. See the documentation diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 3f9b7d09a..7f8bcec35 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -24,7 +24,10 @@ developer rather than the application developer. :mod:`repoze.bfg` developers use :term:`ZCML` (an XML dialect) to perform various configuration tasks; in particular, as in Zope3, one more more :term:`view` functions is associated with a :term:`model` type via -ZCML. +ZCML. It is also possible to configure :mod:`repoze.bfg` views +without :term:`ZCML` (instead configuration is done inside Python +decorators) by using an add-on package named +:term:`repoze.bfg.convention`. Like Pylons, :mod:`repoze.bfg` is mostly policy-free. It makes no assertions about which database you should use, and its built-in diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 194c168c3..ad74fb8e0 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -332,6 +332,10 @@ changes will not require an application restart to be detected. See production applications, as template rendering is slowed when it is turned on. +Various other settings may exist in this section having to do with +debugging a :mod:`repoze.bfg` application. See +:ref:`environment_chapter` for more information about these settings. + The ``[server:main]`` section of the configuration file configures a WSGI server which listens on port 6543. It is configured to listen on all interfaces (``0.0.0.0``). The ``Paste#http`` server will create a @@ -392,7 +396,7 @@ that should point at your application project's URL (if any). ``packages=find_packages()`` causes all packages within the project to be found when packaging the application. ``include_package_data`` will include non-Python files when the application is packaged (if -those files are checked into version control). ``zip_safe` indicates +those files are checked into version control). ``zip_safe`` indicates that this package is not safe to ship as a zipped egg (it will unpack as a directory, which is more convenient). ``install_requires`` and ``tests_require`` indicate that this package depends on the @@ -468,8 +472,9 @@ registry`. It looks like so: :language: xml #. Lines 1-3 provide the root node and namespaces for the - configuration language. ``bfg`` is the namespace for - :mod:`repoze.bfg` -specific configuration directives. + configuration language. ``http://namespaces.repoze.org/bfg`` is + the default XML namespace. Add-on packages may require other + namespaces. #. Line 6 initializes :mod:`repoze.bfg`-specific configuration directives by including the ``repoze.bfg.includes`` package. This diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index b9391b273..e12f0ef81 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -90,7 +90,8 @@ press ``return`` after running ``paster serve MyProject.ini``. entry point URI ``egg:MyProject#app`` (see :ref:`MyProject_ini` for more information about entry point URIs, and how they relate to callables), will receive the key/value pairs - ``{'reload_templates':'true'}``. + ``{'reload_templates':'true', 'debug_authorization':'false', + 'debug_notfound':'false'}``. #. The constructor itself is invoked. A generated :mod:`repoze.bfg` ``app`` function will look like the below. @@ -109,14 +110,14 @@ press ``return`` after running ``paster serve MyProject.ini``. package which allows the user to pass framework-related (as opposed to application-related) options to an application constructor. It picks off framework-related options from the ``**kw`` dictionary - passed in to the constructor. We actually use a framework option - named ``reload_templates`` in our configuration. Note that we make - no use of this option in our application, but the fact that we use - ``get_options`` to parse the ``*kw`` dict, and subsequently pass - along the result as the ``options`` argument to ``make_app``. - ``reload_templates`` has special meaning to the framework: if it's - ``true``, we will cause templates to be automatically reloaded by - the application when they are changed. + passed in to the constructor. For example, we actually use a + framework option named ``reload_templates`` in our configuration. + Note that we make no use of this option in our application, but the + fact that we use ``get_options`` to parse the ``*kw`` dict, and + subsequently pass along the result as the ``options`` argument to + ``make_app``. ``reload_templates`` has special meaning to the + framework: if it's ``true``, we will cause templates to be + automatically reloaded by the application when they are changed. ``get_root`` is the first argument to ``make_app``, and it is a callable that is invoked on every request to retrieve the diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 48a9ac52e..fcddb55dd 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -13,7 +13,7 @@ its default and best-supported templating language. However, :mod:`repoze.bfg` uses a different implementation of the :term:`ZPT` specification than Zope does: the :term:`Chameleon` :term:`chameleon.zpt` templating engine. This templating engine -complies with the `Zope Page Template +complies largely with the `Zope Page Template `_ template specification and is significantly faster. @@ -27,7 +27,7 @@ significantly faster. :mod:`repoze.bfg`. Given that there is a :term:`chameleon.zpt` template named -``foo.html`` in a directory in your application named ``templates``, +``foo.pt`` in a directory in your application named ``templates``, you can render the template from a view like so: .. code-block:: python @@ -35,12 +35,12 @@ you can render the template from a view like so: from repoze.bfg.chameleon_zpt import render_template_to_response def sample_view(context, request): - return render_template_to_response('templates/foo.html', foo=1, bar=2) + return render_template_to_response('templates/foo.pt', foo=1, bar=2) The first argument to ``render_template_to_response`` shown above (and its sister function ``render_template``, not shown, which just returns a string body) is the template *path*. Above, the path -``templates/foo.html`` is *relative*. Relative to what, you ask? +``templates/foo.pt`` is *relative*. Relative to what, you ask? Relative to the directory in which the ``views.py`` file which names it lives, which is usually the :mod:`repoze.bfg` application's :term:`package` directory. @@ -59,7 +59,7 @@ string manually as a response body: from repoze.bfg.chameleon_zpt import render_template from webob import Response def sample_view(context, request): - result = render_template('templates/foo.html', foo=1, bar=2) + result = render_template('templates/foo.pt', foo=1, bar=2) response = Response(result) response.content_type = 'text/plain' return response -- cgit v1.2.3