# SOME DESCRIPTIVE TITLE.

# Copyright (C) 2001 Python Software Foundation

# This file is distributed under the same license as the Python package.

# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

#

# Translators:

# Alireza Shabani (Revisto) <[email protected]>, 2025

# Danial Behzadi <[email protected]>, 2025

# Rafael Fontenelle <[email protected]>, 2025

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.14\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2025-07-11 14:21+0000\n"

"PO-Revision-Date: 2021-06-28 00:49+0000\n"

"Last-Translator: Rafael Fontenelle <[email protected]>, 2025\n"

"Language-Team: Persian (https://app.transifex.com/python-doc/teams/5390/"

"fa/)\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Language: fa\n"

"Plural-Forms: nplurals=2; plural=(n > 1);\n"

#: ../../c-api/intro.rst:8

msgid "Introduction"

msgstr ""

#: ../../c-api/intro.rst:10

msgid ""

"The Application Programmer's Interface to Python gives C and C++ programmers "

"access to the Python interpreter at a variety of levels. The API is equally "

"usable from C++, but for brevity it is generally referred to as the Python/C "

"API. There are two fundamentally different reasons for using the Python/C "

"API. The first reason is to write *extension modules* for specific purposes; "

"these are C modules that extend the Python interpreter. This is probably "

"the most common use. The second reason is to use Python as a component in a "

"larger application; this technique is generally referred to as :dfn:"

"`embedding` Python in an application."

msgstr ""

#: ../../c-api/intro.rst:20

msgid ""

"Writing an extension module is a relatively well-understood process, where a "

"\"cookbook\" approach works well. There are several tools that automate the "

"process to some extent. While people have embedded Python in other "

"applications since its early existence, the process of embedding Python is "

"less straightforward than writing an extension."

msgstr ""

#: ../../c-api/intro.rst:26

msgid ""

"Many API functions are useful independent of whether you're embedding or "

"extending Python; moreover, most applications that embed Python will need "

"to provide a custom extension as well, so it's probably a good idea to "

"become familiar with writing an extension before attempting to embed Python "

"in a real application."

msgstr ""

#: ../../c-api/intro.rst:34

msgid "Language version compatibility"

msgstr ""

#: ../../c-api/intro.rst:36

msgid "Python's C API is compatible with C11 and C++11 versions of C and C++."

msgstr ""

#: ../../c-api/intro.rst:38

msgid ""

"This is a lower limit: the C API does not require features from later C/C++ "

"versions. You do *not* need to enable your compiler's \"c11 mode\"."

msgstr ""

#: ../../c-api/intro.rst:44

msgid "Coding standards"

msgstr ""

#: ../../c-api/intro.rst:46

msgid ""

"If you're writing C code for inclusion in CPython, you **must** follow the "

"guidelines and standards defined in :PEP:`7`. These guidelines apply "

"regardless of the version of Python you are contributing to. Following "

"these conventions is not necessary for your own third party extension "

"modules, unless you eventually expect to contribute them to Python."

msgstr ""

#: ../../c-api/intro.rst:56

msgid "Include Files"

msgstr ""

#: ../../c-api/intro.rst:58

msgid ""

"All function, type and macro definitions needed to use the Python/C API are "

"included in your code by the following line::"

msgstr ""

#: ../../c-api/intro.rst:61

msgid ""

"#define PY_SSIZE_T_CLEAN\n"

"#include <Python.h>"

msgstr ""

#: ../../c-api/intro.rst:64

msgid ""

"This implies inclusion of the following standard headers: ``<stdio.h>``, "

"``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib."

"h>`` (if available)."

msgstr ""

#: ../../c-api/intro.rst:70

msgid ""

"Since Python may define some pre-processor definitions which affect the "

"standard headers on some systems, you *must* include :file:`Python.h` before "

"any standard headers are included."

msgstr ""

#: ../../c-api/intro.rst:74

msgid ""

"It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including "

"``Python.h``. See :ref:`arg-parsing` for a description of this macro."

msgstr ""

#: ../../c-api/intro.rst:77

msgid ""

"All user visible names defined by Python.h (except those defined by the "

"included standard headers) have one of the prefixes ``Py`` or ``_Py``. "

"Names beginning with ``_Py`` are for internal use by the Python "

"implementation and should not be used by extension writers. Structure member "

"names do not have a reserved prefix."

msgstr ""

#: ../../c-api/intro.rst:84

msgid ""

"User code should never define names that begin with ``Py`` or ``_Py``. This "

"confuses the reader, and jeopardizes the portability of the user code to "

"future Python versions, which may define additional names beginning with one "

"of these prefixes."

msgstr ""

#: ../../c-api/intro.rst:89

msgid ""

"The header files are typically installed with Python. On Unix, these are "

