cpython/Doc/c-api/dict.rst

212 lines
6.9 KiB
ReStructuredText
Raw Normal View History

2008-01-20 05:30:57 -04:00
.. highlightlang:: c
.. _dictobjects:
Dictionary Objects
------------------
.. index:: object: dictionary
.. ctype:: PyDictObject
This subtype of :ctype:`PyObject` represents a Python dictionary object.
.. cvar:: PyTypeObject PyDict_Type
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
This instance of :ctype:`PyTypeObject` represents the Python dictionary
Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ........ r85572 | georg.brandl | 2010-10-16 20:51:05 +0200 (Sa, 16 Okt 2010) | 1 line #10122: typo fix. ........ r85573 | georg.brandl | 2010-10-16 20:53:08 +0200 (Sa, 16 Okt 2010) | 1 line #10124: typo fix. ........ r85606 | georg.brandl | 2010-10-17 08:32:59 +0200 (So, 17 Okt 2010) | 1 line #10058: tweak wording about exception returns. ........ r85609 | georg.brandl | 2010-10-17 11:19:03 +0200 (So, 17 Okt 2010) | 1 line #8556: use less confusing mapping key in example. ........ r85610 | georg.brandl | 2010-10-17 11:23:05 +0200 (So, 17 Okt 2010) | 1 line #8686: remove potentially confusing wording that does not add any value. ........ r85611 | georg.brandl | 2010-10-17 11:33:24 +0200 (So, 17 Okt 2010) | 1 line #8811: small fixes to sqlite3 docs. ........ r85612 | georg.brandl | 2010-10-17 11:37:54 +0200 (So, 17 Okt 2010) | 1 line #8855: add shelve security warning. ........ r85613 | georg.brandl | 2010-10-17 11:43:35 +0200 (So, 17 Okt 2010) | 1 line Fix hmac docs: it takes and returns bytes, except for hexdigest(). ........ r85614 | georg.brandl | 2010-10-17 11:46:11 +0200 (So, 17 Okt 2010) | 1 line #8968: add actual name of token constants. ........ r85615 | georg.brandl | 2010-10-17 12:05:13 +0200 (So, 17 Okt 2010) | 1 line #459007: merge info from PC/getpathp.c and using/windows.rst to document the forming of sys.path under Windows. ........ r85616 | georg.brandl | 2010-10-17 12:07:29 +0200 (So, 17 Okt 2010) | 1 line Fix copy-paste error in example. ........ r85617 | georg.brandl | 2010-10-17 12:09:06 +0200 (So, 17 Okt 2010) | 1 line #5212: md5 weaknesses do not affect hmac, so remove the note about that. ........ r85618 | georg.brandl | 2010-10-17 12:14:38 +0200 (So, 17 Okt 2010) | 1 line #9086: correct wrong terminology about linking with pythonXY.dll. ........ r85619 | georg.brandl | 2010-10-17 12:15:50 +0200 (So, 17 Okt 2010) | 1 line Make file names consistent. ........ r85620 | georg.brandl | 2010-10-17 12:22:28 +0200 (So, 17 Okt 2010) | 1 line Remove second parser module example; it referred to non-readily-available example files, and this kind of discovery is much better done with the AST nowadays anyway. ........ r85621 | georg.brandl | 2010-10-17 12:24:54 +0200 (So, 17 Okt 2010) | 1 line #9105: move pickle warning to a bit more prominent location. ........ r85622 | georg.brandl | 2010-10-17 12:28:04 +0200 (So, 17 Okt 2010) | 1 line #9112: document error() and exit() methods of ArgumentParser. ........ r85624 | georg.brandl | 2010-10-17 12:34:28 +0200 (So, 17 Okt 2010) | 1 line Some markup and style fixes in argparse docs. ........ r85626 | georg.brandl | 2010-10-17 12:38:20 +0200 (So, 17 Okt 2010) | 1 line #9117: fix syntax for class definition. ........ r85627 | georg.brandl | 2010-10-17 12:44:11 +0200 (So, 17 Okt 2010) | 1 line #9138: reword introduction to classes in Python. ........ r85629 | georg.brandl | 2010-10-17 12:51:45 +0200 (So, 17 Okt 2010) | 1 line #5962: clarify sys.exit() vs. threads. ........ r85631 | georg.brandl | 2010-10-17 12:53:54 +0200 (So, 17 Okt 2010) | 1 line Fix capitalization. ........ r85633 | georg.brandl | 2010-10-17 12:59:41 +0200 (So, 17 Okt 2010) | 1 line #9204: remove mentions of removed types in the types module. ........ r85635 | georg.brandl | 2010-10-17 13:03:22 +0200 (So, 17 Okt 2010) | 1 line #5121: fix claims about default values leading to segfaults. ........ r85636 | georg.brandl | 2010-10-17 13:06:14 +0200 (So, 17 Okt 2010) | 1 line #9237: document sys.call_tracing(). ........ r85638 | georg.brandl | 2010-10-17 13:13:37 +0200 (So, 17 Okt 2010) | 1 line Port changes to pickle docs apparently lost in py3k. ........ r85639 | georg.brandl | 2010-10-17 13:23:56 +0200 (So, 17 Okt 2010) | 1 line Make twisted example a bit more logical. ........ r85641 | georg.brandl | 2010-10-17 13:29:07 +0200 (So, 17 Okt 2010) | 1 line Fix documentation of dis.opmap direction. ........ r85642 | georg.brandl | 2010-10-17 13:36:28 +0200 (So, 17 Okt 2010) | 1 line #9730: fix example. ........
2010-11-26 04:49:15 -04:00
type. This is the same object as :class:`dict` in the Python layer.
2008-01-20 05:30:57 -04:00
.. cfunction:: int PyDict_Check(PyObject *p)
Return true if *p* is a dict object or an instance of a subtype of the dict
type.
.. cfunction:: int PyDict_CheckExact(PyObject *p)
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Return true if *p* is a dict object, but not an instance of a subtype of
the dict type.
2008-01-20 05:30:57 -04:00
.. cfunction:: PyObject* PyDict_New()
Return a new empty dictionary, or *NULL* on failure.
.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Return a proxy object for a mapping which enforces read-only behavior.
This is normally used to create a proxy to prevent modification of the
dictionary for non-dynamic class types.
2008-01-20 05:30:57 -04:00
.. cfunction:: void PyDict_Clear(PyObject *p)
Empty an existing dictionary of all key-value pairs.
.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Determine if dictionary *p* contains *key*. If an item in *p* is matches
*key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
This is equivalent to the Python expression ``key in p``.
2008-01-20 05:30:57 -04:00
.. cfunction:: PyObject* PyDict_Copy(PyObject *p)
Return a new dictionary that contains the same key-value pairs as *p*.
.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure.
2008-01-20 05:30:57 -04:00
.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyUnicode_FromString()
2008-01-20 05:30:57 -04:00
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :ctype:`char\*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure.
2008-01-20 05:30:57 -04:00
.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
on failure.
2008-01-20 05:30:57 -04:00
.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
Remove the entry in dictionary *p* which has a key specified by the string
*key*. Return ``0`` on success or ``-1`` on failure.
.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Return the object from dictionary *p* which has a key *key*. Return *NULL*
if the key *key* is not present, but *without* setting an exception.
2008-01-20 05:30:57 -04:00
2008-06-01 01:16:28 -03:00
.. cfunction:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
Variant of :cfunc:`PyDict_GetItem` that does not suppress
exceptions. Return *NULL* **with** an exception set if an exception
occurred. Return *NULL* **without** an exception set if the key
wasn't present.
2008-01-20 05:30:57 -04:00
2008-06-01 01:16:28 -03:00
2008-01-20 05:30:57 -04:00
.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a
:ctype:`char\*`, rather than a :ctype:`PyObject\*`.
.. cfunction:: PyObject* PyDict_Items(PyObject *p)
2010-11-04 04:24:55 -03:00
Return a :ctype:`PyListObject` containing all the items from the dictionary.
2008-01-20 05:30:57 -04:00
.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
2010-11-04 04:24:55 -03:00
Return a :ctype:`PyListObject` containing all the keys from the dictionary.
2008-01-20 05:30:57 -04:00
.. cfunction:: PyObject* PyDict_Values(PyObject *p)
2010-11-04 04:24:55 -03:00
Return a :ctype:`PyListObject` containing all the values from the dictionary
*p*.
2008-01-20 05:30:57 -04:00
.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)
.. index:: builtin: len
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Return the number of items in the dictionary. This is equivalent to
``len(p)`` on a dictionary.
2008-01-20 05:30:57 -04:00
.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Iterate over all key-value pairs in the dictionary *p*. The
:ctype:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either
point to :ctype:`PyObject\*` variables that will be filled in with each key
and value, respectively, or may be *NULL*. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
since the structure is sparse, the offsets are not consecutive.
2008-01-20 05:30:57 -04:00
For example::
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
/* do something interesting with the values... */
...
}
The dictionary *p* should not be mutated during iteration. It is safe to
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
modify the values of the keys as you iterate over the dictionary, but only
so long as the set of keys does not change. For example::
2008-01-20 05:30:57 -04:00
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
long i = PyLong_AsLong(value);
if (i == -1 && PyErr_Occurred()) {
return -1;
}
PyObject *o = PyLong_FromLong(i + 1);
if (o == NULL)
return -1;
if (PyDict_SetItem(self->dict, key, o) < 0) {
Py_DECREF(o);
return -1;
}
Py_DECREF(o);
}
.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
*b* may be a dictionary, or any object supporting :func:`PyMapping_Keys`
and :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
will be replaced if a matching key is found in *b*, otherwise pairs will
only be added if there is not a matching key in *a*. Return ``0`` on
success or ``-1`` if an exception was raised.
2008-01-20 05:30:57 -04:00
.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)
This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in
Python. Return ``0`` on success or ``-1`` if an exception was raised.
.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines The type for ppos has been Py_ssize_t since 2.5, reflect this in the documentation. ........ r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines Reformat paragraph. ........ r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines Issue #4129: Belatedly document which C API functions had their argument(s) or return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this might cause problems on 64-bit platforms. ........ r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines Issue #4129: Document more int -> Py_ssize_t changes. ........ r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........ r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines Reference to an int type, whereas it's a Py_ssize_t as the synopsis states. ........ r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines Since I edited this file, reformat for future edits. ........ r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines Reformat prior to editing. ........
2009-04-26 18:06:15 -03:00
Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
*seq2* must be an iterable object producing iterable objects of length 2,
viewed as key-value pairs. In case of duplicate keys, the last wins if
*override* is true, else the first wins. Return ``0`` on success or ``-1``
if an exception was raised. Equivalent Python (except for the return
value)::
2008-01-20 05:30:57 -04:00
def PyDict_MergeFromSeq2(a, seq2, override):
for key, value in seq2:
if override or key not in a:
a[key] = value