آموزش افزونه نویسی برای پایتون با زبان C

امروز با مقاله دیگری از سری مقاله های آموزش پایتون همراه شما هستیم، در این مقاله میخواهیم چگونگی افزونه نویسی در پایتون به کمک کدهای زبان C را مورد بررسی قرار دهیم..

به منظور نوشتن افزونه های اختصاصی جهت استفاده در اسکریپت های پایتون و اپلیکیشن های خود، لازم است به فایل های header پایتون دسترسی داشته باشید.در دستگاه هایی که سیستم عامل Unix بر روی آن نصب است، می بایست یک پکیج مختص توسعه دهنده (developer-specific) نظیر python2.5-dev را نصب نمایید.

کاربران ویندوز این فایل های header را به هنگام استفاده از binary Python installer به صورت یک پکیج دریافت می کنند. علاوه بر آن، برای درک مفاهیم این مبحث و نوشتن افزونه های اختصاصی خود جهت استفاده در اسکریپت های پایتون، لازم است آشنایی در سطح پیشرفته با زبان های C یا C++ داشته باشید.

آموزش Python : اولین نمونه از افزونه اختصاصی Python

کد ماژول و افزونه های پایتون، بایستی مانند زیر در چهار بخش سازمان دهی شود:

فایل header با اسم و پسوند Python.h.
توابع C که می خواهید به عنوان interface و الگوی پیاده سازی ماژول اختصاصی خود در اختیار توسعه دهنده قرار دهید.
یک جدول که اسم توابع اختصاصی شما را به توابع C داخل افزونه (کتابخانه یا ماژول) نگاشت می کند (method mapping table).
یک تابع سازنده جهت مقداردهی اولیه و نمونه سازی از کلاس (initialization function).

فایل Python.h

لازم است فایل Python.h را داخل فایلی که کدهای C شما را دربرمی گیرد (source file) قید نمایید. بدین وسیله شما به توابع کتابخانه ای درون ساخته ی پایتون (internal Python API) که برای ادغام و معرفی ماژول مورد نظر در interpreter (hook کردن کد ماژول شما در مفسر) بکار می رود، دسترسی خواهید داشت. لازم است Python.h را قبل از هر فایل header مورد نیاز دیگری لحاظ نمایید.

توابع C

اسم متد، نوع و تعداد پارامترهای ورودی (Signature) توابع اختصاصی شما و پیاده سازی آن، بایستی بر اساس یکی از الگوهای زیر انجام شود:

static PyObject *MyFunction( PyObject *self, PyObject *args );
static PyObject *MyFunctionWithKeywords(PyObject *self,
                                 PyObject *args,
                                 PyObject *kw);
static PyObject *MyFunctionWithNoArgs( PyObject *self );

هر یک از متدهای اعلان شده ی فوق، در خروجی خود یک آبجکت Python برمی گرداند. در پایتون مفهومی به نام تابع void (تابعی که خروجی ندارد یا مقداری را برنمی گرداند) وجود ندارد. اگر شما نمی خواهید که توابع مقدار خروجی داشته باشند، لازم است مقدار None را بازگردانی نمایید. header های پایتون یک macro (خط دستور) به نام Py_RETURN_NONE در خود به صورت از پیش تعریف شده دارند که این کار را انجام می دهند.

از آنجایی که اسم توابع C هیچگاه خارج از ماژول/افزونه قابل مشاهده و دسترسی نیستند، شما می توانید هر اسمی برای متدهای اختصاصی خود انتخاب کنید. لازم به ذکر است که این توابع با کلیدواژه ی static تعریف می شوند. اسم توابع C معمولا از ترکیبی از اسم ماژول و متد مورد نظر تشکیل می شود. در زیر نمونه ای را مشاهده می کنید:

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Do your stuff here. */
   Py_RETURN_NONE;
}

کد حاضر یک تابع Python به نام func را تعریف می کند که داخل افزونه ی module کپسوله سازی شده است. حال شما به این توابع C داخل جدول نگاشت متد (method table) Pointer و اشاره گر تعریف می کنید که در بخش بعدی کد برنامه ی شما انجام می شود.

آموزش برنامه نویسی پایتون : جدول نگاشت توابع

