From a54e4cf75402575ba7b12a03acc0738126c16e2d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 8 Oct 2015 23:52:05 -0700 Subject: wrap 79 cols --- docs/narr/firstapp.rst | 2 +- docs/narr/project.rst | 598 ++++++++++++++++++++++++------------------------- 2 files changed, 291 insertions(+), 309 deletions(-) (limited to 'docs') diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index b85c1f3d1..6a952dec9 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -190,7 +190,7 @@ WSGI Application Creation After configuring views and ending configuration, the script creates a WSGI *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app` method. - A call to ``make_wsgi_app`` implies that all configuration is finished +A call to ``make_wsgi_app`` implies that all configuration is finished (meaning all method calls to the configurator, which sets up views and various other configuration settings, have been performed). The ``make_wsgi_app`` method returns a :term:`WSGI` application object that can be used by any WSGI diff --git a/docs/narr/project.rst b/docs/narr/project.rst index c9e89aff4..25f3931e9 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -3,25 +3,24 @@ Creating a :app:`Pyramid` Project ================================= -As we saw in :ref:`firstapp_chapter`, it's possible to create a -:app:`Pyramid` application completely manually. However, it's usually more -convenient to use a :term:`scaffold` to generate a basic :app:`Pyramid` -:term:`project`. +As we saw in :ref:`firstapp_chapter`, it's possible to create a :app:`Pyramid` +application completely manually. However, it's usually more convenient to use +a :term:`scaffold` to generate a basic :app:`Pyramid` :term:`project`. A project is a directory that contains at least one Python :term:`package`. You'll use a scaffold to create a project, and you'll create your application -logic within a package that lives inside the project. Even if your -application is extremely simple, it is useful to place code that drives the -application within a package, because (1) a package is more easily extended -with new code, and (2) an application that lives inside a package can also be -distributed more easily than one which does not live within a package. +logic within a package that lives inside the project. Even if your application +is extremely simple, it is useful to place code that drives the application +within a package, because (1) a package is more easily extended with new code, +and (2) an application that lives inside a package can also be distributed more +easily than one which does not live within a package. -:app:`Pyramid` comes with a variety of scaffolds that you can use to generate -a project. Each scaffold makes different configuration assumptions about -what type of application you're trying to construct. +:app:`Pyramid` comes with a variety of scaffolds that you can use to generate a +project. Each scaffold makes different configuration assumptions about what +type of application you're trying to construct. -These scaffolds are rendered using the ``pcreate`` command that is installed -as part of Pyramid. +These scaffolds are rendered using the ``pcreate`` command that is installed as +part of Pyramid. .. index:: single: scaffolds @@ -34,11 +33,11 @@ as part of Pyramid. Scaffolds Included with :app:`Pyramid` -------------------------------------- -The convenience scaffolds included with :app:`Pyramid` differ from -each other on a number of axes: +The convenience scaffolds included with :app:`Pyramid` differ from each other +on a number of axes: -- the persistence mechanism they offer (no persistence mechanism, - :term:`ZODB`, or :term:`SQLAlchemy`) +- the persistence mechanism they offer (no persistence mechanism, :term:`ZODB`, + or :term:`SQLAlchemy`) - the mechanism they use to map URLs to code (:term:`traversal` or :term:`URL dispatch`) @@ -52,8 +51,7 @@ The included scaffolds are these: URL mapping via :term:`traversal` and persistence via :term:`ZODB` ``alchemy`` - URL mapping via :term:`URL dispatch` and persistence via - :term:`SQLAlchemy` + URL mapping via :term:`URL dispatch` and persistence via :term:`SQLAlchemy` .. index:: single: creating a project @@ -64,9 +62,9 @@ The included scaffolds are these: Creating the Project -------------------- -In :ref:`installing_chapter`, you created a virtual Python environment via -the ``virtualenv`` command. To start a :app:`Pyramid` :term:`project`, use -the ``pcreate`` command installed within the virtualenv. We'll choose the +In :ref:`installing_chapter`, you created a virtual Python environment via the +``virtualenv`` command. To start a :app:`Pyramid` :term:`project`, use the +``pcreate`` command installed within the virtualenv. We'll choose the ``starter`` scaffold for this purpose. When we invoke ``pcreate``, it will create a directory that represents our project. @@ -101,14 +99,14 @@ Here's sample output from a run of ``pcreate`` on UNIX for a project we name Running /Users/chrism/projects/pyramid/bin/python setup.py egg_info As a result of invoking the ``pcreate`` command, a directory named -``MyProject`` is created. That directory is a :term:`project` directory. -The ``setup.py`` file in that directory can be used to distribute your -application, or install your application for deployment or development. +``MyProject`` is created. That directory is a :term:`project` directory. The +``setup.py`` file in that directory can be used to distribute your application, +or install your application for deployment or development. A ``.ini`` file named ``development.ini`` will be created in the project -directory. You will use this ``.ini`` file to configure a server, to run -your application, and to debug your application. It contains configuration -that enables an interactive debugger and settings optimized for development. +directory. You will use this ``.ini`` file to configure a server, to run your +application, and to debug your application. It contains configuration that +enables an interactive debugger and settings optimized for development. Another ``.ini`` file named ``production.ini`` will also be created in the project directory. It contains configuration that disables any interactive @@ -117,28 +115,28 @@ number of debugging settings. You can use this file to put your application into production. The ``MyProject`` project directory contains an additional subdirectory named -``myproject`` (note the case difference) representing a Python -:term:`package` which holds very simple :app:`Pyramid` sample code. This is -where you'll edit your application's Python code and templates. - -We created this project within an ``env`` virtualenv directory. However, -note that this is not mandatory. The project directory can go more or less -anywhere on your filesystem. You don't need to put it in a special "web -server" directory, and you don't need to put it within a virtualenv -directory. The author uses Linux mainly, and tends to put project -directories which he creates within his ``~/projects`` directory. On -Windows, it's a good idea to put project directories within a directory that -contains no space characters, so it's wise to *avoid* a path that contains, -i.e., ``My Documents``. As a result, the author, when he uses Windows, just -puts his projects in ``C:\projects``. +``myproject`` (note the case difference) representing a Python :term:`package` +which holds very simple :app:`Pyramid` sample code. This is where you'll edit +your application's Python code and templates. + +We created this project within an ``env`` virtualenv directory. However, note +that this is not mandatory. The project directory can go more or less anywhere +on your filesystem. You don't need to put it in a special "web server" +directory, and you don't need to put it within a virtualenv directory. The +author uses Linux mainly, and tends to put project directories which he creates +within his ``~/projects`` directory. On Windows, it's a good idea to put +project directories within a directory that contains no space characters, so +it's wise to *avoid* a path that contains, i.e., ``My Documents``. As a +result, the author, when he uses Windows, just puts his projects in +``C:\projects``. .. warning:: You'll need to avoid using ``pcreate`` to create a project with the same name as a Python standard library component. In particular, this means you - should avoid using the names ``site`` or ``test``, both of which - conflict with Python standard library packages. You should also avoid - using the name ``pyramid``, which will conflict with Pyramid itself. + should avoid using the names ``site`` or ``test``, both of which conflict + with Python standard library packages. You should also avoid using the name + ``pyramid``, which will conflict with Pyramid itself. .. index:: single: setup.py develop @@ -153,10 +151,10 @@ newly created project directory and use the Python interpreter from the command ``python setup.py develop`` The file named ``setup.py`` will be in the root of the pcreate-generated -project directory. The ``python`` you're invoking should be the one that -lives in the ``bin`` (or ``Scripts`` on Windows) directory of your virtual -Python environment. Your terminal's current working directory *must* be the -newly created project directory. +project directory. The ``python`` you're invoking should be the one that lives +in the ``bin`` (or ``Scripts`` on Windows) directory of your virtual Python +environment. Your terminal's current working directory *must* be the newly +created project directory. On UNIX: @@ -181,10 +179,10 @@ Elided output from a run of this command on UNIX is shown below: ... Finished processing dependencies for MyProject==0.0 -This will install a :term:`distribution` representing your project -into the virtual environment interpreter's library set so it can be -found by ``import`` statements and by other console scripts such as -``pserve``, ``pshell``, ``proutes``, and ``pviews``. +This will install a :term:`distribution` representing your project into the +virtual environment interpreter's library set so it can be found by ``import`` +statements and by other console scripts such as ``pserve``, ``pshell``, +``proutes``, and ``pviews``. .. index:: single: running tests @@ -193,8 +191,8 @@ found by ``import`` statements and by other console scripts such as Running the Tests for Your Application -------------------------------------- -To run unit tests for your application, you should invoke them using the -Python interpreter from the :term:`virtualenv` you created during +To run unit tests for your application, you should invoke them using the Python +interpreter from the :term:`virtualenv` you created during :ref:`installing_chapter` (the ``python`` command that lives in the ``bin`` directory of your virtualenv). @@ -278,12 +276,12 @@ Here's sample output from a run of ``pserve`` on UNIX: When you use ``pserve`` to start the application implied by the default rendering of a scaffold, it will respond to requests on *all* IP addresses -possessed by your system, not just requests to ``localhost``. This is what -the ``0.0.0.0`` in ``serving on http://0.0.0.0:6543`` means. The server will -respond to requests made to ``127.0.0.1`` and on any external IP address. -For example, your system might be configured to have an external IP address -``192.168.1.50``. If that's the case, if you use a browser running on the -same system as Pyramid, it will be able to access the application via +possessed by your system, not just requests to ``localhost``. This is what the +``0.0.0.0`` in ``serving on http://0.0.0.0:6543`` means. The server will +respond to requests made to ``127.0.0.1`` and on any external IP address. For +example, your system might be configured to have an external IP address +``192.168.1.50``. If that's the case, if you use a browser running on the same +system as Pyramid, it will be able to access the application via ``http://127.0.0.1:6543/`` as well as via ``http://192.168.1.50:6543/``. However, *other people* on other computers on the same network will also be able to visit your Pyramid application in their browser by visiting @@ -305,28 +303,26 @@ example: You can change the port on which the server runs on by changing the same portion of the ``development.ini`` file. For example, you can change the ``port = 6543`` line in the ``development.ini`` file's ``[server:main]`` -section to ``port = 8080`` to run the server on port 8080 instead of -port 6543. +section to ``port = 8080`` to run the server on port 8080 instead of port 6543. You can shut down a server started this way by pressing ``Ctrl-C`` (or ``Ctrl-Break`` on Windows). The default server used to run your Pyramid application when a project is -created from a scaffold is named :term:`Waitress`. This server is what -prints the ``serving on...`` line when you run ``pserve``. It's a good idea -to use this server during development because it's very simple. It can also -be used for light production. Setting your application up under a different -server is not advised until you've done some development work under the -default server, particularly if you're not yet experienced with Python web -development. Python web server setup can be complex, and you should get some -confidence that your application works in a default environment before trying -to optimize it or make it "more like production". It's awfully easy to get -sidetracked trying to set up a non-default server for hours without actually -starting to do any development. One of the nice things about Python web -servers is that they're largely interchangeable, so if your application works -under the default server, it will almost certainly work under any other -server in production if you eventually choose to use a different one. Don't -worry about it right now. +created from a scaffold is named :term:`Waitress`. This server is what prints +the ``serving on...`` line when you run ``pserve``. It's a good idea to use +this server during development because it's very simple. It can also be used +for light production. Setting your application up under a different server is +not advised until you've done some development work under the default server, +particularly if you're not yet experienced with Python web development. Python +web server setup can be complex, and you should get some confidence that your +application works in a default environment before trying to optimize it or make +it "more like production". It's awfully easy to get sidetracked trying to set +up a non-default server for hours without actually starting to do any +development. One of the nice things about Python web servers is that they're +largely interchangeable, so if your application works under the default server, +it will almost certainly work under any other server in production if you +eventually choose to use a different one. Don't worry about it right now. For more detailed information about the startup process, see :ref:`startup_chapter`. For more information about environment variables and @@ -338,10 +334,10 @@ configuration file settings that influence startup and runtime behavior, see Reloading Code ~~~~~~~~~~~~~~ -During development, it's often useful to run ``pserve`` using its -``--reload`` option. When ``--reload`` is passed to ``pserve``, changes to -any Python module your project uses will cause the server to restart. This -typically makes development easier, as changes to Python code made within a +During development, it's often useful to run ``pserve`` using its ``--reload`` +option. When ``--reload`` is passed to ``pserve``, changes to any Python +module your project uses will cause the server to restart. This typically +makes development easier, as changes to Python code made within a :app:`Pyramid` application is not put into effect until the server restarts. For example, on UNIX: @@ -364,10 +360,10 @@ files, you'll see the server restart automatically: serving on http://0.0.0.0:6543 Changes to template files (such as ``.pt`` or ``.mak`` files) won't cause the -server to restart. Changes to template files don't require a server restart -as long as the ``pyramid.reload_templates`` setting in the -``development.ini`` file is ``true``. Changes made to template files when -this setting is true will take effect immediately without a server restart. +server to restart. Changes to template files don't require a server restart as +long as the ``pyramid.reload_templates`` setting in the ``development.ini`` +file is ``true``. Changes made to template files when this setting is true +will take effect immediately without a server restart. .. index:: single: WSGI @@ -396,22 +392,21 @@ The Debug Toolbar If you click on the :app:`Pyramid` logo at the top right of the page, a new target window will open to present a debug toolbar that provides various -niceties while you're developing. This logo will float above every HTML -page served by :app:`Pyramid` while you develop an application, and allows -you to show the toolbar as necessary. +niceties while you're developing. This logo will float above every HTML page +served by :app:`Pyramid` while you develop an application, and allows you to +show the toolbar as necessary. .. image:: project-debug.png -If you don't see the Pyramid logo on the top right of the page, it means -you're browsing from a system that does not have debugging access. By -default, for security reasons, only a browser originating from ``localhost`` -(``127.0.0.1``) can see the debug toolbar. To allow your browser on a -remote system to access the server, add a line within the ``[app:main]`` -section of the ``development.ini`` file in the form ``debugtoolbar.hosts = X -.X.X.X``. For example, if your Pyramid application is running on a remote -system, and you're browsing from a host with the IP address ``192.168.1.1``, -you'd add something like this to enable the toolbar when your system -contacts Pyramid: +If you don't see the Pyramid logo on the top right of the page, it means you're +browsing from a system that does not have debugging access. By default, for +security reasons, only a browser originating from ``localhost`` (``127.0.0.1``) +can see the debug toolbar. To allow your browser on a remote system to access +the server, add a line within the ``[app:main]`` section of the +``development.ini`` file in the form ``debugtoolbar.hosts = X .X.X.X``. For +example, if your Pyramid application is running on a remote system, and you're +browsing from a host with the IP address ``192.168.1.1``, you'd add something +like this to enable the toolbar when your system contacts Pyramid: .. code-block:: ini @@ -423,9 +418,9 @@ For more information about what the debug toolbar allows you to do, see `the documentation for pyramid_debugtoolbar `_. -The debug toolbar will not be shown (and all debugging will be turned off) -when you use the ``production.ini`` file instead of the ``development.ini`` -ini file to run the application. +The debug toolbar will not be shown (and all debugging will be turned off) when +you use the ``production.ini`` file instead of the ``development.ini`` ini file +to run the application. You can also turn the debug toolbar off by editing ``development.ini`` and commenting out a line. For example, instead of: @@ -451,9 +446,9 @@ Put a hash mark at the beginning of the ``pyramid_debugtoolbar`` line: Then restart the application to see that the toolbar has been turned off. Note that if you comment out the ``pyramid_debugtoolbar`` line, the ``#`` -*must* be in the first column. If you put it anywhere else, and then -attempt to restart the application, you'll receive an error that ends -something like this: +*must* be in the first column. If you put it anywhere else, and then attempt +to restart the application, you'll receive an error that ends something like +this: .. code-block:: text @@ -471,8 +466,7 @@ which contains a Python :term:`package`. The package is *also* named contains a package that shares its name except for case. All :app:`Pyramid` ``pcreate``-generated projects share a similar structure. -The ``MyProject`` project we've generated has the following directory -structure: +The ``MyProject`` project we've generated has the following directory structure: .. code-block:: text @@ -498,29 +492,29 @@ structure: The ``MyProject`` :term:`Project` --------------------------------- -The ``MyProject`` :term:`project` directory is the distribution and -deployment wrapper for your application. It contains both the ``myproject`` +The ``MyProject`` :term:`project` directory is the distribution and deployment +wrapper for your application. It contains both the ``myproject`` :term:`package` representing your application as well as files used to describe, run, and test your application. -#. ``CHANGES.txt`` describes the changes you've made to the application. It - is conventionally written in :term:`ReStructuredText` format. +#. ``CHANGES.txt`` describes the changes you've made to the application. It is + conventionally written in :term:`ReStructuredText` format. #. ``README.txt`` describes the application in general. It is conventionally written in :term:`ReStructuredText` format. -#. ``development.ini`` is a :term:`PasteDeploy` configuration file that can - be used to execute your application during development. +#. ``development.ini`` is a :term:`PasteDeploy` configuration file that can be + used to execute your application during development. -#. ``production.ini`` is a :term:`PasteDeploy` configuration file that can - be used to execute your application in a production configuration. +#. ``production.ini`` is a :term:`PasteDeploy` configuration file that can be + used to execute your application in a production configuration. #. ``MANIFEST.in`` is a :term:`distutils` "manifest" file, naming which files should be included in a source distribution of the package when ``python setup.py sdist`` is run. -#. ``setup.py`` is the file you'll use to test and distribute your - application. It is a standard :term:`setuptools` ``setup.py`` file. +#. ``setup.py`` is the file you'll use to test and distribute your application. + It is a standard :term:`setuptools` ``setup.py`` file. .. index:: single: PasteDeploy @@ -531,9 +525,9 @@ describe, run, and test your application. ``development.ini`` ~~~~~~~~~~~~~~~~~~~ -The ``development.ini`` file is a :term:`PasteDeploy` configuration file. -Its purpose is to specify an application to run when you invoke ``pserve``, -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 ``pserve``, as well +as the deployment settings provided to that application. The generated ``development.ini`` file looks like so: @@ -542,33 +536,32 @@ The generated ``development.ini`` file looks like so: :linenos: This file contains several sections including ``[app:main]``, -``[server:main]``, and several other sections related to logging -configuration. +``[server:main]``, and several other sections related to logging configuration. The ``[app:main]`` section represents configuration for your :app:`Pyramid` -application. The ``use`` setting is the only setting required to be present -in the ``[app:main]`` section. Its default value, ``egg:MyProject``, -indicates that our MyProject project contains the application that should be -served. Other settings added to this section are passed as keyword arguments -to the function named ``main`` in our package's ``__init__.py`` module. You -can provide startup-time configuration parameters to your application by -adding more settings to this section. +application. The ``use`` setting is the only setting required to be present in +the ``[app:main]`` section. Its default value, ``egg:MyProject``, indicates +that our MyProject project contains the application that should be served. +Other settings added to this section are passed as keyword arguments to the +function named ``main`` in our package's ``__init__.py`` module. You can +provide startup-time configuration parameters to your application by adding +more settings to this section. .. seealso:: See :ref:`pastedeploy_entry_points` for more information about the meaning of the ``use = egg:MyProject`` value in this section. The ``pyramid.reload_templates`` setting in the ``[app:main]`` section is a :app:`Pyramid`-specific setting which is passed into the framework. If it -exists, and its value is ``true``, supported template changes will not -require an application restart to be detected. See -:ref:`reload_templates_section` for more information. +exists, and its value is ``true``, supported template changes will not require +an application restart to be detected. See :ref:`reload_templates_section` for +more information. .. warning:: The ``pyramid.reload_templates`` option should be turned off for production applications, as template rendering is slowed when it is turned on. -The ``pyramid.includes`` setting in the ``[app:main]`` section tells Pyramid -to "include" configuration from another package. In this case, the line +The ``pyramid.includes`` setting in the ``[app:main]`` section tells Pyramid to +"include" configuration from another package. In this case, the line ``pyramid.includes = pyramid_debugtoolbar`` tells Pyramid to include configuration from the ``pyramid_debugtoolbar`` package. This turns on a debugging panel in development mode which can be opened by clicking on the @@ -576,14 +569,14 @@ debugging panel in development mode which can be opened by clicking on the toolbar will also make it possible to interactively debug exceptions when an error occurs. -Various other settings may exist in this section having to do with debugging -or influencing runtime behavior of a :app:`Pyramid` application. See +Various other settings may exist in this section having to do with debugging or +influencing runtime behavior of a :app:`Pyramid` application. See :ref:`environment_chapter` for more information about these settings. The name ``main`` in ``[app:main]`` signifies that this is the default application run by ``pserve`` when it is invoked against this configuration -file. The name ``main`` is a convention used by PasteDeploy signifying that -it is the default application. +file. The name ``main`` is a convention used by PasteDeploy signifying that it +is the default application. The ``[server:main]`` section of the configuration file configures a WSGI server which listens on TCP port 6543. It is configured to listen on all @@ -594,14 +587,12 @@ access to your system can see your Pyramid application. The sections that live between the markers ``# Begin logging configuration`` and ``# End logging configuration`` represent Python's standard library -:mod:`logging` module configuration for your application. The sections -between these two markers are passed to the `logging module's config file -configuration engine -`_ when the -``pserve`` or ``pshell`` commands are executed. The default configuration -sends application logging output to the standard error output of your -terminal. For more information about logging configuration, see -:ref:`logging_chapter`. +:mod:`logging` module configuration for your application. The sections between +these two markers are passed to the `logging module's config file configuration +engine `_ when +the ``pserve`` or ``pshell`` commands are executed. The default configuration +sends application logging output to the standard error output of your terminal. +For more information about logging configuration, see :ref:`logging_chapter`. See the :term:`PasteDeploy` documentation for more information about other types of things you can put into this ``.ini`` file, such as other @@ -614,20 +605,20 @@ implementations. ``production.ini`` ~~~~~~~~~~~~~~~~~~ -The ``production.ini`` file is a :term:`PasteDeploy` configuration file with -a purpose much like that of ``development.ini``. However, it disables the -debug toolbar, and filters all log messages except those above the WARN -level. It also turns off template development options such that templates -are not automatically reloaded when changed, and turns off all debugging -options. This file is appropriate to use instead of ``development.ini`` when -you put your application into production. +The ``production.ini`` file is a :term:`PasteDeploy` configuration file with a +purpose much like that of ``development.ini``. However, it disables the debug +toolbar, and filters all log messages except those above the WARN level. It +also turns off template development options such that templates are not +automatically reloaded when changed, and turns off all debugging options. This +file is appropriate to use instead of ``development.ini`` when you put your +application into production. It's important to use ``production.ini`` (and *not* ``development.ini``) to benchmark your application and put it into production. ``development.ini`` configures your system with a debug toolbar that helps development, but the inclusion of this toolbar slows down page rendering times by over an order of -magnitude. The debug toolbar is also a potential security risk if you have -it configured incorrectly. +magnitude. The debug toolbar is also a potential security risk if you have it +configured incorrectly. .. index:: single: MANIFEST.in @@ -639,42 +630,40 @@ The ``MANIFEST.in`` file is a :term:`distutils` configuration file which specifies the non-Python files that should be included when a :term:`distribution` of your Pyramid project is created when you run ``python setup.py sdist``. Due to the information contained in the default -``MANIFEST.in``, an sdist of your Pyramid project will include ``.txt`` -files, ``.ini`` files, ``.rst`` files, graphics files, and template files, as -well as ``.py`` files. See +``MANIFEST.in``, an sdist of your Pyramid project will include ``.txt`` files, +``.ini`` files, ``.rst`` files, graphics files, and template files, as well as +``.py`` files. See http://docs.python.org/distutils/sourcedist.html#the-manifest-in-template for more information about the syntax and usage of ``MANIFEST.in``. -Without the presence of a ``MANIFEST.in`` file or without checking your -source code into a version control repository, ``setup.py sdist`` places only -*Python source files* (files ending with a ``.py`` extension) into tarballs -generated by ``python setup.py sdist``. This means, for example, if your -project was not checked into a setuptools-compatible source control system, -and your project directory didn't contain a ``MANIFEST.in`` file that told -the ``sdist`` machinery to include ``*.pt`` files, the -``myproject/templates/mytemplate.pt`` file would not be included in the -generated tarball. - -Projects generated by Pyramid scaffolds include a default ``MANIFEST.in`` -file. The ``MANIFEST.in`` file contains declarations which tell it to -include files like ``*.pt``, ``*.css`` and ``*.js`` in the generated tarball. -If you include files with extensions other than the files named in the -project's ``MANIFEST.in`` and you don't make use of a setuptools-compatible -version control system, you'll need to edit the ``MANIFEST.in`` file and -include the statements necessary to include your new files. See -http://docs.python.org/distutils/sourcedist.html#principle for more -information about how to do this. - -You can also delete ``MANIFEST.in`` from your project and rely on a -setuptools feature which simply causes all files checked into a version -control system to be put into the generated tarball. To allow this to -happen, check all the files that you'd like to be distributed along with your -application's Python files into Subversion. After you do this, when you -rerun ``setup.py sdist``, all files checked into the version control system -will be included in the tarball. If you don't use Subversion, and instead -use a different version control system, you may need to install a setuptools -add-on such as ``setuptools-git`` or ``setuptools-hg`` for this behavior to -work properly. +Without the presence of a ``MANIFEST.in`` file or without checking your source +code into a version control repository, ``setup.py sdist`` places only *Python +source files* (files ending with a ``.py`` extension) into tarballs generated +by ``python setup.py sdist``. This means, for example, if your project was not +checked into a setuptools-compatible source control system, and your project +directory didn't contain a ``MANIFEST.in`` file that told the ``sdist`` +machinery to include ``*.pt`` files, the ``myproject/templates/mytemplate.pt`` +file would not be included in the generated tarball. + +Projects generated by Pyramid scaffolds include a default ``MANIFEST.in`` file. +The ``MANIFEST.in`` file contains declarations which tell it to include files +like ``*.pt``, ``*.css`` and ``*.js`` in the generated tarball. If you include +files with extensions other than the files named in the project's +``MANIFEST.in`` and you don't make use of a setuptools-compatible version +control system, you'll need to edit the ``MANIFEST.in`` file and include the +statements necessary to include your new files. See +http://docs.python.org/distutils/sourcedist.html#principle for more information +about how to do this. + +You can also delete ``MANIFEST.in`` from your project and rely on a setuptools +feature which simply causes all files checked into a version control system to +be put into the generated tarball. To allow this to happen, check all the +files that you'd like to be distributed along with your application's Python +files into Subversion. After you do this, when you rerun ``setup.py sdist``, +all files checked into the version control system will be included in the +tarball. If you don't use Subversion, and instead use a different version +control system, you may need to install a setuptools add-on such as +``setuptools-git`` or ``setuptools-hg`` for this behavior to work properly. .. index:: single: setup.py @@ -688,11 +677,11 @@ testing, packaging, and distributing your application. .. note:: - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - `_ and `The - Hitchhiker's Guide to Packaging `_. + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + `_ and `The Hitchhiker's + Guide to Packaging `_. Our generated ``setup.py`` looks like this: @@ -701,47 +690,47 @@ Our generated ``setup.py`` looks like this: :linenos: The ``setup.py`` file calls the setuptools ``setup`` function, which does -various things depending on the arguments passed to ``setup.py`` on the -command line. +various things depending on the arguments passed to ``setup.py`` on the command +line. -Within the arguments to this function call, information about your -application is kept. While it's beyond the scope of this documentation to -explain everything about setuptools setup files, we'll provide a whirlwind -tour of what exists in this file in this section. +Within the arguments to this function call, information about your application +is kept. While it's beyond the scope of this documentation to explain +everything about setuptools setup files, we'll provide a whirlwind tour of what +exists in this file in this section. Your application's name can be any string; it is specified in the ``name`` field. The version number is specified in the ``version`` value. A short -description is provided in the ``description`` field. The -``long_description`` is conventionally the content of the README and CHANGES -file appended together. The ``classifiers`` field is a list of `Trove +description is provided in the ``description`` field. The ``long_description`` +is conventionally the content of the README and CHANGES file appended together. +The ``classifiers`` field is a list of `Trove `_ classifiers describing your application. ``author`` and ``author_email`` are text fields which probably don't need any description. ``url`` is a field 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 that this package is not safe -to use as a zipped egg; instead it will always unpack as a directory, which -is more convenient. ``install_requires`` and ``tests_require`` indicate that -this package 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 ``development.ini`` file; this file defines the -``main`` entry point that represents our project's application. - -Usually you only need to think about the contents of the ``setup.py`` file -when distributing your application to other people, when adding Python -package dependencies, or when versioning your application for your own use. -For fun, you can try this command now: +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 that this package is not safe to use as a zipped egg; +instead it will always unpack as a directory, which is more convenient. +``install_requires`` and ``tests_require`` indicate that this package 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 ``development.ini`` file; this file defines the ``main`` entry point +that represents our project's application. + +Usually you only need to think about the contents of the ``setup.py`` file when +distributing your application to other people, when adding Python package +dependencies, or when versioning your application for your own use. For fun, +you can try this command now: .. code-block:: text $ $VENV/bin/python setup.py sdist -This will create a tarball of your application in a ``dist`` subdirectory -named ``MyProject-0.1.tar.gz``. You can send this tarball to other people -who want to install and use your application. +This will create a tarball of your application in a ``dist`` subdirectory named +``MyProject-0.1.tar.gz``. You can send this tarball to other people who want +to install and use your application. .. index:: single: package @@ -752,19 +741,17 @@ The ``myproject`` :term:`Package` The ``myproject`` :term:`package` lives inside the ``MyProject`` :term:`project`. It contains: -#. An ``__init__.py`` file signifies that this is a Python :term:`package`. - It also contains code that helps users run the application, including a +#. An ``__init__.py`` file signifies that this is a Python :term:`package`. It + also contains code that helps users run the application, including a ``main`` function which is used as a entry point for commands such as ``pserve``, ``pshell``, ``pviews``, and others. -#. A ``templates`` directory, which contains :term:`Chameleon` (or - other types of) templates. +#. A ``templates`` directory, which contains :term:`Chameleon` (or other types + of) templates. -#. A ``tests.py`` module, which contains unit test code for the - application. +#. A ``tests.py`` module, which contains unit test code for the application. -#. A ``views.py`` module, which contains view code for the - application. +#. A ``views.py`` module, which contains view code for the application. These are purely conventions established by the scaffold. :app:`Pyramid` doesn't insist that you name things in any particular way. However, it's @@ -803,11 +790,11 @@ also informs Python that the directory which contains it is a *package*. specify renderers with the ``.pt`` extension. Line 9 registers a static view, which will serve up the files from the - ``myproject:static`` :term:`asset specification` (the ``static`` - directory of the ``myproject`` package). + ``myproject:static`` :term:`asset specification` (the ``static`` directory + of the ``myproject`` package). - Line 10 adds a :term:`route` to the configuration. This route is later - used by a view in the ``views`` module. + Line 10 adds a :term:`route` to the configuration. This route is later used + by a view in the ``views`` module. Line 11 calls ``config.scan()``, which picks up view registrations declared elsewhere in the package (in this case, in the ``views.py`` module). @@ -823,38 +810,37 @@ also informs Python that the directory which contains it is a *package*. Much of the heavy lifting in a :app:`Pyramid` application is done by *view callables*. A :term:`view callable` is the main tool of a :app:`Pyramid` web -application developer; it is a bit of code which accepts a :term:`request` -and which returns a :term:`response`. +application developer; it is a bit of code which accepts a :term:`request` and +which returns a :term:`response`. .. literalinclude:: MyProject/myproject/views.py :language: python :linenos: Lines 4-6 define and register a :term:`view callable` named ``my_view``. The -function named ``my_view`` is decorated with a ``view_config`` decorator -(which is processed by the ``config.scan()`` line in our ``__init__.py``). -The view_config decorator asserts that this view be found when a -:term:`route` named ``home`` is matched. In our case, because our -``__init__.py`` maps the route named ``home`` to the URL pattern ``/``, this -route will match when a visitor visits the root URL. The view_config -decorator 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 an :term:`asset -specification` that specifies the ``mytemplate.pt`` file within the -``templates`` directory of the ``myproject`` package. The asset -specification could have also been specified as -``myproject:templates/mytemplate.pt``; the leading package name and colon is +function named ``my_view`` is decorated with a ``view_config`` decorator (which +is processed by the ``config.scan()`` line in our ``__init__.py``). The +view_config decorator asserts that this view be found when a :term:`route` +named ``home`` is matched. In our case, because our ``__init__.py`` maps the +route named ``home`` to the URL pattern ``/``, this route will match when a +visitor visits the root URL. The view_config decorator 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 an :term:`asset specification` that +specifies the ``mytemplate.pt`` file within the ``templates`` directory of the +``myproject`` package. The asset specification could have also been specified +as ``myproject:templates/mytemplate.pt``; the leading package name and colon is optional. The template file pointed to is a :term:`Chameleon` ZPT template file (``templates/my_template.pt``). This view callable function is handed a single piece of information: the -:term:`request`. The *request* is an instance of the :term:`WebOb` -``Request`` class representing the browser's request to our server. +:term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` +class representing the browser's request to our server. This view is configured to invoke a :term:`renderer` on a template. The dictionary the view returns (on line 6) provides the value the renderer -substitutes into the template when generating HTML. The renderer then -returns the HTML in a :term:`response`. +substitutes into the template when generating HTML. The renderer then returns +the HTML in a :term:`response`. .. note:: Dictionaries provide values to :term:`template`\s. @@ -863,8 +849,8 @@ returns the HTML in a :term:`response`. ` to aid debugging. If an exception is raised, uncaught tracebacks are displayed after the startup messages on :ref:`the console running the server `. Also - ``print()`` statements may be inserted into the application for debugging - to send output to this console. + ``print()`` statements may be inserted into the application for debugging to + send output to this console. .. note:: ``development.ini`` has a setting that controls how templates are reloaded, ``pyramid.reload_templates``. @@ -873,14 +859,14 @@ returns the HTML in a :term:`response`. templates automatically reload without a server restart. This is convenient while developing, but slows template rendering speed. - - When set to ``False`` (the default value), changing templates requires - a server restart to reload them. Production applications should use + - When set to ``False`` (the default value), changing templates requires a + server restart to reload them. Production applications should use ``pyramid.reload_templates = False``. .. seealso:: - See also :ref:`views_which_use_a_renderer` for more information - about how views, renderers, and templates relate and cooperate. + See also :ref:`views_which_use_a_renderer` for more information about how + views, renderers, and templates relate and cooperate. .. seealso:: @@ -908,8 +894,8 @@ template. It includes CSS and images. This is the single :term:`Chameleon` template that 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 ``@view_config`` as the -``renderer`` of the ``my_view`` view callable in the ``views.py`` file. See +rendered. It is referenced by the call to ``@view_config`` as the ``renderer`` +of the ``my_view`` view callable in the ``views.py`` 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 @@ -930,10 +916,9 @@ The ``tests.py`` module includes unit tests for your application. :linenos: This sample ``tests.py`` file has a single unit test defined within it. This -test is executed when you run ``python setup.py test``. You may add more -tests here as you build your application. You are not required to write -tests to use :app:`Pyramid`. This file is simply provided for convenience and -example. +test is executed when you run ``python setup.py test``. You may add more tests +here as you build your application. You are not required to write tests to use +:app:`Pyramid`. This file is simply provided for convenience and example. See :ref:`testing_chapter` for more information about writing :app:`Pyramid` unit tests. @@ -947,28 +932,27 @@ Modifying Package Structure --------------------------- It is best practice for your application's code layout to not stray too much -from accepted Pyramid scaffold defaults. If you refrain from changing -things very much, other Pyramid coders will be able to more quickly -understand your application. However, the code layout choices made for you -by a scaffold are in no way magical or required. Despite the choices -made for you by any scaffold, you can decide to lay your code out any -way you see fit. +from accepted Pyramid scaffold defaults. If you refrain from changing things +very much, other Pyramid coders will be able to more quickly understand your +application. However, the code layout choices made for you by a scaffold are +in no way magical or required. Despite the choices made for you by any +scaffold, you can decide to lay your code out any way you see fit. For example, the configuration method named :meth:`~pyramid.config.Configurator.add_view` requires you to pass a :term:`dotted Python name` or a direct object reference as the class or -function to be used as a view. By default, the ``starter`` scaffold would -have you add view functions to the ``views.py`` module in your package. -However, you might be more comfortable creating a ``views`` *directory*, and -adding a single file for each view. +function to be used as a view. By default, the ``starter`` scaffold would have +you add view functions to the ``views.py`` module in your package. However, you +might be more comfortable creating a ``views`` *directory*, and adding a single +file for each view. If your project package name was ``myproject`` and you wanted to arrange all your views in a Python subpackage within the ``myproject`` :term:`package` named ``views`` instead of within a single ``views.py`` file, you might do the following. -- Create a ``views`` directory inside your ``myproject`` package directory - (the same directory which holds ``views.py``). +- Create a ``views`` directory inside your ``myproject`` package directory (the + same directory which holds ``views.py``). - Create a file within the new ``views`` directory named ``__init__.py``. (It can be empty. This just tells Python that the ``views`` directory is a @@ -980,20 +964,19 @@ following. specification` values in ``blog.py`` must now be fully qualified with the project's package name (``myproject:templates/blog.pt``). -You can then continue to add view callable functions to the ``blog.py`` -module, but you can also add other ``.py`` files which contain view callable -functions to the ``views`` directory. As long as you use the -``@view_config`` directive to register views in conjunction with -``config.scan()``, they will be picked up automatically when the application is -restarted. +You can then continue to add view callable functions to the ``blog.py`` module, +but you can also add other ``.py`` files which contain view callable functions +to the ``views`` directory. As long as you use the ``@view_config`` directive +to register views in conjunction with ``config.scan()``, they will be picked up +automatically when the application is restarted. Using the Interactive Shell --------------------------- It is possible to use the ``pshell`` command to load a Python interpreter -prompt with a similar configuration as would be loaded if you were running -your Pyramid application via ``pserve``. This can be a useful debugging tool. -See :ref:`interactive_shell` for more details. +prompt with a similar configuration as would be loaded if you were running your +Pyramid application via ``pserve``. This can be a useful debugging tool. See +:ref:`interactive_shell` for more details. .. _what_is_this_pserve_thing: @@ -1022,30 +1005,29 @@ restarting of the server when code changes. Using an Alternate WSGI Server ------------------------------ -Pyramid scaffolds generate projects which use the :term:`Waitress` WSGI -server. Waitress is a server that is suited for development and light -production usage. It's not the fastest nor the most featureful WSGI server. -Instead, its main feature is that it works on all platforms that Pyramid -needs to run on, making it a good choice as a default server from the -perspective of Pyramid's developers. +Pyramid scaffolds generate projects which use the :term:`Waitress` WSGI server. +Waitress is a server that is suited for development and light production +usage. It's not the fastest nor the most featureful WSGI server. Instead, its +main feature is that it works on all platforms that Pyramid needs to run on, +making it a good choice as a default server from the perspective of Pyramid's +developers. Any WSGI server is capable of running a :app:`Pyramid` application. But we -suggest you stick with the default server for development, and that you wait -to investigate other server options until you're ready to deploy your -application to production. Unless for some reason you need to develop on a -non-local system, investigating alternate server options is usually a -distraction until you're ready to deploy. But we recommend developing using -the default configuration on a local system that you have complete control -over; it will provide the best development experience. +suggest you stick with the default server for development, and that you wait to +investigate other server options until you're ready to deploy your application +to production. Unless for some reason you need to develop on a non-local +system, investigating alternate server options is usually a distraction until +you're ready to deploy. But we recommend developing using the default +configuration on a local system that you have complete control over; it will +provide the best development experience. One popular production alternative to the default Waitress server is -:term:`mod_wsgi`. You can use mod_wsgi to serve your :app:`Pyramid` -application using the Apache web server rather than any "pure-Python" server -like Waitress. It is fast and featureful. See :ref:`modwsgi_tutorial` for -details. +:term:`mod_wsgi`. You can use mod_wsgi to serve your :app:`Pyramid` application +using the Apache web server rather than any "pure-Python" server like Waitress. +It is fast and featureful. See :ref:`modwsgi_tutorial` for details. Another good production alternative is :term:`Green Unicorn` (aka -``gunicorn``). It's faster than Waitress and slightly easier to configure -than mod_wsgi, although it depends, in its default configuration, on having a -buffering HTTP proxy in front of it. It does not, as of this writing, work -on Windows. +``gunicorn``). It's faster than Waitress and slightly easier to configure than +mod_wsgi, although it depends, in its default configuration, on having a +buffering HTTP proxy in front of it. It does not, as of this writing, work on +Windows. -- cgit v1.2.3