<commit_before>.. _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`


Base Application Template
-------------------------

We include a basic template to have a good layout for a Pecan project. This is
accomplished by  the ``pecan`` command line script bundled with the framework. 
Invoking the command to create a project is trivial::

    $ pecan create -t base

The above command will prompt you for a project name. I chose *test_project*,
but you can also provided as an argument at the end of the example command
above, like::

    $ pecan create -t base test_project

This is how it looks like when we run the whole command:: 

    $ pecan create -t 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 model
          Creating ./test_project/test_project/model/
          Copying __init__.py to ./test_project/test_project/model/__init__.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::

    ├── MANIFEST.in
    ├── config.py
    ├── public
    │   ├── css
    │   │   └── style.css
    │   └── javascript
    │       └── shared.js
    ├── setup.py
    ├── start.py
    ├── test_project
    │   ├── __init__.py
    │   ├── app.py
    │   ├── controllers
    │   │   ├── __init__.py
    │   │   └── root.py
    │   ├── model
    │   │   └── __init__.py
    │   ├── templates
    │   │   ├── error.html
    │   │   ├── index.html
    │   │   ├── layout.html
    │   │   └── success.html
    │   └── tests
    │       ├── __init__.py
    │       ├── test_config.py
    │       └── test_root.py
    └── test_project.egg-info
        ├── PKG-INFO
        ├── SOURCES.txt
        ├── dependency_links.txt
        ├── not-zip-safe
        ├── paster_plugins.txt
        ├── requires.txt
        └── top_level.txt

    9 directories, 25 files

The amount of files and directories may vary from time to time, but the above
structure should give you an idea of what you should expect.

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 few 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.
*  **model**:        Container for your model files.
*  **tests**:        All your application test files.

To avoid unneeded dependencies and to remain as flexible as possible, Pecan doesn't impose any database or
ORM (Object Relational Mapper) out of the box. You may notice that **model/__init__.py** is mostly empty. 
Its contents generally contain any code necessary to define tables, ORM definitions, and parse bindings from 
your configuration file.


.. _running_application:

Running the application
-----------------------
The most important file to run your application is your configuration file, the
base project template should have created one for you already and it should be
named ``config.py``.

This file already contains the necessary information to run a Pecan app, like
ports, static paths and so forth. 

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! <commit_msg>updated the note at the top<commit_after>.. _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` which includes the recommended way
    of setting up a proper development environment.


Base Application Template
-------------------------

We include a basic template to have a good layout for a Pecan project. This is
accomplished by  the ``pecan`` command line script bundled with the framework. 
Invoking the command to create a project is trivial::

    $ pecan create -t base

The above command will prompt you for a project name. I chose *test_project*,
but you can also provided as an argument at the end of the example command
above, like::

    $ pecan create -t base test_project

This is how it looks like when we run the whole command:: 

    $ pecan create -t 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 model
          Creating ./test_project/test_project/model/
          Copying __init__.py to ./test_project/test_project/model/__init__.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::

    ├── MANIFEST.in
    ├── config.py
    ├── public
    │   ├── css
    │   │   └── style.css
    │   └── javascript
    │       └── shared.js
    ├── setup.py
    ├── start.py
    ├── test_project
    │   ├── __init__.py
    │   ├── app.py
    │   ├── controllers
    │   │   ├── __init__.py
    │   │   └── root.py
    │   ├── model
    │   │   └── __init__.py
    │   ├── templates
    │   │   ├── error.html
    │   │   ├── index.html
    │   │   ├── layout.html
    │   │   └── success.html
    │   └── tests
    │       ├── __init__.py
    │       ├── test_config.py
    │       └── test_root.py
    └── test_project.egg-info
        ├── PKG-INFO
        ├── SOURCES.txt
        ├── dependency_links.txt
        ├── not-zip-safe
        ├── paster_plugins.txt
        ├── requires.txt
        └── top_level.txt

    9 directories, 25 files

The amount of files and directories may vary from time to time, but the above
structure should give you an idea of what you should expect.

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 few 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.
*  **model**:        Container for your model files.
*  **tests**:        All your application test files.

To avoid unneeded dependencies and to remain as flexible as possible, Pecan doesn't impose any database or
ORM (Object Relational Mapper) out of the box. You may notice that **model/__init__.py** is mostly empty. 
Its contents generally contain any code necessary to define tables, ORM definitions, and parse bindings from 
your configuration file.


.. note::
    With your base project you also got some ready-to-run tests. Try running
    ``py.test`` (the recommended test runner for Pecan) and see them passing!


.. _running_application:

Running the application
-----------------------
The most important file to run your application is your configuration file, the
base project template should have created one for you already and it should be
named ``config.py``.

This file already contains the necessary information to run a Pecan app, like
ports, static paths and so forth. 

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::

    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! 
{'fraction_non_alphanumeric': 0.08975654570509876, 'fraction_numerical': 0.00532843362425356, 'mean_word_length': 2.6154101627366324, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5495728', 'n_tokens_mistral': 3204, 'n_tokens_neox': 3066, 'n_words': 1306}