این جدول نگاشت متد (method table) یک آرایه ی ساده از structure های PyMethodDef است (PyMethodDef یک مدل برای تعریف متد است). این structure ساختاری مشابه زیر دارد:

struct PyMethodDef {
   char *ml_name;
   PyCFunction ml_meth;
   int ml_flags;
   char *ml_doc;
};

در زیر هر یک از اعضای این ساختار شرح داده اند:

فیلد ml_name : اسم تابع پایتون.
فیلد ml_meth : آدرس تابعی که هر یک از signature های نام برده در بخش قبلی را دارا می باشد.
فیلد ml_flags : این فیلد به مفسر پایتون اعلان می کند که فیلد دوم (ml_meth) کدام یک از signature های نام برده را اتخاذ می کند :

این flag معمولا مقداری از METH_VARARGS دارد.

اگر می خواهید آرگومان های کلیدواژه ای را در تابع تزریق نمایید، این flag می تواند OR بیتی با METH_KEYWORDS را شامل شود.

این flag همچنین می تواند مقدار METH_NOARGS را داشته باشد، بدین معنی که هیچ پارامتری به تابع فرستاده نمی شود.

فیلد ml_doc : این docstring (رشته یا comment ای که توضیحی درباره ی کارایی تابع می دهد) تابع است. اگر برنامه نویس comment ای برای تابع تنظیم نکند، در آن صورت مقدار آن NULL خواهد بود.

این جدول بایستی با یک sentinel که از NULL و 0 برای اعضای مرتبط تشکیل شده، خاتمه یابد.

مثال :

برای متد اعلان شده در بالا، از جدول نگاشت تابع (method mapping table) زیر استفاده می کنیم:

static PyMethodDef module_methods[ ] = {
   { &quotfunc&quot, (PyCFunction)module_func, METH_NOARGS, NULL },
   { NULL, NULL, 0, NULL }
};

آموزش زبان پایتون : تابع مقداردهی اولیه (initModule)

آخرین بخش ماژول یا افزونه ی اختصاصی شما بایستی تابع مقداردهنده ی اولیه (initialization function) را شامل شود. این تابع را مفسر پایتون زمانی که ماژول در حافظه بارگذاری می شود، فرامی خواند. لازم است اسم این تابع initModule انتخاب شود (Module اسم ماژول و init اسم خود تابع می باشد).

تابع مقداردهنده ی اولیه بایستی از کتابخانه که می نویسید export و خروجی گرفته شده باشد. header های Python با اعلان دستور PyMODINIT_FUNC امکان انجام این کار را در محیطی که اسکریپت ها در آن کامپایل می شوند را فراهم می آورد. کافی است به هنگام تعریف تابع مورد نظر از آن استفاده نمایید.

تابع مقداردهنده ی اولیه ی زبان C شما دارای ساختار کلی زیر می باشد:

PyMODINIT_FUNC initModule() {
   Py_InitModule3(func, module_methods, &quotdocstring...&quot);
}

در زیر شرح هر یک از پارامترهای تابع Py_InitModule3 را به تفصیل مشاهده می کنید:

پارامتر func : تابعی است که قرار است export و به اصطلاح خروجی گرفته شود.
پارامتر module_methods : اسم جدول نگاشت تابع (mapping table) که در بالا به آن اشاره شد.
پارامتر docstring : این پارامتر همان رشته ی متنی و comment ای است که جهت ارائه ی توضیح درباره ی قابلیت تابع در افزونه ی اختصاصی درج می شود.

در زیر تمامی بخش های تشکیل دهنده یک افزونه استاندارد را یکجا مشاهده می کنید:

#include < python.h>
static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Do your stuff here. */
   Py_RETURN_NONE;
}
static PyMethodDef module_methods[ ] = {
   { &quotfunc&quot, (PyCFunction)module_func, METH_NOARGS, NULL },
   { NULL, NULL, 0, NULL }
};
PyMODINIT_FUNC initModule() {
   Py_InitModule3(func, module_methods, &quotdocstring...&quot);
}
< /python.h>

مثال :

نمونه کاربردی که کلیه مفاهیم فوق را به صورت عملی بکار می برد را در زیر مشاهده می کنید:

