# 1. Python’ı Başka Bir Uygulamaya Gömme

Önceki bölümlerde Python’un nasıl genişletileceği, yani Python’a bir C fonksiyonları kitaplığı ekleyerek Python’un işlevselliğinin nasıl genişletileceği tartışıldı. Bunu ayrıca tam tersi şekilde de yapmak mümkündür: Python’u içine gömerek C/C++ uygulamanızı zenginleştirin. Gömme işlemi, uygulamanıza bazı işlevlerini C veya C++ yerine Python’da uygulama yeteneği sağlar. Bu birçok amaç için kullanılabilir; bir örnek olarak kullanıcıların Python’da bazı komut dosyaları yazarak uygulamayı ihtiyaçlarına göre uyarlamalarına izin vermek olabilir. Bazı işlevler Python’da daha kolay yazılabilecekse kendiniz de kullanabilirsiniz.

Python’u gömmek, onu genişletmeye benzer, ancak tam olarak değil. Aralarındaki farksa Python’u genişlettiğinizde, uygulamanın ana programının hala Python yorumlayıcısı olması; Python’u gömerseniz, ana programın Python ile hiçbir ilgisi olmayabilmesidir — bunun yerine, uygulamanın bazı bölümleri bazı Python kodlarını çalıştırmak için zaman zaman Python yorumlayıcısını çağırır.

Yani Python’u gömüyorsanız, kendi ana programınızı sağlıyorsunuz demektir. Bu ana programın yapması gereken şeylerden biri Python yorumlayıcısını başlatmaktır. En azından `Py_Initialize()` fonksiyonunu çağırmalısınız. Python’a komut satırı argümanlarını iletmek için opsiyonel çağrılar vardır. Daha sonra uygulamanın herhangi bir yerinden yorumlayıcıyı çağırabilirsiniz.

Yorumlayıcıyı çağırmanın birkaç farklı yolu vardır: Python deyimlerini içeren bir dizeyi `PyRun_SimpleString()` öğesine veya bir stdio dosya işaretçisini ve bir dosya adını (yalnızca hata mesajlarında tanımlama için) `PyRun_SimpleFile()` ‘a iletebilirsiniz. Python nesnelerini oluşturmak ve kullanmak için önceki bölümlerde açıklanan alt düzey işlemleri de çağırabilirsiniz.

Ayrıca bakınız

Python/C API Referans Kılavuzu

  Python’un C arayüzünün detayları bu kılavuzda verilmiştir. Çok sayıda gerekli bilgi burada bulunabilir.

## 1.1. Çok Üst Düzey Gömme

Python’u gömmenin en basit şekli, çok yüksek seviyeli arayüzün kullanılmasıdır. Bu arabirim, uygulamayla doğrudan etkileşime girmeye gerek kalmadan bir Python betiği yürütmeyi amaçlamaktadır. Bu örnek olarak bir dosya üzerinde bazı işlemler gerçekleştirmek için kullanılabilir.

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

    int
    main(int argc, char *argv[])
    {
        PyStatus status;
        PyConfig config;
        PyConfig_InitPythonConfig(&config);

        /* optional but recommended */
        status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);
        if (PyStatus_Exception(status)) {
            goto exception;
        }

        status = Py_InitializeFromConfig(&config);
        if (PyStatus_Exception(status)) {
            goto exception;
        }
        PyConfig_Clear(&config);

        PyRun_SimpleString("from time import time,ctime\n"
                           "print('Today is', ctime(time()))\n");
        if (Py_FinalizeEx() < 0) {
            exit(120);
        }
        return 0;

      exception:
         PyConfig_Clear(&config);
         Py_ExitStatusException(status);
    }

Not

`#define PY_SSIZE_T_CLEAN` was used to indicate that `Py_ssize_t` should be used in some APIs instead of `int`. It is not necessary since Python 3.13, but we keep it here for backward compatibility. See Strings and buffers for a description of this macro.

