diff --git a/docs/0.0.1/Makefile b/docs/0.0.1/Makefile new file mode 100644 index 0000000..0d6c079 --- /dev/null +++ b/docs/0.0.1/Makefile @@ -0,0 +1,130 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Pecan.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Pecan.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Pecan" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Pecan" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/0.0.1/source/app_engine.rst b/docs/0.0.1/source/app_engine.rst new file mode 100644 index 0000000..f80dea4 --- /dev/null +++ b/docs/0.0.1/source/app_engine.rst @@ -0,0 +1,164 @@ +.. _app_engine: + +App Engine Support +========================= + +Pecan runs smoothly in Google's App Engine. There is **no** hacking/patching or weird +changes that you need to make to work with Pecan. However, since App Engine has certain +restrictions you may want to be aware of how to set it up correctly. + +.. note:: + We do not discuss here how to get an App Engine environment here, nor App Engine + specifics that are not related to Pecan. For more info on App Engine go to + `their docs `_ + + +Dependencies +--------------- +Pecan has a few dependencies and one of them is already supported by App Engine (WebOb) +so no need to grab that. Just so you are aware, this is the list of things that you absolutely need +to grab: + + * simplegeneric == 0.7 + * Paste == 1.7.5.1 + +These are optional, depending on the templating engine you want to use. However, depending on your choice, +you might want to check the engine's dependencies as well. The only engine from this list that doesn't require +a dependency is Kajiki. + + * Genshi == 0.6 + * Kajiki == 0.3.1 + * Mako == 0.3 + +From this point forward, we will assume you are getting Kajiki, to avoid describing third party dependencies. + + +Creating the project +============================ +Create a directory called ``pecan_gae`` and ``cd`` into it so we can start adding files. We go step by +step into what needs to go there to get everything running properly. + +app.yaml +------------ + +To start off, you will need your ``app.yaml`` file set properly to map to Pecan. This is how that file should look +like:: + + application: foo-bar + version: 1 + runtime: python + api_version: 1 + + handlers: + + - url: /.* + script: main.py + +Remember the application name will have to match your registered app name in App Engine. The file above maps +everything to a ``main.py`` file. + +This file will be the *root* of our project and will handle everything. + +main.py +------------ +You can name this anything you want, but for consistency we are going with main.py. This file will handle +all the incoming requests including static files for our Pecan application. This is how it should look:: + + from google.appengine.ext.webapp import util + import sys + if './lib' not in sys.path: + sys.path.append('./lib') + + from pecan import Pecan, expose + + + class RootController(object): + + @expose('kajiki:index.html') + def index(self): + return dict(name="Joe Wu Zap") + + + def main(): + application = Pecan(RootController(), template_path='templates') + util.run_wsgi_app(application) + + + if __name__ == '__main__': + main() + +We are doing a few things here... first we are importing the ``util`` module from App Engine that will +run our Pecan app, then we are importing ``sys`` because we need to add ``lib`` to our path. + +The ``lib`` directory is where all our dependencies (including Pecan) will live, so we need to make sure +App Engine will see that as well as all our libraries within ``lib`` (it would not be enough to add a ``__init__.py`` +file there. + +templates +----------- +The templates directory is where we will have all of our html templates for Pecan. If you don't have it already, go ahead +and create it and add this html file to it and name it index.html:: + + + + + Hello, ${name}! + + + +

Hello, ${name}!