#include < python.h>
static PyObject* helloworld(PyObject* self)
{
    return Py_BuildValue(&quots&quot, &quotHello, Python extensions!!&quot);
}
static char helloworld_docs[ ] =
    &quothelloworld( ): Any message you want to put here!!\n&quot
static PyMethodDef helloworld_funcs[ ] = {
    {&quothelloworld&quot, (PyCFunction)helloworld, 
     METH_NOARGS, helloworld_docs},
    {NULL}
};
void inithelloworld(void)
{
    Py_InitModule3(&quothelloworld&quot, helloworld_funcs,
                   &quotExtension module example!&quot);
}
< /python.h>

دستور Py_BuildValue در مثال بالا، یک مقدار Python را build یا کامپایل می کند. کد مورد نظر را داخل فایل hello.c ذخیره نمایید. در زیر با نحوه ی کامپایل و نصب ماژول که از اسکریپت پایتون فراخوانی می شود، را خواهید آموخت.

کامپایل و نصب افزونه ها (build)

پکیج distutils توزیع و نصب ماژول های پایتون، خواه ماژول های اصلی و خالص خود پایوتن باشد خواه ماژول های اختصاصی و تنظیم شده توسط توسعه دهنده، را با روشی استاندارد بسیار آسان می سازد. ماژول ها در همان قالب اولیه (source form) توزیع شده و در اختیار برنامه نویس قرار می گیرد. برنامه نویس سپس ماژول مورد نظر را با فراخوانی اسکریپت نصب (setup script) به نام setup.py ، نصب می نماید.

جهت نصب ماژول ذکر شده در بالا، بایستی اسکریپت setup.py را آماده نموده و به روش زیر اجرا نمایید:

from distutils.core import setup, Extension
setup(name='helloworld', version='1.0',  \
      ext_modules=[Extension('helloworld', ['hello.c'])])

اکنون با فراخوانی دستور زیر، تمامی مراحل لازم نظیر کامپایل و آماده سازی (linking & compilation) کد را انجام دهید. کد زیر کلیه ی مراحل مورد نیاز کامپایل و لینک ماژول با کامپایلر، دستورات linker و flag های مناسب را انجام داده، متعاقبا خروجی (.dll) را در پوشه ی مربوطه جایگذاری (کپی) می کند.

$ python setup.py install

در سیستم های مبتنی بر Unix، لازم است این دستور را با حساب کاربری root اجرا نمایید تا امکان یا مجوز درج داده در پوشه ی site-packages را داشته باشید. در سیستم عامل ویندوز لازم به انجام این کار نیست.

آموزش Python : وارد کردن و استفاده از افزونه ها در پروژه

پس از نصب افزونه ی دلخواه خود، می توانید آن را در اسکرپیت پایتون خود با دستور import وارد کرده و فراخوانی نمایید:

#!/usr/bin/python
import helloworld
print helloworld.helloworld()

خروجی زیر را تولید می کند:

Hello, Python extensions!!

ارسال پارامتر به تابع

در طول توسعه پروژه، گاه می بایست توابعی را اعلان و فراخوانی نمایید که پارامترهایی را به عنوان ورودی می پذیرد. از اینرو بایستی signature (اسم تابع + نوع، تعداد پارامتر ورودی) مربوطه را برای توابع C ماژول اختصاصی خود انتخاب نمایید. به طور مثال، تابع ذیل را در نظر بگیرید که تعدادی پارامتر به عنوان ورودی پذیرفته و بدین صورت اعلان می شود:

static PyObject *module_func(PyObject *self, PyObject *args) {
   /* Parse args and do something interesting here. */
   Py_RETURN_NONE;
}

متد table که تابع جدید را در خود کپسوله می کند، به صورت زیر خواهد بود:

static PyMethodDef module_methods[ ] = {
   { &quotfunc&quot, (PyCFunction)module_func, METH_NOARGS, NULL },
   { &quotfunc&quot, module_func, METH_VARARGS, NULL },
   { NULL, NULL, 0, NULL }
};

می توانید با استفاده از تابع کتابخانه ای PyArg_ParseTuple آرگومان های مورد نیاز را از متغیر اشاره گر (pointer) به PyObject که به عنوان آرگومان به تابع C ارسال شده، استخراج نمایید.