"located in the directories :file:`{prefix}/include/pythonversion/` and :file:"

"`{exec_prefix}/include/pythonversion/`, where :option:`prefix <--prefix>` "

"and :option:`exec_prefix <--exec-prefix>` are defined by the corresponding "

"parameters to Python's :program:`configure` script and *version* is ``'%d."

"%d' % sys.version_info[:2]``. On Windows, the headers are installed in :"

"file:`{prefix}/include`, where ``prefix`` is the installation directory "

"specified to the installer."

msgstr ""

#: ../../c-api/intro.rst:98

msgid ""

"To include the headers, place both directories (if different) on your "

"compiler's search path for includes. Do *not* place the parent directories "

"on the search path and then use ``#include <pythonX.Y/Python.h>``; this will "

"break on multi-platform builds since the platform independent headers under :"

"option:`prefix <--prefix>` include the platform specific headers from :"

"option:`exec_prefix <--exec-prefix>`."

msgstr ""

#: ../../c-api/intro.rst:105

msgid ""

"C++ users should note that although the API is defined entirely using C, the "

"header files properly declare the entry points to be ``extern \"C\"``. As a "

"result, there is no need to do anything special to use the API from C++."

msgstr ""

#: ../../c-api/intro.rst:111

msgid "Useful macros"

msgstr ""

#: ../../c-api/intro.rst:113

msgid ""

"Several useful macros are defined in the Python header files. Many are "

"defined closer to where they are useful (for example, :c:macro:"

"`Py_RETURN_NONE`, :c:macro:`PyMODINIT_FUNC`). Others of a more general "

"utility are defined here. This is not necessarily a complete listing."

msgstr ""

#: ../../c-api/intro.rst:122

msgid "Return the absolute value of ``x``."

msgstr ""

#: ../../c-api/intro.rst:128

msgid ""

"Ask the compiler to always inline a static inline function. The compiler can "

"ignore it and decide to not inline the function."

msgstr ""

#: ../../c-api/intro.rst:131

msgid ""

"It can be used to inline performance critical static inline functions when "

"building Python in debug mode with function inlining disabled. For example, "

"MSC disables function inlining when building in debug mode."

msgstr ""

#: ../../c-api/intro.rst:135

msgid ""

"Marking blindly a static inline function with Py_ALWAYS_INLINE can result in "

"worse performances (due to increased code size for example). The compiler is "

"usually smarter than the developer for the cost/benefit analysis."

msgstr ""

#: ../../c-api/intro.rst:139

msgid ""

"If Python is :ref:`built in debug mode <debug-build>` (if the :c:macro:"

"`Py_DEBUG` macro is defined), the :c:macro:`Py_ALWAYS_INLINE` macro does "

"nothing."

msgstr ""

#: ../../c-api/intro.rst:142

msgid "It must be specified before the function return type. Usage::"

msgstr ""

#: ../../c-api/intro.rst:144

msgid "static inline Py_ALWAYS_INLINE int random(void) { return 4; }"

msgstr ""

#: ../../c-api/intro.rst:150

msgid ""

"Argument must be a character or an integer in the range [-128, 127] or [0, "

"255]. This macro returns ``c`` cast to an ``unsigned char``."

msgstr ""

#: ../../c-api/intro.rst:155

msgid ""

"Use this for deprecated declarations. The macro must be placed before the "

"symbol name."

msgstr ""

#: ../../c-api/intro.rst:158 ../../c-api/intro.rst:244

#: ../../c-api/intro.rst:262

msgid "Example::"

msgstr ""

#: ../../c-api/intro.rst:160

msgid "Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);"

msgstr ""

#: ../../c-api/intro.rst:162

msgid "MSVC support was added."

msgstr ""

#: ../../c-api/intro.rst:167

msgid ""

"Like ``getenv(s)``, but returns ``NULL`` if :option:`-E` was passed on the "

"command line (see :c:member:`PyConfig.use_environment`)."

msgstr ""

#: ../../c-api/intro.rst:172

msgid "Return the maximum value between ``x`` and ``y``."

msgstr ""

#: ../../c-api/intro.rst:178

msgid "Return the size of a structure (``type``) ``member`` in bytes."

msgstr ""

#: ../../c-api/intro.rst:184

msgid "Return the minimum value between ``x`` and ``y``."

msgstr ""

#: ../../c-api/intro.rst:190

msgid ""

"Disable inlining on a function. For example, it reduces the C stack "

"consumption: useful on LTO+PGO builds which heavily inline code (see :issue:"

"`33720`)."

msgstr ""

#: ../../c-api/intro.rst:194

msgid "Usage::"

msgstr ""

#: ../../c-api/intro.rst:196

msgid "Py_NO_INLINE static int random(void) { return 4; }"

msgstr ""

#: ../../c-api/intro.rst:202