Setting `PyConfig.program_name` should be called before `Py_InitializeFromConfig()` to inform the interpreter about paths to Python run-time libraries. Next, the Python interpreter is initialized with `Py_Initialize()`, followed by the execution of a hard-coded Python script that prints the date and time. Afterwards, the `Py_FinalizeEx()` call shuts the interpreter down, followed by the end of the program. In a real program, you may want to get the Python script from another source, perhaps a text-editor routine, a file, or a database. Getting the Python code from a file can better be done by using the `PyRun_SimpleFile()` function, which saves you the trouble of allocating memory space and loading the file contents.

## 1.2. Çok Yüksek Düzeyde Gömmenin Ötesinde: Genel Bir Bakış

Yüksek seviyeli arayüz size uygulamanızdan rastgele Python kodu parçalarını yürütme yeteneği verir, ancak veri değerleri alışverişi en hafif tabirle oldukça zahmetlidir. Bunu istiyorsanız, daha düşük seviyeli aramalar kullanmalısınız. Daha fazla C kodu yazmak zorunda kalma pahasına neredeyse her şeyi başarabilirsiniz.

Farklı amaçlara rağmen Python’u genişletmek ve Python’u gömmek tamamen aynı aktivitedir. Önceki bölümlerde tartışılan konuların çoğu hala geçerlidir. Bunu göstermek için Python’dan C’ye uzantı kodunun gerçekten ne yaptığını düşünün:

1. Veri değerlerini Python’dan C’ye çevirin,

2. Çevrilen değerleri kullanarak bir C rutinine bir fonksiyon çağrısı yapın, ve

3. Çağrıdaki veri değerlerini C’den Python’a çevirin.

Python’u yerleştirirken, arayüz kodu şunları yapar:

1. Veri değerlerini C’den Python’a çevirin,

2. Çevrilen değerleri kullanarak bir Python arabirim rutinine bir fonksiyon çağrısı gerçekleştirin ve

3. Çağrıdaki veri değerlerini C’den Python’a dönüştürün.

Gördüğünüz gibi, veri dönüştürme adımları, diller arası aktarımın farklı yönüne uyum sağlamak için basitçe değiştirilir. Tek fark, her iki veri dönüşümü arasında çağırdığınız rutindir. Uzatırken C rutini çağırırsınız, gömerken Python rutini çağırırsınız.

Bu bölüm, verilerin Python’dan C’ye nasıl dönüştürüleceğini ve bunun tam tersini tartışmayacaktır. Ayrıca, referansların doğru kullanımı ve hataların ele alınmasının anlaşıldığı varsayılmaktadır. Bu hususlar, yorumlayıcının genişletilmesinden farklı olmadığı için, gerekli bilgiler için önceki bölümlere başvurabilirsiniz.

## 1.3. Saf Gömme

İlk program, bir Python betiğinde bir fonksiyonu çalıştırmayı amaçlar. Çok yüksek seviyeli arayüzle ilgili bölümde olduğu gibi, Python yorumlayıcısı uygulama ile doğrudan etkileşime girmez (ancak bu bir sonraki bölümde değişecektir).

Python betiğinde tanımlanan bir işlevi çalıştırma kodu:

    #define PY_SSIZE_T_CLEAN
    #include <Python.h>

    int
    main(int argc, char *argv[])
    {
        PyObject *pName, *pModule, *pFunc;
        PyObject *pArgs, *pValue;
        int i;

        if (argc < 3) {
            fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
            return 1;
        }

        Py_Initialize();
        pName = PyUnicode_DecodeFSDefault(argv[1]);
        /* Error checking of pName left out */

        pModule = PyImport_Import(pName);
        Py_DECREF(pName);

        if (pModule != NULL) {
            pFunc = PyObject_GetAttrString(pModule, argv[2]);
            /* pFunc is a new reference */

            if (pFunc && PyCallable_Check(pFunc)) {
                pArgs = PyTuple_New(argc - 3);
                for (i = 0; i < argc - 3; ++i) {
                    pValue = PyLong_FromLong(atoi(argv[i + 3]));
                    if (!pValue) {
                        Py_DECREF(pArgs);
                        Py_DECREF(pModule);
                        fprintf(stderr, "Cannot convert argument\n");
                        return 1;
                    }
                    /* pValue reference stolen here: */
                    PyTuple_SetItem(pArgs, i, pValue);
                }
                pValue = PyObject_CallObject(pFunc, pArgs);
                Py_DECREF(pArgs);
                if (pValue != NULL) {
                    printf("Result of call: %ld\n", PyLong_AsLong(pValue));
                    Py_DECREF(pValue);
                }
                else {
                    Py_DECREF(pFunc);
                    Py_DECREF(pModule);
                    PyErr_Print();
                    fprintf(stderr,"Call failed\n");
                    return 1;
                }
            }
            else {
                if (PyErr_Occurred())
                    PyErr_Print();
                fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
            }
            Py_XDECREF(pFunc);
            Py_DECREF(pModule);
        }
        else {
            PyErr_Print();
            fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
            return 1;
        }
        if (Py_FinalizeEx() < 0) {
            return 120;
        }
        return 0;
    }