اولین آرگومان ارسالی به PyArg_ParseTuple، آرگومان args می باشد. این آرگومان همان آبجکتی است که باید parse یا تحلیل نحوی شود. پارامتر دوم یک رشته ی فرمت دهی (format string) است که آرگومان ها را به آن شکلی که مورد انتظار شما است، به نمایش می گذارد. به تعداد آرگومان ها، یک یا چند کاراکتر در رشته ی فرمت دهی وجود دارد که نشانگر آرگومان های مزبور می باشند.

static PyObject *module_func(PyObject *self, PyObject *args) {
   int i;
   double d;
   char *s;
   if (!PyArg_ParseTuple(args, &quotids&quot, &i, &d, &s)) {
      return NULL;
   }
   /* Do something interesting here. */
   Py_RETURN_NONE;
}

با کامپایل نمودن ورژن جدید از ماژول خود و وارد کردن آن در متن پروژه، قادر خواهید بود تابع مورد نظر را با تعداد دلخواه و نوع مختلف از آرگومان ها فراخوانی نمایید:

module.func(1, s=&quotthree&quot, d=2.0)
module.func(i=1, d=2.0, s=&quotthree&quot)
module.func(s=&quotthree&quot, d=2.0, i=1)

تابع PyArg_ParseTuple

در زیر تعداد و نوع ورودی های تابع را به شکل استاندارد (signature) PyArg_ParseTuple مشاهده می کنید:

int PyArg_ParseTuple(PyObject* tuple,char* format,...)

در صورتی که عملیات با موفقیت انجام شود، مقداری غیر صفر و چنانچه عملیات ناموفق بوده و خطا رخ داد، مقدار 0 در خروجی بازگردانی می شود. tuple، آبجکت PyObject* بوده که همان آرگومان دوم ارسال شده به تابع C می باشد. آرگومان سوم، format، یک رشته ی C می باشد که نشانگر آرگومان های الزامی و اختیاری می باشد.

در زیر لیستی از کدهای فرمت دهی که به تابع PyArg_ParseTuple ارسال می شود همراه با شرح هر یک مشاهده می کنید:

کد c در پایتون معادل char در زبان C : یک رشته پایتون با طول 1 (رشته ی حاوی یک کاراکتر) معادل char در C می شود.
کد d در پایتون معادل double در زبان C : یک مقدار عددی float (ممیز و اعشاری) که معادل double (اعشاری با دقت بیشتر) در C محسوب می شود.
کد f در پایتون معادل float در زبان C : یک float (مقدار عددی اعشاری از نوع float) در پایتون معادل float در C محسوب می شود.
کد i در پایتون معادل int در زبان C : یک int (نوع عدد صحیح) معادل long در زبان C درنظر گرفته می شود.
کد l در پایتون معادل long در زبان C : یک int در زبان پایتون معادل نوع داده ای long در زبان C در نظر گرفته می شود.
کد L در پایتون معادل long long در زبان C : یک int یا نوع داده ای عدد صحیح در زبان پایتون، معادل long long در زبان C محسوب می شود.
کد O در پایتون معادل PyObject* در زبان C : یک اشاره گر غیر NULL به آرگومان Python بازگردانی می کند.
کد s در پایتون معادل char* در زبان C : رشته پایتون بدون مقادیر null جاسازی شده (embedded) به char* در زبان C فرمت دهی / تبدیل می شود.
کد s# در پایتون معادل char*+int در زبان C : رشته Python را به آدرس و طول سازگار در C تبدیل می کند.
کد t# در پایتون معادل char*+int در زبان C : کاربردی مشابه s# دارد با این تفاوت که هر آبجکتی که اینترفیس read-only را پیاده سازی کند، می پذیرد.
کد u در پایتون معادل Py_UNICODE* در زبان C : کاراکترهای Unicode (null-terminated buffer) مستقر در بافر که انتهای آن به null ختم می شود را به آبجکت Unicode پایتون تبدیل می کند.
کد u# در پایتون معادل Py_UNICODE*+int در زبان C : نوع دیگر از u که در دو متغیر C ذخیره می شود، اولی یک اشاره گر به آدرس Unicode مستقر در بافر و دومی طول آن.
کد w# در پایتون معادل char*+int در زبان C : مشابه s#، اما هر آّبجکتی که اینترفیس read/write بافر را پیاده سازی می کند، پذیرفته و با آن سازگاری دارد.
کد z در پایتون معادل char* در زبان C : کاربری مشابه s دارد با این تفاوت که None نیز می پذیرد (char* زبان C را بر روی NULL تنظیم می کند).
کد z# در پایتون معادل char*+int در زبان C : کاربردی مشابه s# دارد اما None نیز می پذیرد (char* زبان C را روی NULL تنظیم می نماید).
کد (...) در پایتون معادل as per ... در زبان C : یک دنباله (sequence) پایتون که هر آیتم در آن یک آرگومان در نظر گرفته می شود.
کد | در پایتون معادل double در زبان C : آرگومان های زیر اختیاری می باشد.
کد : در پایتون معادل double در زبان C : قبل از اسم تابع در پیغام های خطا قرار می گیرد.
کد ; در پایتون معادل double در زبان C : قبل از درج کل متن پیغام خطا قرار می گیرد.

