diff options
Diffstat (limited to 'docs/source/quick_start.rst')
| -rw-r--r-- | docs/source/quick_start.rst | 106 |
1 files changed, 60 insertions, 46 deletions
diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst index f0a52ed..2907885 100644 --- a/docs/source/quick_start.rst +++ b/docs/source/quick_start.rst @@ -7,29 +7,32 @@ Let's create a small sample project with Pecan. .. note:: This guide does not cover the installation of Pecan. If you need - instructions for installing Pecan, go to :ref:`installation`. + instructions for installing Pecan, refer to :ref:`installation`. .. _app_template: Base Application Template ------------------------- -A basic template for getting started is included with Pecan. From -your shell, type:: +Pecan includes a basic template for starting a new project. From your +shell, type:: $ pecan create test_project This example uses *test_project* as your project name, but you can replace it with any valid Python package name you like. -Go ahead and change into your newly created project directory. You'll want to -deploy it in "development mode", such that it’s available on ``sys.path``, yet -can still be edited directly from its source distribution:: +Go ahead and change into your newly created project directory.:: $ cd test_project + +You'll want to deploy it in "development mode", such that it’s +available on ``sys.path``, yet can still be edited directly from its +source distribution:: + $ python setup.py develop -This is how the layout of your new project should look:: +Your new project contain these files:: $ ls @@ -59,69 +62,77 @@ This is how the layout of your new project should look:: ├── test_functional.py └── test_units.py -The amount of files and directories may vary, but the above structure should -give you an idea of what you should expect. +The number of files and directories may vary based on the version of +Pecan, but the above structure should give you an idea of what to +expect. -A few things have been created for you, so let's review them one by one: +Let's review the files created by the template. -* **public**: All your static files (like CSS, Javascript, and images) live - here. Pecan comes with a simple file server that serves these static files +**public** + All your static files (like CSS, Javascript, and images) live here. + Pecan comes with a simple file server that serves these static files as you develop. +Pecan application structure generally follows the MVC_ pattern. The +directories under ``test_project`` encompass your models, controllers +and templates. -Pecan application structure generally follows the -`MVC <http://en.wikipedia.org/wiki/Model–view–controller>`_ pattern. The -remaining directories encompass your models, controllers and templates... +.. _MVC: http://en.wikipedia.org/wiki/Model–view–controller -* **test_project/controllers**: The container directory for your controller files. -* **test_project/templates**: All your templates go in here. -* **test_project/model**: Container for your model files. +**test_project/controllers** + The container directory for your controller files. +**test_project/templates** + All your templates go in here. +**test_project/model** + Container for your model files. -...and finally, a directory to house unit and integration tests: +Finally, a directory to house unit and integration tests: -* **test_project/tests**: All of the tests for your application. +**test_project/tests** + All of the tests for your application. -The **test_project/app.py** file controls how the Pecan application will be -created. This file must contain a ``setup_app`` function which returns the +The ``test_project/app.py`` file controls how the Pecan application will be +created. This file must contain a :func:`setup_app` function which returns the WSGI application object. Generally you will not need to modify the ``app.py`` file provided by the base application template unless you need to customize your app in a way that cannot be accomplished using config. See :ref:`python_based_config` below. -To avoid unneeded dependencies and to remain as flexible as possible, Pecan -doesn't impose any database or ORM -(`Object Relational Mapper -<http://en.wikipedia.org/wiki/Object-relational_mapping>`_) out of the box. -You may notice that **model/__init__.py** is mostly empty. If your project -will interact with a database, this if where you should add code to parse -bindings from your configuration file and define tables and ORM definitions. +To avoid unneeded dependencies and to remain as flexible as possible, +Pecan doesn't impose any database or ORM (`Object Relational +Mapper`_). If your project will interact with a database, you can add +code to ``model/__init__.py`` to load database bindings from your +configuration file and define tables and ORM definitions. + +.. _Object Relational Mapper: http://en.wikipedia.org/wiki/Object-relational_mapping .. _running_application: Running the Application ----------------------- -Before starting up your Pecan app, you'll need a configuration file. The -base project template should have created one for you already, ``config.py``. -This file already contains the basic necessary information to run your Pecan -app, like the host and port to serve it on, where your controllers and templates -are stored on disk, and which directory to serve static files from. +The base project template creates the configuration file with the +basic settings you need to run your Pecan application in +``config.py``. This file includes the host and port to run the server +on, the location where your controllers and templates are stored on +disk, and the name of the directory containing any static files. -If you just run ``pecan serve``, passing ``config.py`` as an argument for -configuration, it will bring up the development server and serve the app:: +If you just run ``pecan serve``, passing ``config.py`` as the +configuration file, it will bring up the development server and serve +the app:: $ pecan serve config.py Starting server in PID 000. serving on 0.0.0.0:8080, view at http://127.0.0.1:8080 The location for the configuration file and the argument itself are very -flexible - you can pass an absolute or relative path to the file. +flexible--you can pass an absolute or relative path to the file. .. _python_based_config: Python-Based Configuration -------------------------- -For ease of use, Pecan configuration files are pure Python - they're even saved +For ease of use, Pecan configuration files are pure Python--they're even saved as ``.py`` files. This is how your default (generated) configuration file should look:: @@ -180,9 +191,10 @@ a later chapter (:ref:`Configuration`). The Application Root -------------------- -The **Root Controller** is the root of your application. You can think of it -as being analogous to your application's root path (in our case, -``http://localhost:8080/``). + +The **Root Controller** is the entry point for your application. You +can think of it as being analogous to your application's root URL path +(in our case, ``http://localhost:8080/``). This is how it looks in the project template (``test_project.controllers.root.RootController``):: @@ -218,12 +230,12 @@ now, let's examine the sample project, controller by controller:: def index(self): return dict() -The ``index`` method is marked as **publically available** via the ``@expose`` +The :func:`index` method is marked as *publically available* via the :func:`@expose` decorator (which in turn uses the ``index.html`` template) at the root of the application (http://127.0.0.1:8080/), so any HTTP ``GET`` that hits the root of your application (``/``) will be routed to this method. -Notice that the ``index`` method returns a Python dictionary - this dictionary +Notice that the :func:`index` method returns a Python dictionary. This dictionary is used as a namespace to render the specified template (``index.html``) into HTML, and is the primary mechanism by which data is passed from controller to template. @@ -234,8 +246,8 @@ template. def index_post(self, q): redirect('http://pecan.readthedocs.org/en/latest/search.html?q=%s' % q) -The ``index_post`` method receives one HTTP ``POST`` argument (``q``). Because -the argument ``method`` to ``@index.when`` has been set to ``'POST'``, any +The :func:`index_post` method receives one HTTP ``POST`` argument (``q``). Because +the argument ``method`` to :func:`@index.when` has been set to ``'POST'``, any HTTP ``POST`` to the application root (in the example project, a form submission) will be routed to this method. @@ -250,11 +262,12 @@ submission) will be routed to this method. message = getattr(status_map.get(status), 'explanation', '') return dict(status=status, message=message) -Finally, we have the ``error`` method, which allows the application to display +Finally, we have the :func:`error` method, which allows the application to display custom pages for certain HTTP errors (``404``, etc...). Running the Tests For Your Application -------------------------------------- + Your application comes with a few example tests that you can run, replace, and add to. To run them:: @@ -279,4 +292,5 @@ The tests themselves can be found in the ``tests`` module in your project. Deploying to a Web Server ------------------------- + Ready to deploy your new Pecan app? Take a look at :ref:`deployment`. |