msgid ""

"Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns ``\"123\"``."

msgstr ""

#: ../../c-api/intro.rst:209

msgid ""

"Use this when you have a code path that cannot be reached by design. For "

"example, in the ``default:`` clause in a ``switch`` statement for which all "

"possible values are covered in ``case`` statements. Use this in places "

"where you might be tempted to put an ``assert(0)`` or ``abort()`` call."

msgstr ""

#: ../../c-api/intro.rst:214

msgid ""

"In release mode, the macro helps the compiler to optimize the code, and "

"avoids a warning about unreachable code. For example, the macro is "

"implemented with ``__builtin_unreachable()`` on GCC in release mode."

msgstr ""

#: ../../c-api/intro.rst:218

msgid ""

"A use for ``Py_UNREACHABLE()`` is following a call a function that never "

"returns but that is not declared :c:macro:`_Py_NO_RETURN`."

msgstr ""

#: ../../c-api/intro.rst:221

msgid ""

"If a code path is very unlikely code but can be reached under exceptional "

"case, this macro must not be used. For example, under low memory condition "

"or if a system call returns a value out of the expected range. In this "

"case, it's better to report the error to the caller. If the error cannot be "

"reported to caller, :c:func:`Py_FatalError` can be used."

msgstr ""

#: ../../c-api/intro.rst:231

msgid ""

"Use this for unused arguments in a function definition to silence compiler "

"warnings. Example: ``int func(int a, int Py_UNUSED(b)) { return a; }``."

msgstr ""

#: ../../c-api/intro.rst:238

msgid ""

"Creates a variable with name ``name`` that can be used in docstrings. If "

"Python is built without docstrings, the value will be empty."

msgstr ""

#: ../../c-api/intro.rst:241

msgid ""

"Use :c:macro:`PyDoc_STRVAR` for docstrings to support building Python "

"without docstrings, as specified in :pep:`7`."

msgstr ""

#: ../../c-api/intro.rst:246

msgid ""

"PyDoc_STRVAR(pop_doc, \"Remove and return the rightmost element.\");\n"

"\n"

"static PyMethodDef deque_methods[] = {\n"

" // ...\n"

" {\"pop\", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},\n"

" // ...\n"

"}"

msgstr ""

#: ../../c-api/intro.rst:256

msgid ""

"Creates a docstring for the given input string or an empty string if "

"docstrings are disabled."

msgstr ""

#: ../../c-api/intro.rst:259

msgid ""

"Use :c:macro:`PyDoc_STR` in specifying docstrings to support building Python "

"without docstrings, as specified in :pep:`7`."

msgstr ""

#: ../../c-api/intro.rst:264

msgid ""

"static PyMethodDef pysqlite_row_methods[] = {\n"

" {\"keys\", (PyCFunction)pysqlite_row_keys, METH_NOARGS,\n"

" PyDoc_STR(\"Returns the keys of the row.\")},\n"

" {NULL, NULL}\n"

"};"

msgstr ""

#: ../../c-api/intro.rst:274

msgid "Objects, Types and Reference Counts"

msgstr ""

#: ../../c-api/intro.rst:278

msgid ""

"Most Python/C API functions have one or more arguments as well as a return "

"value of type :c:expr:`PyObject*`. This type is a pointer to an opaque data "

"type representing an arbitrary Python object. Since all Python object types "

"are treated the same way by the Python language in most situations (e.g., "

"assignments, scope rules, and argument passing), it is only fitting that "

"they should be represented by a single C type. Almost all Python objects "

"live on the heap: you never declare an automatic or static variable of type :"

"c:type:`PyObject`, only pointer variables of type :c:expr:`PyObject*` can "

"be declared. The sole exception are the type objects; since these must "

"never be deallocated, they are typically static :c:type:`PyTypeObject` "

"objects."

msgstr ""

#: ../../c-api/intro.rst:289

msgid ""

"All Python objects (even Python integers) have a :dfn:`type` and a :dfn:"

"`reference count`. An object's type determines what kind of object it is (e."

"g., an integer, a list, or a user-defined function; there are many more as "

"explained in :ref:`types`). For each of the well-known types there is a "

"macro to check whether an object is of that type; for instance, "

"``PyList_Check(a)`` is true if (and only if) the object pointed to by *a* is "

"a Python list."

msgstr ""

#: ../../c-api/intro.rst:300

msgid "Reference Counts"

msgstr ""

#: ../../c-api/intro.rst:302

msgid ""

"The reference count is important because today's computers have a finite "

"(and often severely limited) memory size; it counts how many different "

"places there are that have a :term:`strong reference` to an object. Such a "

"place could be another object, or a global (or static) C variable, or a "

"local variable in some C function. When the last :term:`strong reference` to "

"an object is released (i.e. its reference count becomes zero), the object is "