بازگردانی مقادیر در خروجی

تابع Py_BuildValue، درست مانند PyArg_ParseTuple ، یک رشته ی فرمت دهی (string format) به عنوان ورودی دریافت می کند. بجای ارسال آدرس مقادیری که کامپایل می کنید، بایستی خود مقادیر را به عنوان آرگومان به تابع مورد نظر بفرستید. در زیر مثالی از نحوه ی پیاده سازی یک تابع که عملیات جمع را انجام می دهد، تابع add، مشاهده می کنید:

static PyObject *foo_add(PyObject *self, PyObject *args) {
   int a;
   int b;
   if (!PyArg_ParseTuple(args, &quotii&quot, &a, &b)) {
      return NULL;
   }
   return Py_BuildValue(&quoti&quot, a + b);
}

معادل پیاده سازی آن در زبان پایتون به صورت زیر می باشد:

def add(a, b):
   return (a + b)

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

static PyObject *foo_add_subtract(PyObject *self, PyObject *args) {
   int a;
   int b;
   if (!PyArg_ParseTuple(args, &quotii&quot, &a, &b)) {
      return NULL;
   }
   return Py_BuildValue(&quotii&quot, a + b, a - b);
}

معادل پیاده سازی آن در زبان پایتون به صورت خواهد بود:

def add_subtract(a, b):
   return (a + b, a - b)

تابع Py_BuildValue

در زیر روش استاندارد تنظیم اسم تابع، نوع و تعداد پارامترهای ورودی آن که signature خوانده می شود را ویژه ی تابع Py_BuildValue مشاهده می کنید:

PyObject* Py_BuildValue(char* format,...)

پارامتر format، یک رشته ی C بوده و نشانگر آبجکت Python است که پارامتر حاضر باید نهایتا به آن کامپایل شود. آرگومان های زیر مقادیر C هستند که خروجی از آن ها ساخته و کامپایل می شود. نتیجه ی PyObject* یک اشاره گر (reference) جدید می باشد.

جدول زیر code string های پرکاربرد را با ذکر کارایی هر یک در اختیار شما قرار می دهد:

