<commit_before>.. _commands:

.. |argparse| replace:: ``argparse``
.. _argparse: http://docs.python.org/dev/library/argparse.html

Command Line Pecan
==================
Any Pecan application can be controlled and inspected from the command line
using the built-in ``pecan`` command.  The usage examples of the ``pecan``
command in this document are intended to be invoked from your project's root
directory.  

Serving a Pecan App For Development
-----------------------------------
Pecan comes bundled with a lightweight WSGI development server based on
Python's ``wsgiref.simpleserver`` module.

Serving your Pecan app is as simple as invoking the ``pecan serve`` command::

    $ pecan serve config.py
    Starting server in PID 000.
    serving on 0.0.0.0:8080, view at http://127.0.0.1:8080

...and then visiting it in your browser.

The server ``host`` and ``port`` in your configuration file can be changed as
described in :ref:`server_configuration`.

.. include:: reload.rst
    :start-after: #reload

The Interactive Shell
---------------------
Pecan applications also come with an interactive Python shell which can be used
to execute expressions in an environment very similar to the one your
application runs in.  To invoke an interactive shell, use the ``pecan shell``
command::

    $ pecan shell config.py
    Pecan Interactive Shell
    Python 2.7.1 (r271:86832, Jul 31 2011, 19:30:53)
    [GCC 4.2.1 (Based on Apple Inc. build 5658)
    
      The following objects are available:
      wsgiapp    - This project's WSGI App instance
      conf       - The current configuration
      app        - webtest.TestApp wrapped around wsgiapp

    >>> conf
    Config({
        'app': Config({
            'root': 'myapp.controllers.root.RootController',
            'modules': ['myapp'],
            'static_root': '/Users/somebody/myapp/public', 
            'template_path': '/Users/somebody/myapp/project/templates',
            'errors': {'404': '/error/404'},
            'debug': True
        }),
        'server': Config({
            'host': '0.0.0.0',
            'port': '8080'
        })
    })
    >>> app
    <webtest.app.TestApp object at 0x101a830>
    >>> app.get('/')
    <200 OK text/html body='<html>\n ...\n\n'/936>

Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).

Using an Alternative Shell
++++++++++++++++++++++++++
``pecan shell`` has optional support for the `IPython <http://ipython.org/>`_
and `bpython <http://bpython-interpreter.org/>`_ alternative shells, each of
which can be specified with the ``--shell`` flag (or its abbreviated alias,
``-s``), e.g.,
::

    $ pecan shell --shell=ipython config.py
    $ pecan shell -s bpython config.py


.. _env_config:

Configuration from and environment variable
-------------------------------------------
In all the examples shown, you will see that the `pecan` commands where
accepting a file path to the configuration file. An alternative to this is to
set the configuration in an environment variable (``PECAN_CONFIG``).

This is completely optional, if a file path is passed in explicitly, Pecan will
honor that before looking for an environment variable.

For example, to ``serve`` a Pecan application, a variable could be exported and
subsequently be re-used when no path is passed in::

    $ export PECAN_CONFIG=/path/to/app/config.py
    $ pecan serve
    Starting server in PID 000.
    serving on 0.0.0.0:8080, view at http://127.0.0.1:8080

Note that the path needs to go to a valid pecan configuration file, otherwise
the command will error out with a meaningful message indicating that the path
is either invalid (for example if a directory is passed in).
<commit_msg>fix some typos on commands docs<commit_after>.. _commands:

.. |argparse| replace:: ``argparse``
.. _argparse: http://docs.python.org/dev/library/argparse.html

Command Line Pecan
==================
Any Pecan application can be controlled and inspected from the command line
using the built-in ``pecan`` command.  The usage examples of the ``pecan``
command in this document are intended to be invoked from your project's root
directory.  

Serving a Pecan App For Development
-----------------------------------
Pecan comes bundled with a lightweight WSGI development server based on
Python's ``wsgiref.simpleserver`` module.

Serving your Pecan app is as simple as invoking the ``pecan serve`` command::

    $ pecan serve config.py
    Starting server in PID 000.
    serving on 0.0.0.0:8080, view at http://127.0.0.1:8080

...and then visiting it in your browser.

The server ``host`` and ``port`` in your configuration file can be changed as
described in :ref:`server_configuration`.

.. include:: reload.rst
    :start-after: #reload

The Interactive Shell
---------------------
Pecan applications also come with an interactive Python shell which can be used
to execute expressions in an environment very similar to the one your
application runs in.  To invoke an interactive shell, use the ``pecan shell``
command::

    $ pecan shell config.py
    Pecan Interactive Shell
    Python 2.7.1 (r271:86832, Jul 31 2011, 19:30:53)
    [GCC 4.2.1 (Based on Apple Inc. build 5658)
    
      The following objects are available:
      wsgiapp    - This project's WSGI App instance
      conf       - The current configuration
      app        - webtest.TestApp wrapped around wsgiapp

    >>> conf
    Config({
        'app': Config({
            'root': 'myapp.controllers.root.RootController',
            'modules': ['myapp'],
            'static_root': '/Users/somebody/myapp/public', 
            'template_path': '/Users/somebody/myapp/project/templates',
            'errors': {'404': '/error/404'},
            'debug': True
        }),
        'server': Config({
            'host': '0.0.0.0',
            'port': '8080'
        })
    })
    >>> app
    <webtest.app.TestApp object at 0x101a830>
    >>> app.get('/')
    <200 OK text/html body='<html>\n ...\n\n'/936>

Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).

Using an Alternative Shell
++++++++++++++++++++++++++
``pecan shell`` has optional support for the `IPython <http://ipython.org/>`_
and `bpython <http://bpython-interpreter.org/>`_ alternative shells, each of
which can be specified with the ``--shell`` flag (or its abbreviated alias,
``-s``), e.g.,
::

    $ pecan shell --shell=ipython config.py
    $ pecan shell -s bpython config.py


.. _env_config:

Configuration from and environment variable
-------------------------------------------
In all the examples shown, you will see that the `pecan` commands where
accepting a file path to the configuration file. An alternative to this is to
specify the configuration file in an environment variable (``PECAN_CONFIG``).

This is completely optional; if a file path is passed in explicitly, Pecan will
honor that before looking for an environment variable.

For example, to ``serve`` a Pecan application, a variable could be exported and
subsequently be re-used when no path is passed in::

    $ export PECAN_CONFIG=/path/to/app/config.py
    $ pecan serve
    Starting server in PID 000.
    serving on 0.0.0.0:8080, view at http://127.0.0.1:8080

Note that the path needs to reference a valid pecan configuration file,
otherwise the command will error out with a meaningful message indicating that
the path is invalid (for example, if a directory is passed in).

{'fraction_non_alphanumeric': 0.13630848051772954, 'fraction_numerical': 0.02669542941890252, 'mean_word_length': 2.865554976550287, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 31, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 10, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6240136', 'n_tokens_mistral': 2236, 'n_tokens_neox': 2055, 'n_words': 862}