"deallocated. If it contains references to other objects, those references "

"are released. Those other objects may be deallocated in turn, if there are "

"no more references to them, and so on. (There's an obvious problem with "

"objects that reference each other here; for now, the solution is \"don't do "

"that.\")"

msgstr ""

#: ../../c-api/intro.rst:319

msgid ""

"Reference counts are always manipulated explicitly. The normal way is to "

"use the macro :c:func:`Py_INCREF` to take a new reference to an object (i.e. "

"increment its reference count by one), and :c:func:`Py_DECREF` to release "

"that reference (i.e. decrement the reference count by one). The :c:func:"

"`Py_DECREF` macro is considerably more complex than the incref one, since it "

"must check whether the reference count becomes zero and then cause the "

"object's deallocator to be called. The deallocator is a function pointer "

"contained in the object's type structure. The type-specific deallocator "

"takes care of releasing references for other objects contained in the object "

"if this is a compound object type, such as a list, as well as performing any "

"additional finalization that's needed. There's no chance that the reference "

"count can overflow; at least as many bits are used to hold the reference "

"count as there are distinct memory locations in virtual memory (assuming "

"``sizeof(Py_ssize_t) >= sizeof(void*)``). Thus, the reference count "

"increment is a simple operation."

msgstr ""

#: ../../c-api/intro.rst:335

msgid ""

"It is not necessary to hold a :term:`strong reference` (i.e. increment the "

"reference count) for every local variable that contains a pointer to an "

"object. In theory, the object's reference count goes up by one when the "

"variable is made to point to it and it goes down by one when the variable "

"goes out of scope. However, these two cancel each other out, so at the end "

"the reference count hasn't changed. The only real reason to use the "

"reference count is to prevent the object from being deallocated as long as "

"our variable is pointing to it. If we know that there is at least one "

"other reference to the object that lives at least as long as our variable, "

"there is no need to take a new :term:`strong reference` (i.e. increment the "

"reference count) temporarily. An important situation where this arises is in "

"objects that are passed as arguments to C functions in an extension module "

"that are called from Python; the call mechanism guarantees to hold a "

"reference to every argument for the duration of the call."

msgstr ""

#: ../../c-api/intro.rst:351

msgid ""

"However, a common pitfall is to extract an object from a list and hold on to "

"it for a while without taking a new reference. Some other operation might "

"conceivably remove the object from the list, releasing that reference, and "

"possibly deallocating it. The real danger is that innocent-looking "

"operations may invoke arbitrary Python code which could do this; there is a "

"code path which allows control to flow back to the user from a :c:func:"

"`Py_DECREF`, so almost any operation is potentially dangerous."

msgstr ""

#: ../../c-api/intro.rst:359

msgid ""

"A safe approach is to always use the generic operations (functions whose "

"name begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or "

"``PyMapping_``). These operations always create a new :term:`strong "

"reference` (i.e. increment the reference count) of the object they return. "

"This leaves the caller with the responsibility to call :c:func:`Py_DECREF` "

"when they are done with the result; this soon becomes second nature."

msgstr ""

#: ../../c-api/intro.rst:370

msgid "Reference Count Details"

msgstr ""

#: ../../c-api/intro.rst:372

msgid ""

"The reference count behavior of functions in the Python/C API is best "

"explained in terms of *ownership of references*. Ownership pertains to "

"references, never to objects (objects are not owned: they are always "

"shared). \"Owning a reference\" means being responsible for calling "

"Py_DECREF on it when the reference is no longer needed. Ownership can also "

"be transferred, meaning that the code that receives ownership of the "

"reference then becomes responsible for eventually releasing it by calling :c:"

"func:`Py_DECREF` or :c:func:`Py_XDECREF` when it's no longer needed---or "

"passing on this responsibility (usually to its caller). When a function "

"passes ownership of a reference on to its caller, the caller is said to "

"receive a *new* reference. When no ownership is transferred, the caller is "

"said to *borrow* the reference. Nothing needs to be done for a :term:"

"`borrowed reference`."

msgstr ""

#: ../../c-api/intro.rst:385

msgid ""

"Conversely, when a calling function passes in a reference to an object, "

"there are two possibilities: the function *steals* a reference to the "

"object, or it does not. *Stealing a reference* means that when you pass a "

"reference to a function, that function assumes that it now owns that "

"reference, and you are not responsible for it any longer."

msgstr ""

#: ../../c-api/intro.rst:395

msgid ""

"Few functions steal references; the two notable exceptions are :c:func:"

"`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference to "

"the item (but not to the tuple or list into which the item is put!). These "

"functions were designed to steal a reference because of a common idiom for "

"populating a tuple or list with newly created objects; for example, the code "

"to create the tuple ``(1, 2, \"three\")`` could look like this (forgetting "