کد c در پایتون معادل char در زبان C : یک char زبان C، به رشته ای با طول یک کاراکتر تبدیل می شود.
کد d در پایتون معادل double در زبان C : یک نوع عددی double زبان C، به float در پایتون تبدیل می شود.
کد f در پایتون معادل float در زبان C : یک float یا نوع عددی اعشاری زبان C، به همان float در پایتون تبدیل می شود.
کد i در پایتون معادل int در زبان C : یک Int زبان C به همان int (نوع عددی صحیح) در پایتون تبدیل می شود.
کد l در پایتون معادل long در زبان C : یک long در زبان C به int در پایتون تبدیل می شود.
کد N در پایتون معادل PyObject* در زبان C : یک آبجکت پایتون ارسال کرده ولی reference count (تعداد دفعاتی که آبجکت مورد نظر به آن دسترسی صورت می گیرد) آن را افزایش نمی دهد.
کد O در پایتون معادل PyObject* در زبان C : یک آبجکت پایتون ارسال کرده و reference count آن را طبق انتظار یک واحد افزایش می دهد.
کد O& در پایتون معادل convert+void* در زبان C : رشته پایتون بدون مقادیر null جاسازی شده (embedded) به char* در زبان C فرمت دهی / تبدیل می شود.
کد s در پایتون معادل char* در زبان C : یک char* که در انتهای خود 0 داشته را به رشته ی Python تبدیل می نماید یا NULL را به None.
کد s# در پایتون معادل char*+int در زبان C : یک رشته ی C و طول (length) آن را به یک آبجکت Python تبدیل می کند. اگر اشاره گر از نوع string (string pointer) برابر NULL باشد، طول یا length نادیده گرفته شده و None در خروجی بازگردانی می کند.
کد u در پایتون معادل Py_UNICODE* در زبان C : یک رشته که در سطح زبان C تعریف شده و انتهای آن مقدار NULL وجود دارد را به یونیکد پایتون تبدیل کرده و اگر NULL بود آن را به None تبدیل می کند. Buffer ای از داده های Unicode که انتهای آن null وجود دارد را به آبجکت پایتون تبدیل می کند. اگر Unicode buffer برابر NULL بود، در خروجی None بازیابی می شود.
کد u# در پایتون معادل Py_UNICODE*+int در زبان C : یک رشته ی تعریف شده در سطح C و طول آن را به آبجکت Unicode پایتون تبدیل می کند یا NULL را به None تبدیل می کند. به عبارت دیگر، یک Unicode (که استانداردهای USC-2 یا UCS-4) مستقر در buffer یا حافظه میانی و طول (length) آن را به آبجکت Unicode پایتون تبدیل می کند. اگر اشاره گر به Unicode موجود در buffer برابر NULL بود، طول آن نادیده گرفته شده و None را در خروجی برمی گرداند.
کد w# در پایتون معادل char*+int در زبان C : مشابه s#، با این تفاوت که هر آبجکتی که اینترفیس read-write را پیاده سازی می کند، می پذیرد. متغیر char * طوری تنظیم شده که به اولین بایت از buffer اشاره کند و Py_ssize_t را بر روی طول buffer تنظیم می کند.
کد z در پایتون معادل char* در زبان C : مشابه s، با این تفاوت که None نیز می پذیرد (char* در C را روی NULL تنظیم می کند).
کد z# در پایتون معادل char*+int در زبان C : کاربردی مشابه s# دارد (char* در C را بر روی NULL تنظیم می کند).
کد (...) در پایتون معادل as per ... در زبان C : از دنباله ای از مقادیر C، یک متغیر tuple در پایتون می سازد.
کد [...] در پایتون معادل as per ... در زبان C : از مقادیر C، یک لیست (list) در پایتون تولید می کند.
کد {...} در پایتون معادل as per ... در زبان C : از دنباله ای از مقادیر C، یک dictionary که المان های آن به صورت متناوب، کلید و مقدار، سازمان دهی شده، ایجاد می کند.

به طور مثال تابع Py_BuildValue("{issi}",23,"zig","zag",42) یک dictionary پایتون به صورت {23:'zig','zag':42} در خروجی تولید می کند.

با دیگر آموزش های ما در زمینه آموزش پایتون و دیگر زبان های برنامه نویسی همراه ما باشید...

آموزش افزونه نویسی برای پایتون با زبان C

آموزش Python : اولین نمونه از افزونه اختصاصی Python

فایل Python.h

توابع C

آموزش برنامه نویسی پایتون : جدول نگاشت توابع

مثال :

آموزش زبان پایتون : تابع مقداردهی اولیه (initModule)

مثال :

کامپایل و نصب افزونه ها (build)

آموزش Python : وارد کردن و استفاده از افزونه ها در پروژه

ارسال پارامتر به تابع

تابع PyArg_ParseTuple

بازگردانی مقادیر در خروجی

تابع Py_BuildValue

یادگیری برنامه نویسی، شروع

۱۲ قانون ساده برای یادگیری یک زبان کدنویسی (بخش۲)

جلسه دوم آموزش پایتون: اشکال زدایی چیست؟