Pecan Web Framework

Common errors

• AttributeError: `pecan.state` is not bound to a context-local context.

  cause Attempting to access `pecan.request` or `pecan.response` outside the scope of an active HTTP request (e.g., during application startup or in a background thread) or when `use_context_locals` is not enabled.
  fix Ensure `use_context_locals = True` is set in your application configuration (`config['app']` dict or passed to `make_app`). Access `pecan.request` and `pecan.response` only within controller methods or hooks that are executed during a request's lifecycle.

• TypeError: setup_app() missing 1 required positional argument: 'config' (or similar configuration loading errors)

  cause The `pecan serve` command or `pecan.make_app` function was called without a valid configuration file path or a properly structured configuration dictionary.
  fix When using `pecan serve`, ensure you pass the path to a valid Python configuration file (e.g., `pecan serve config.py`). When using `make_app` directly, provide a dictionary for the `config` argument or pass root controller path and app config as keyword arguments, for example: `app = make_app('myapp.controllers.root.RootController', **app_config_dict)`.

Warnings

• breaking Pecan 1.8.0 (and subsequent versions) requires Python 3.10 or higher. Support for Python 3.8 and 3.9 has been removed.
  Fix: Upgrade your Python environment to 3.10 or newer before upgrading to Pecan 1.8.0. If you need Python 3.8/3.9 support, use Pecan < 1.8.0.
• gotcha Pecan is a lean framework and does not provide out-of-the-box support for common 'full-stack' features like sessions or database integrations.
  Fix: Be prepared to integrate these functionalities manually using third-party libraries. Pecan's documentation includes tutorials for integrating these.
• breaking Pecan 1.4.0 introduced a requirement for `webob >= 1.8`. Older versions of `webob` may cause unexpected behavior or errors.
  Fix: Ensure your environment has `webob` installed at version `1.8` or newer when using Pecan 1.4.0 or later.

Install

• pip install pecan Install stable release

Imports

• expose

  from pecan import expose

  Decorator for controller methods to expose them via HTTP.
• make_app

  from pecan import make_app

  Function to create a Pecan WSGI application instance.
• conf

  from pecan import conf

  Global configuration object, accessible at runtime.
• RestController

  from pecan.rest import RestController

  Base class for building RESTful controllers.

Quickstart

This minimal example demonstrates how to define a `RootController` with two exposed methods (`index` and `hello`). The `make_app` function initializes the WSGI application using this controller and a simple configuration. To run a Pecan application, the standard method is `pecan serve config.py`, where `config.py` contains the application's configuration. The `if __name__ == '__main__':` block provides a way to run it directly for demonstration purposes without the `pecan` command-line tool, serving on `0.0.0.0:8080`.

import os
from wsgiref.simple_server import make_server

from pecan import make_app, expose

# app.py
class RootController(object):
    @expose()
    def index(self):
        return 'Hello, Pecan!'

    @expose('json')
    def hello(self, name='World'):
        return {'message': f'Hello, {name}!'}

# config.py (simulated for quickstart)
config = {
    'root': 'app.RootController',
    'template_path': 'templates',
    'debug': True,
    'app': {
        'modules': ['app'],
        'static_root': 'public'
    },
    'server': {
        'port': os.environ.get('PORT', '8080'),
        'host': '0.0.0.0'
    }
}

# To run this, you would typically use `pecan serve config.py`
# For a self-contained example:
if __name__ == '__main__':
    app = make_app(config['root'], **config['app'])
    server = make_server(config['server']['host'], int(config['server']['port']), app)
    print(f"Serving Pecan on http://{config['server']['host']}:{config['server']['port']}")
    print("Visit / and /hello?name=Pecan")
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        pass