"about error handling for the moment; a better way to code this is shown "

"below)::"

msgstr ""

#: ../../c-api/intro.rst:403

msgid ""

"PyObject *t;\n"

"\n"

"t = PyTuple_New(3);\n"

"PyTuple_SetItem(t, 0, PyLong_FromLong(1L));\n"

"PyTuple_SetItem(t, 1, PyLong_FromLong(2L));\n"

"PyTuple_SetItem(t, 2, PyUnicode_FromString(\"three\"));"

msgstr ""

#: ../../c-api/intro.rst:410

msgid ""

"Here, :c:func:`PyLong_FromLong` returns a new reference which is immediately "

"stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object "

"although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab "

"another reference before calling the reference-stealing function."

msgstr ""

#: ../../c-api/intro.rst:415

msgid ""

"Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple "

"items; :c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to "

"do this since tuples are an immutable data type. You should only use :c:"

"func:`PyTuple_SetItem` for tuples that you are creating yourself."

msgstr ""

#: ../../c-api/intro.rst:420

msgid ""

"Equivalent code for populating a list can be written using :c:func:"

"`PyList_New` and :c:func:`PyList_SetItem`."

msgstr ""

#: ../../c-api/intro.rst:423

msgid ""

"However, in practice, you will rarely use these ways of creating and "

"populating a tuple or list. There's a generic function, :c:func:"

"`Py_BuildValue`, that can create most common objects from C values, directed "

"by a :dfn:`format string`. For example, the above two blocks of code could "

"be replaced by the following (which also takes care of the error checking)::"

msgstr ""

#: ../../c-api/intro.rst:429

msgid ""

"PyObject *tuple, *list;\n"

"\n"

"tuple = Py_BuildValue(\"(iis)\", 1, 2, \"three\");\n"

"list = Py_BuildValue(\"[iis]\", 1, 2, \"three\");"

msgstr ""

#: ../../c-api/intro.rst:434

msgid ""

"It is much more common to use :c:func:`PyObject_SetItem` and friends with "

"items whose references you are only borrowing, like arguments that were "

"passed in to the function you are writing. In that case, their behaviour "

"regarding references is much saner, since you don't have to take a new "

"reference just so you can give that reference away (\"have it be stolen\"). "

"For example, this function sets all items of a list (actually, any mutable "

"sequence) to a given item::"

msgstr ""

#: ../../c-api/intro.rst:441

msgid ""

"int\n"

"set_all(PyObject *target, PyObject *item)\n"

"{\n"

" Py_ssize_t i, n;\n"

"\n"

" n = PyObject_Length(target);\n"

" if (n < 0)\n"

" return -1;\n"

" for (i = 0; i < n; i++) {\n"

" PyObject *index = PyLong_FromSsize_t(i);\n"

" if (!index)\n"

" return -1;\n"

" if (PyObject_SetItem(target, index, item) < 0) {\n"

" Py_DECREF(index);\n"

" return -1;\n"

" }\n"

" Py_DECREF(index);\n"

" }\n"

" return 0;\n"

"}"

msgstr ""

#: ../../c-api/intro.rst:464

msgid ""

"The situation is slightly different for function return values. While "

"passing a reference to most functions does not change your ownership "

"responsibilities for that reference, many functions that return a reference "

"to an object give you ownership of the reference. The reason is simple: in "

"many cases, the returned object is created on the fly, and the reference "

"you get is the only reference to the object. Therefore, the generic "

"functions that return object references, like :c:func:`PyObject_GetItem` "

"and :c:func:`PySequence_GetItem`, always return a new reference (the caller "

"becomes the owner of the reference)."

msgstr ""

#: ../../c-api/intro.rst:473

msgid ""

"It is important to realize that whether you own a reference returned by a "

"function depends on which function you call only --- *the plumage* (the type "

"of the object passed as an argument to the function) *doesn't enter into it!"

"* Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, "

"you don't own the reference --- but if you obtain the same item from the "

"same list using :c:func:`PySequence_GetItem` (which happens to take exactly "

"the same arguments), you do own a reference to the returned object."

msgstr ""

#: ../../c-api/intro.rst:485

msgid ""

"Here is an example of how you could write a function that computes the sum "

"of the items in a list of integers; once using :c:func:`PyList_GetItem`, "

"and once using :c:func:`PySequence_GetItem`. ::"

msgstr ""

#: ../../c-api/intro.rst:489

msgid ""

"long\n"

"sum_list(PyObject *list)\n"

"{\n"

" Py_ssize_t i, n;\n"

" long total = 0, value;\n"

" PyObject *item;\n"

"\n"

" n = PyList_Size(list);\n"

" if (n < 0)\n"

" return -1; /* Not a list */\n"

" for (i = 0; i < n; i++) {\n"