+ + + + +lib +----- +The ``lib`` directory should contain the source for all the dependencies we need. For our example, it should +contain 3 libraries: + + * kajiki + * paste + * pecan + +That is all you need to get this project started! + +.. note:: + When grabing the source of the dependencies we mention, make sure you are actually grabing the module itself + and not adding the top directory source (where setup.py lives) + +Layout +--------- +This is how your layout (only showing directories) should look like:: + + pecan_gae + |____app.yaml + |____lib + | |____kajiki + | | |____tests + | | |____data + | |____paste + | | |____auth + | | |____cowbell + | | |____debug + | | |____evalexception + | | | |____media + | | |____exceptions + | | |____util + | |____pecan + |____templates + + +Trying it out +========================= +Now everything should be ready to start serving, so go ahead and run the development server:: + + $ ./dev_appserver.py pecan_gae + INFO 2010-10-10 12:44:29,476 dev_appserver_main.py:431] Running application pecan-gae on port 8080: http://localhost:8080 + + +If you go to your browser and hit ``localhost:8080`` you should see something like this:: + + Hello, Joe Wu Zap! + +This is the most basic example for App Engine, you can start adding more controllers to handle a bigger +application and connect everything together. diff --git a/docs/0.0.1/source/conf.py b/docs/0.0.1/source/conf.py new file mode 100644 index 0000000..89870dd --- /dev/null +++ b/docs/0.0.1/source/conf.py @@ -0,0 +1,216 @@ +# -*- coding: utf-8 -*- +# +# Pecan documentation build configuration file, created by +# sphinx-quickstart on Sat Oct 9 14:41:27 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Pecan' +copyright = u'2010, Jonathan LaCour' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.1' +# The full version, including alpha/beta/rc tags. +release = '0.0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Pecandoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Pecan.tex', u'Pecan Documentation', + u'Jonathan LaCour', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'pecan', u'Pecan Documentation', + [u'Jonathan LaCour'], 1) +] diff --git a/docs/0.0.1/source/configuration.rst b/docs/0.0.1/source/configuration.rst new file mode 100644 index 0000000..1db79a4 --- /dev/null +++ b/docs/0.0.1/source/configuration.rst @@ -0,0 +1,77 @@ +.. _configuration: + +Configuration +============= +Pecan is very easy to configured. As long as you follow certain conventions; +using, setting and dealing with configuration should be very intuitive. + +Python files is what the framework uses to get the values from configuration +files. These files need to specify the values in a key/value way (Python +dictionaries). + +Even if you want custom configuration values, you need to get them in the +configuration file as dictionaries. + +No Configuration +---------------- +What happens when no configuration is passed? Or if you are missing some values? +Pecan fills in anything that you might have left behind. This includes either +**app** or **server** completely and even if you left out specifics about them, +like the port number the server should be running on. + +Defaults +-------- +Below is the complete default values the framework uses:: + + + server = { + 'port' : '8080', + 'host' : '0.0.0.0' + } + + app = { + 'root' : None, + 'static_root' : 'public', + 'template_path' : '', + 'debug' : False + } + + + +.. _application_configuration: + +Application Configuration +------------------------- +This is the part of the configuration that is specific to your application. +Things like debug mode, Root Controller and possible Hooks, should be specified +here. This is what is used when the framework is wrapping your application into +a valid WSGI app. + +A typical application configuration would look like this:: + + app = { + 'root' : RootController(), + 'static_root' : 'public', + 'template_path' : 'project/templates', + 'debug' : True + } + +Let's look at each value and what it means: + +**app** is a reserved variable name for the configuration, so make sure you are +not overriding, otherwise you will get default values. + +**root** Needs the Root Controller of your application, this where your main +class that points to all the spots in your application should be. Rememeber +that you are passing the actual object so you would need to import it at the +top of the file. In the example configuration, this would be something like:: + + from myproject.controllers.root import RootController + +**static_root** Points to the directory where your static files live in. + +**template_path** The path where your templates are. + +**debug** Enables ``WebError`` to have full tracebacks in the browser (this is +OFF by default). + diff --git a/docs/0.0.1/source/hooks.rst b/docs/0.0.1/source/hooks.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/0.0.1/source/index.rst b/docs/0.0.1/source/index.rst new file mode 100644 index 0000000..d047e08 --- /dev/null +++ b/docs/0.0.1/source/index.rst @@ -0,0 +1,122 @@ +.. Pecan documentation master file, created by + sphinx-quickstart on Sat Oct 9 14:41:27 2010. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Pecan's documentation +========================= + +A WSGI object-dispatching web framework, in the spirit of TurboGears, only +much much smaller, with many fewer dependencies. + + +Contents: + +.. toctree:: + :maxdepth: 2 + + installation.rst + routing.rst + configuration.rst + templates.rst + hooks.rst + jsonify.rst + secure_controller.rst + validation_n_errors.rst + + +Introduction +============ +Pecan packs a few good features but it is also extremely lean, it requires just +a few dependencies but for the most part it feels like a full fledged web +framework! + + * Object-Dispatch for easy routing + * Pre and Post Hooks + * REST controllers + * Validation and Error handling + * Secure controllers + * Template language support + * AppEngine out of the box (no patching!) + + + +Pecan Hello World +------------------ +In this example we use ``httpserver`` from ``paste`` but feel free to use any +WSGI server you want:: + + from paste import httpserver + from pecan import make_app, expose + + + class RootController(object): + + @expose() + def index(self): + return 'Hello, World!' + + app = make_app(RootController(), debug=True) + httpserver.serve(app, host='0.0.0.0', port=8080) + + +Tutorials +========= +We provide a couple of easy ways to get started including a short tutorial on +App Engine. + +.. toctree:: + :maxdepth: 2 + + quick_start.rst + app_engine.rst + + +API +=== +The following section lists the main sections of Pecan, where you can find more +specific details about methods and modules available. + +.. toctree:: + :maxdepth: 2 + + decorators.rst + hooks.rst + jsonify.rst + pecan.rst + rest.rst + routing.rst + secure.rst + templating.rst + +License +------- +The Pecan framework and the documentation is BSD Licensed:: + + Copyright (c) <2010>, Pecan Framework + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + * Neither the name of the nor the + names of its contributors may be used to endorse or promote products + derived from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY + DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + diff --git a/docs/0.0.1/source/installation.rst b/docs/0.0.1/source/installation.rst new file mode 100644 index 0000000..930842d --- /dev/null +++ b/docs/0.0.1/source/installation.rst @@ -0,0 +1,45 @@ +.. _installation: + +Installation +============ +We recommend installing Pecan with ``pip`` but you can also try with +``easy_install`` and ``virtualenv``. Creating a spot in your environment where +Pecan can be isolated from other packages is best practice. + +To get started with an environment for Pecan, create a virtual environment for +it without any site-packages that might pollute:: + + virtualenv --no-site-packages pecan-env + cd pecan-env + source bin/activate + +The above commands created a virtual environment and *activated* it. Those +actions will encapsulate anything that we do with the framework, making it +easier to debug problems if needed. + +But we do not have Pecan yet, so let's grab it from PYPI:: + + pip install pecan + +After a lot of output, you should have Pecan successfully installed and ready +to use. + + +Development (Unstable) Version +------------------------------ +If you want to run the development version of Pecan you will +need GIT installed and clone the repo from github:: + + git clone https://github.com/cleverdevil/pecan.git + +If you are still in the *pecan-dev* virtual environment that we created before, +you should call ``setup.py`` to install:: + + python setup.py develop + + +Testing +======= +For testing purposes, we use `py.test `_ and +WebTest, so make sure you have those installed in your environment before +running the tests. diff --git a/docs/0.0.1/source/jsonify.rst b/docs/0.0.1/source/jsonify.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/0.0.1/source/quick_start.rst b/docs/0.0.1/source/quick_start.rst new file mode 100644 index 0000000..7defab2 --- /dev/null +++ b/docs/0.0.1/source/quick_start.rst @@ -0,0 +1,201 @@ +.. _quick_start: + +Quick Start +=========== +Here we will cover the basics for a small project in Pecan. More advanced +examples and methods are not covered here. + +.. note:: + We will not cover how to get Pecan installed here. If you need installation + details please go to :ref:`installation` + + +We include a basic template to have a good layout for a Pecan project. This is +accomplished by ``PasteScript`` so we need to invoke a command to create our +example project:: + + $ paster create -t pecan-base + +The above commnad will prompt you for a project name. I chose *test_project*, +this is how it looks like when we run the whole command:: + + $ paster create -t pecan-base + Selected and implied templates: + pecan#pecan-base Template for creating a basic Framework package + + Enter project name: test_project + Variables: + egg: test_project + package: test_project + project: test_project + Creating template pecan-base + Creating directory ./test_project + Recursing into +egg+ + Creating ./test_project/test_project/ + Copying __init__.py to ./test_project/test_project/__init__.py + Recursing into controllers + Creating ./test_project/test_project/controllers/ + Copying __init__.py to ./test_project/test_project/controllers/__init__.py + Copying root.py to ./test_project/test_project/controllers/root.py + Recursing into templates + Creating ./test_project/test_project/templates/ + Copying index.html to ./test_project/test_project/templates/index.html + Copying layout.html to ./test_project/test_project/templates/layout.html + Copying success.html to ./test_project/test_project/templates/success.html + Recursing into public + Creating ./test_project/public/ + Recursing into css + Creating ./test_project/public/css/ + Copying style.css to ./test_project/public/css/style.css + Recursing into javascript + Creating ./test_project/public/javascript/ + Copying shared.js to ./test_project/public/javascript/shared.js + Copying start.py_tmpl to ./test_project/start.py + + +This is how the structure of your new project should look like:: + + . + ├── config.py + ├── public + │   ├── css + │   │   └── style.css + │   └── javascript + │   └── shared.js + ├── start.py + └── test_project + ├── __init__.py + ├── controllers + │   ├── __init__.py + │   └── root.py + └── templates + ├── index.html + ├── layout.html + └── success.html + + 6 directories, 10 files + + +A few things have been set for you, let's review them one by one: + +* **public**: All your public static files like CSS and Javascript are placed + here. If you have some images (this example app doesn't) it would make sense + to get them here as well. + + +Inside the project name you chose you have a couple of directories, and for the +most part, it will contain your models, controllers and templates: + +* **controllers**: The container directory for your controller files. +* **templates**: All your templates would go in here. + +Note how there is no **model** directory. Since we haven't defined any +database for the app the template doesn't supply you one. In case you need it +later you could create a ``models.py`` file or a ``model`` directory. + + +.. _running_application: + +Running the application +----------------------- +There are 2 files that are important to start your application. In this case +``start.py`` and ``config.py`` are in charge of getting everything up and running. + +If you just run ``start.py`` with Python, passing ``config`` as an argument for +configuration it will bring up the development server and serve the app:: + + python start.py config + Serving on http://0.0.0.0:8080 + serving on 0.0.0.0:8080 view at http://127.0.0.1:8080 + +To get up and running in no time the template helps a lot! + +.. note:: + If you fail to pass an argument you will get a small error message asking + for a configuration file. Remember you need to pass the name of the + configuration file without the ".py" extension. + + +Simple Configuration +-------------------- +We mentioned that you get a Python file with some configurations. The only +Python syntax that you will see is the first line that imports the +RootController that is in turn placed as the application root. Everything else, +including possible custom configurations are set as Python dictionaries. + +This is how your default configuration file should look like:: + + from test_project.controllers.root import RootController + + + # Server Specific Configurations + server = { + 'port' : '8080', + 'host' : '0.0.0.0' + } + + # Pecan Application Configurations + app = { + 'root' : RootController(), + 'static_root' : 'public', + 'template_path' : 'test_project/templates', + 'debug' : True + } + + # Custom Configurations must be in Python dictionary format:: + # + # foo = {'bar':'baz'} + # + # All configurations are accessible at:: + # pecan.conf + + +**Nothing** in the configuration file above is actually required for Pecan to +be able to run. If you fail to provide some values Pecan will fill in the +missing things it needs to run. + +You also get the ability to set your own configurations as dictionaries and you +get a commented out example on how to do that. + +We are not going to explain much more about configuration here, if you need +more specific details, go to the :ref:Configuration section. + + +Root Controller +--------------- +The Root Controller is the main point of contact between your application and +the framework. + +This is how it looks from the project template:: + + from pecan import expose, request + from formencode import Schema, validators as v + + + class SampleForm(Schema): + name = v.String(not_empty=True) + age = v.Int(not_empty=True) + + + class RootController(object): + @expose('index.html') + def index(self, name='', age=''): + return dict(errors=request.validation_error, name=name, age=age) + + @expose('success.html', schema=SampleForm(), error_handler='index') + def handle_form(self, name, age): + return dict(name=name, age=age) + + +Here you can specify other classes if you need to do so later on your project, +but for now we have an *index* method and a *handle_form* one. + +**index**: Is *exposed* as the root of the application, so anything that hits +'/' will touch this method. +Since we are doing some validation and want to pass any errors we might get to +the template, we set ``errors`` to receive anything that +``request.validation_error`` returns. + + +**handle_form**: It receives 2 parameters (*name* and *age*) that are validated +through the *SampleForm* schema class. diff --git a/docs/0.0.1/source/routing.rst b/docs/0.0.1/source/routing.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/0.0.1/source/secure_controller.rst b/docs/0.0.1/source/secure_controller.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/0.0.1/source/templates.rst b/docs/0.0.1/source/templates.rst new file mode 100644 index 0000000..e69de29 diff --git a/docs/0.0.1/source/validation_n_errors.rst b/docs/0.0.1/source/validation_n_errors.rst new file mode 100644 index 0000000..e69de29