Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Observar 1
Favorito 0
Wiki 捐赠
gooderp18绿色标准版
Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.
Branch: master
Branches Tags
${ item.name }
Criar branch ${ searchTerm }
de master
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/c-api/object.html

772 linhas
94KB
Original Link permanente Anotar Histórico 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="Object Protocol" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/c-api/object.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  12. <meta property="og:image:alt" content="Python documentation" />

  13. <meta property="og:image:width" content="200" />

  14. <meta property="og:image:height" content="200" />

  15. <meta name="theme-color" content="#3776ab" />

  16. 

  17.     <title>Object Protocol &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  18.     

  19.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  20.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  21.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  22.     

  23.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  24.     <script src="../_static/doctools.js?v=888ff710"></script>

  25.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  26.     

  27.     <script src="../_static/sidebar.js"></script>

  28.     

  29.     <link rel="search" type="application/opensearchdescription+xml"

  30.           title="Search within Python 3.12.3 documentation"

  31.           href="../_static/opensearch.xml"/>

  32.     <link rel="author" title="About these documents" href="../about.html" />

  33.     <link rel="index" title="Index" href="../genindex.html" />

  34.     <link rel="search" title="Search" href="../search.html" />

  35.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  36.     <link rel="next" title="Call Protocol" href="call.html" />

  37.     <link rel="prev" title="Abstract Objects Layer" href="abstract.html" />

  38.     <link rel="canonical" href="https://docs.python.org/3/c-api/object.html" />

  39.     

  40.       

  41.     

  42. 

  43.     

  44.     <style>

  45.       @media only screen {

  46.         table.full-width-table {

  47.             width: 100%;

  48.         }

  49.       }

  50.     </style>

  51. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  52.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  53.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  54.             <script type="text/javascript" src="../_static/menu.js"></script>

  55.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  56.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  57. 

  58.   </head>

  59. <body>

  60. <div class="mobile-nav">

  61.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  62.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  63.     <nav class="nav-content" role="navigation">

  64.         <label for="menuToggler" class="toggler__label">

  65.             <span></span>

  66.         </label>

  67.         <span class="nav-items-wrapper">

  68.             <a href="https://www.python.org/" class="nav-logo">

  69.                 <img src="../_static/py.svg" alt="Python logo"/>

  70.             </a>

  71.             <span class="version_switcher_placeholder"></span>

  72.             <form role="search" class="search" action="../search.html" method="get">

  73.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  74.                     <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>

  75.                 </svg>

  76.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  77.                 <input type="submit" value="Go"/>

  78.             </form>

  79.         </span>

  80.     </nav>

  81.     <div class="menu-wrapper">

  82.         <nav class="menu" role="navigation" aria-label="main navigation">

  83.             <div class="language_switcher_placeholder"></div>

  84.             

  85. <label class="theme-selector-label">

  86.     Theme

  87.     <select class="theme-selector" oninput="activateTheme(this.value)">

  88.         <option value="auto" selected>Auto</option>

  89.         <option value="light">Light</option>

  90.         <option value="dark">Dark</option>

  91.     </select>

  92. </label>

  93.   <div>

  94.     <h4>Previous topic</h4>

  95.     <p class="topless"><a href="abstract.html"

  96.                           title="previous chapter">Abstract Objects Layer</a></p>

  97.   </div>

  98.   <div>

  99.     <h4>Next topic</h4>

  100.     <p class="topless"><a href="call.html"

  101.                           title="next chapter">Call Protocol</a></p>

  102.   </div>

  103.   <div role="note" aria-label="source link">

  104.     <h3>This Page</h3>

  105.     <ul class="this-page-menu">

  106.       <li><a href="../bugs.html">Report a Bug</a></li>

  107.       <li>

  108.         <a href="https://github.com/python/cpython/blob/main/Doc/c-api/object.rst"

  109.             rel="nofollow">Show Source

  110.         </a>

  111.       </li>

  112.     </ul>

  113.   </div>

  114.         </nav>

  115.     </div>

  116. </div>

  117. 

  118.   

  119.     <div class="related" role="navigation" aria-label="related navigation">

  120.       <h3>Navigation</h3>

  121.       <ul>

  122.         <li class="right" style="margin-right: 10px">

  123.           <a href="../genindex.html" title="General Index"

  124.              accesskey="I">index</a></li>

  125.         <li class="right" >

  126.           <a href="../py-modindex.html" title="Python Module Index"

  127.              >modules</a> |</li>

  128.         <li class="right" >

  129.           <a href="call.html" title="Call Protocol"

  130.              accesskey="N">next</a> |</li>

  131.         <li class="right" >

  132.           <a href="abstract.html" title="Abstract Objects Layer"

  133.              accesskey="P">previous</a> |</li>

  134. 

  135.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  136.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  137.           <li class="switchers">

  138.             <div class="language_switcher_placeholder"></div>

  139.             <div class="version_switcher_placeholder"></div>

  140.           </li>

  141.           <li>

  142.               

  143.           </li>

  144.     <li id="cpython-language-and-version">

  145.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  146.     </li>

  147. 

  148.           <li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>

  149.           <li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> &#187;</li>

  150.         <li class="nav-item nav-item-this"><a href="">Object Protocol</a></li>

  151.                 <li class="right">

  152.                     

  153. 

  154.     <div class="inline-search" role="search">

  155.         <form class="inline-search" action="../search.html" method="get">

  156.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  157.           <input type="submit" value="Go" />

  158.         </form>

  159.     </div>

  160.                      |

  161.                 </li>

  162.             <li class="right">

  163. <label class="theme-selector-label">

  164.     Theme

  165.     <select class="theme-selector" oninput="activateTheme(this.value)">

  166.         <option value="auto" selected>Auto</option>

  167.         <option value="light">Light</option>

  168.         <option value="dark">Dark</option>

  169.     </select>

  170. </label> |</li>

  171.             

  172.       </ul>

  173.     </div>    

  174. 

  175.     <div class="document">

  176.       <div class="documentwrapper">

  177.         <div class="bodywrapper">

  178.           <div class="body" role="main">

  179.             

  180.   <section id="object-protocol">

  181. <span id="object"></span><h1>Object Protocol<a class="headerlink" href="#object-protocol" title="Link to this heading">¶</a></h1>

  182. <dl class="c var">

  183. <dt class="sig sig-object c" id="c.Py_NotImplemented">

  184. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">Py_NotImplemented</span></span></span><a class="headerlink" href="#c.Py_NotImplemented" title="Link to this definition">¶</a><br /></dt>

  185. <dd><p>The <code class="docutils literal notranslate"><span class="pre">NotImplemented</span></code> singleton, used to signal that an operation is

  186. not implemented for the given type combination.</p>

  187. </dd></dl>

  188. 

  189. <dl class="c macro">

  190. <dt class="sig sig-object c" id="c.Py_RETURN_NOTIMPLEMENTED">

  191. <span class="sig-name descname"><span class="n"><span class="pre">Py_RETURN_NOTIMPLEMENTED</span></span></span><a class="headerlink" href="#c.Py_RETURN_NOTIMPLEMENTED" title="Link to this definition">¶</a><br /></dt>

  192. <dd><p>Properly handle returning <a class="reference internal" href="#c.Py_NotImplemented" title="Py_NotImplemented"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_NotImplemented</span></code></a> from within a C

  193. function (that is, create a new <a class="reference internal" href="../glossary.html#term-strong-reference"><span class="xref std std-term">strong reference</span></a>

  194. to NotImplemented and return it).</p>

  195. </dd></dl>

  196. 

  197. <dl class="c macro">

  198. <dt class="sig sig-object c" id="c.Py_PRINT_RAW">

  199. <span class="sig-name descname"><span class="n"><span class="pre">Py_PRINT_RAW</span></span></span><a class="headerlink" href="#c.Py_PRINT_RAW" title="Link to this definition">¶</a><br /></dt>

  200. <dd><p>Flag to be used with multiple functions that print the object (like

  201. <a class="reference internal" href="#c.PyObject_Print" title="PyObject_Print"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Print()</span></code></a> and <a class="reference internal" href="file.html#c.PyFile_WriteObject" title="PyFile_WriteObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_WriteObject()</span></code></a>).

  202. If passed, these function would use the <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> of the object

  203. instead of the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>.</p>

  204. </dd></dl>

  205. 

  206. <dl class="c function">

  207. <dt class="sig sig-object c" id="c.PyObject_Print">

  208. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Print</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <span class="n"><span class="pre">FILE</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">fp</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">flags</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Print" title="Link to this definition">¶</a><br /></dt>

  209. <dd><p>Print an object <em>o</em>, on file <em>fp</em>.  Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error.  The flags argument

  210. is used to enable certain printing options.  The only option currently supported

  211. is <a class="reference internal" href="#c.Py_PRINT_RAW" title="Py_PRINT_RAW"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_PRINT_RAW</span></code></a>; if given, the <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> of the object is written

  212. instead of the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>.</p>

  213. </dd></dl>

  214. 

  215. <dl class="c function">

  216. <dt class="sig sig-object c" id="c.PyObject_HasAttr">

  217. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_HasAttr</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr_name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_HasAttr" title="Link to this definition">¶</a><br /></dt>

  218. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>o</em> has the attribute <em>attr_name</em>, and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.  This

  219. is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">hasattr(o,</span> <span class="pre">attr_name)</span></code>.  This function

  220. always succeeds.</p>

  221. <div class="admonition note">

  222. <p class="admonition-title">Note</p>

  223. <p>Exceptions that occur when this calls <a class="reference internal" href="../reference/datamodel.html#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code></a> and

  224. <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a> methods are silently ignored.

  225. For proper error handling, use <a class="reference internal" href="#c.PyObject_GetAttr" title="PyObject_GetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetAttr()</span></code></a> instead.</p>

  226. </div>

  227. </dd></dl>

  228. 

  229. <dl class="c function">

  230. <dt class="sig sig-object c" id="c.PyObject_HasAttrString">

  231. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_HasAttrString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr_name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_HasAttrString" title="Link to this definition">¶</a><br /></dt>

  232. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is the same as <a class="reference internal" href="#c.PyObject_HasAttr" title="PyObject_HasAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_HasAttr()</span></code></a>, but <em>attr_name</em> is

  233. specified as a <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> UTF-8 encoded bytes string,

  234. rather than a <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p>

  235. <div class="admonition note">

  236. <p class="admonition-title">Note</p>

  237. <p>Exceptions that occur when this calls <a class="reference internal" href="../reference/datamodel.html#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattr__()</span></code></a> and

  238. <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getattribute__()</span></code></a> methods or while creating the temporary

  239. <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> object are silently ignored.

  240. For proper error handling, use <a class="reference internal" href="#c.PyObject_GetAttrString" title="PyObject_GetAttrString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetAttrString()</span></code></a> instead.</p>

  241. </div>

  242. </dd></dl>

  243. 

  244. <dl class="c function">

  245. <dt class="sig sig-object c" id="c.PyObject_GetAttr">

  246. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GetAttr</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr_name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetAttr" title="Link to this definition">¶</a><br /></dt>

  247. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Retrieve an attribute named <em>attr_name</em> from object <em>o</em>. Returns the attribute

  248. value on success, or <code class="docutils literal notranslate"><span class="pre">NULL</span></code> on failure.  This is the equivalent of the Python

  249. expression <code class="docutils literal notranslate"><span class="pre">o.attr_name</span></code>.</p>

  250. </dd></dl>

  251. 

  252. <dl class="c function">

  253. <dt class="sig sig-object c" id="c.PyObject_GetAttrString">

  254. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GetAttrString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr_name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetAttrString" title="Link to this definition">¶</a><br /></dt>

  255. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is the same as <a class="reference internal" href="#c.PyObject_GetAttr" title="PyObject_GetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetAttr()</span></code></a>, but <em>attr_name</em> is

  256. specified as a <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> UTF-8 encoded bytes string,

  257. rather than a <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p>

  258. </dd></dl>

  259. 

  260. <dl class="c function">

  261. <dt class="sig sig-object c" id="c.PyObject_GenericGetAttr">

  262. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GenericGetAttr</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GenericGetAttr" title="Link to this definition">¶</a><br /></dt>

  263. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Generic attribute getter function that is meant to be put into a type

  264. object’s <code class="docutils literal notranslate"><span class="pre">tp_getattro</span></code> slot.  It looks for a descriptor in the dictionary

  265. of classes in the object’s MRO as well as an attribute in the object’s

  266. <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> (if present).  As outlined in <a class="reference internal" href="../reference/datamodel.html#descriptors"><span class="std std-ref">Implementing Descriptors</span></a>,

  267. data descriptors take preference over instance attributes, while non-data

  268. descriptors don’t.  Otherwise, an <a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> is raised.</p>

  269. </dd></dl>

  270. 

  271. <dl class="c function">

  272. <dt class="sig sig-object c" id="c.PyObject_SetAttr">

  273. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_SetAttr</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr_name</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">v</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_SetAttr" title="Link to this definition">¶</a><br /></dt>

  274. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set the value of the attribute named <em>attr_name</em>, for object <em>o</em>, to the value

  275. <em>v</em>. Raise an exception and return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure;

  276. return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.  This is the equivalent of the Python statement

  277. <code class="docutils literal notranslate"><span class="pre">o.attr_name</span> <span class="pre">=</span> <span class="pre">v</span></code>.</p>

  278. <p>If <em>v</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, the attribute is deleted. This behaviour is deprecated

  279. in favour of using <a class="reference internal" href="#c.PyObject_DelAttr" title="PyObject_DelAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_DelAttr()</span></code></a>, but there are currently no

  280. plans to remove it.</p>

  281. </dd></dl>

  282. 

  283. <dl class="c function">

  284. <dt class="sig sig-object c" id="c.PyObject_SetAttrString">

  285. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_SetAttrString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr_name</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">v</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_SetAttrString" title="Link to this definition">¶</a><br /></dt>

  286. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is the same as <a class="reference internal" href="#c.PyObject_SetAttr" title="PyObject_SetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_SetAttr()</span></code></a>, but <em>attr_name</em> is

  287. specified as a <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> UTF-8 encoded bytes string,

  288. rather than a <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p>

  289. <p>If <em>v</em> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, the attribute is deleted, but this feature is

  290. deprecated in favour of using <a class="reference internal" href="#c.PyObject_DelAttrString" title="PyObject_DelAttrString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_DelAttrString()</span></code></a>.</p>

  291. </dd></dl>

  292. 

  293. <dl class="c function">

  294. <dt class="sig sig-object c" id="c.PyObject_GenericSetAttr">

  295. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GenericSetAttr</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">value</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GenericSetAttr" title="Link to this definition">¶</a><br /></dt>

  296. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Generic attribute setter and deleter function that is meant

  297. to be put into a type object’s <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattro</span></code></a>

  298. slot.  It looks for a data descriptor in the

  299. dictionary of classes in the object’s MRO, and if found it takes preference

  300. over setting or deleting the attribute in the instance dictionary. Otherwise, the

  301. attribute is set or deleted in the object’s <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> (if present).

  302. On success, <code class="docutils literal notranslate"><span class="pre">0</span></code> is returned, otherwise an <a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>

  303. is raised and <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned.</p>

  304. </dd></dl>

  305. 

  306. <dl class="c function">

  307. <dt class="sig sig-object c" id="c.PyObject_DelAttr">

  308. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_DelAttr</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr_name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_DelAttr" title="Link to this definition">¶</a><br /></dt>

  309. <dd><p>Delete attribute named <em>attr_name</em>, for object <em>o</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.

  310. This is the equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o.attr_name</span></code>.</p>

  311. </dd></dl>

  312. 

  313. <dl class="c function">

  314. <dt class="sig sig-object c" id="c.PyObject_DelAttrString">

  315. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_DelAttrString</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">attr_name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_DelAttrString" title="Link to this definition">¶</a><br /></dt>

  316. <dd><p>This is the same as <a class="reference internal" href="#c.PyObject_DelAttr" title="PyObject_DelAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_DelAttr()</span></code></a>, but <em>attr_name</em> is

  317. specified as a <span class="c-expr sig sig-inline c"><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="p">*</span></span> UTF-8 encoded bytes string,

  318. rather than a <span class="c-expr sig sig-inline c"><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n">PyObject</span></a><span class="p">*</span></span>.</p>

  319. </dd></dl>

  320. 

  321. <dl class="c function">

  322. <dt class="sig sig-object c" id="c.PyObject_GenericGetDict">

  323. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GenericGetDict</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">context</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GenericGetDict" title="Link to this definition">¶</a><br /></dt>

  324. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>A generic implementation for the getter of a <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> descriptor. It

  325. creates the dictionary if necessary.</p>

  326. <p>This function may also be called to get the <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>

  327. of the object <em>o</em>. Pass <code class="docutils literal notranslate"><span class="pre">NULL</span></code> for <em>context</em> when calling it.

  328. Since this function may need to allocate memory for the

  329. dictionary, it may be more efficient to call <a class="reference internal" href="#c.PyObject_GetAttr" title="PyObject_GetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetAttr()</span></code></a>

  330. when accessing an attribute on the object.</p>

  331. <p>On failure, returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set.</p>

  332. <div class="versionadded">

  333. <p><span class="versionmodified added">New in version 3.3.</span></p>

  334. </div>

  335. </dd></dl>

  336. 

  337. <dl class="c function">

  338. <dt class="sig sig-object c" id="c.PyObject_GenericSetDict">

  339. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GenericSetDict</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">value</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">context</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GenericSetDict" title="Link to this definition">¶</a><br /></dt>

  340. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>A generic implementation for the setter of a <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> descriptor. This

  341. implementation does not allow the dictionary to be deleted.</p>

  342. <div class="versionadded">

  343. <p><span class="versionmodified added">New in version 3.3.</span></p>

  344. </div>

  345. </dd></dl>

  346. 

  347. <dl class="c function">

  348. <dt class="sig sig-object c" id="c._PyObject_GetDictPtr">

  349. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">_PyObject_GetDictPtr</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c._PyObject_GetDictPtr" title="Link to this definition">¶</a><br /></dt>

  350. <dd><p>Return a pointer to <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> of the object <em>obj</em>.

  351. If there is no <code class="docutils literal notranslate"><span class="pre">__dict__</span></code>, return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> without setting an exception.</p>

  352. <p>This function may need to allocate memory for the

  353. dictionary, so it may be more efficient to call <a class="reference internal" href="#c.PyObject_GetAttr" title="PyObject_GetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetAttr()</span></code></a>

  354. when accessing an attribute on the object.</p>

  355. </dd></dl>

  356. 

  357. <dl class="c function">

  358. <dt class="sig sig-object c" id="c.PyObject_RichCompare">

  359. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_RichCompare</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o1</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o2</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">opid</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_RichCompare" title="Link to this definition">¶</a><br /></dt>

  360. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Compare the values of <em>o1</em> and <em>o2</em> using the operation specified by <em>opid</em>,

  361. which must be one of <a class="reference internal" href="typeobj.html#c.Py_LT" title="Py_LT"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_LT</span></code></a>, <a class="reference internal" href="typeobj.html#c.Py_LE" title="Py_LE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_LE</span></code></a>, <a class="reference internal" href="typeobj.html#c.Py_EQ" title="Py_EQ"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_EQ</span></code></a>,

  362. <a class="reference internal" href="typeobj.html#c.Py_NE" title="Py_NE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_NE</span></code></a>, <a class="reference internal" href="typeobj.html#c.Py_GT" title="Py_GT"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_GT</span></code></a>, or <a class="reference internal" href="typeobj.html#c.Py_GE" title="Py_GE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_GE</span></code></a>, corresponding to <code class="docutils literal notranslate"><span class="pre">&lt;</span></code>,

  363. <code class="docutils literal notranslate"><span class="pre">&lt;=</span></code>, <code class="docutils literal notranslate"><span class="pre">==</span></code>, <code class="docutils literal notranslate"><span class="pre">!=</span></code>, <code class="docutils literal notranslate"><span class="pre">&gt;</span></code>, or <code class="docutils literal notranslate"><span class="pre">&gt;=</span></code> respectively. This is the equivalent of

  364. the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">op</span> <span class="pre">o2</span></code>, where <code class="docutils literal notranslate"><span class="pre">op</span></code> is the operator corresponding

  365. to <em>opid</em>. Returns the value of the comparison on success, or <code class="docutils literal notranslate"><span class="pre">NULL</span></code> on failure.</p>

  366. </dd></dl>

  367. 

  368. <dl class="c function">

  369. <dt class="sig sig-object c" id="c.PyObject_RichCompareBool">

  370. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_RichCompareBool</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o1</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o2</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">opid</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_RichCompareBool" title="Link to this definition">¶</a><br /></dt>

  371. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Compare the values of <em>o1</em> and <em>o2</em> using the operation specified by <em>opid</em>,

  372. like <a class="reference internal" href="#c.PyObject_RichCompare" title="PyObject_RichCompare"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_RichCompare()</span></code></a>, but returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> if

  373. the result is false, <code class="docutils literal notranslate"><span class="pre">1</span></code> otherwise.</p>

  374. </dd></dl>

  375. 

  376. <div class="admonition note">

  377. <p class="admonition-title">Note</p>

  378. <p>If <em>o1</em> and <em>o2</em> are the same object, <a class="reference internal" href="#c.PyObject_RichCompareBool" title="PyObject_RichCompareBool"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_RichCompareBool()</span></code></a>

  379. will always return <code class="docutils literal notranslate"><span class="pre">1</span></code> for <a class="reference internal" href="typeobj.html#c.Py_EQ" title="Py_EQ"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_EQ</span></code></a> and <code class="docutils literal notranslate"><span class="pre">0</span></code> for <a class="reference internal" href="typeobj.html#c.Py_NE" title="Py_NE"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_NE</span></code></a>.</p>

  380. </div>

  381. <dl class="c function">

  382. <dt class="sig sig-object c" id="c.PyObject_Format">

  383. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Format</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">format_spec</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Format" title="Link to this definition">¶</a><br /></dt>

  384. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Format <em>obj</em> using <em>format_spec</em>. This is equivalent to the Python

  385. expression <code class="docutils literal notranslate"><span class="pre">format(obj,</span> <span class="pre">format_spec)</span></code>.</p>

  386. <p><em>format_spec</em> may be <code class="docutils literal notranslate"><span class="pre">NULL</span></code>. In this case the call is equivalent

  387. to <code class="docutils literal notranslate"><span class="pre">format(obj)</span></code>.

  388. Returns the formatted string on success, <code class="docutils literal notranslate"><span class="pre">NULL</span></code> on failure.</p>

  389. </dd></dl>

  390. 

  391. <dl class="c function">

  392. <dt class="sig sig-object c" id="c.PyObject_Repr">

  393. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Repr</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Repr" title="Link to this definition">¶</a><br /></dt>

  394. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-0">Compute a string representation of object <em>o</em>.  Returns the string

  395. representation on success, <code class="docutils literal notranslate"><span class="pre">NULL</span></code> on failure.  This is the equivalent of the

  396. Python expression <code class="docutils literal notranslate"><span class="pre">repr(o)</span></code>.  Called by the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a> built-in function.</p>

  397. <div class="versionchanged">

  398. <p><span class="versionmodified changed">Changed in version 3.4: </span>This function now includes a debug assertion to help ensure that it

  399. does not silently discard an active exception.</p>

  400. </div>

  401. </dd></dl>

  402. 

  403. <dl class="c function">

  404. <dt class="sig sig-object c" id="c.PyObject_ASCII">

  405. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_ASCII</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_ASCII" title="Link to this definition">¶</a><br /></dt>

  406. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-1">As <a class="reference internal" href="#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code></a>, compute a string representation of object <em>o</em>, but

  407. escape the non-ASCII characters in the string returned by

  408. <a class="reference internal" href="#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code></a> with <code class="docutils literal notranslate"><span class="pre">\x</span></code>, <code class="docutils literal notranslate"><span class="pre">\u</span></code> or <code class="docutils literal notranslate"><span class="pre">\U</span></code> escapes.  This generates

  409. a string similar to that returned by <a class="reference internal" href="#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code></a> in Python 2.

  410. Called by the <a class="reference internal" href="../library/functions.html#ascii" title="ascii"><code class="xref py py-func docutils literal notranslate"><span class="pre">ascii()</span></code></a> built-in function.</p>

  411. <span class="target" id="index-2"></span></dd></dl>

  412. 

  413. <dl class="c function">

  414. <dt class="sig sig-object c" id="c.PyObject_Str">

  415. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Str</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Str" title="Link to this definition">¶</a><br /></dt>

  416. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Compute a string representation of object <em>o</em>.  Returns the string

  417. representation on success, <code class="docutils literal notranslate"><span class="pre">NULL</span></code> on failure.  This is the equivalent of the

  418. Python expression <code class="docutils literal notranslate"><span class="pre">str(o)</span></code>.  Called by the <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> built-in function

  419. and, therefore, by the <a class="reference internal" href="../library/functions.html#print" title="print"><code class="xref py py-func docutils literal notranslate"><span class="pre">print()</span></code></a> function.</p>

  420. <div class="versionchanged">

  421. <p><span class="versionmodified changed">Changed in version 3.4: </span>This function now includes a debug assertion to help ensure that it

  422. does not silently discard an active exception.</p>

  423. </div>

  424. </dd></dl>

  425. 

  426. <dl class="c function">

  427. <dt class="sig sig-object c" id="c.PyObject_Bytes">

  428. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Bytes</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Bytes" title="Link to this definition">¶</a><br /></dt>

  429. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-3">Compute a bytes representation of object <em>o</em>.  <code class="docutils literal notranslate"><span class="pre">NULL</span></code> is returned on

  430. failure and a bytes object on success.  This is equivalent to the Python

  431. expression <code class="docutils literal notranslate"><span class="pre">bytes(o)</span></code>, when <em>o</em> is not an integer.  Unlike <code class="docutils literal notranslate"><span class="pre">bytes(o)</span></code>,

  432. a TypeError is raised when <em>o</em> is an integer instead of a zero-initialized

  433. bytes object.</p>

  434. </dd></dl>

  435. 

  436. <dl class="c function">

  437. <dt class="sig sig-object c" id="c.PyObject_IsSubclass">

  438. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_IsSubclass</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">derived</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">cls</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_IsSubclass" title="Link to this definition">¶</a><br /></dt>

  439. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if the class <em>derived</em> is identical to or derived from the class

  440. <em>cls</em>, otherwise return <code class="docutils literal notranslate"><span class="pre">0</span></code>.  In case of an error, return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>

  441. <p>If <em>cls</em> is a tuple, the check will be done against every entry in <em>cls</em>.

  442. The result will be <code class="docutils literal notranslate"><span class="pre">1</span></code> when at least one of the checks returns <code class="docutils literal notranslate"><span class="pre">1</span></code>,

  443. otherwise it will be <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>

  444. <p>If <em>cls</em> has a <a class="reference internal" href="../reference/datamodel.html#class.__subclasscheck__" title="class.__subclasscheck__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__subclasscheck__()</span></code></a> method, it will be called to

  445. determine the subclass status as described in <span class="target" id="index-4"></span><a class="pep reference external" href="https://peps.python.org/pep-3119/"><strong>PEP 3119</strong></a>.  Otherwise,

  446. <em>derived</em> is a subclass of <em>cls</em> if it is a direct or indirect subclass,

  447. i.e. contained in <code class="docutils literal notranslate"><span class="pre">cls.__mro__</span></code>.</p>

  448. <p>Normally only class objects, i.e. instances of <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate"><span class="pre">type</span></code></a> or a derived

  449. class, are considered classes.  However, objects can override this by having

  450. a <a class="reference internal" href="../library/stdtypes.html#class.__bases__" title="class.__bases__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__bases__</span></code></a> attribute (which must be a tuple of base classes).</p>

  451. </dd></dl>

  452. 

  453. <dl class="c function">

  454. <dt class="sig sig-object c" id="c.PyObject_IsInstance">

  455. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_IsInstance</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">inst</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">cls</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_IsInstance" title="Link to this definition">¶</a><br /></dt>

  456. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>inst</em> is an instance of the class <em>cls</em> or a subclass of

  457. <em>cls</em>, or <code class="docutils literal notranslate"><span class="pre">0</span></code> if not.  On error, returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets an exception.</p>

  458. <p>If <em>cls</em> is a tuple, the check will be done against every entry in <em>cls</em>.

  459. The result will be <code class="docutils literal notranslate"><span class="pre">1</span></code> when at least one of the checks returns <code class="docutils literal notranslate"><span class="pre">1</span></code>,

  460. otherwise it will be <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>

  461. <p>If <em>cls</em> has a <a class="reference internal" href="../reference/datamodel.html#class.__instancecheck__" title="class.__instancecheck__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__instancecheck__()</span></code></a> method, it will be called to

  462. determine the subclass status as described in <span class="target" id="index-5"></span><a class="pep reference external" href="https://peps.python.org/pep-3119/"><strong>PEP 3119</strong></a>.  Otherwise, <em>inst</em>

  463. is an instance of <em>cls</em> if its class is a subclass of <em>cls</em>.</p>

  464. <p>An instance <em>inst</em> can override what is considered its class by having a

  465. <a class="reference internal" href="../library/stdtypes.html#instance.__class__" title="instance.__class__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__class__</span></code></a> attribute.</p>

  466. <p>An object <em>cls</em> can override if it is considered a class, and what its base

  467. classes are, by having a <a class="reference internal" href="../library/stdtypes.html#class.__bases__" title="class.__bases__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__bases__</span></code></a> attribute (which must be a tuple

  468. of base classes).</p>

  469. </dd></dl>

  470. 

  471. <dl class="c function">

  472. <dt class="sig sig-object c" id="c.PyObject_Hash">

  473. <a class="reference internal" href="hash.html#c.Py_hash_t" title="Py_hash_t"><span class="n"><span class="pre">Py_hash_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Hash</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Hash" title="Link to this definition">¶</a><br /></dt>

  474. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-6">Compute and return the hash value of an object <em>o</em>.  On failure, return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.

  475. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">hash(o)</span></code>.</p>

  476. <div class="versionchanged">

  477. <p><span class="versionmodified changed">Changed in version 3.2: </span>The return type is now Py_hash_t.  This is a signed integer the same size

  478. as <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code></a>.</p>

  479. </div>

  480. </dd></dl>

  481. 

  482. <dl class="c function">

  483. <dt class="sig sig-object c" id="c.PyObject_HashNotImplemented">

  484. <a class="reference internal" href="hash.html#c.Py_hash_t" title="Py_hash_t"><span class="n"><span class="pre">Py_hash_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_HashNotImplemented</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_HashNotImplemented" title="Link to this definition">¶</a><br /></dt>

  485. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set a <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> indicating that <code class="docutils literal notranslate"><span class="pre">type(o)</span></code> is not <a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a> and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.

  486. This function receives special treatment when stored in a <code class="docutils literal notranslate"><span class="pre">tp_hash</span></code> slot,

  487. allowing a type to explicitly indicate to the interpreter that it is not

  488. hashable.</p>

  489. </dd></dl>

  490. 

  491. <dl class="c function">

  492. <dt class="sig sig-object c" id="c.PyObject_IsTrue">

  493. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_IsTrue</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_IsTrue" title="Link to this definition">¶</a><br /></dt>

  494. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if the object <em>o</em> is considered to be true, and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.

  495. This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">not</span> <span class="pre">o</span></code>.  On failure, return

  496. <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>

  497. </dd></dl>

  498. 

  499. <dl class="c function">

  500. <dt class="sig sig-object c" id="c.PyObject_Not">

  501. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Not</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Not" title="Link to this definition">¶</a><br /></dt>

  502. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> if the object <em>o</em> is considered to be true, and <code class="docutils literal notranslate"><span class="pre">1</span></code> otherwise.

  503. This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">o</span></code>.  On failure, return

  504. <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>

  505. </dd></dl>

  506. 

  507. <dl class="c function">

  508. <dt class="sig sig-object c" id="c.PyObject_Type">

  509. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Type</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Type" title="Link to this definition">¶</a><br /></dt>

  510. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-7">When <em>o</em> is non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code>, returns a type object corresponding to the object type

  511. of object <em>o</em>. On failure, raises <a class="reference internal" href="../library/exceptions.html#SystemError" title="SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> and returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.  This

  512. is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">type(o)</span></code>.

  513. This function creates a new <a class="reference internal" href="../glossary.html#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to the return value.

  514. There’s really no reason to use this

  515. function instead of the <a class="reference internal" href="structures.html#c.Py_TYPE" title="Py_TYPE"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_TYPE()</span></code></a> function, which returns a

  516. pointer of type <span class="c-expr sig sig-inline c"><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><span class="n">PyTypeObject</span></a><span class="p">*</span></span>, except when a new

  517. <a class="reference internal" href="../glossary.html#term-strong-reference"><span class="xref std std-term">strong reference</span></a> is needed.</p>

  518. </dd></dl>

  519. 

  520. <dl class="c function">

  521. <dt class="sig sig-object c" id="c.PyObject_TypeCheck">

  522. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_TypeCheck</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">type</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_TypeCheck" title="Link to this definition">¶</a><br /></dt>

  523. <dd><p>Return non-zero if the object <em>o</em> is of type <em>type</em> or a subtype of <em>type</em>, and

  524. <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.  Both parameters must be non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>

  525. </dd></dl>

  526. 

  527. <dl class="c function">

  528. <dt class="sig sig-object c" id="c.PyObject_Size">

  529. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Size</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Size" title="Link to this definition">¶</a><br /></dt>

  530. <dt class="sig sig-object c" id="c.PyObject_Length">

  531. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Length</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Length" title="Link to this definition">¶</a><br /></dt>

  532. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-8">Return the length of object <em>o</em>.  If the object <em>o</em> provides either the sequence

  533. and mapping protocols, the sequence length is returned.  On error, <code class="docutils literal notranslate"><span class="pre">-1</span></code> is

  534. returned.  This is the equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">len(o)</span></code>.</p>

  535. </dd></dl>

  536. 

  537. <dl class="c function">

  538. <dt class="sig sig-object c" id="c.PyObject_LengthHint">

  539. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_LengthHint</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="n"><span class="pre">defaultvalue</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_LengthHint" title="Link to this definition">¶</a><br /></dt>

  540. <dd><p>Return an estimated length for the object <em>o</em>. First try to return its

  541. actual length, then an estimate using <a class="reference internal" href="../reference/datamodel.html#object.__length_hint__" title="object.__length_hint__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__length_hint__()</span></code></a>, and

  542. finally return the default value. On error return <code class="docutils literal notranslate"><span class="pre">-1</span></code>. This is the

  543. equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">operator.length_hint(o,</span> <span class="pre">defaultvalue)</span></code>.</p>

  544. <div class="versionadded">

  545. <p><span class="versionmodified added">New in version 3.4.</span></p>

  546. </div>

  547. </dd></dl>

  548. 

  549. <dl class="c function">

  550. <dt class="sig sig-object c" id="c.PyObject_GetItem">

  551. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GetItem</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">key</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetItem" title="Link to this definition">¶</a><br /></dt>

  552. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return element of <em>o</em> corresponding to the object <em>key</em> or <code class="docutils literal notranslate"><span class="pre">NULL</span></code> on failure.

  553. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o[key]</span></code>.</p>

  554. </dd></dl>

  555. 

  556. <dl class="c function">

  557. <dt class="sig sig-object c" id="c.PyObject_SetItem">

  558. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_SetItem</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">key</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">v</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_SetItem" title="Link to this definition">¶</a><br /></dt>

  559. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Map the object <em>key</em> to the value <em>v</em>.  Raise an exception and

  560. return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure; return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.  This is the

  561. equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">o[key]</span> <span class="pre">=</span> <span class="pre">v</span></code>.  This function <em>does

  562. not</em> steal a reference to <em>v</em>.</p>

  563. </dd></dl>

  564. 

  565. <dl class="c function">

  566. <dt class="sig sig-object c" id="c.PyObject_DelItem">

  567. <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_DelItem</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">key</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_DelItem" title="Link to this definition">¶</a><br /></dt>

  568. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Remove the mapping for the object <em>key</em> from the object <em>o</em>.  Return <code class="docutils literal notranslate"><span class="pre">-1</span></code>

  569. on failure.  This is equivalent to the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o[key]</span></code>.</p>

  570. </dd></dl>

  571. 

  572. <dl class="c function">

  573. <dt class="sig sig-object c" id="c.PyObject_Dir">

  574. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_Dir</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Dir" title="Link to this definition">¶</a><br /></dt>

  575. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">dir(o)</span></code>, returning a (possibly

  576. empty) list of strings appropriate for the object argument, or <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if there

  577. was an error.  If the argument is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, this is like the Python <code class="docutils literal notranslate"><span class="pre">dir()</span></code>,

  578. returning the names of the current locals; in this case, if no execution frame

  579. is active then <code class="docutils literal notranslate"><span class="pre">NULL</span></code> is returned but <a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> will return false.</p>

  580. </dd></dl>

  581. 

  582. <dl class="c function">

  583. <dt class="sig sig-object c" id="c.PyObject_GetIter">

  584. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GetIter</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetIter" title="Link to this definition">¶</a><br /></dt>

  585. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">iter(o)</span></code>. It returns a new

  586. iterator for the object argument, or the object  itself if the object is already

  587. an iterator.  Raises <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> and returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if the object cannot be

  588. iterated.</p>

  589. </dd></dl>

  590. 

  591. <dl class="c function">

  592. <dt class="sig sig-object c" id="c.PyObject_GetAIter">

  593. <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GetAIter</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetAIter" title="Link to this definition">¶</a><br /></dt>

  594. <dd><em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.10.</em><p>This is the equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">aiter(o)</span></code>. Takes an

  595. <code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterable</span></code> object and returns an <code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterator</span></code> for it.

  596. This is typically a new iterator but if the argument is an

  597. <code class="xref py py-class docutils literal notranslate"><span class="pre">AsyncIterator</span></code>, this returns itself. Raises <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> and

  598. returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if the object cannot be iterated.</p>

  599. <div class="versionadded">

  600. <p><span class="versionmodified added">New in version 3.10.</span></p>

  601. </div>

  602. </dd></dl>

  603. 

  604. <dl class="c function">

  605. <dt class="sig sig-object c" id="c.PyObject_GetTypeData">

  606. <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GetTypeData</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span>, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">cls</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetTypeData" title="Link to this definition">¶</a><br /></dt>

  607. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.12.</em><p>Get a pointer to subclass-specific data reserved for <em>cls</em>.</p>

  608. <p>The object <em>o</em> must be an instance of <em>cls</em>, and <em>cls</em> must have been

  609. created using negative <a class="reference internal" href="type.html#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.basicsize</span></code></a>.

  610. Python does not check this.</p>

  611. <p>On error, set an exception and return <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>

  612. <div class="versionadded">

  613. <p><span class="versionmodified added">New in version 3.12.</span></p>

  614. </div>

  615. </dd></dl>

  616. 

  617. <dl class="c function">

  618. <dt class="sig sig-object c" id="c.PyType_GetTypeDataSize">

  619. <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t"><span class="n"><span class="pre">Py_ssize_t</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyType_GetTypeDataSize</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><span class="n"><span class="pre">PyTypeObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">cls</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GetTypeDataSize" title="Link to this definition">¶</a><br /></dt>

  620. <dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.12.</em><p>Return the size of the instance memory space reserved for <em>cls</em>, i.e. the size of the

  621. memory <a class="reference internal" href="#c.PyObject_GetTypeData" title="PyObject_GetTypeData"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetTypeData()</span></code></a> returns.</p>

  622. <p>This may be larger than requested using <a class="reference internal" href="type.html#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">-PyType_Spec.basicsize</span></code></a>;

  623. it is safe to use this larger size (e.g. with <code class="xref c c-func docutils literal notranslate"><span class="pre">memset()</span></code>).</p>

  624. <p>The type <em>cls</em> <strong>must</strong> have been created using

  625. negative <a class="reference internal" href="type.html#c.PyType_Spec.basicsize" title="PyType_Spec.basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyType_Spec.basicsize</span></code></a>.

  626. Python does not check this.</p>

  627. <p>On error, set an exception and return a negative value.</p>

  628. <div class="versionadded">

  629. <p><span class="versionmodified added">New in version 3.12.</span></p>

  630. </div>

  631. </dd></dl>

  632. 

  633. <dl class="c function">

  634. <dt class="sig sig-object c" id="c.PyObject_GetItemData">

  635. <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyObject_GetItemData</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><span class="n"><span class="pre">PyObject</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">o</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetItemData" title="Link to this definition">¶</a><br /></dt>

  636. <dd><p>Get a pointer to per-item data for a class with

  637. <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_ITEMS_AT_END" title="Py_TPFLAGS_ITEMS_AT_END"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_ITEMS_AT_END</span></code></a>.</p>

  638. <p>On error, set an exception and return <code class="docutils literal notranslate"><span class="pre">NULL</span></code>.

  639. <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised if <em>o</em> does not have

  640. <a class="reference internal" href="typeobj.html#c.Py_TPFLAGS_ITEMS_AT_END" title="Py_TPFLAGS_ITEMS_AT_END"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TPFLAGS_ITEMS_AT_END</span></code></a> set.</p>

  641. <div class="versionadded">

  642. <p><span class="versionmodified added">New in version 3.12.</span></p>

  643. </div>

  644. </dd></dl>

  645. 

  646. </section>

  647. 

  648. 

  649.             <div class="clearer"></div>

  650.           </div>

  651.         </div>

  652.       </div>

  653.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  654.         <div class="sphinxsidebarwrapper">

  655.   <div>

  656.     <h4>Previous topic</h4>

  657.     <p class="topless"><a href="abstract.html"

  658.                           title="previous chapter">Abstract Objects Layer</a></p>

  659.   </div>

  660.   <div>

  661.     <h4>Next topic</h4>

  662.     <p class="topless"><a href="call.html"

  663.                           title="next chapter">Call Protocol</a></p>

  664.   </div>

  665.   <div role="note" aria-label="source link">

  666.     <h3>This Page</h3>

  667.     <ul class="this-page-menu">

  668.       <li><a href="../bugs.html">Report a Bug</a></li>

  669.       <li>

  670.         <a href="https://github.com/python/cpython/blob/main/Doc/c-api/object.rst"

  671.             rel="nofollow">Show Source

  672.         </a>

  673.       </li>

  674.     </ul>

  675.   </div>

  676.         </div>

  677. <div id="sidebarbutton" title="Collapse sidebar">

  678. <span>«</span>

  679. </div>

  680. 

  681.       </div>

  682.       <div class="clearer"></div>

  683.     </div>  

  684.     <div class="related" role="navigation" aria-label="related navigation">

  685.       <h3>Navigation</h3>

  686.       <ul>

  687.         <li class="right" style="margin-right: 10px">

  688.           <a href="../genindex.html" title="General Index"

  689.              >index</a></li>

  690.         <li class="right" >

  691.           <a href="../py-modindex.html" title="Python Module Index"

  692.              >modules</a> |</li>

  693.         <li class="right" >

  694.           <a href="call.html" title="Call Protocol"

  695.              >next</a> |</li>

  696.         <li class="right" >

  697.           <a href="abstract.html" title="Abstract Objects Layer"

  698.              >previous</a> |</li>

  699. 

  700.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  701.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  702.           <li class="switchers">

  703.             <div class="language_switcher_placeholder"></div>

  704.             <div class="version_switcher_placeholder"></div>

  705.           </li>

  706.           <li>

  707.               

  708.           </li>

  709.     <li id="cpython-language-and-version">

  710.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  711.     </li>

  712. 

  713.           <li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> &#187;</li>

  714.           <li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> &#187;</li>

  715.         <li class="nav-item nav-item-this"><a href="">Object Protocol</a></li>

  716.                 <li class="right">

  717.                     

  718. 

  719.     <div class="inline-search" role="search">

  720.         <form class="inline-search" action="../search.html" method="get">

  721.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  722.           <input type="submit" value="Go" />

  723.         </form>

  724.     </div>

  725.                      |

  726.                 </li>

  727.             <li class="right">

  728. <label class="theme-selector-label">

  729.     Theme

  730.     <select class="theme-selector" oninput="activateTheme(this.value)">

  731.         <option value="auto" selected>Auto</option>

  732.         <option value="light">Light</option>

  733.         <option value="dark">Dark</option>

  734.     </select>

  735. </label> |</li>

  736.             

  737.       </ul>

  738.     </div>  

  739.     <div class="footer">

  740.     &copy; 

  741.       <a href="../copyright.html">

  742.     

  743.     Copyright

  744.     

  745.       </a>

  746.      2001-2024, Python Software Foundation.

  747.     <br />

  748.     This page is licensed under the Python Software Foundation License Version 2.

  749.     <br />

  750.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  751.     <br />

  752.     

  753.       See <a href="/license.html">History and License</a> for more information.<br />

  754.     

  755.     

  756.     <br />

  757. 

  758.     The Python Software Foundation is a non-profit corporation.

  759. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  760. <br />

  761.     <br />

  762.       Last updated on Apr 09, 2024 (13:47 UTC).

  763.     

  764.       <a href="/bugs.html">Found a bug</a>?

  765.     

  766.     <br />

  767. 

  768.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  769.     </div>

  770. 

  771.   </body>

  772. </html>
上海开阖软件有限公司 沪ICP备12045867号-1