نسخه پایدار (Stable Version)

توصیه می‌کنیم Pecan را با pip http://www.pip-installer.org نصب کنید، اما می‌توانید از easy_install نیز استفاده کنید. ایجاد فضایی در محیط کاری شما که در آن Pecan از سایر بسته‌ها مجزا و ایزوله باشد، بهترین شیوه است.

برای شروع کار با یک محیط برای Pecan، توصیه می‌کنیم با استفاده از virtualenv http://www.virtualenv.org یک محیط مجازی جدید http://www.virtualenv.org ایجاد کنید:

$ virtualenv pecan-env
$ cd pecan-env
$ source bin/activate

دستورات بالا یک محیط مجازی ایجاد کرده و آن را فعال می‌کنند. این کار وابستگی‌های نصب‌شدهٔ Pecan را از بسته‌های سیستمی شما ایزوله می‌کند و در صورت نیاز اشکال‌زدایی مشکلات را ساده‌تر می‌سازد.

سپس، Pecan را نصب می‌کنیم:

$ pip install pecan

$ git clone https://github.com/pecan/pecan.git

$ cd pecan
$ python setup.py develop

$ pip install -e git://github.com/pecan/pecan.git#egg=pecan

قالب پایه برنامه (Base Application Template)

برنامه Pecan شامل یک قالب پایه برای شروع یک پروژه جدید است. در شل خود، دستور زیر را وارد کنید:

$ pecan create test_project

این مثال از test_project به عنوان نام پروژه شما استفاده می‌کند، اما می‌توانید آن را با هر نام بسته معتبر Python که مایلید جایگزین کنید.

به دایرکتوری پروژه‌ای که تازه ایجاد کرده‌اید بروید:

$ cd test_project

شما باید آن را در "حالت توسعه" (development mode) مستقر کنید، به طوری که در sys.path در دسترس باشد، اما همچنان بتوان آن را مستقیماً از توزیع منبع آن ویرایش کرد:

$ python setup.py develop

پروژه جدید شما شامل این فایل‌ها خواهد بود:

$ ls
├── MANIFEST.in
├── config.py
├── public
│   ├── css
│   │   └── style.css
│   └── images
├── setup.cfg
├── setup.py
└── test_project
    ├── __init__.py
    ├── app.py
    ├── controllers
    │   ├── __init__.py
    │   └── root.py
    ├── model
    │   └── __init__.py
    ├── templates
    │   ├── error.html
    │   ├── index.html
    └── layout.html
    └── tests
        ├── __init__.py
        ├── config.py
        ├── test_functional.py
        └── test_units.py

تعداد فایل‌ها و دایرکتوری‌ها ممکن است بر اساس نسخه Pecan متفاوت باشد، اما ساختار بالا باید دید کلی از آنچه انتظار می‌رود را به شما بدهد.

بیایید فایل‌های ایجاد شده توسط قالب را بررسی کنیم:

ساختار برنامه Pecan عموماً از الگوی MVC <http://en.wikipedia.org/wiki/Model–view–controller> پیروی می‌کند. دایرکتوری‌های زیر test_project شامل مدل‌ها، کنترل‌کننده‌ها و قالب‌های شما هستند.

در نهایت، دایرکتوری برای نگهداری آزمون‌های واحد (unit) و یکپارچه‌سازی (integration):

فایل test_project/app.py چگونگی ایجاد برنامه Pecan را کنترل می‌کند. این فایل باید حاوی یک تابع setup_app() باشد که شیء برنامه WSGI را برمی‌گرداند. معمولاً نیازی به ویرایش فایل app.py ارائه شده توسط قالب پایه برنامه نخواهید داشت، مگر اینکه نیاز به سفارشی‌سازی برنامه خود به روشی داشته باشید که با استفاده از پیکربندی امکان‌پذیر نباشد. به بخش پیکربندی مبتنی بر پایتون (Python-Based Configuration) در ادامه مراجعه کنید.

برای جلوگیری از وابستگی‌های غیرضروری و حفظ بیشترین انعطاف‌پذیری ممکن، Pecan هیچ پایگاه داده یا ORM (نگاشت شیء-رابطه‌ای http://en.wikipedia.org/wiki/Object-relational_mapping) را تحمیل نمی‌کند. اگر پروژه شما با یک پایگاه داده در ارتباط است، می‌توانید کدی به model/__init__.py اضافه کنید تا اتصالات پایگاه داده را از فایل پیکربندی شما بارگیری کند و جدول‌ها و تعاریف ORM را مشخص نماید..SS اجرای برنامه

قالب پایهٔ پروژه، فایل پیکربندی را با تنظیمات اولیه‌ای که برای اجرای برنامهٔ Pecan خود نیاز دارید در config.py ایجاد می‌کند. این فایل شامل میزبان و درگاهی است که کارساز باید روی آن اجرا شود، مکانی از دیسک که کنترل‌کننده‌ها و قالب‌های شما در آن ذخیره شده‌اند، و نام دایرکتوری حاوی فایل‌های ایستا (static).

اگر تنها دستور pecan serve را با ارسال config.py به عنوان فایل پیکربندی اجرا کنید، کارساز توسعه راه‌اندازی شده و برنامه را ارائه می‌دهد:

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

محل فایل پیکربندی و خود آرگومان بسیار انعطاف‌پذیر هستند - می‌توانید یک مسیر مطلق یا نسبی را به فایل ارسال کنید.

پیکربندی مبتنی بر پایتون

برای سهولت در استفاده، فایل‌های پیکربندی Pecan از نوع پایتون خالص هستند--آن‌ها حتی به عنوان فایل‌های .py ذخیره می‌شوند.

فایل پیکربندی پیش‌فرض (تولیدشده) شما باید به این صورت باشد:

# Server Specific Configurations
server = {
    'port': '8080',
    'host': '0.0.0.0'
}
# Pecan Application Configurations
app = {
    'root': '${package}.controllers.root.RootController',
    'modules': ['${package}'],
    'static_root': '%(confdir)s/public',
    'template_path': '%(confdir)s/${package}/templates',
    'debug': True,
    'errors': {
        '404': '/error/404',
        '__force_dict__': True
    }
}
logging = {
    'loggers': {
        'root' : {'level': 'INFO', 'handlers': ['console']},
        '${package}': {'level': 'DEBUG', 'handlers': ['console']}
    },
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
            'formatter': 'simple'
        }
    },
    'formatters': {
        'simple': {
            'format': ('%(asctime)s %(levelname)-5.5s [%(name)s]'
                       '[%(threadName)s] %(message)s')
        }
    }
}
# Custom Configurations must be in Python dictionary format::
#
# foo = {'bar':'baz'}
#
# All configurations are accessible at::
# pecan.conf