Bu kod, `argv[1]` kullanarak bir Python betiği yükler ve `argv[2]` içinde adlandırılan fonksiyonu çağırır. Tamsayı argümanları, `argv` dizisinin diğer değerleridir. Bu programı derler, ve bağlarsanız (bitmiş yürütülebilir dosyayı call olarak adlandıralım) ve onu aşağıdaki gibi bir Python betiğini çalıştırmak için kullanırsanız:

    def multiply(a,b):
        print("Will compute", a, "times", b)
        c = 0
        for i in range(0, a):
            c = c + b
        return c

o zaman sonuç olmalıdır:

    $ call multiply multiply 3 2
    Will compute 3 times 2
    Result of call: 6

Program işlevselliği açısından oldukça büyük olmasına rağmen, kodun çoğu Python ve C arasında veri dönüştürme ve hata raporlama içindir. Python’u gömmekle ilgili ilginç kısım şununla başlar

    Py_Initialize();
    pName = PyUnicode_DecodeFSDefault(argv[1]);
    /* Error checking of pName left out */
    pModule = PyImport_Import(pName);

After initializing the interpreter, the script is loaded using `PyImport_Import()`. This routine needs a Python string as its argument, which is constructed using the `PyUnicode_DecodeFSDefault()` data conversion routine.

    pFunc = PyObject_GetAttrString(pModule, argv[2]);
    /* pFunc is a new reference */

    if (pFunc && PyCallable_Check(pFunc)) {
        ...
    }
    Py_XDECREF(pFunc);

Komut dosyası yüklendikten sonra, aradığımız ad `PyObject_GetAttrString()` kullanılarak alınır. Ad varsa ve döndürülen nesne çağrılabilirse bunun bir fonksiyon olduğunu güvenle varsayabilirsiniz. Program daha sonra normal olarak bir dizi argüman oluşturarak devam eder. Python işlevine yapılan çağrı şu şekilde yapılır:

    pValue = PyObject_CallObject(pFunc, pArgs);

Fonksiyon döndürüldüğünde, `pValue` ya `NULL` olur ya da fonksiyonun dönüş değerine bir başvuru içerir. Değeri inceledikten sonra referans bıraktığınızdan emin olun.

## 1.4. Gömülü Python’u Genişletme

Şimdiye kadar, gömülü Python yorumlayıcısının uygulamanın kendisinden işlevselliğe erişimi yoktu. Python API, gömülü yorumlayıcıyı genişleterek buna izin verir. Yani, gömülü yorumlayıcı, uygulama tarafından sağlanan rutinlerle genişletilir. Kulağa karmaşık gelse de, o kadar da kötü değil. Uygulamanın Python yorumlayıcısını başlattığını bir süreliğine unutun. Bunun yerine, uygulamayı bir dizi altyordam olarak düşünün ve tıpkı normal bir Python uzantısı yazacağınız gibi, Python’un bu rutinlere erişmesini sağlayan bir tutkal kodu yazın. Örneğin:

    static int numargs=0;

    /* Return the number of arguments of the application command line */
    static PyObject*
    emb_numargs(PyObject *self, PyObject *args)
    {
        if(!PyArg_ParseTuple(args, ":numargs"))
            return NULL;
        return PyLong_FromLong(numargs);
    }

    static PyMethodDef emb_module_methods[] = {
        {"numargs", emb_numargs, METH_VARARGS,
         "Return the number of arguments received by the process."},
        {NULL, NULL, 0, NULL}
    };

    static struct PyModuleDef emb_module = {
        .m_base = PyModuleDef_HEAD_INIT,
        .m_name = "emb",
        .m_size = 0,
        .m_methods = emb_module_methods,
    };

    static PyObject*
    PyInit_emb(void)
    {
        return PyModuleDef_Init(&emb_module);
    }

