From 9f026927c95721ec1f3337cb9e5e837523c2c8df Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 4 Nov 2010 01:32:09 -0400 Subject: fix project documentation to account for starter paster template changes --- docs/narr/MyProject/MyProject.ini | 15 - docs/narr/MyProject/myproject/configure.zcml | 16 - docs/narr/MyProject/myproject/run.py | 17 - .../myproject/templates/static/default.css | 380 --------------------- .../myproject/templates/static/images/img01.gif | Bin 3840 -> 0 bytes .../myproject/templates/static/images/img02.gif | Bin 4689 -> 0 bytes .../myproject/templates/static/images/img03.gif | Bin 229 -> 0 bytes .../myproject/templates/static/images/img04.gif | Bin 92 -> 0 bytes .../myproject/templates/static/images/spacer.gif | Bin 43 -> 0 bytes .../myproject/templates/static/templatelicense.txt | 243 ------------- docs/narr/project.rst | 266 ++++++--------- docs/narr/startup.rst | 30 +- 12 files changed, 125 insertions(+), 842 deletions(-) delete mode 100644 docs/narr/MyProject/MyProject.ini delete mode 100644 docs/narr/MyProject/myproject/configure.zcml delete mode 100644 docs/narr/MyProject/myproject/run.py delete mode 100644 docs/narr/MyProject/myproject/templates/static/default.css delete mode 100644 docs/narr/MyProject/myproject/templates/static/images/img01.gif delete mode 100644 docs/narr/MyProject/myproject/templates/static/images/img02.gif delete mode 100644 docs/narr/MyProject/myproject/templates/static/images/img03.gif delete mode 100644 docs/narr/MyProject/myproject/templates/static/images/img04.gif delete mode 100644 docs/narr/MyProject/myproject/templates/static/images/spacer.gif delete mode 100644 docs/narr/MyProject/myproject/templates/static/templatelicense.txt (limited to 'docs') diff --git a/docs/narr/MyProject/MyProject.ini b/docs/narr/MyProject/MyProject.ini deleted file mode 100644 index 6741af913..000000000 --- a/docs/narr/MyProject/MyProject.ini +++ /dev/null @@ -1,15 +0,0 @@ -[DEFAULT] -debug = true - -[app:main] -use = egg:MyProject#app -reload_templates = true -debug_authorization = false -debug_notfound = false -debug_templates = true -default_locale_name = en - -[server:main] -use = egg:Paste#http -host = 0.0.0.0 -port = 6543 diff --git a/docs/narr/MyProject/myproject/configure.zcml b/docs/narr/MyProject/myproject/configure.zcml deleted file mode 100644 index 1d0b3e61c..000000000 --- a/docs/narr/MyProject/myproject/configure.zcml +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - - diff --git a/docs/narr/MyProject/myproject/run.py b/docs/narr/MyProject/myproject/run.py deleted file mode 100644 index 9b6ba7072..000000000 --- a/docs/narr/MyProject/myproject/run.py +++ /dev/null @@ -1,17 +0,0 @@ -from pyramid.configuration import Configurator -from myproject.models import get_root - -def app(global_config, **settings): - """ This function returns a WSGI application. - - It is usually called by the PasteDeploy framework during - ``paster serve``. - """ - config = Configurator(root_factory=get_root, settings=settings) - config.begin() - zcml_file = settings.get('configure_zcml', 'configure.zcml') - config.load_zcml(zcml_file) - config.end() - return config.make_wsgi_app() - - diff --git a/docs/narr/MyProject/myproject/templates/static/default.css b/docs/narr/MyProject/myproject/templates/static/default.css deleted file mode 100644 index 41b3debde..000000000 --- a/docs/narr/MyProject/myproject/templates/static/default.css +++ /dev/null @@ -1,380 +0,0 @@ -/* -Design by Free CSS Templates -http://www.freecsstemplates.org -Released for free under a Creative Commons Attribution 2.5 License -*/ - -body { - margin: 0; - padding: 0; - background: url(images/img01.gif) repeat-x left top; - font-size: 13px; - font-family: "Trebuchet MS", Georgia, "Times New Roman", Times, serif; - text-align: justify; - color: #FFFFFF; -} - -h1, h2, h3 { - margin: 0; - text-transform: lowercase; - font-weight: normal; - color: #FFFFFF; -} - -h1 { - letter-spacing: -1px; - font-size: 32px; -} - -h2 { - font-size: 23px; -} - -p, ul, ol { - margin: 0 0 2em 0; - text-align: justify; - line-height: 26px; -} - -a:link { - color: #8BD80E; -} - -a:hover, a:active { - text-decoration: none; - color: #8BD80E; -} - -a:visited { - color: #8BD80E; -} - -img { - border: none; -} - -img.left { - float: left; - margin-right: 15px; -} - -img.right { - float: right; - margin-left: 15px; -} - -/* Form */ - -form { - margin: 0; - padding: 0; -} - -fieldset { - margin: 0; - padding: 0; - border: none; -} - -legend { - display: none; -} - -input, textarea, select { - font-family: "Trebuchet MS", Arial, Helvetica, sans-serif; - font-size: 13px; - color: #333333; -} - -#wrapper { - margin: 0; - padding: 0; - background: #000000; -} - -/* Header */ - -#header { - width: 713px; - margin: 0 auto; - height: 42px; -} - -/* Menu */ - -#menu { - float: left; - width: 713px; - height: 50px; - background: url(images/img02.gif) no-repeat left top; -} - -#menu ul { - margin: 0; - padding: 0px 0 0 10px; - list-style: none; - line-height: normal; -} - -#menu li { - display: block; - float: left; -} - -#menu a { - display: block; - float: left; - background: url(images/img04.gif) no-repeat right 55%; - margin-top: 5px; - margin-right: 3px; - padding: 8px 17px; - text-decoration: none; - font-size: 13px; - color: #000000; -} - -#menu a:hover { - color: #000000; -} - -#menu .current_page_item a { - color: #000000; -} - -/** LOGO */ - -#logo { - width: 713px; - height: 80px; - margin: 0 auto; -} - -#logo h1, #logo h2 { - float: left; - margin: 0; - padding: 30px 0 0 0px; - line-height: normal; -} - -#logo h1 { - font-family: Georgia, "Times New Roman", Times, serif; - font-size:40px; -} - -#logo h1 a { - text-decoration: none; - color: #4C4C4C; -} - -#logo h1 a:hover { text-decoration: underline; } - -#logo h2 { - float: left; - padding: 45px 0 0 18px; - font: 18px Georgia, "Times New Roman", Times, serif; - color: #8BD80E; -} - -#logo p a { - text-decoration: none; - color: #8BD80E; -} - -#logo p a:hover { text-decoration: underline; } - - - -/* Page */ - -#page { - width: 663px; - margin: 0 auto; - background: #4C4C4C url(images/img03.gif) no-repeat left bottom; - padding: 0 25px; -} - -/* Content */ - -#content { - float: left; - width: 410px; - -} - -/* Post */ - -.post { - padding: 15px 0px; - margin-bottom: 20px; -} - -.post .title { - margin-bottom: 20px; - padding-bottom: 5px; -} - -.post h1 { - padding: 0px 0 0 0px; - background: url(images/img08.jpg) no-repeat left top; - font-size: 24px; - color: #FFFFFF; -} - -.post h2 { - padding: 0px 0 0 0px; - font-size: 22px; - color: #FFFFFF; -} - -.post .entry { -} - -.post .meta { - padding: 15px 15px 30px 0px; - font-family: Arial, Helvetica, sans-serif; - font-size: 11px; -} - -.post .meta p { - margin: 0; - padding-top: 15px; - line-height: normal; - color: #FFFFFF; -} - -.post .meta .byline { - float: left; -} - -.post .meta .links { - float: right; -} - -.post .meta .more { - padding: 0 10px 0 18px; -} - -.post .meta .comments { -} - -.post .meta b { - display: none; -} - - -/* Sidebar */ - -#sidebar { - width: 210px; - float: right; - margin: 0; - padding: 0; -} - -#sidebar ul { - margin: 0; - padding: 0; - list-style: none; -} - -#sidebar li { - margin-bottom: 40px; -} - -#sidebar li ul { -} - -#sidebar li li { - margin: 0; -} - -#sidebar h2 { - width: 250px; - padding: 8px 0 0 0px; - margin-bottom: 10px; - background: url(images/img07.jpg) no-repeat left top; - font-size: 20px; - color: #FFFFFF; -} - -/* Search */ - -#search { - -} - -#search h2 { - margin-bottom: 20px; -} - -#s { - width: 140px; - margin-right: 5px; - padding: 3px; - border: 1px solid #BED99C; -} - -#x { - padding: 3px; - border: none; - background: #8BD80E; - text-transform: lowercase; - font-size: 11px; - color: #FFFFFF; -} - -/* Boxes */ - -.box1 { - padding: 20px; -} - -.box2 { - color: #BABABA; -} - -.box2 h2 { - margin-bottom: 15px; - font-size: 16px; - color: #FFFFFF; -} - -.box2 ul { - margin: 0; - padding: 0; - list-style: none; -} - -.box2 a:link, .box2 a:hover, .box2 a:active, .box2 a:visited { - color: #EDEDED; -} - -/* Footer */ -#footer-wrap { -} - -#footer { - margin: 0 auto; - padding: 20px 0 10px 0; - background: #000000; -} - -html>body #footer { - height: auto; -} - -#footer p { - font-size: 11px; -} - -#legal { - clear: both; - padding-top: 17px; - text-align: center; - color: #FFFFFF; -} - -#legal a { - font-weight: normal; - color: #FFFFFF; -} diff --git a/docs/narr/MyProject/myproject/templates/static/images/img01.gif b/docs/narr/MyProject/myproject/templates/static/images/img01.gif deleted file mode 100644 index 5f082bd99..000000000 Binary files a/docs/narr/MyProject/myproject/templates/static/images/img01.gif and /dev/null differ diff --git a/docs/narr/MyProject/myproject/templates/static/images/img02.gif b/docs/narr/MyProject/myproject/templates/static/images/img02.gif deleted file mode 100644 index 45a3ae976..000000000 Binary files a/docs/narr/MyProject/myproject/templates/static/images/img02.gif and /dev/null differ diff --git a/docs/narr/MyProject/myproject/templates/static/images/img03.gif b/docs/narr/MyProject/myproject/templates/static/images/img03.gif deleted file mode 100644 index d92ea38f9..000000000 Binary files a/docs/narr/MyProject/myproject/templates/static/images/img03.gif and /dev/null differ diff --git a/docs/narr/MyProject/myproject/templates/static/images/img04.gif b/docs/narr/MyProject/myproject/templates/static/images/img04.gif deleted file mode 100644 index 950c4af9d..000000000 Binary files a/docs/narr/MyProject/myproject/templates/static/images/img04.gif and /dev/null differ diff --git a/docs/narr/MyProject/myproject/templates/static/images/spacer.gif b/docs/narr/MyProject/myproject/templates/static/images/spacer.gif deleted file mode 100644 index 5bfd67a2d..000000000 Binary files a/docs/narr/MyProject/myproject/templates/static/images/spacer.gif and /dev/null differ diff --git a/docs/narr/MyProject/myproject/templates/static/templatelicense.txt b/docs/narr/MyProject/myproject/templates/static/templatelicense.txt deleted file mode 100644 index ccb6b06ab..000000000 --- a/docs/narr/MyProject/myproject/templates/static/templatelicense.txt +++ /dev/null @@ -1,243 +0,0 @@ -Creative Commons - -Creative Commons Legal Code - -*Attribution 2.5* - -CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE -LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN -ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION -ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE -INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM -ITS USE. - -/License/ - -THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE -COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY -COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS -AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. - -BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE -TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS YOU THE -RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS -AND CONDITIONS. - -*1. Definitions* - - 1. *"Collective Work"* means a work, such as a periodical issue, - anthology or encyclopedia, in which the Work in its entirety in - unmodified form, along with a number of other contributions, - constituting separate and independent works in themselves, are - assembled into a collective whole. A work that constitutes a - Collective Work will not be considered a Derivative Work (as - defined below) for the purposes of this License. - 2. *"Derivative Work"* means a work based upon the Work or upon the - Work and other pre-existing works, such as a translation, musical - arrangement, dramatization, fictionalization, motion picture - version, sound recording, art reproduction, abridgment, - condensation, or any other form in which the Work may be recast, - transformed, or adapted, except that a work that constitutes a - Collective Work will not be considered a Derivative Work for the - purpose of this License. For the avoidance of doubt, where the - Work is a musical composition or sound recording, the - synchronization of the Work in timed-relation with a moving image - ("synching") will be considered a Derivative Work for the purpose - of this License. - 3. *"Licensor"* means the individual or entity that offers the Work - under the terms of this License. - 4. *"Original Author"* means the individual or entity who created the - Work. - 5. *"Work"* means the copyrightable work of authorship offered under - the terms of this License. - 6. *"You"* means an individual or entity exercising rights under this - License who has not previously violated the terms of this License - with respect to the Work, or who has received express permission - from the Licensor to exercise rights under this License despite a - previous violation. - -*2. Fair Use Rights.* Nothing in this license is intended to reduce, -limit, or restrict any rights arising from fair use, first sale or other -limitations on the exclusive rights of the copyright owner under -copyright law or other applicable laws. - -*3. License Grant.* Subject to the terms and conditions of this License, -Licensor hereby grants You a worldwide, royalty-free, non-exclusive, -perpetual (for the duration of the applicable copyright) license to -exercise the rights in the Work as stated below: - - 1. to reproduce the Work, to incorporate the Work into one or more - Collective Works, and to reproduce the Work as incorporated in the - Collective Works; - 2. to create and reproduce Derivative Works; - 3. to distribute copies or phonorecords of, display publicly, perform - publicly, and perform publicly by means of a digital audio - transmission the Work including as incorporated in Collective Works; - 4. to distribute copies or phonorecords of, display publicly, perform - publicly, and perform publicly by means of a digital audio - transmission Derivative Works. - 5. - - For the avoidance of doubt, where the work is a musical composition: - - 1. *Performance Royalties Under Blanket Licenses*. Licensor - waives the exclusive right to collect, whether individually - or via a performance rights society (e.g. ASCAP, BMI, - SESAC), royalties for the public performance or public - digital performance (e.g. webcast) of the Work. - 2. *Mechanical Rights and Statutory Royalties*. Licensor waives - the exclusive right to collect, whether individually or via - a music rights agency or designated agent (e.g. Harry Fox - Agency), royalties for any phonorecord You create from the - Work ("cover version") and distribute, subject to the - compulsory license created by 17 USC Section 115 of the US - Copyright Act (or the equivalent in other jurisdictions). - 6. *Webcasting Rights and Statutory Royalties*. For the avoidance of - doubt, where the Work is a sound recording, Licensor waives the - exclusive right to collect, whether individually or via a - performance-rights society (e.g. SoundExchange), royalties for the - public digital performance (e.g. webcast) of the Work, subject to - the compulsory license created by 17 USC Section 114 of the US - Copyright Act (or the equivalent in other jurisdictions). - -The above rights may be exercised in all media and formats whether now -known or hereafter devised. The above rights include the right to make -such modifications as are technically necessary to exercise the rights -in other media and formats. All rights not expressly granted by Licensor -are hereby reserved. - -*4. Restrictions.*The license granted in Section 3 above is expressly -made subject to and limited by the following restrictions: - - 1. You may distribute, publicly display, publicly perform, or - publicly digitally perform the Work only under the terms of this - License, and You must include a copy of, or the Uniform Resource - Identifier for, this License with every copy or phonorecord of the - Work You distribute, publicly display, publicly perform, or - publicly digitally perform. You may not offer or impose any terms - on the Work that alter or restrict the terms of this License or - the recipients' exercise of the rights granted hereunder. You may - not sublicense the Work. You must keep intact all notices that - refer to this License and to the disclaimer of warranties. You may - not distribute, publicly display, publicly perform, or publicly - digitally perform the Work with any technological measures that - control access or use of the Work in a manner inconsistent with - the terms of this License Agreement. The above applies to the Work - as incorporated in a Collective Work, but this does not require - the Collective Work apart from the Work itself to be made subject - to the terms of this License. If You create a Collective Work, - upon notice from any Licensor You must, to the extent practicable, - remove from the Collective Work any credit as required by clause - 4(b), as requested. If You create a Derivative Work, upon notice - from any Licensor You must, to the extent practicable, remove from - the Derivative Work any credit as required by clause 4(b), as - requested. - 2. If you distribute, publicly display, publicly perform, or publicly - digitally perform the Work or any Derivative Works or Collective - Works, You must keep intact all copyright notices for the Work and - provide, reasonable to the medium or means You are utilizing: (i) - the name of the Original Author (or pseudonym, if applicable) if - supplied, and/or (ii) if the Original Author and/or Licensor - designate another party or parties (e.g. a sponsor institute, - publishing entity, journal) for attribution in Licensor's - copyright notice, terms of service or by other reasonable means, - the name of such party or parties; the title of the Work if - supplied; to the extent reasonably practicable, the Uniform - Resource Identifier, if any, that Licensor specifies to be - associated with the Work, unless such URI does not refer to the - copyright notice or licensing information for the Work; and in the - case of a Derivative Work, a credit identifying the use of the - Work in the Derivative Work (e.g., "French translation of the Work - by Original Author," or "Screenplay based on original Work by - Original Author"). Such credit may be implemented in any - reasonable manner; provided, however, that in the case of a - Derivative Work or Collective Work, at a minimum such credit will - appear where any other comparable authorship credit appears and in - a manner at least as prominent as such other comparable authorship - credit. - -*5. Representations, Warranties and Disclaimer* - -UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR -OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY -KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, -INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, -FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF -LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, -WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE -EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. - -*6. Limitation on Liability.* EXCEPT TO THE EXTENT REQUIRED BY -APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL -THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY -DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF -LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -*7. Termination* - - 1. This License and the rights granted hereunder will terminate - automatically upon any breach by You of the terms of this License. - Individuals or entities who have received Derivative Works or - Collective Works from You under this License, however, will not - have their licenses terminated provided such individuals or - entities remain in full compliance with those licenses. Sections - 1, 2, 5, 6, 7, and 8 will survive any termination of this License. - 2. Subject to the above terms and conditions, the license granted - here is perpetual (for the duration of the applicable copyright in - the Work). Notwithstanding the above, Licensor reserves the right - to release the Work under different license terms or to stop - distributing the Work at any time; provided, however that any such - election will not serve to withdraw this License (or any other - license that has been, or is required to be, granted under the - terms of this License), and this License will continue in full - force and effect unless terminated as stated above. - -*8. Miscellaneous* - - 1. Each time You distribute or publicly digitally perform the Work or - a Collective Work, the Licensor offers to the recipient a license - to the Work on the same terms and conditions as the license - granted to You under this License. - 2. Each time You distribute or publicly digitally perform a - Derivative Work, Licensor offers to the recipient a license to the - original Work on the same terms and conditions as the license - granted to You under this License. - 3. If any provision of this License is invalid or unenforceable under - applicable law, it shall not affect the validity or enforceability - of the remainder of the terms of this License, and without further - action by the parties to this agreement, such provision shall be - reformed to the minimum extent necessary to make such provision - valid and enforceable. - 4. No term or provision of this License shall be deemed waived and no - breach consented to unless such waiver or consent shall be in - writing and signed by the party to be charged with such waiver or - consent. - 5. This License constitutes the entire agreement between the parties - with respect to the Work licensed here. There are no - understandings, agreements or representations with respect to the - Work not specified here. Licensor shall not be bound by any - additional provisions that may appear in any communication from - You. This License may not be modified without the mutual written - agreement of the Licensor and You. - -Creative Commons is not a party to this License, and makes no warranty -whatsoever in connection with the Work. Creative Commons will not be -liable to You or any party on any legal theory for any damages -whatsoever, including without limitation any general, special, -incidental or consequential damages arising in connection to this -license. Notwithstanding the foregoing two (2) sentences, if Creative -Commons has expressly identified itself as the Licensor hereunder, it -shall have all rights and obligations of Licensor. - -Except for the limited purpose of indicating to the public that the Work -is licensed under the CCPL, neither party will use the trademark -"Creative Commons" or any related trademark or logo of Creative Commons -without the prior written consent of Creative Commons. Any permitted use -will be in compliance with Creative Commons' then-current trademark -usage guidelines, as may be published on its website or otherwise made -available upon request from time to time. - -Creative Commons may be contacted at http://creativecommons.org/ -. - -« Back to Commons Deed <./> diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 471ae8754..08bc9e8ae 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -18,6 +18,7 @@ templates". .. index:: single: paster templates single: pyramid_starter paster template + single: pyramid_starter_zcml paster template single: pyramid_zodb paster template single: pyramid_alchemy paster template single: pyramid_routesalchemy paster template @@ -44,6 +45,10 @@ The included templates are these: ``pyramid_starter`` URL mapping via :term:`traversal` and no persistence mechanism. +``pyramid_starter_zcml`` + URL mapping via :term:`traversal` and no persistence mechanism, using + :term:`ZCML` (declarative configuration). + ``pyramid_zodb`` URL mapping via :term:`traversal` and persistence via :term:`ZODB` @@ -67,19 +72,12 @@ The included templates are these: URL mapping via :term:`URL dispatch` and Pylons-style view handlers, some extra functionality, and SQLAlchemy set up. -The project templates which start with ``pyramid_`` uses :term:`ZCML` (see -:ref:`declarative_chapter`) instead of :term:`imperative configuration`. - -The project templates which start with ``pylons_`` use imperative -configuration (the type of configuration which we've been showing so far in -the book). - -Each also makes the assumption that you want your code to live in a Python -:term:`package`. Even if your application is extremely simple, it is useful -to place code that drives the application within a package, because a package -is more easily extended with new code. An application that lives inside a -package can also be distributed more easily than one which does not live -within a package. +Each paster template makes the assumption that you want your code to live in +a Python :term:`package`. Even if your application is extremely simple, it +is useful to place code that drives the application within a package, because +a package is more easily extended with new code. An application that lives +inside a package can also be distributed more easily than one which does not +live within a package. .. index:: single: creating a project @@ -145,16 +143,15 @@ created in a directory named ``MyProject``. That directory is a directory can be used to distribute your application, or install your application for deployment or development. -A sample :term:`PasteDeploy` ``.ini`` file named ``MyProject.ini`` -will also be created in the project directory. You will use this -``.ini`` file to configure a server, to run your application, and to -and debug your application. +A :term:`PasteDeploy` ``.ini`` file named ``development.ini`` will also be +created in the project directory. You will use this ``.ini`` file to +configure a server, to run your application, and to and debug your +application. -The ``MyProject`` project directory contains an additional -subdirectory named ``myproject`` (note the case difference) -representing a Python :term:`package` which holds very simple -:mod:`pyramid` sample code. This is where you'll edit your -application's Python code and templates. +The ``MyProject`` project directory contains an additional subdirectory named +``myproject`` (note the case difference) representing a Python +:term:`package` which holds very simple :mod:`pyramid` sample code. This is +where you'll edit your application's Python code and templates. .. index:: single: setup.py develop @@ -268,7 +265,7 @@ the name ``main`` as a section name: .. code-block:: text [chrism@vitaminf shellenv]$ ../bin/paster --plugin=pyramid \ - pshell MyProject.ini main + pshell development.ini main Python 2.4.5 (#1, Aug 29 2008, 12:27:37) [GCC 4.0.1 (Apple Inc. build 5465)] on darwin Type "help" for more information. "root" is the Pyramid app root object. @@ -289,7 +286,7 @@ Python interpreter shell unconditionally. .. code-block:: text [chrism@vitaminf shellenv]$ ../bin/paster --plugin=pyramid pshell \ - --disable-ipython MyProject.ini main + --disable-ipython development.ini main You should always use a section name argument that refers to the actual ``app`` section within the Paste configuration file that points @@ -319,7 +316,7 @@ The command you use to invoke the interactive shell should be: .. code-block:: text [chrism@vitaminf shellenv]$ ../bin/paster --plugin=pyramid pshell \ - MyProject.ini myapp + development.ini myapp If you use ``main`` as the section name argument instead of ``myapp`` against the above ``.ini`` file, an error will likely occur. Use the @@ -342,17 +339,17 @@ Running The Project Application Once a project is installed for development, you can run the application it represents using the ``paster serve`` command against the generated configuration file. In our case, this file is named -``MyProject.ini``: +``development.ini``: .. code-block:: text - $ ../bin/paster serve MyProject.ini + $ ../bin/paster serve development.ini Here's sample output from a run of ``paster serve``: .. code-block:: text - $ ../bin/paster serve MyProject.ini + $ ../bin/paster serve development.ini Starting server in PID 16601. serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 @@ -370,7 +367,7 @@ For example: .. code-block:: text - $ ../bin/paster serve MyProject.ini --reload + $ ../bin/paster serve development.ini --reload Starting subprocess with file monitor Starting server in PID 16601. serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 @@ -427,30 +424,31 @@ This is the page shown by default when you visit an unmodified The Project Structure --------------------- -Our generated :mod:`pyramid` ``pyramid_starter`` application is a -setuptools :term:`project` (named ``MyProject``), which contains a -Python :term:`package` (which is *also* named ``myproject``, but -lowercased; the paster template generates a project which contains a -package that shares its name except for case). All :mod:`pyramid` -``paster`` -generated projects share a similar structure. +Our generated :mod:`pyramid` ``pyramid_starter`` application is a setuptools +:term:`project` (named ``MyProject``), which contains a Python +:term:`package` (which is *also* named ``myproject``, but lowercased; the +paster template generates a project which contains a package that shares its +name except for case). All :mod:`pyramid` ``paster`` -generated projects +share a similar structure. The ``MyProject`` project we've generated has the following directory structure:: - MyProject/ + MyProject |-- CHANGES.txt - |-- README.txt + |-- development.ini |-- myproject | |-- __init__.py - | |-- configure.zcml | |-- models.py - | |-- run.py | |-- templates | | |-- mytemplate.pt - | | `-- static/ + | | `-- static + | | |-- favicon.ico + | | |-- logo.png + | | `-- pylons.css | |-- tests.py | `-- views.py - |-- MyProject.ini + |-- README.txt |-- setup.cfg `-- setup.py @@ -469,7 +467,7 @@ describe, run, and test your application. #. ``README.txt`` describes the application in general. It is conventionally written in :term:`ReStructuredText` format. -#. ``MyProject.ini`` is a :term:`PasteDeploy` configuration file that +#. ``development.ini`` is a :term:`PasteDeploy` configuration file that can be used to execute your application. #. ``setup.cfg`` is a :term:`setuptools` configuration file used by @@ -485,17 +483,16 @@ describe, run, and test your application. .. _MyProject_ini: -``MyProject.ini`` -~~~~~~~~~~~~~~~~~ +``development.ini`` +~~~~~~~~~~~~~~~~~~~ -The ``MyProject.ini`` file is a :term:`PasteDeploy` configuration -file. Its purpose is to specify an application to run when you invoke -``paster serve``, as well as the deployment settings provided to that -application. +The ``development.ini`` file is a :term:`PasteDeploy` configuration file. +Its purpose is to specify an application to run when you invoke ``paster +serve``, as well as the deployment settings provided to that application. -The generated ``MyProject.ini`` file looks like so: +The generated ``development.ini`` file looks like so: -.. literalinclude:: MyProject/MyProject.ini +.. literalinclude:: MyProject/development.ini :linenos: This file contains several "sections" including ``[DEFAULT]``, @@ -531,15 +528,15 @@ indicates that this is an entry point *URI* specifier, where the file. This string representation of an ``.ini`` file has a section named ``[paste.app_factory]``. Within this section, there is a key named ``app`` (the entry point name) which has a value - ``myproject.run:app``. The *key* ``app`` is what our + ``myproject:app``. The *key* ``app`` is what our ``egg:MyProject#app`` value of the ``use`` section in our config file is pointing at. The value represents a :term:`dotted Python name` path, which refers to a callable in our ``myproject`` - package's ``run.py`` module. In English, this entry point can thus + package's ``__init__.py`` module. In English, this entry point can thus be referred to as a "Paste application factory in the ``MyProject`` project which has the entry point named ``app`` where the entry - point refers to a ``app`` function in the ``mypackage.run`` - module". If indeed if you open up the ``run.py`` module generated + point refers to a ``app`` function in the ``mypackage`` + module". If indeed if you open up the ``__init__.py`` module generated within the ``myproject`` package, you'll see a ``app`` function. This is the function called by :term:`PasteDeploy` when the ``paster serve`` command is invoked against our application. It @@ -550,7 +547,7 @@ The ``use`` setting is the only setting required in the ``[app:main]`` section unless you've changed the callable referred to by the ``MyProject#app`` entry point to accept more arguments: other settings you add to this section are passed as keywords arguments to the -callable represented by this entry point (``app`` in our ``run.py`` +callable represented by this entry point (``app`` in our ``__init__.py`` module). You can provide startup-time configuration parameters to your application by requiring more settings in this section. @@ -649,7 +646,7 @@ always unpack as a directory, which is more convenient. depends on the ``pyramid`` package. ``test_suite`` points at the package for our application, which means all tests found in the package will be run when ``setup.py test`` is invoked. We examined -``entry_points`` in our discussion of the ``MyProject.ini`` file; this +``entry_points`` in our discussion of the ``development.ini`` file; this file defines the ``app`` entry point that represents our project's application. @@ -703,18 +700,12 @@ The ``myproject`` :term:`package` lives inside the ``MyProject`` :term:`project`. It contains: #. An ``__init__.py`` file which signifies that this is a Python - :term:`package`. It is conventionally empty, save for a single - comment at the top. - -#. A ``configure.zcml`` is a :term:`ZCML` file which maps view names - to model types. Its contents populate the :term:`application - registry` when loaded. + :term:`package`. It also contains code that helps users run the + application, include an ``app`` function which is used as a Paste entry + point. #. A ``models.py`` module, which contains :term:`model` code. -#. A ``run.py`` module, which contains code that helps users run the - application. - #. A ``templates`` directory, which contains :term:`Chameleon` (or other types of) templates. @@ -729,64 +720,52 @@ These are purely conventions established by the ``paster`` template: particular way. .. index:: - single: configure.zcml + single: __init__.py -``configure.zcml`` -~~~~~~~~~~~~~~~~~~ +``__init__.py`` +~~~~~~~~~~~~~~~ -The ``configure.zcml`` contains configuration statements that populate -the :term:`application registry`. It looks like so: +We need a small Python module that configures our application and which +advertises an entry point for use by our :term:`PasteDeploy` ``.ini`` file. +This is the file named ``__init__.py``. The presence of an ``__init__.py`` +also informs Python that the directory which contains it is a *package*. -.. literalinclude:: MyProject/myproject/configure.zcml +.. literalinclude:: MyProject/myproject/__init__.py :linenos: - :language: xml -#. Line 1 provides the root node and namespaces for the configuration - language. ``http://pylonshq.com/pyramid`` is the default XML - namespace. Add-on packages may require other namespaces. +#. Line 1 imports the :term:`Configurator` class from + :mod:`pyramid.configuration` that we use later. + +#. Line 2 imports the ``get_root`` function from + :mod:`myproject.models` that we use later. + +#. Lines 4-17 define a function that returns a :mod:`pyramid` + WSGI application. This function is meant to be called + by the :term:`PasteDeploy` framework as a result of running + ``paster serve``. -#. Line 3 initializes :mod:`pyramid` -specific configuration - directives by including the ``pyramid.includes`` package. This - causes all of the ZCML within the ``configure.zcml`` of the - ``pyramid.includes`` package to be "included" in this - configuration file's scope. Effectively this means that we can use - (for this example) the ``view`` and ``static`` directives which - follow later in this file. + Within this function, configuration is performed. -#. Lines 5-9 register a "default view" (a view that has no ``name`` + Lines 12-14 register a "default view" (a view that has no ``name`` attribute). It is registered so that it will be found when the :term:`context` of the request is an instance of the - :class:`myproject.models.MyModel` class. The ``view`` attribute - points at a Python function that does all the work for this view, - also known as a :term:`view callable`. Note that the values of - both the ``context`` attribute and the ``view`` attribute begin - with a single period. Names that begin with a period are - "shortcuts" which point at files relative to the :term:`package` in - which the ``configure.zcml`` file lives. In this case, since the - ``configure.zcml`` file lives within the :mod:`myproject` package, - the shortcut ``.models.MyModel`` could also be spelled - ``myproject.models.MyModel`` (forming a full Python dotted-path - name to the ``MyModel`` class). Likewise the shortcut - ``.views.my_view`` could be replaced with - ``myproject.views.my_view``. - - The view declaration also names a ``renderer``, which in this case - is a template that will be used to render the result of the view - callable. This particular view declaration points at - ``templates/mytemplate.pt``, which is a *relative* file - specification; it's relative to the directory in which the - ``configure.zcml`` file lives. The template file it points at is a - :term:`Chameleon` ZPT template file. - -#. Lines 11-14 register a static view, which will register a view - which serves up the files from the ``templates/static`` directory - relative to the directory in which the ``configure.zcml`` file - lives. - -#. Line 16 ends the ``configure`` root tag. - -.. index:: - single: views.py + :class:`myproject.models.MyModel` class. The first argument to + ``add_view`` points at a Python function that does all the work for this + view, also known as a :term:`view callable` via a :term:`dotted Python + name`. The view declaration also names a ``renderer``, which in this case + is a template that will be used to render the result of the view callable. + This particular view declaration points at + ``myproject:templates/mytemplate.pt``, which is a :term:`resource + specification` that specifies the ``mytemplate.pt`` file within the + ``templates`` directory of the ``myproject`` package. The template file + it actually points to is a :term:`Chameleon` ZPT template file. + + Line 15 registers a static view, which will serve up the files from the + ``mypackage:templates/static`` :term:`resource specification` (the + ``templates/static`` directory of the ``mypackage`` package). + + Line 17 returns a :term:`WSGI` application to the caller of the function + (Paste). ``views.py`` ~~~~~~~~~~~~ @@ -800,10 +779,10 @@ code which accepts a :term:`request` and which returns a .. literalinclude:: MyProject/myproject/views.py :linenos: -This bit of code was registered as the view callable within -``configure.zcml``. ``configure.zcml`` said that the default URL for -instances that are of the class :class:`myproject.models.MyModel` -should run this :func:`myproject.views.my_view` function. +This bit of code was registered as the view callable within ``__init__.py`` +(via ``add_view``). ``add_view`` said that the default URL for instances +that are of the class :class:`myproject.models.MyModel` should run this +:func:`myproject.views.my_view` function. This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the @@ -811,16 +790,16 @@ the :term:`request`. The *request* is an instance of the our server. This view returns a dictionary. When this view is invoked, a -:term:`renderer` converts the dictionary returned by the view into -HTML, and returns the result as the :term:`response`. This view is -configured to invoke a renderer which uses a :term:`Chameleon` ZPT -template (``templates/my_template.pt``, as specified in the -``configure.zcml`` file). +:term:`renderer` converts the dictionary returned by the view into HTML, and +returns the result as the :term:`response`. This view is configured to +invoke a renderer which uses a :term:`Chameleon` ZPT template +(``mypackage:templates/my_template.pt``, as specified in the ``__init__.py`` +file call to ``add_view``). -See :ref:`views_which_use_a_renderer` for more information about how -views, renderers, and templates relate and cooperate. +See :ref:`views_which_use_a_renderer` for more information about how views, +renderers, and templates relate and cooperate. -.. note:: because our ``MyProject.ini`` has a ``reload_templates = +.. note:: because our ``development.ini`` has a ``reload_templates = true`` directive indicating that templates should be reloaded when they change, you won't need to restart the application server to see changes you make to templates. During development, this is @@ -862,39 +841,14 @@ make any assumption about which sort of datastore you'll want to use, so the sample application uses an instance of :class:`myproject.models.MyModel` to represent the root. -.. index:: - single: run.py - -``run.py`` -~~~~~~~~~~ - -We need a small Python module that configures our application and -which advertises an entry point for use by our :term:`PasteDeploy` -``.ini`` file. This is the file named ``run.py``: - -.. literalinclude:: MyProject/myproject/run.py - :linenos: - -#. Line 1 imports the :term:`Configurator` class from - :mod:`pyramid.configuration` that we use later. - -#. Line 2 imports the ``get_root`` function from - :mod:`myproject.models` that we use later. - -#. Lines 4-13 define a function that returns a :mod:`pyramid` - WSGI application. This function is meant to be called - by the :term:`PasteDeploy` framework as a result of running - ``paster serve``. - ``templates/mytemplate.pt`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The single :term:`Chameleon` template exists in the project. Its -contents are too long to show here, but it displays a default page -when rendered. It is referenced by the ``view`` declaration's -``renderer`` attribute in the ``configure.zcml`` file. See -:ref:`views_which_use_a_renderer` for more information about -renderers. +The single :term:`Chameleon` template exists in the project. Its contents +are too long to show here, but it displays a default page when rendered. It +is referenced by the call to ``add_view`` as the ``renderer`` attribute in +the ``__init__`` file. See :ref:`views_which_use_a_renderer` for more +information about renderers. Templates are accessed and used by view configurations and sometimes by view functions themselves. See :ref:`templates_used_directly` and diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index c86a279ee..506504454 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -31,13 +31,13 @@ the purposes of this discussion, we'll assume that you are using this command to run your :mod:`pyramid` application. Here's a high-level time-ordered overview of what happens when you -press ``return`` after running ``paster serve MyProject.ini``. +press ``return`` after running ``paster serve development.ini``. #. The :term:`PasteDeploy` ``paster`` command is invoked under your - shell with the arguments ``serve`` and ``MyProject.ini``. As a + shell with the arguments ``serve`` and ``development.ini``. As a result, the :term:`PasteDeploy` framework recognizes that it is meant to begin to run and serve an application using the - information contained within the ``MyProject.ini`` file. + information contained within the ``development.ini`` file. #. The PasteDeploy framework finds a section named either ``[app:main]``, ``[pipeline:main]``, or ``[composite::main]`` in @@ -61,13 +61,13 @@ press ``return`` after running ``paster serve MyProject.ini``. constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. - For :mod:`pyramid` applications, the constructor will be a - function named ``app`` in the ``run.py`` file within the - :term:`package` in which your application lives. If this function - succeeds, it will return a :mod:`pyramid` :term:`router` - instance. Here's the contents of an example ``run.py`` module: + For :mod:`pyramid` applications, the constructor will be a function named + ``app`` in the ``__init__.py`` file within the :term:`package` in which + your application lives. If this function succeeds, it will return a + :mod:`pyramid` :term:`router` instance. Here's the contents of an example + ``__init__.py`` module: - .. literalinclude:: MyProject/myproject/run.py + .. literalinclude:: MyProject/myproject/__init__.py :linenos: Note that the constructor function accepts a ``global_config`` @@ -80,9 +80,9 @@ press ``return`` after running ``paster serve MyProject.ini``. the ``use=`` setting) when this function is called by the :term:`PasteDeploy` framework when you run ``paster serve``. - Our generated ``MyProject.ini`` file looks like so: + Our generated ``development.ini`` file looks like so: - .. literalinclude:: MyProject/MyProject.ini + .. literalinclude:: MyProject/development.ini :linenos: In this case, the ``myproject.run:app`` function referred to by the @@ -124,10 +124,10 @@ press ``return`` after running ``paster serve MyProject.ini``. emitted (see :ref:`events_chapter` for more information about events). -#. Assuming there were no errors, the ``app`` function in - ``myproject`` returns the router instance created by - ``make_wsgi_app`` back to PasteDeploy. As far as PasteDeploy is - concerned, it is "just another WSGI application". +#. Assuming there were no errors, the ``app`` function in ``myproject`` + returns the router instance created by ``make_wsgi_app`` back to + PasteDeploy. As far as PasteDeploy is concerned, it is "just another WSGI + application". #. PasteDeploy starts the WSGI *server* defined within the ``[server:main]`` section. In our case, this is the ``Paste#http`` -- cgit v1.2.3