From 878328bdfc3b5ac832f1728e4a0461e3129cf8d4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 27 Dec 2009 03:46:22 +0000 Subject: Latex rendering. Documentation licensing. --- docs/narr/introduction.rst | 273 ++++++++++++++------------------------------- 1 file changed, 86 insertions(+), 187 deletions(-) (limited to 'docs/narr/introduction.rst') diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index fdc3ce77b..09b690a12 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -1,47 +1,95 @@ :mod:`repoze.bfg` Introduction ============================== -:mod:`repoze.bfg` is a Python web framework. It is inspired by -:term:`Zope`, :term:`Pylons`, and :term:`Django`. :mod:`repoze.bfg` -uses the :term:`WSGI` protocol to handle requests and responses. - -Similarities to Other Frameworks --------------------------------- - -.. sidebar:: Django's Authors Explain Why It Doesn't Use "MVC" Terminology - - Django appears to be a MVC framework, but you call the Controller - the "view", and the View the "template". How come you don't use the - standard names? Well, the standard names are debatable. - - In our interpretation of MVC, the "view" describes the data that - gets presented to the user. It's not necessarily how the data looks, - but which data is presented. The view describes which data you see, - not how you see it. It's a subtle distinction. - - So, in our case, a "view" is the Python callback function for a - particular URL, because that callback function describes which data - is presented. - - Furthermore, it's sensible to separate content from presentation - - which is where templates come in. In Django, a "view" describes - which data is presented, but a view normally delegates to a - template, which describes how the data is presented. +:mod:`repoze.bfg` is an open source Python web application framework. +It is inspired by :term:`Zope`, :term:`Pylons`, and :term:`Django`. +It uses the :term:`WSGI` protocol to handle requests and responses. + +:mod:`repoze.bfg` is written by Agendaless Consulting and a community +of contributors. It is developed primarily by people who come from +the world of :term:`Zope` but for whom Zope as a web application +development platform has lost some of its attraction. Its authors +also have experience developing applications using many other web +frameworks. - Where does the "controller" fit in, then? In Django's case, it's - probably the framework itself: the machinery that sends a request to - the appropriate view, according to the Django URL configuration. +The first release of :mod:`repoze.bfg` was made in July of 2008. +Since its first release, it has undergone many improvements, and has +gained features steadily. Still, it strives to maintain the following +attributes: + +Simplicity + :mod:`repoze.bfg` attempts to be a *"pay only for what you eat"* + framework in which you can be productive quickly with partial + knowledge. We contrast this with *"pay up front for what anyone + might eventually want to eat"* frameworks, which tend to expect you + to understand a great many concepts and technologies fully before + you can be truly productive. :mod:`repoze.bfg` doesn't force you to + use any particular technology to produce an application, and we try + to keep the core set of concepts you need to understand to a + minimum. + +Minimalism + :mod:`repoze.bfg` provides only the very basics: *URL to code + mapping*, *templating*, *security*, and *resources*. There is not + much more to the framework than these pieces: you are expected to + provide the rest. + +Documentation + Because :mod:`repoze.bfg` is minimal, it's relatively easy to keep + its documentation up-to-date, which is helpful to bring new + developers up to speed. It's our goal that nothing remain + undocumented about :mod:`repoze.bfg`. + +Speed + :mod:`repoze.bfg` is faster than many other popular Python web + frameworks for common tasks such as templating and simple response + generation. The "hardware is cheap" mantra has its limits when + you're responsible for managing a great many machines: the fewer you + need, the less pain you'll have. + +Familiarity + As web developers, we've become accustomed to working in very + particular ways over the years. This framework is a canonization of + practices that "fit our brains". + +Trustability + :mod:`repoze.bfg` is developed conservatively and tested + exhaustively. *If it ain't tested, it's broke.* Every release of + :mod:`repoze.bfg` has 100% unit test converage. + +A Sense of Fun + Developing a :mod:`repoze.bfg` application should not feel foreign + or "enterprisey". We like to keep things down-to-earth. + +Similarities to Other Web Frameworks +------------------------------------ :mod:`repoze.bfg` was inspired by :term:`Zope`, :term:`Pylons` and :term:`Django`. +.. sidebar:: Django's Authors Explain Why It Doesn't Use "MVC" Terminology + + Django appears to be a MVC framework, but you call the Controller + the "view", and the View the "template". How come you don't use the + standard names? Well, the standard names are debatable. In our + interpretation of MVC, the "view" describes the data that gets + presented to the user. It's not necessarily how the data looks, but + which data is presented. The view describes which data you see, not + how you see it. It's a subtle distinction. So, in our case, a + "view" is the Python callback function for a particular URL, + because that callback function describes which data is presented. + Furthermore, it's sensible to separate content from presentation - + which is where templates come in. In Django, a "view" describes + which data is presented, but a view normally delegates to a + template, which describes how the data is presented. + The :mod:`repoze.bfg` concept of :term:`traversal` is inspired by :term:`Zope`. Additionally, :mod:`repoze.bfg` uses a :term:`Zope Component Architecture` :term:`application registry` internally, as does Zope 2, Zope 3, and :term:`Grok`. Like Zope, :mod:`repoze.bfg` allows you to create applications which do not need to be forked or -otherwise modified to be extended or overridden by a third party -developer. +otherwise modified in order to be extended or overridden by a third +party developer. The :mod:`repoze.bfg` concept of :term:`URL dispatch` is inspired by the :term:`Routes` system used by :term:`Pylons`. Like Pylons, @@ -55,18 +103,18 @@ is dependent upon :term:`WSGI`. The Django docs explain that Django is not an "MVC" ("model/view/controller") framework in their `FAQ -`_. The sidebar to -the right has the Django authors' take on why "MVC" terminology -doesn't match the web very well. The concepts of :term:`view` and -:term:`model` are used by :mod:`repoze.bfg` as they would be by -Django. +`_. The sidebar in +this section describes the Django authors' take on why "MVC" +terminology doesn't match the web very well. The concepts of +:term:`view` and :term:`model` are used by :mod:`repoze.bfg` as they +would be by Django. The skeleton code generator of :mod:`repoze.bfg` generates a directory layout very similar to the directory layout suggested by the `Django Book `_ . -Differences from Other Frameworks ---------------------------------- +Differences from Other Web Frameworks +------------------------------------- Like :term:`Zope`, the :mod:`repoze.bfg` framework imposes more `control inversion `_ upon @@ -121,152 +169,3 @@ relational database. :mod:`repoze.bfg` makes no such assumption; it allows you to use a relational database but doesn't encourage or discourage an application developer about such a decision. -Why? ----- - -*Familiarity*: As web developers, we've become accustomed to working -in very particular ways over the years. This framework is a -canonization of practices that "fit our brains". - -*Simplicity*: :mod:`repoze.bfg` attempts to be a *"pay only for what -you eat"* framework in which you can be productive quickly with -partial knowledge. We contrast this with *"pay up front for what -anyone might eventually want to eat"* frameworks, which tend to expect -you to understand a great many concepts and technologies fully before -you can be truly productive. :mod:`repoze.bfg` doesn't force you to -use any particular technology to produce an application, and we try to -keep the core set of concepts you need to understand to a minimum. - -*Minimalism*: :mod:`repoze.bfg` provides only the very basics: *URL to -code mapping*, *templating*, *security*, and *resources*. There is -not much more to the framework than these pieces: you are expected to -provide the rest. - -*Documentation*: Because :mod:`repoze.bfg` is minimal, it's relatively -easy to keep its documentation up-to-date, which is helpful to bring -new developers up to speed. It's our goal that nothing remain -undocumented about :mod:`repoze.bfg`. - -*Speed*: :mod:`repoze.bfg` is faster than many other popular Python -web frameworks for common tasks such as templating and simple response -generation. The "hardware is cheap" mantra has its limits when you're -responsible for managing a great many machines: the fewer you need, -the less pain you'll have. - -It's Tested ------------ - -*If it ain't tested, it's broke.* We strive to test :mod:`repoze.bfg` -completely. Below a run of the ``nosetests`` command configured to -show code coverage information run against the :mod:`repoze.bfg` -trunk shortly after the 1.2a1 release. - -.. code-block:: bash - :linenos: - - [chrism@snowpro trunk]$ python setup.py nosetests --with-coverage - running nosetests - running egg_info - writing requirements to repoze.bfg.egg-info/requires.txt - writing repoze.bfg.egg-info/PKG-INFO - writing namespace_packages to repoze.bfg.egg-info/namespace_packages.txt - writing top-level names to repoze.bfg.egg-info/top_level.txt - writing dependency_links to repoze.bfg.egg-info/dependency_links.txt - writing entry points to repoze.bfg.egg-info/entry_points.txt - writing manifest file 'repoze.bfg.egg-info/SOURCES.txt' - running build_ext - ........................................................................... - ........................................................................... - ........................................................................... - ........................................................................... - ........................................................................... - ........................................................................... - ........................................................................... - ........................................................................... - ........................................................................... - ........................................................................... - ................................................. - Name Stmts Exec Cover Missing - ------------------------------------------------------------------------------------ - repoze.bfg 0 0 100% - repoze.bfg.authentication 198 198 100% - repoze.bfg.authorization 51 51 100% - repoze.bfg.chameleon_text 46 46 100% - repoze.bfg.chameleon_zpt 39 39 100% - repoze.bfg.compat 8 8 100% - repoze.bfg.compat.pkgutil_26 0 0 100% - repoze.bfg.configuration 605 605 100% - repoze.bfg.encode 49 49 100% - repoze.bfg.events 22 22 100% - repoze.bfg.exceptions 2 2 100% - repoze.bfg.includes 1 1 100% - repoze.bfg.interfaces 66 66 100% - repoze.bfg.location 14 14 100% - repoze.bfg.log 9 9 100% - repoze.bfg.paster 58 58 100% - repoze.bfg.path 38 38 100% - repoze.bfg.registry 15 15 100% - repoze.bfg.renderers 47 47 100% - repoze.bfg.request 57 57 100% - repoze.bfg.resource 127 127 100% - repoze.bfg.router 109 109 100% - repoze.bfg.scripting 12 12 100% - repoze.bfg.security 123 123 100% - repoze.bfg.settings 38 38 100% - repoze.bfg.static 53 53 100% - repoze.bfg.testing 282 282 100% - repoze.bfg.tests 1 1 100% - repoze.bfg.tests.fixtureapp 1 1 100% - repoze.bfg.tests.fixtureapp.models 4 4 100% - repoze.bfg.tests.fixtureapp.subpackage 1 1 100% - repoze.bfg.tests.fixtureapp.views 4 4 100% - repoze.bfg.tests.grokkedapp 53 53 100% - repoze.bfg.tests.grokkedapp.another 37 37 100% - repoze.bfg.tests.grokkedapp.subpackage 3 3 100% - repoze.bfg.tests.grokkedapp.subpackage.notinit 3 3 100% - repoze.bfg.tests.grokkedapp.subpackage.subsubpackage 3 3 100% - repoze.bfg.tests.routesapp 1 1 100% - repoze.bfg.tests.routesapp.views 4 4 100% - repoze.bfg.tests.test_authentication 487 487 100% - repoze.bfg.tests.test_authorization 132 132 100% - repoze.bfg.tests.test_chameleon_text 165 165 100% - repoze.bfg.tests.test_chameleon_zpt 150 150 100% - repoze.bfg.tests.test_compat 7 7 100% - repoze.bfg.tests.test_configuration 2277 2277 100% - repoze.bfg.tests.test_encode 47 47 100% - repoze.bfg.tests.test_events 80 80 100% - repoze.bfg.tests.test_integration 64 64 100% - repoze.bfg.tests.test_location 34 34 100% - repoze.bfg.tests.test_log 11 11 100% - repoze.bfg.tests.test_paster 111 111 100% - repoze.bfg.tests.test_path 122 122 100% - repoze.bfg.tests.test_registry 34 34 100% - repoze.bfg.tests.test_renderers 150 150 100% - repoze.bfg.tests.test_request 138 138 100% - repoze.bfg.tests.test_resource 352 352 100% - repoze.bfg.tests.test_router 494 494 100% - repoze.bfg.tests.test_scripting 47 47 100% - repoze.bfg.tests.test_security 315 315 100% - repoze.bfg.tests.test_settings 138 138 100% - repoze.bfg.tests.test_static 126 126 100% - repoze.bfg.tests.test_testing 562 562 100% - repoze.bfg.tests.test_threadlocal 74 74 100% - repoze.bfg.tests.test_traversal 926 926 100% - repoze.bfg.tests.test_url 224 224 100% - repoze.bfg.tests.test_urldispatch 192 192 100% - repoze.bfg.tests.test_view 407 407 100% - repoze.bfg.tests.test_wsgi 99 99 100% - repoze.bfg.tests.test_zcml 781 781 100% - repoze.bfg.threadlocal 26 26 100% - repoze.bfg.traversal 187 187 100% - repoze.bfg.url 76 76 100% - repoze.bfg.urldispatch 101 101 100% - repoze.bfg.view 120 120 100% - repoze.bfg.wsgi 26 26 100% - repoze.bfg.zcml 299 299 100% - ------------------------------------------------------------------------------------ - TOTAL 11765 11765 100% - ---------------------------------------------------------------------- - Ran 799 tests in 2.080s - - OK -- cgit v1.2.3