" item = PyList_GetItem(list, i); /* Can't fail */\n"

" if (!PyLong_Check(item)) continue; /* Skip non-integers */\n"

" value = PyLong_AsLong(item);\n"

" if (value == -1 && PyErr_Occurred())\n"

" /* Integer too big to fit in a C long, bail out */\n"

" return -1;\n"

" total += value;\n"

" }\n"

" return total;\n"

"}"

msgstr ""

#: ../../c-api/intro.rst:515

msgid ""

"long\n"

"sum_sequence(PyObject *sequence)\n"

"{\n"

" Py_ssize_t i, n;\n"

" long total = 0, value;\n"

" PyObject *item;\n"

" n = PySequence_Length(sequence);\n"

" if (n < 0)\n"

" return -1; /* Has no length */\n"

" for (i = 0; i < n; i++) {\n"

" item = PySequence_GetItem(sequence, i);\n"

" if (item == NULL)\n"

" return -1; /* Not a sequence, or other failure */\n"

" if (PyLong_Check(item)) {\n"

" value = PyLong_AsLong(item);\n"

" Py_DECREF(item);\n"

" if (value == -1 && PyErr_Occurred())\n"

" /* Integer too big to fit in a C long, bail out */\n"

" return -1;\n"

" total += value;\n"

" }\n"

" else {\n"

" Py_DECREF(item); /* Discard reference ownership */\n"

" }\n"

" }\n"

" return total;\n"

"}"

msgstr ""

#: ../../c-api/intro.rst:549

msgid "Types"

msgstr ""

#: ../../c-api/intro.rst:551

msgid ""

"There are few other data types that play a significant role in the Python/C "

"API; most are simple C types such as :c:expr:`int`, :c:expr:`long`, :c:expr:"

"`double` and :c:expr:`char*`. A few structure types are used to describe "

"static tables used to list the functions exported by a module or the data "

"attributes of a new object type, and another is used to describe the value "

"of a complex number. These will be discussed together with the functions "

"that use them."

msgstr ""

#: ../../c-api/intro.rst:561

msgid ""

"A signed integral type such that ``sizeof(Py_ssize_t) == sizeof(size_t)``. "

"C99 doesn't define such a thing directly (size_t is an unsigned integral "

"type). See :pep:`353` for details. ``PY_SSIZE_T_MAX`` is the largest "

"positive value of type :c:type:`Py_ssize_t`."

msgstr ""

#: ../../c-api/intro.rst:570

msgid "Exceptions"

msgstr ""

#: ../../c-api/intro.rst:572

msgid ""

"The Python programmer only needs to deal with exceptions if specific error "

"handling is required; unhandled exceptions are automatically propagated to "

"the caller, then to the caller's caller, and so on, until they reach the top-"

"level interpreter, where they are reported to the user accompanied by a "

"stack traceback."

msgstr ""

#: ../../c-api/intro.rst:580

msgid ""

"For C programmers, however, error checking always has to be explicit. All "

"functions in the Python/C API can raise exceptions, unless an explicit claim "

"is made otherwise in a function's documentation. In general, when a "

"function encounters an error, it sets an exception, discards any object "

"references that it owns, and returns an error indicator. If not documented "

"otherwise, this indicator is either ``NULL`` or ``-1``, depending on the "

"function's return type. A few functions return a Boolean true/false result, "

"with false indicating an error. Very few functions return no explicit error "

"indicator or have an ambiguous return value, and require explicit testing "

"for errors with :c:func:`PyErr_Occurred`. These exceptions are always "

"explicitly documented."

msgstr ""

#: ../../c-api/intro.rst:595

msgid ""

"Exception state is maintained in per-thread storage (this is equivalent to "

"using global storage in an unthreaded application). A thread can be in one "

"of two states: an exception has occurred, or not. The function :c:func:"

"`PyErr_Occurred` can be used to check for this: it returns a borrowed "

"reference to the exception type object when an exception has occurred, and "

"``NULL`` otherwise. There are a number of functions to set the exception "

"state: :c:func:`PyErr_SetString` is the most common (though not the most "

"general) function to set the exception state, and :c:func:`PyErr_Clear` "

"clears the exception state."

msgstr ""

#: ../../c-api/intro.rst:605

msgid ""

"The full exception state consists of three objects (all of which can be "

"``NULL``): the exception type, the corresponding exception value, and the "

"traceback. These have the same meanings as the Python result of ``sys."

"exc_info()``; however, they are not the same: the Python objects represent "

"the last exception being handled by a Python :keyword:`try` ... :keyword:"

"`except` statement, while the C level exception state only exists while an "

"exception is being passed on between C functions until it reaches the Python "

"bytecode interpreter's main loop, which takes care of transferring it to "

"``sys.exc_info()`` and friends."