Yukarıdaki kodu `main()` fonksiyonunun hemen üstüne ekleyin. Ayrıca, `Py_Initialize()`: çağrısından önce aşağıdaki iki ifadeyi ekleyin:

    numargs = argc;
    PyImport_AppendInittab("emb", &PyInit_emb);

These two lines initialize the `numargs` variable, and make the `emb.numargs()` function accessible to the embedded Python interpreter. With these extensions, the Python script can do things like

    import emb
    print("Number of arguments", emb.numargs())

Gerçek bir uygulamada, yöntemler uygulamanın API’sini Python’a gösterir.

## 1.5. Python’u C++’a Gömmek

Python’u bir C++ programına yerleştirmek de mümkündür; bunun tam olarak nasıl yapılacağı, kullanılan C++ sisteminin ayrıntılarına bağlı olacaktır; genel olarak ana programı C++ ile yazmanız ve programınızı derlemek ve bağlamak için C++ derleyicisini kullanmanız gerekecektir. Python’un kendisini C++ kullanarak yeniden derlemeye gerek yoktur.

## 1.6. Unix benzeri sistemler altında Derleme ve Bağlama

Python yorumlayıcısını uygulamanıza gömmek için derleyicinize (ve bağlayıcınıza) iletilecek doğru bayrakları bulmak mutlaka önemli değildir, özellikle Python’un C dinamik uzantıları buna karşı bağlatılı olan (`.so` dosyaları) olarak uygulanan kütüphane modüllerini yüklemesi gerektiğinden.

Gerekli derleyici ve bağlayıcı bayraklarını bulmak için, yükleme işleminin bir parçası olarak oluşturulan `pythonX.Y-config` betiğini çalıştırabilirsiniz (bir `python3-config` betiği de mevcut olabilir). Bu komut dosyası, size doğrudan yardımcı olacak birkaç seçeneğe sahiptir:

- `pythonX.Y-config --cflags` derleme sırasında size önerilen bayrakları verecektir:

      $ /opt/bin/python3.11-config --cflags
      -I/opt/include/python3.11 -I/opt/include/python3.11 -Wsign-compare  -DNDEBUG -g -fwrapv -O3 -Wall

- `pythonX.Y-config --ldflags --embed`, bağlantı kurarken size önerilen bayrakları verecektir:

      $ /opt/bin/python3.11-config --ldflags --embed
      -L/opt/lib/python3.11/config-3.11-x86_64-linux-gnu -L/opt/lib -lpython3.11 -lpthread -ldl  -lutil -lm

Not

Birkaç Python kurulumu arasında (ve özellikle sistem Python ile kendi derlenmiş Python’unuz arasında) karışıklığı önlemek için, yukarıdaki örnekte olduğu gibi mutlak `pythonX.Y-config` yolunu kullanmanız önerilir.

Bu prosedür sizin için işe yaramazsa (tüm Unix benzeri platformlar için çalışması garanti edilmez; ancak, memnuniyetle karşılıyoruz: hata raporları) dinamik hakkında sisteminizin belgelerini okumanız gerekecektir ve/veya Python’un `Makefile` (konumunu bulmak için `sysconfig.get_makefile_filename()` kullanın) ve derleme seçeneklerini bağlamayı inceleyin. Bu durumda, `sysconfig` modülü, birleştirmek isteyeceğiniz konfigürasyon değerlerini programlı olarak çıkarmak için kullanışlı bir araçtır. Örneğin:

    >>> import sysconfig
    >>> sysconfig.get_config_var('LIBS')
    '-lpthread -ldl  -lutil'
    >>> sysconfig.get_config_var('LINKFORSHARED')
    '-Xlinker -export-dynamic'