همچنین می‌توانید پیکربندی‌های سفارشی خود را به صورت دیکشنری‌های پایتون اضافه کنید.

موارد زیادی برای پوشش دادن وجود دارد، بنابراین در فصلی دیگر مجدداً به فایل‌های پیکربندی بازخواهیم گشت (Configuring Pecan Applications <#configuration>)..SS ریشه برنامه (The Application Root)

کنترلر ریشه یا Root Controller نقطه ورود برنامه شما است. می‌توانید آن را مشابه مسیر URL ریشه برنامه خود (در این حالت، http://localhost:8080) در نظر بگیرید.

این کنترلر در قالب پروژه (test_project.controllers.root.RootController) به این شکل است:

from pecan import expose
from webob.exc import status_map
class RootController(object):
    @expose(generic=True, template='index.html')
    def index(self):
        return dict()
    @index.when(method='POST')
    def index_post(self, q):
        redirect('https://pecan.readthedocs.io/en/latest/search.html?q=%s' % q)
    @expose('error.html')
    def error(self, status):
        try:
            status = int(status)
        except ValueError:
            status = 0
        message = getattr(status_map.get(status), 'explanation', '')
        return dict(status=status, message=message)

در صورت نیاز می‌توانید کلاس‌ها و متدهای بیشتری را مشخص کنید، اما در حال حاضر بیایید پروژه نمونه را کنترلر به کنترلر بررسی کنیم:

@expose(generic=True, template='index.html')
def index(self):
    return dict()

متد index() از طریق دکوراتور expose() <#pecan.decorators.expose> (که به نوبه خود از قالب index.html استفاده می‌کند) در ریشه برنامه (http://127.0.0.1:8080) به عنوان در دسترس عموم نشانه‌گذاری شده است؛ بنابراین هر درخواست HTTP GET که به ریشه برنامه شما (/) برسد، به این متد هدایت خواهد شد.

توجه داشته باشید که متد index() یک دیکشنری پایتون را برمی‌گرداند. این دیکشنری به عنوان یک فضای نام برای تبدیل قالب مشخص‌شده (index.html) به HTML استفاده می‌شود و سازوکار اصلی انتقال داده از کنترلر به قالب است.

@index.when(method='POST')
def index_post(self, q):
    redirect('https://pecan.readthedocs.io/en/latest/search.html?q=%s' % q)

متد index_post() یک آرگومان HTTP POST دریافت می‌کند (q). از آنجا که آرگومان method برای @index.when() روی 'POST' تنظیم شده است، هر درخواست HTTP POST به ریشه برنامه (در پروژه نمونه، ارسال یک فرم) به این متد هدایت خواهد شد.

@expose('error.html')
def error(self, status):
    try:
        status = int(status)
    except ValueError:
        status = 0
    message = getattr(status_map.get(status), 'explanation', '')
    return dict(status=status, message=message)

در نهایت، متد error() را داریم که به برنامه امکان می‌دهد صفحه‌های سفارشی را برای برخی از خطاهای HTTP نمایش دهد (404 و غیره...)..SS "اجرای آزمون‌ها برای برنامه شما (Running the Tests For Your Application)"

برنامه شما شامل چند آزمون نمونه است که می‌توانید آن‌ها را اجرا، جایگزین یا به آن‌ها مواردی اضافه کنید. برای اجرای آن‌ها:

$ pip install tox && tox -e py

خود آزمون‌ها را می‌توان در ماژول tests در پروژه خود پیدا کرد.

استقرار روی یک وب‌سرور (Deploying to a Web Server)

آماده استقرار برنامه جدید Pecan خود هستید؟ نگاهی به Deploying Pecan in Production <#deployment> بیندازید.

مسیریابی بر اساس متد درخواست (Routing Based on Request Method)

آرگومان generic در expose() <#pecan.decorators.expose> امکان چندریختی یا بازتعریف (overloading) نشانی‌های URL را بر اساس متد درخواست فراهم می‌کند. در مثال زیر، یک URL یکسان می‌تواند با استفاده از کنترلرهای عمومی (generic controllers) به دو متد مختلف سرویس‌دهی شود (یکی برای رسیدگی به HTTP GET و دیگری برای HTTP POST):

from pecan import expose
class RootController(object):
    # HTTP GET /
    @expose(generic=True, template='json')
    def index(self):
        return dict()
    # HTTP POST /
    @index.when(method='POST', template='json')
    def index_POST(self, **kw):
        uuid = create_something()
        return dict(uuid=uuid)

مسیریابی به زیرکنترلرها با _lookup

متد ویژهٔ _lookup() روشی را برای پردازش بخشی از یک URL و سپس بازگرداندن یک شیء کنترلر جدید جهت هدایت بخش باقی‌مانده فراهم می‌کند.

یک متد _lookup() می‌تواند یک یا چند آرگومان را بپذیرد، که بخش‌هایی از مسیر URL هستند که باید پردازش شوند (تفکیک‌شده با /). متد _lookup() همچنین باید آرگومان‌های مکانی متغیر را که نشان‌دهندهٔ ادامهٔ مسیر هستند دریافت کند، و هر بخشی از مسیر را که خود پردازش نمی‌کند در مقدار بازگشتی خود بگنجاند. مثال زیر از یک لیست *remainder استفاده می‌کند که با ادامه یافتن الگوریتم ارجاع به شیء (object-dispatch)، به کنترلر بازگردانده‌شده ارسال خواهد شد.

علاوه بر کاربرد در ساخت پویای کنترلرها، متد _lookup() به عنوان آخرین راه‌حل نیز فراخوانی می‌شود؛ زمانی که هیچ متد کنترلر دیگری با URL همخوانی نداشته باشد و متد _default() نیز تعریف نشده باشد.

from pecan import expose, abort
from somelib import get_student_by_name
class StudentController(object):
    def __init__(self, student):
        self.student = student
    @expose()
    def name(self):
        return self.student.name
class RootController(object):
    @expose()
    def _lookup(self, primary_key, *remainder):
        student = get_student_by_primary_key(primary_key)
        if student:
            return StudentController(student), remainder
        else:
            abort(404)

یک درخواست HTTP GET به /8/name نام دانش‌آموزی را بازمی‌گرداند که در آن primary_key == 8 باشد.

بازگشت به متد جایگزین با _default

متد _default() به عنوان آخرین راه‌حل، هنگامی که هیچ متد کنترلر دیگری از طریق ارجاع استاندارد به شیء با URL تطابق نداشته باشد، فراخوانی می‌شود.

from pecan import expose
class RootController(object):
    @expose()
    def english(self):
        return 'hello'
    @expose()
    def french(self):
        return 'bonjour'
    @expose()
    def _default(self):
        return 'I cannot say hello in that language'

در مثال بالا، درخواستی به /spanish به RootController._default() هدایت خواهد شد..SS تعریف مسیریابی سفارشی با _route

متد _route() به کنترل‌کننده اجازه می‌دهد سازوکار مسیریابی Pecan را به‌طور کامل بازنویسی کند. خود Pecan از متد _route() برای پیاده‌سازی RestController <#pecan.rest.RestController> استفاده می‌کند. اگر می‌خواهید یک سیستم مسیریابی جایگزین بر بستر Pecan طراحی کنید، تعریف یک کلاس کنترل‌کنندهٔ پایه که متد _route() را مشخص کند، به شما امکان کنترل کامل را می‌دهد.

تعیین پاسخ سفارشی

با تغییر ویژگی status در شیء پاسخ، یک کد وضعیت HTTP مشخص (مانند 203 Non-Authoritative Information) تنظیم کنید.

from pecan import expose, response
class RootController(object):
    @expose('json')
    def hello(self):
        response.status = 203
        return {'foo': 'bar'}

برای برانگیختن خطاهای HTTP از تابع کمکی abort() <#pecan.core.abort> استفاده کنید.

from pecan import expose, abort
class RootController(object):
    @expose('json')
    def hello(self):
        abort(404)

تابع abort() <#pecan.core.abort> یک نمونه از WSGIHTTPException را برمی‌انگیزد که توسط Pecan برای رندر کردن بدنه‌های پیش‌فرض پاسخ در خطاهای HTTP استفاده می‌شود. این استثنا در محیط درخواست WSGI (environ) در pecan.original_exception ذخیره می‌شود، جایی که بعداً در چرخهٔ درخواست (برای مثال توسط میان‌افزارهای دیگر یا Custom Error Documents <#errors>) قابل دسترسی است.

اگر می‌خواهید یک پاسخ صریح را بازگردانید، می‌توانید این کار را با استفاده از Response <#pecan.core.Response> انجام دهید:

from pecan import expose, Response
class RootController(object):
    @expose()
    def hello(self):
        return Response('Hello, World!', 202)

class MyRequest(pecan.Request):
    pass
class MyResponse(pecan.Response):
    pass

from myproject import MyRequest, MyResponse
app = {
    'root' : 'project.controllers.root.RootController',
    'modules' : ['project'],
    'static_root'   : '%(confdir)s/public',
    'template_path' : '%(confdir)s/project/templates',
    'request_cls': MyRequest,
    'response_cls': MyResponse
}

نگاشت آرگومان‌های کنترل‌کننده (Controller)

در Pecan، متغیرهای GET و POST در پروتکل HTTP که در طول فرآیند مسیریابی (routing) مصرف نمی‌شوند، می‌توانند به عنوان آرگومان به متد کنترل‌کننده منتقل شوند.

بسته به امضای (signature) متد، این متغیرها می‌توانند به‌طور صریح به آرگومان‌ها نگاشت شوند:

from pecan import expose
class RootController(object):
    @expose()
    def index(self, arg):
        return arg
    @expose()
    def kwargs(self, **kwargs):
        return str(kwargs)

$ curl http://localhost:8080/?arg=foo
foo
$ curl http://localhost:8080/kwargs?a=1&b=2&c=3
{u'a': u'1', u'c': u'3', u'b': u'2'}

یا می‌توانند بر اساس موقعیت (positionally) مصرف شوند:

from pecan import expose
class RootController(object):
    @expose()
    def args(self, *args):
        return ','.join(args)

$ curl http://localhost:8080/args/one/two/three
one,two,three

همین نتیجه را می‌توان با متغیرهای بدنه در HTTP POST نیز به دست آورد:

from pecan import expose
class RootController(object):
    @expose()
    def index(self, arg):
        return arg

$ curl -X POST "http://localhost:8080/" -H "Content-Type: application/x-www-form-urlencoded" -d "arg=foo"
foo

import os
from random import choice
from webob.static import FileIter
from pecan import expose, response
class RootController(object):
    @expose(content_type='image/gif')
    def gifs(self):
        filepath = choice((
            "/path/to/funny/gifs/catdance.gif",
            "/path/to/funny/gifs/babydance.gif",
            "/path/to/funny/gifs/putindance.gif"
        ))
        f = open(filepath, 'rb')
        response.app_iter = FileIter(f)
        response.headers[
            'Content-Disposition'
        ] = 'attachment; filename="%s"' % os.path.basename(f.name)

import os
from mimetypes import guess_type
from webob.static import FileIter
from pecan import expose, response
class RootController(object):
    @expose()
    def download(self):
        f = open('/path/to/some/file', 'rb')
        response.app_iter = FileIter(f)
        response.headers['Content-Type'] = guess_type(f.name)
        response.headers[
            'Content-Disposition'
        ] = 'attachment; filename="%s"' % os.path.basename(f.name)

مدیریت بارگذاری فایل‌ها (Handling File Uploads)

Pecan مدیریت بارگذاری فایل‌ها را از طریق فرم‌های استاندارد multipart ساده می‌کند. کافی است فرم خود را با یک ورودی فایل تعریف کنید:

<form action="/upload" method="POST" enctype="multipart/form-data">
  <input type="file" name="file" />
  <button type="submit">Upload</button>
</form>

سپس می‌توانید فایل بارگذاری‌شده را از شیء request در کنترلر (controller) برنامه بخوانید:

from pecan import expose, request
class RootController(object):
    @expose()
    def upload(self):
        assert isinstance(request.POST['file'], cgi.FieldStorage)
        data = request.POST['file'].file.read()

pecan.request.context['current_user'] = some_user
print pecan.request.context.items()

توابع کمکی (Helper Functions)

همچنین Pecan توابع کمکی مفید متعددی را برای جابه‌جایی میان مسیرهای مختلف فراهم می‌کند. تابع redirect() <#pecan.core.redirect> به شما اجازه می‌دهد بازهدایت‌های داخلی یا HTTP 302 صادر کنید.

همچنین ببینید:

تعیین نشانی وب برای یک کنترلر (Determining the URL for a Controller)

با توجه به این‌که امکان تغییر چشمگیر مسیریابی در زمان اجرا وجود دارد، همیشه امکان تعیین دقیق یک نگاشت بین متد کنترلر و یک نشانی وب (URL) وجود ندارد.

برای مثال، در کد زیر که از _lookup() برای تغییر مسیریابی بر اساس یک شرط استفاده می‌کند:

from pecan import expose, abort
from somelib import get_user_region
class DefaultRegionController(object):
    @expose()
    def name(self):
        return "Default Region"
class USRegionController(object):
    @expose()
    def name(self):
        return "US Region"
class RootController(object):
    @expose()
    def _lookup(self, user_id, *remainder):
        if get_user_region(user_id) == 'us':
            return USRegionController(), remainder
        else:
            return DefaultRegionController(), remainder

این منطق به موقعیت مکانی یک کاربر معین و بازگرداندن یک کلاس کاملاً متفاوت بر اساس شرط وابسته است. یک تابع کمکی برای تعیین این‌که USRegionController.name به کدام نشانی وب تعلق دارد، در انجام درست این کار ناموفق خواهد بود.

بازنویسی قالب‌ها (Overriding Templates)

تابع override_template() <#pecan.core.override_template> به شما امکان می‌دهد قالب تعیین‌شده برای یک متد کنترلر را هنگام در معرض قرار گرفتن آن بازنویسی کنید. هنگامی که override_template() <#pecan.core.override_template> در داخل بدنه متد کنترلر فراخوانی شود، قالب مورد استفاده برای آن فراخوانی از متد را تغییر می‌دهد.

class MyController(object):
    @expose('template_one.html')
    def index(self):
        # ...
        override_template('template_two.html')
        return dict(message='I will now render with template_two.html')

رندر دستی (Manual Rendering)

تابع render() <#pecan.core.render> به شما این امکان را می‌دهد که با استفاده از چارچوب قالب‌سازی Pecan خروجی را به‌صورت دستی رندر کنید. کافی است مسیر قالب و مقادیر مورد نیاز قالب را ارسال کنید؛ render() <#pecan.core.render> خروجی رندرشده را در قالب متن برمی‌گرداند.

@expose()
def controller(self):
    return render('my_template.html', dict(message='I am the namespace'))

تعریف رندرکننده‌های سفارشی (Defining Custom Renderers)

برای تعریف یک رندرکنندهٔ سفارشی، می‌توانید کلاسی ایجاد کنید که از پروتکل رندرکننده پیروی کند:

class MyRenderer(object):
    def __init__(self, path, extra_vars):
        '''
        Your renderer is provided with a path to templates,
        as configured by your application, and any extra
        template variables, also as configured
        '''
        pass
    def render(self, template_path, namespace):
        '''
        Lookup the template based on the path, and render
        your output based upon the supplied namespace
        dictionary, as returned from the controller.
        '''
        return str(namespace)

برای فعال‌سازی رندرکنندهٔ سفارشی خود، کلید custom_renderers را در پیکربندی برنامهٔ خود تعریف کنید:

app = {
    'custom_renderers' : {
        'my_renderer' : MyRenderer
    },
    # ...
}

... و رندرکننده را در متد expose() <#pecan.decorators.expose> مشخص کنید:

class RootController(object):
    @expose('my_renderer:template.html')
    def index(self):
        return dict(name='Bob')

نگاشت URL (URL Mapping)

به‌طور پیش‌فرض، RestController <#pecan.rest.RestController> بدین صورت مسیریابی می‌کند:

کلاس RestController <#pecan.rest.RestController> در Pecan از رشته‌پرس‌وجوی ?_method= برای دور زدن عدم پشتیبانی از افعال PUT و DELETE هنگام ارسال فرم‌ها در بیشتر مرورگرهای امروزی استفاده می‌کند.

علاوه بر مدیریت REST، کلاس RestController <#pecan.rest.RestController> همچنین از بازنویسی‌های مسیریابی index()، _default() و _lookup() پشتیبانی می‌کند.

هشدار:

from pecan import expose
from pecan.rest import RestController
from mymodel import Author, Book
class BooksController(RestController):
    @expose()
    def get(self, author_id, id):
        author = Author.get(author_id)
        if not author_id:
            abort(404)
        book = author.get_book(id)
        if not book:
            abort(404)
        return book.title
class AuthorsController(RestController):
    books = BooksController()
    @expose()
    def get(self, id):
        author = Author.get(id)
        if not author:
            abort(404)
        return author.name
class RootController(object):
    authors = AuthorsController()

تعریف عملیات سفارشی

افزون بر متدهای پیش‌فرض تعریف‌شده در بالا، می‌توانید با تعریف دیکشنری ویژه _custom_actions، رفتارهای بیشتری را به یک RestController <#pecan.rest.RestController> اضافه کنید.

برای نمونه:

from pecan import expose
from pecan.rest import RestController
from mymodel import Book
class BooksController(RestController):
    _custom_actions = {
        'checkout': ['POST']
    }
    @expose()
    def checkout(self, id):
        book = Book.get(id)
        if not book:
            abort(404)
        book.checkout()

_custom_actions نام متدها را به فهرستی از افعال معتبر HTTP برای آن عملیات‌های سفارشی نگاشت می‌کند. در این مورد، متد checkout() از فعل POST پشتیبانی می‌کند..SH "پیکربندی برنامه‌های PECAN (CONFIGURING PECAN APPLICATIONS)"

پیکربندی Pecan بسیار آسان است. تا زمانی که از قراردادهای مشخصی پیروی کنید، استفاده، تنظیم و کار با پیکربندی بسیار شهودی خواهد بود.

فایل‌های پیکربندی Pecan از نوع پایتون خالص هستند. هر "بخش" (section) از پیکربندی، یک دیکشنری اختصاص داده‌شده به یک نام متغیر در ماژول پیکربندی است.

مقادیر پیش‌فرض (Default Values)

در زیر فهرست کاملی از مقادیر پیش‌فرضی که این چارچوب استفاده می‌کند آمده است:

server = {
    'port' : '8080',
    'host' : '0.0.0.0'
}
app = {
    'root' : None,
    'modules' : [],
    'static_root' : 'public',
    'template_path' : ''
}

پیکربندی برنامه (Application Configuration)

مقادیر پیکربندی app توسط Pecan استفاده می‌شوند تا برنامه شما را درون یک برنامه معتبر WSGI http://www.wsgi.org/en/latest/what.html قرار دهند. پیکربندی app مختص برنامه شما است و شامل مقادیری مانند مکان کلاس کنترل‌کننده ریشه (root controller) می‌باشد.

یک پیکربندی متداول برنامه ممکن است به این شکل باشد:

app = {
    'root' : 'project.controllers.root.RootController',
    'modules' : ['project'],
    'static_root'   : '%(confdir)s/public',
    'template_path' : '%(confdir)s/project/templates',
    'debug' : True
}

بیایید به هر مقدار و معنای آن نگاهی بیندازیم:

هشدار:

هشدار:

همچنین ببینید:

server = {
    'port' : '8080',
    'host' : '0.0.0.0'
}

پیکربندی‌های اضافی (Additional Configuration)

ممکن است برنامهٔ شما در زمان اجرا به مقادیر پیکربندی دیگری (مانند اطلاعات احراز هویت API شخص ثالث) نیاز داشته باشد. این تنظیمات را در بلوک‌های اختصاصی خودشان در فایل پیکربندی قرار دهید.

twitter = {
    'api_key' : 'FOO',
    'api_secret' : 'SECRET'
}

دسترسی به پیکربندی در زمان اجرا (Accessing Configuration at Runtime)

شما می‌توانید در زمان اجرا از طریق pecan.conf به هر مقدار پیکربندی دسترسی داشته باشید. این موارد شامل مقادیر سفارشی، مقادیر مربوط به برنامه و مقادیر خاص سرور است.

برای مثال، اگر نیاز به تعیین یک مدیر (administrator) سراسری داشتید، می‌توانید این کار را به این صورت در فایل پیکربندی انجام دهید:

administrator = 'foo_bar_user'

و در pecan.conf به این شکل قابل دسترسی خواهد بود:

>>> from pecan import conf
>>> conf.administrator
'foo_bar_user'

تبدیل به دیکشنری (Dictionary Conversion)

در شرایط خاصی ممکن است بخواهید با کلیدها و مقادیر دقیقاً در قالب دیکشنری رفتار کنید. شیء Config <#pecan.configuration.Config> دارای یک متد کمکی برای این منظور است که یک نمایش دیکشنری از پیکربندی، شامل مقادیر تو در تو را بازمی‌گرداند.

در ادامه نحوهٔ دسترسی به متد to_dict() <#pecan.configuration.Config.to_dict> و آنچه به عنوان نتیجه بازمی‌گرداند (جهت اختصار کوتاه شده است) آورده شده است:

>>> from pecan import conf
>>> conf
Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
>>> conf.to_dict()
{'app': {'errors': {}, 'template_path': '', 'static_root': 'public', [...]

>>> from pecan import conf
>>> conf
Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
>>> conf.to_dict('prefixed_')
{'prefixed_app': {'prefixed_errors': {}, 'prefixed_template_path': '', 'prefixed_static_root': 'prefixed_public', [...]

کلیدهای نقطه‌دار، شناسه‌های غیرپایتونی و دیکشنری‌های بومی (Dotted Keys, Non-Python Identifiers, and Native Dictionaries)

گاهی اوقات می‌خواهید یک گزینهٔ پیکربندی را مشخص کنید که شامل کلیدهای نقطه‌دار است یا یک شناسهٔ معتبر در Python نیست، مانند (). این شرایط به‌ویژه هنگام پیکربندی logging در Python رایج است. با ارسال یک کلید ویژه، یعنی __force_dict__، می‌توان با بلوک‌های پیکربندی مجزا مانند دیکشنری‌های بومی رفتار کرد.

logging = {
    'root': {'level': 'INFO', 'handlers': ['console']},
    'loggers': {
        'sqlalchemy.engine': {'level': 'INFO', 'handlers': ['console']},
        '__force_dict__': True
    },
    'formatters': {
        'custom': {
            '()': 'my.package.customFormatter'
        }
    }
}
from myapp import conf
assert isinstance(conf.logging.loggers, dict)
assert isinstance(conf.logging.loggers['sqlalchemy.engine'], dict)

مبانی دکوراتور secure (secure Decorator Basics)

می‌توانید با استفاده از دکوراتور secure() <#pecan.secure.secure>، کل زیردرخت‌های کنترلر یا فراخوانی متدهای مجزا را تحت کنترل دسترسی قرار دهید.

برای اعمال دکوراتور روی یک متد، از یک آرگومان استفاده کنید:

secure('<check_permissions_method_name>')

برای ایمن‌سازی یک کلاس، آن را با دو آرگومان فراخوانی کنید:

secure(object_instance, '<check_permissions_method_name>')

from pecan import expose
from pecan.secure import secure
class HighlyClassifiedController(object):
    pass
class UnclassifiedController(object):
    pass
class RootController(object):
    @classmethod
    def check_permissions(cls):
        if user_is_admin():
            return True
        return False
    @expose()
    def index(self):
      #
      # This controller is unlocked to everyone,
      # and will not run any security checks.
      #
      return dict()
    @secure('check_permissions')
    @expose()
    def topsecret(self):
        #
        # This controller is top-secret, and should
        # only be reachable by administrators.
        #
        return dict()
    highly_classified = secure(HighlyClassifiedController(), 'check_permissions')
    unclassified = UnclassifiedController()

from pecan import expose
from pecan.secure import SecureController, unlocked
class HighlyClassifiedController(object):
    pass
class UnclassifiedController(object):
    pass
class RootController(SecureController):
    @classmethod
    def check_permissions(cls):
        if user_is_admin():
            return True
        return False
    @expose()
    @unlocked
    def index(self):
      #
      # This controller is unlocked to everyone,
      # and will not run any security checks.
      #
      return dict()
    @expose()
    def topsecret(self):
        #
        # This controller is top-secret, and should
        # only be reachable by administrators.
        #
        return dict()
    highly_classified = HighlyClassifiedController()
    unclassified = unlocked(UnclassifiedController())

نوشتن متدهای احراز هویت/مجوزدهی (Writing Authentication/Authorization Methods)

متد check_permissions() <#pecan.secure.SecureControllerBase.check_permissions> باید برای تعیین وضعیت احراز هویت و مجوزدهی کاربر به کار رود. کدی که در اینجا پیاده‌سازی می‌کنید می‌تواند از بررسی‌های سادهٔ نشست (کاربر فعلی به عنوان مدیر سیستم احراز هویت شده است) تا اتصال به یک سرویس LDAP متغیر باشد.

اطلاعات بیشتر دربارهٔ secure (More on secure)

متد secure() <#pecan.secure.secure> کاربردهای پیشرفتهٔ گوناگونی دارد که به شما امکان می‌دهد خط‌مشی‌های امنیتی پایداری برای برنامهٔ خود تعریف کنید.

نخست، می‌توانید نام یک متد کلاس یا یک متد نمونه از کنترلر را در قالب یک رشته ارسال کنید تا به عنوان متد check_permissions() <#pecan.secure.SecureControllerBase.check_permissions> استفاده شود. متدهای نمونه به‌ویژه در صورتی کاربرد دارند که بخواهید دسترسی به ویژگی‌های نمونه‌ای از یک مدل را اعتبارسنجی کنید. مثال زیر از یک فایل‌سیستم مجازی پایه را در نظر بگیرید.

from pecan import expose
from pecan.secure import secure
from myapp.session import get_current_user
from myapp.model import FileObject
class FileController(object):
    def __init__(self, name):
        self.file_object = FileObject(name)
    def read_access(self):
        self.file_object.read_access(get_current_user())
    def write_access(self):
        self.file_object.write_access(get_current_user())
    @secure('write_access')
    @expose()
    def upload_file(self):
        pass
    @secure('read_access')
    @expose()
    def download_file(self):
        pass
class RootController(object):
    @expose()
    def _lookup(self, name, *remainder):
        return FileController(name), remainder

متد secure() <#pecan.secure.secure> همچنین یک آرگومان از نوع تابع می‌پذیرد. هنگام ارسال یک تابع، اطمینان حاصل کنید که تابع مورد نظر از فایلی دیگر وارد شده باشد یا در همان فایل پیش از تعریف کلاس تعریف شده باشد، در غیر این صورت احتمالاً در زمان وارد کردن ماژول با خطا مواجه خواهید شد.

from pecan import expose
from pecan.secure import secure
from myapp.auth import user_authenitcated
class RootController(object):
    @secure(user_authenticated)
    @expose()
    def index(self):
        return 'Logged in'

همچنین می‌توانید از متد secure() <#pecan.secure.secure> برای تغییر رفتار یک SecureController <#pecan.secure.SecureController> استفاده کنید. دکوریت کردن یک متد یا بسته‌بندی (wrap) یک زیرکنترلر به Pecan اعلام می‌کند که به جای متد پیش‌فرض کنترلر، از یک تابع امنیتی دیگر استفاده کند. این قابلیت برای شرایطی که به سطح یا نوع متفاوتی از امنیت نیاز دارید بسیار مفید است.

from pecan import expose
from pecan.secure import SecureController, secure
from myapp.auth import user_authenticated, admin_user
class ApiController(object):
    pass
class RootController(SecureController):
    @classmethod
    def check_permissions(cls):
        return user_authenticated()
    @classmethod
    def check_api_permissions(cls):
        return admin_user()
    @expose()
    def index(self):
        return 'logged in user'
    api = secure(ApiController(), 'check_api_permissions')

در مثال بالا، Pecan تنها زمانی admin_user() را فراخوانی می‌کند که درخواستی برای /api/ ثبت شود..SS "چندین کنترل‌کننده امن (Multiple Secure Controllers)"

کنترل‌کننده‌های امن را می‌توان به‌صورت تودرتو قرار داد تا سطوح امنیتی افزایشی را روی کنترل‌کننده‌های فرعی فراهم کنند. در مثال زیر، هنگامی که درخواستی برای /admin/index/ ثبت می‌شود، Pecan ابتدا check_permissions() <#pecan.secure.SecureControllerBase.check_permissions> را روی RootController و سپس check_permissions() <#pecan.secure.SecureControllerBase.check_permissions> را روی AdminController فراخوانی می‌کند.

from pecan import expose
from pecan.secure import SecureController
from myapp.auth import user_logged_in, is_admin
class AdminController(SecureController):
    @classmethod
    def check_permissions(cls):
        return is_admin()
    @expose()
    def index(self):
        return 'admin dashboard'
class RootController(SecureController):
    @classmethod
    def check_permissions(cls):
        return user_logged_in
    @expose()
    def index(self):
        return 'user dashboard'

پیاده‌سازی قلاب PECAN (Implementating a Pecan Hook)

در مثال زیر، یک قلاب ساده اطلاعاتی درباره درخواست جمع‌آوری کرده و آن را در stdout چاپ می‌کند.

پیاده‌سازی قلاب شما باید PecanHook <#pecan.hooks.PecanHook> را وارد (import) کند تا بتواند به‌عنوان کلاس پایه استفاده شود. از آنجا، می‌توانید متدهای on_route() <#pecan.hooks.PecanHook.on_route>، before() <#pecan.hooks.PecanHook.before>، after() <#pecan.hooks.PecanHook.after> یا on_error() <#pecan.hooks.PecanHook.on_error> را برای تعریف رفتار مورد نظر بازنویسی کنید.

from pecan.hooks import PecanHook
class SimpleHook(PecanHook):
    def before(self, state):
        print "\nabout to enter the controller..."
    def after(self, state):
        print "\nmethod: \t %s" % state.request.method
        print "\nresponse: \t %s" % state.response.status

به هر یک از متدهای on_route() <#pecan.hooks.PecanHook.on_route>، before() <#pecan.hooks.PecanHook.before> و after() <#pecan.hooks.PecanHook.after> یک شیء وضعیت مشترک ارسال می‌شود که شامل اطلاعات مفیدی است؛ از جمله اشیاء request و response، و اینکه کدام کنترل‌کننده توسط مسیریابی Pecan انتخاب شده است:

class SimpleHook(PecanHook):
    def on_route(self, state):
        print "\nabout to map the URL to a Python method (controller)..."
        assert state.controller is None  # Routing hasn't occurred yet
        assert isinstance(state.request, webob.Request)
        assert isinstance(state.response, webob.Response)
        assert isinstance(state.hooks, list)  # A list of hooks to apply
    def before(self, state):
        print "\nabout to enter the controller..."
        if state.request.path == '/':
            #
            # `state.controller` is a reference to the actual
            # `@pecan.expose()`-ed controller that will be routed to
            # and used to generate the response body
            #
            assert state.controller.__func__ is RootController.index.__func__
            assert isinstance(state.arguments, inspect.Arguments)
            print state.arguments.args
            print state.arguments.varargs
            print state.arguments.keywords
        assert isinstance(state.request, webob.Request)
        assert isinstance(state.response, webob.Response)
        assert isinstance(state.hooks, list)

به on_error() <#pecan.hooks.PecanHook.on_error> یک شیء وضعیت مشترک و استثنای اصلی پاس داده می‌شود. اگر یک گرداننده on_error() <#pecan.hooks.PecanHook.on_error> یک شیء Response برگرداند، این پاسخ به کاربر نهایی تحویل داده می‌شود و هیچ قلاب on_error() <#pecan.hooks.PecanHook.on_error> دیگری اجرا نخواهد شد:

class CustomErrorHook(PecanHook):
    def on_error(self, state, exc):
        if isinstance(exc, SomeExceptionType):
            return webob.Response('Custom Error!', status=500)

app = {
    'root' : '...'
    # ...
    'hooks': lambda: [SimpleHook()]
}

from pecan import expose
from pecan.hooks import HookController
from my_hooks import SimpleHook
class SimpleController(HookController):
    __hooks__ = [SimpleHook()]
    @expose('json')
    def index(self):
        print "DO SOMETHING!"
        return dict()

pecan serve config.py
serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
about to enter the controller...
DO SOMETHING!
method:      GET
response:    200 OK

from pecan import expose
from pecan.hooks import PecanHook, HookController
class ParentHook(PecanHook):
    priority = 1
    def before(self, state):
        print "\nabout to enter the parent controller..."
class CommonHook(PecanHook):
    priority = 2
    def before(self, state):
        print "\njust a common hook..."
class SubHook(PecanHook):
    def before(self, state):
        print "\nabout to enter the subcontroller..."
class SubMixin(object):
    __hooks__ = [SubHook()]
# We'll use the same instance for both controllers,
# to avoid double calls
common = CommonHook()
class SubController(HookController, SubMixin):
    __hooks__ = [common]
    @expose('json')
    def index(self):
        print "\nI AM THE SUB!"
        return dict()
class RootController(HookController):
    __hooks__ = [common, ParentHook()]
    @expose('json')
    def index(self):
        print "\nI AM THE ROOT!"
        return dict()
    sub = SubController()

pecan serve config.py
serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
GET / HTTP/1.1" 200
about to enter the parent controller...
just a common hook
I AM THE ROOT!

pecan serve config.py
serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
GET /sub HTTP/1.1" 200
about to enter the parent controller...
just a common hook
about to enter the subcontroller...
I AM THE SUB!

RequestViewerHook

این قلاب برای اهداف اشکال‌زدایی مفید است. این قلاب به تمام صفت‌های شیء response به‌علاوهٔ چند صفت دیگر که مختص این فریم‌ورک هستند دسترسی دارد.

دو روش اصلی وجود دارد که این قلاب می‌تواند اطلاعات مربوط به یک درخواست را ارائه دهد:

به‌طور پیش‌فرض، هر دو خروجی فعال هستند.

همچنین ببینید:

پیکربندی RequestViewerHook

چندین روش برای پیکربندی مناسب و اجرای این قلاب وجود دارد. با این حال، دانستن این نکته مفید است که برای راه‌اندازی و اجرای آن به هیچ پیکربندی اولیه‌ای نیاز نیست.

به‌طور پیش‌فرض، اطلاعات مربوط به این موارد را خروجی می‌دهد:

پیکربندی پیش‌فرض این مقادیر را از طریق stdout در ترمینال نمایش می‌دهد و همچنین آن‌ها را به سرایندهای پاسخ (به فرم X-Pecan-item_name) اضافه می‌کند.

خروجی ترمینال برای یک درخواست /favicon.ico ممکن است به این شکل باشد:

path         - /favicon.ico
status       - 404 Not Found
method       - GET
controller   - The resource could not be found.
params       - []
hooks        - ['RequestViewerHook']

در مورد بالا، فایل پیدا نشد و اطلاعات در stdout چاپ شد. علاوه بر این، سرایندهای زیر در پاسخ HTTP حضور خواهند داشت:

X-Pecan-path        /favicon.ico
X-Pecan-status      404 Not Found
X-Pecan-method      GET
X-Pecan-controller  The resource could not be found.
X-Pecan-params      []
X-Pecan-hooks       ['RequestViewerHook']

دیکشنری پیکربندی انعطاف‌پذیر است (هیچ‌یک از کلیدها الزامی نیستند) و می‌تواند شامل دو کلید باشد: items و blacklist.

در صورتی که قلاب مستقیماً پیکربندی شود، به این صورت خواهد بود (برای اختصار کوتاه شده است):

...
'hooks': lambda: [
    RequestViewerHook({'items':['path']})
]