msgstr ""

#: ../../c-api/intro.rst:617

msgid ""

"Note that starting with Python 1.5, the preferred, thread-safe way to access "

"the exception state from Python code is to call the function :func:`sys."

"exc_info`, which returns the per-thread exception state for Python code. "

"Also, the semantics of both ways to access the exception state have changed "

"so that a function which catches an exception will save and restore its "

"thread's exception state so as to preserve the exception state of its "

"caller. This prevents common bugs in exception handling code caused by an "

"innocent-looking function overwriting the exception being handled; it also "

"reduces the often unwanted lifetime extension for objects that are "

"referenced by the stack frames in the traceback."

msgstr ""

#: ../../c-api/intro.rst:628

msgid ""

"As a general principle, a function that calls another function to perform "

"some task should check whether the called function raised an exception, and "

"if so, pass the exception state on to its caller. It should discard any "

"object references that it owns, and return an error indicator, but it "

"should *not* set another exception --- that would overwrite the exception "

"that was just raised, and lose important information about the exact cause "

"of the error."

msgstr ""

#: ../../c-api/intro.rst:637

msgid ""

"A simple example of detecting exceptions and passing them on is shown in "

"the :c:func:`!sum_sequence` example above. It so happens that this example "

"doesn't need to clean up any owned references when it detects an error. The "

"following example function shows some error cleanup. First, to remind you "

"why you like Python, we show the equivalent Python code::"

msgstr ""

#: ../../c-api/intro.rst:643

msgid ""

"def incr_item(dict, key):\n"

" try:\n"

" item = dict[key]\n"

" except KeyError:\n"

" item = 0\n"

" dict[key] = item + 1"

msgstr ""

#: ../../c-api/intro.rst:652

msgid "Here is the corresponding C code, in all its glory::"

msgstr ""

#: ../../c-api/intro.rst:654

msgid ""

"int\n"

"incr_item(PyObject *dict, PyObject *key)\n"

"{\n"

" /* Objects all initialized to NULL for Py_XDECREF */\n"

" PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;\n"

" int rv = -1; /* Return value initialized to -1 (failure) */\n"

"\n"

" item = PyObject_GetItem(dict, key);\n"

" if (item == NULL) {\n"

" /* Handle KeyError only: */\n"

" if (!PyErr_ExceptionMatches(PyExc_KeyError))\n"

" goto error;\n"

"\n"

" /* Clear the error and use zero: */\n"

" PyErr_Clear();\n"

" item = PyLong_FromLong(0L);\n"

" if (item == NULL)\n"

" goto error;\n"

" }\n"

" const_one = PyLong_FromLong(1L);\n"

" if (const_one == NULL)\n"

" goto error;\n"

"\n"

" incremented_item = PyNumber_Add(item, const_one);\n"

" if (incremented_item == NULL)\n"

" goto error;\n"

"\n"

" if (PyObject_SetItem(dict, key, incremented_item) < 0)\n"

" goto error;\n"

" rv = 0; /* Success */\n"

" /* Continue with cleanup code */\n"

"\n"

" error:\n"

" /* Cleanup code, shared by success and failure path */\n"

"\n"

" /* Use Py_XDECREF() to ignore NULL references */\n"

" Py_XDECREF(item);\n"

" Py_XDECREF(const_one);\n"

" Py_XDECREF(incremented_item);\n"

"\n"

" return rv; /* -1 for error, 0 for success */\n"

"}"

msgstr ""

#: ../../c-api/intro.rst:704

msgid ""

"This example represents an endorsed use of the ``goto`` statement in C! It "

"illustrates the use of :c:func:`PyErr_ExceptionMatches` and :c:func:"

"`PyErr_Clear` to handle specific exceptions, and the use of :c:func:"

"`Py_XDECREF` to dispose of owned references that may be ``NULL`` (note the "

"``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a "

"``NULL`` reference). It is important that the variables used to hold owned "

"references are initialized to ``NULL`` for this to work; likewise, the "

"proposed return value is initialized to ``-1`` (failure) and only set to "

"success after the final call made is successful."

msgstr ""

#: ../../c-api/intro.rst:718

msgid "Embedding Python"

msgstr ""

#: ../../c-api/intro.rst:720

msgid ""

"The one important task that only embedders (as opposed to extension writers) "

"of the Python interpreter have to worry about is the initialization, and "

"possibly the finalization, of the Python interpreter. Most functionality of "

"the interpreter can only be used after the interpreter has been initialized."

msgstr ""

#: ../../c-api/intro.rst:733

msgid ""

"The basic initialization function is :c:func:`Py_Initialize`. This "

"initializes the table of loaded modules, and creates the fundamental "

"modules :mod:`builtins`, :mod:`__main__`, and :mod:`sys`. It also "

"initializes the module search path (``sys.path``)."

msgstr ""

#: ../../c-api/intro.rst:738

msgid ""

":c:func:`Py_Initialize` does not set the \"script argument list\" (``sys."

"argv``). If this variable is needed by Python code that will be executed "

"later, setting :c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` "

"must be set: see :ref:`Python Initialization Configuration <init-config>`."

msgstr ""

#: ../../c-api/intro.rst:743

msgid ""

"On most systems (in particular, on Unix and Windows, although the details "

"are slightly different), :c:func:`Py_Initialize` calculates the module "

"search path based upon its best guess for the location of the standard "

"Python interpreter executable, assuming that the Python library is found in "

"a fixed location relative to the Python interpreter executable. In "

"particular, it looks for a directory named :file:`lib/python{X.Y}` relative "

"to the parent directory where the executable named :file:`python` is found "

"on the shell command search path (the environment variable :envvar:`PATH`)."

msgstr ""

#: ../../c-api/intro.rst:752

msgid ""

"For instance, if the Python executable is found in :file:`/usr/local/bin/"

"python`, it will assume that the libraries are in :file:`/usr/local/lib/"

"python{X.Y}`. (In fact, this particular path is also the \"fallback\" "

"location, used when no executable file named :file:`python` is found along :"

"envvar:`PATH`.) The user can override this behavior by setting the "

"environment variable :envvar:`PYTHONHOME`, or insert additional directories "

"in front of the standard path by setting :envvar:`PYTHONPATH`."

msgstr ""

#: ../../c-api/intro.rst:766

msgid ""

"The embedding application can steer the search by setting :c:member:"

"`PyConfig.program_name` *before* calling :c:func:`Py_InitializeFromConfig`. "

"Note that :envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` "

"is still inserted in front of the standard path. An application that "

"requires total control has to provide its own implementation of :c:func:"

"`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and :c:"

"func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`)."

msgstr ""

#: ../../c-api/intro.rst:777

msgid ""

"Sometimes, it is desirable to \"uninitialize\" Python. For instance, the "

"application may want to start over (make another call to :c:func:"

"`Py_Initialize`) or the application is simply done with its use of Python "

"and wants to free memory allocated by Python. This can be accomplished by "

"calling :c:func:`Py_FinalizeEx`. The function :c:func:`Py_IsInitialized` "

"returns true if Python is currently in the initialized state. More "

"information about these functions is given in a later chapter. Notice that :"

"c:func:`Py_FinalizeEx` does *not* free all memory allocated by the Python "

"interpreter, e.g. memory allocated by extension modules currently cannot be "

"released."

msgstr ""

#: ../../c-api/intro.rst:791

msgid "Debugging Builds"

msgstr ""

#: ../../c-api/intro.rst:793

msgid ""

"Python can be built with several macros to enable extra checks of the "

"interpreter and extension modules. These checks tend to add a large amount "

"of overhead to the runtime so they are not enabled by default."

msgstr ""

#: ../../c-api/intro.rst:797

msgid ""

"A full list of the various types of debugging builds is in the file :file:"

"`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are "

"available that support tracing of reference counts, debugging the memory "

"allocator, or low-level profiling of the main interpreter loop. Only the "

"most frequently used builds will be described in the remainder of this "

"section."

msgstr ""

#: ../../c-api/intro.rst:805

msgid ""

"Compiling the interpreter with the :c:macro:`!Py_DEBUG` macro defined "

"produces what is generally meant by :ref:`a debug build of Python <debug-"

"build>`. :c:macro:`!Py_DEBUG` is enabled in the Unix build by adding :option:"

"`--with-pydebug` to the :file:`./configure` command. It is also implied by "

"the presence of the not-Python-specific :c:macro:`!_DEBUG` macro. When :c:"

"macro:`!Py_DEBUG` is enabled in the Unix build, compiler optimization is "

"disabled."

msgstr ""

#: ../../c-api/intro.rst:813

msgid ""

"In addition to the reference count debugging described below, extra checks "

"are performed, see :ref:`Python Debug Build <debug-build>`."

msgstr ""

#: ../../c-api/intro.rst:816

msgid ""

"Defining :c:macro:`Py_TRACE_REFS` enables reference tracing (see the :option:"

"`configure --with-trace-refs option <--with-trace-refs>`). When defined, a "

"circular doubly linked list of active objects is maintained by adding two "

"extra fields to every :c:type:`PyObject`. Total allocations are tracked as "

"well. Upon exit, all existing references are printed. (In interactive mode "

"this happens after every statement run by the interpreter.)"

msgstr ""

#: ../../c-api/intro.rst:823

msgid ""

"Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source "

"distribution for more detailed information."

msgstr ""

#: ../../c-api/intro.rst:830

msgid "Recommended third party tools"