diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 663a1189..ad91fe68 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,18 +1,26 @@
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
- rev: v0.3.4
+ rev: v0.9.1
hooks:
- id: ruff
- name: Run Ruff on Lib/test/
+ name: Run Ruff (lint) on Doc/
+ args: [--exit-non-zero-on-fix]
+ files: ^Doc/
+ - id: ruff
+ name: Run Ruff (lint) on Lib/test/
args: [--exit-non-zero-on-fix]
files: ^Lib/test/
- id: ruff
- name: Run Ruff on Argument Clinic
+ name: Run Ruff (lint) on Argument Clinic
args: [--exit-non-zero-on-fix, --config=Tools/clinic/.ruff.toml]
files: ^Tools/clinic/|Lib/test/test_clinic.py
+ - id: ruff-format
+ name: Run Ruff (format) on Doc/
+ args: [--check]
+ files: ^Doc/
- repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v4.5.0
+ rev: v5.0.0
hooks:
- id: check-case-conflict
- id: check-merge-conflict
@@ -25,8 +33,13 @@ repos:
- id: trailing-whitespace
types_or: [c, inc, python, rst]
+ - repo: https://github.com/woodruffw/zizmor-pre-commit
+ rev: v1.1.1
+ hooks:
+ - id: zizmor
+
- repo: https://github.com/sphinx-contrib/sphinx-lint
- rev: v0.9.1
+ rev: v1.0.0
hooks:
- id: sphinx-lint
args: [--enable=default-role]
diff --git a/.readthedocs.yml b/.readthedocs.yml
index 898a9ae8..250d7ea0 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -8,11 +8,14 @@ sphinx:
configuration: Doc/conf.py
build:
- os: ubuntu-22.04
+ os: ubuntu-24.04
tools:
python: "3"
commands:
+ - asdf plugin add uv
+ - asdf install uv latest
+ - asdf global uv latest
- make -C Doc venv html
- mkdir _readthedocs
- mv Doc/build/html _readthedocs/html
diff --git a/Doc/.ruff.toml b/Doc/.ruff.toml
new file mode 100644
index 00000000..111ce03b
--- /dev/null
+++ b/Doc/.ruff.toml
@@ -0,0 +1,42 @@
+target-version = "py312" # Align with the version in oldest_supported_sphinx
+fix = true
+output-format = "full"
+line-length = 79
+extend-exclude = [
+ "includes/*",
+ # Temporary exclusions:
+ "tools/extensions/pyspecific.py",
+]
+
+[lint]
+preview = true
+select = [
+ "C4", # flake8-comprehensions
+ "B", # flake8-bugbear
+ "E", # pycodestyle
+ "F", # pyflakes
+ "FA", # flake8-future-annotations
+ "FLY", # flynt
+ "FURB", # refurb
+ "G", # flake8-logging-format
+ "I", # isort
+ "LOG", # flake8-logging
+ "N", # pep8-naming
+ "PERF", # perflint
+ "PGH", # pygrep-hooks
+ "PT", # flake8-pytest-style
+ "TCH", # flake8-type-checking
+ "UP", # pyupgrade
+ "W", # pycodestyle
+]
+ignore = [
+ "E501", # Ignore line length errors (we use auto-formatting)
+]
+
+[format]
+preview = true
+quote-style = "preserve"
+docstring-code-format = true
+exclude = [
+ "tools/extensions/lexers/*",
+]
diff --git a/Doc/Makefile b/Doc/Makefile
index 1cbfc722..b8896da4 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -6,6 +6,7 @@
# You can set these variables from the command line.
PYTHON = python3
VENVDIR = ./venv
+UV = uv
SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
BLURB = PATH=$(VENVDIR)/bin:$$PATH blurb
JOBS = auto
@@ -13,15 +14,15 @@ PAPER =
SOURCES =
DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py)
REQUIREMENTS = requirements.txt
-SPHINXERRORHANDLING = -W
+SPHINXERRORHANDLING = --fail-on-warning
# Internal variables.
-PAPEROPT_a4 = -D latex_elements.papersize=a4paper
-PAPEROPT_letter = -D latex_elements.papersize=letterpaper
+PAPEROPT_a4 = --define latex_elements.papersize=a4paper
+PAPEROPT_letter = --define latex_elements.papersize=letterpaper
-ALLSPHINXOPTS = -b $(BUILDER) \
- -d build/doctrees \
- -j $(JOBS) \
+ALLSPHINXOPTS = --builder $(BUILDER) \
+ --doctree-dir build/doctrees \
+ --jobs $(JOBS) \
$(PAPEROPT_$(PAPER)) \
$(SPHINXOPTS) $(SPHINXERRORHANDLING) \
. build/$(BUILDER) $(SOURCES)
@@ -143,21 +144,17 @@ pydoc-topics: build
.PHONY: gettext
gettext: BUILDER = gettext
-gettext: SPHINXOPTS += '-d build/doctrees-gettext'
+gettext: override SPHINXOPTS := --doctree-dir build/doctrees-gettext $(SPHINXOPTS)
gettext: build
.PHONY: htmlview
htmlview: html
$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
-.PHONY: ensure-sphinx-autobuild
-ensure-sphinx-autobuild: venv
- $(VENVDIR)/bin/sphinx-autobuild --version > /dev/null || $(VENVDIR)/bin/python3 -m pip install sphinx-autobuild
-
.PHONY: htmllive
-htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
+htmllive: SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-autobuild
htmllive: SPHINXOPTS = --re-ignore="/venv/" --open-browser --delay 0
-htmllive: ensure-sphinx-autobuild html
+htmllive: _ensure-sphinx-autobuild html
.PHONY: clean
clean: clean-venv
@@ -174,92 +171,149 @@ venv:
echo "To recreate it, remove it first with \`make clean-venv'."; \
else \
echo "Creating venv in $(VENVDIR)"; \
- $(PYTHON) -m venv $(VENVDIR); \
- $(VENVDIR)/bin/python3 -m pip install --upgrade pip; \
- $(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \
+ if $(UV) --version >/dev/null 2>&1; then \
+ $(UV) venv --python=$(PYTHON) $(VENVDIR); \
+ VIRTUAL_ENV=$(VENVDIR) $(UV) pip install -r $(REQUIREMENTS); \
+ else \
+ $(PYTHON) -m venv $(VENVDIR); \
+ $(VENVDIR)/bin/python3 -m pip install --upgrade pip; \
+ $(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \
+ fi; \
echo "The venv has been created in the $(VENVDIR) directory"; \
fi
+.PHONY: dist-no-html
+dist-no-html: dist-text dist-pdf dist-epub dist-texinfo
+
.PHONY: dist
dist:
rm -rf dist
mkdir -p dist
-
+ $(MAKE) dist-html
+ $(MAKE) dist-text
+ $(MAKE) dist-pdf
+ $(MAKE) dist-epub
+ $(MAKE) dist-texinfo
+
+.PHONY: dist-html
+dist-html:
# archive the HTML
- make html
+ @echo "Building HTML..."
+ mkdir -p dist
+ rm -rf build/html
+ find dist -name 'python-$(DISTVERSION)-docs-html*' -exec rm -rf {} \;
+ $(MAKE) html
cp -pPR build/html dist/python-$(DISTVERSION)-docs-html
tar -C dist -cf dist/python-$(DISTVERSION)-docs-html.tar python-$(DISTVERSION)-docs-html
bzip2 -9 -k dist/python-$(DISTVERSION)-docs-html.tar
(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-html.zip python-$(DISTVERSION)-docs-html)
rm -r dist/python-$(DISTVERSION)-docs-html
rm dist/python-$(DISTVERSION)-docs-html.tar
+ @echo "Build finished and archived!"
+.PHONY: dist-text
+dist-text:
# archive the text build
- make text
+ @echo "Building text..."
+ mkdir -p dist
+ rm -rf build/text
+ find dist -name 'python-$(DISTVERSION)-docs-text*' -exec rm -rf {} \;
+ $(MAKE) text
cp -pPR build/text dist/python-$(DISTVERSION)-docs-text
tar -C dist -cf dist/python-$(DISTVERSION)-docs-text.tar python-$(DISTVERSION)-docs-text
bzip2 -9 -k dist/python-$(DISTVERSION)-docs-text.tar
(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-text.zip python-$(DISTVERSION)-docs-text)
rm -r dist/python-$(DISTVERSION)-docs-text
rm dist/python-$(DISTVERSION)-docs-text.tar
+ @echo "Build finished and archived!"
+.PHONY: dist-pdf
+dist-pdf:
# archive the A4 latex
+ @echo "Building LaTeX (A4 paper)..."
+ mkdir -p dist
rm -rf build/latex
- make latex PAPER=a4
- -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
- (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
+ find dist -name 'python-$(DISTVERSION)-docs-pdf*' -exec rm -rf {} \;
+ $(MAKE) latex PAPER=a4
+ # remove zip & bz2 dependency on all-pdf,
+ # as otherwise the full latexmk process is run twice.
+ # ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
+ -sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
+ (cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`nproc`+1)) --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
+ @echo "Build finished and archived!"
- # archive the letter latex
- rm -rf build/latex
- make latex PAPER=letter
- -sed -i 's/makeindex/makeindex -q/' build/latex/Makefile
- (cd build/latex; make clean && make all-pdf && make FMT=pdf zip bz2)
- cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-letter.zip
- cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-letter.tar.bz2
-
+.PHONY: dist-epub
+dist-epub:
# copy the epub build
+ @echo "Building EPUB..."
+ mkdir -p dist
rm -rf build/epub
- make epub
+ rm -f dist/python-$(DISTVERSION)-docs.epub
+ $(MAKE) epub
cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub
+ @echo "Build finished and archived!"
+.PHONY: dist-texinfo
+dist-texinfo:
# archive the texinfo build
+ @echo "Building Texinfo..."
+ mkdir -p dist
rm -rf build/texinfo
- make texinfo
- make info --directory=build/texinfo
+ find dist -name 'python-$(DISTVERSION)-docs-texinfo*' -exec rm -rf {} \;
+ $(MAKE) texinfo
+ $(MAKE) info --directory=build/texinfo
cp -pPR build/texinfo dist/python-$(DISTVERSION)-docs-texinfo
tar -C dist -cf dist/python-$(DISTVERSION)-docs-texinfo.tar python-$(DISTVERSION)-docs-texinfo
bzip2 -9 -k dist/python-$(DISTVERSION)-docs-texinfo.tar
(cd dist; zip -q -r -9 python-$(DISTVERSION)-docs-texinfo.zip python-$(DISTVERSION)-docs-texinfo)
rm -r dist/python-$(DISTVERSION)-docs-texinfo
rm dist/python-$(DISTVERSION)-docs-texinfo.tar
+ @echo "Build finished and archived!"
+
+.PHONY: _ensure-package
+_ensure-package: venv
+ if $(UV) --version >/dev/null 2>&1; then \
+ VIRTUAL_ENV=$(VENVDIR) $(UV) pip install $(PACKAGE); \
+ else \
+ $(VENVDIR)/bin/python3 -m pip install $(PACKAGE); \
+ fi
+
+.PHONY: _ensure-pre-commit
+_ensure-pre-commit:
+ $(MAKE) _ensure-package PACKAGE=pre-commit
+
+.PHONY: _ensure-sphinx-autobuild
+_ensure-sphinx-autobuild:
+ $(MAKE) _ensure-package PACKAGE=sphinx-autobuild
.PHONY: check
-check: venv
- $(VENVDIR)/bin/python3 -m pre_commit --version > /dev/null || $(VENVDIR)/bin/python3 -m pip install pre-commit
+check: _ensure-pre-commit
$(VENVDIR)/bin/python3 -m pre_commit run --all-files
.PHONY: serve
serve:
- @echo "The serve target was removed, use htmlview instead (see bpo-36329)"
+ @echo "The serve target was removed, use htmllive instead (see gh-80510)"
# Targets for daily automated doc build
# By default, Sphinx only rebuilds pages where the page content has changed.
# This means it doesn't always pick up changes to preferred link targets, etc
# To ensure such changes are picked up, we build the published docs with
-# `-E` (to ignore the cached environment) and `-a` (to ignore already existing
-# output files)
+# ``--fresh-env`` (to ignore the cached environment) and ``--write-all``
+# (to ignore already existing output files)
# for development releases: always build
.PHONY: autobuild-dev
+autobuild-dev: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short)
autobuild-dev:
- make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+ $(MAKE) dist-no-html SPHINXOPTS='$(SPHINXOPTS) --fresh-env --write-all --html-define daily=1' DISTVERSION=$(DISTVERSION)
-# for quick rebuilds (HTML only)
+# for HTML-only rebuilds
.PHONY: autobuild-dev-html
+autobuild-dev-html: DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py --short)
autobuild-dev-html:
- make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+ $(MAKE) dist-html SPHINXOPTS='$(SPHINXOPTS) --fresh-env --write-all --html-define daily=1' DISTVERSION=$(DISTVERSION)
# for stable releases: only build if not in pre-release stage (alpha, beta)
# release candidate downloads are okay, since the stable tree can be in that stage
@@ -269,7 +323,7 @@ autobuild-stable:
echo "Not building; $(DISTVERSION) is not a release version."; \
exit 1;; \
esac
- @make autobuild-dev
+ @$(MAKE) autobuild-dev
.PHONY: autobuild-stable-html
autobuild-stable-html:
@@ -277,4 +331,4 @@ autobuild-stable-html:
echo "Not building; $(DISTVERSION) is not a release version."; \
exit 1;; \
esac
- @make autobuild-dev-html
+ @$(MAKE) autobuild-dev-html
diff --git a/Doc/README.rst b/Doc/README.rst
index a3bb5fa5..2d114875 100644
--- a/Doc/README.rst
+++ b/Doc/README.rst
@@ -28,7 +28,7 @@ install the tools into there.
Using make
----------
-To get started on UNIX, you can create a virtual environment and build
+To get started on Unix, you can create a virtual environment and build
documentation with the commands::
make venv
@@ -40,13 +40,13 @@ If you'd like to create the virtual environment in a different location,
you can specify it using the ``VENVDIR`` variable.
You can also skip creating the virtual environment altogether, in which case
-the Makefile will look for instances of ``sphinx-build`` and ``blurb``
+the ``Makefile`` will look for instances of ``sphinx-build`` and ``blurb``
installed on your process ``PATH`` (configurable with the ``SPHINXBUILD`` and
``BLURB`` variables).
-On Windows, we try to emulate the Makefile as closely as possible with a
+On Windows, we try to emulate the ``Makefile`` as closely as possible with a
``make.bat`` file. If you need to specify the Python interpreter to use,
-set the PYTHON environment variable.
+set the ``PYTHON`` environment variable.
Available make targets are:
@@ -62,15 +62,19 @@ Available make targets are:
* "htmlview", which re-uses the "html" builder, but then opens the main page
in your default web browser.
+* "htmllive", which re-uses the "html" builder, rebuilds the docs,
+ starts a local server, and automatically reloads the page in your browser
+ when you make changes to reST files (Unix only).
+
* "htmlhelp", which builds HTML files and a HTML Help project file usable to
convert them into a single Compiled HTML (.chm) file -- these are popular
under Microsoft Windows, but very handy on every platform.
To create the CHM file, you need to run the Microsoft HTML Help Workshop
- over the generated project (.hhp) file. The make.bat script does this for
+ over the generated project (.hhp) file. The ``make.bat`` script does this for
you on Windows.
-* "latex", which builds LaTeX source files as input to "pdflatex" to produce
+* "latex", which builds LaTeX source files as input to ``pdflatex`` to produce
PDF documents.
* "text", which builds a plain text file for each source file.
@@ -95,8 +99,6 @@ Available make targets are:
* "check", which checks for frequent markup errors.
-* "serve", which serves the build/html directory on port 8000.
-
* "dist", (Unix only) which creates distributable archives of HTML, text,
PDF, and EPUB builds.
@@ -131,8 +133,5 @@ Bugs in the content should be reported to the
Bugs in the toolset should be reported to the tools themselves.
-You can also send a mail to the Python Documentation Team at docs@python.org,
-and we will process your request as soon as possible.
-
-If you want to help the Documentation Team, you are always welcome. Just send
-a mail to docs@python.org.
+To help with the documentation, or report any problems, please leave a message
+on `discuss.python.org `_.
diff --git a/Doc/about.rst b/Doc/about.rst
index 5e6160ff..8f635d7f 100644
--- a/Doc/about.rst
+++ b/Doc/about.rst
@@ -1,10 +1,11 @@
-=====================
-About these documents
-=====================
+========================
+About this documentation
+========================
-These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
-document processor specifically written for the Python documentation.
+Python's documentation is generated from `reStructuredText`_ sources
+using `Sphinx`_, a documentation generator originally created for Python
+and now maintained as an independent project.
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Sphinx: https://www.sphinx-doc.org/
@@ -20,14 +21,14 @@ volunteers are always welcome!
Many thanks go to:
* Fred L. Drake, Jr., the creator of the original Python documentation toolset
- and writer of much of the content;
+ and author of much of the content;
* the `Docutils `_ project for creating
reStructuredText and the Docutils suite;
* Fredrik Lundh for his Alternative Python Reference project from which Sphinx
got many good ideas.
-Contributors to the Python Documentation
+Contributors to the Python documentation
----------------------------------------
Many people have contributed to the Python language, the Python standard
diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst
index b3609c23..0deb632f 100644
--- a/Doc/c-api/allocation.rst
+++ b/Doc/c-api/allocation.rst
@@ -15,10 +15,8 @@ Allocating Objects on the Heap
.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
Initialize a newly allocated object *op* with its type and initial
- reference. Returns the initialized object. If *type* indicates that the
- object participates in the cyclic garbage detector, it is added to the
- detector's set of observed objects. Other fields of the object are not
- affected.
+ reference. Returns the initialized object. Other fields of the object are
+ not affected.
.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
@@ -37,6 +35,10 @@ Allocating Objects on the Heap
The size of the memory allocation is determined from the
:c:member:`~PyTypeObject.tp_basicsize` field of the type object.
+ Note that this function is unsuitable if *typeobj* has
+ :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
+ use :c:func:`PyObject_GC_New` instead.
+
.. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
@@ -51,6 +53,10 @@ Allocating Objects on the Heap
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.
+ Note that this function is unsuitable if *typeobj* has
+ :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
+ use :c:func:`PyObject_GC_NewVar` instead.
+
.. c:function:: void PyObject_Del(void *op)
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 657b10d3..9d53d0e5 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -5,7 +5,7 @@
Parsing arguments and building values
=====================================
-These functions are useful when creating your own extensions functions and
+These functions are useful when creating your own extension functions and
methods. Additional information and examples are available in
:ref:`extending-index`.
@@ -229,12 +229,24 @@ There are three ways strings and buffers can be converted to C:
Numbers
-------
+These formats allow representing Python numbers or single characters as C numbers.
+Formats that require :class:`int`, :class:`float` or :class:`complex` can
+also use the corresponding special methods :meth:`~object.__index__`,
+:meth:`~object.__float__` or :meth:`~object.__complex__` to convert
+the Python object to the required type.
+
+For signed integer formats, :exc:`OverflowError` is raised if the value
+is out of range for the C type.
+For unsigned integer formats, no range checking is done --- the
+most significant bits are silently truncated when the receiving field is too
+small to receive the value.
+
``b`` (:class:`int`) [unsigned char]
- Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
+ Convert a nonnegative Python integer to an unsigned tiny integer, stored in a C
:c:expr:`unsigned char`.
``B`` (:class:`int`) [unsigned char]
- Convert a Python integer to a tiny int without overflow checking, stored in a C
+ Convert a Python integer to a tiny integer without overflow checking, stored in a C
:c:expr:`unsigned char`.
``h`` (:class:`int`) [short int]
@@ -280,10 +292,10 @@ Numbers
length 1, to a C :c:expr:`int`.
``f`` (:class:`float`) [float]
- Convert a Python floating point number to a C :c:expr:`float`.
+ Convert a Python floating-point number to a C :c:expr:`float`.
``d`` (:class:`float`) [double]
- Convert a Python floating point number to a C :c:expr:`double`.
+ Convert a Python floating-point number to a C :c:expr:`double`.
``D`` (:class:`complex`) [Py_complex]
Convert a Python complex number to a C :c:type:`Py_complex` structure.
@@ -307,7 +319,7 @@ Other objects
.. _o_ampersand:
-``O&`` (object) [*converter*, *anything*]
+``O&`` (object) [*converter*, *address*]
Convert a Python object to a C variable through a *converter* function. This
takes two arguments: the first is a function, the second is the address of a C
variable (of arbitrary type), converted to :c:expr:`void *`. The *converter*
@@ -321,14 +333,20 @@ Other objects
the conversion has failed. When the conversion fails, the *converter* function
should raise an exception and leave the content of *address* unmodified.
- If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a
+ .. c:macro:: Py_CLEANUP_SUPPORTED
+ :no-typesetting:
+
+ If the *converter* returns :c:macro:`!Py_CLEANUP_SUPPORTED`, it may get called a
second time if the argument parsing eventually fails, giving the converter a
chance to release any memory that it had already allocated. In this second
call, the *object* parameter will be ``NULL``; *address* will have the same value
as in the original call.
+ Examples of converters: :c:func:`PyUnicode_FSConverter` and
+ :c:func:`PyUnicode_FSDecoder`.
+
.. versionchanged:: 3.1
- ``Py_CLEANUP_SUPPORTED`` was added.
+ :c:macro:`!Py_CLEANUP_SUPPORTED` was added.
``p`` (:class:`bool`) [int]
Tests the value passed in for truth (a boolean **p**\ redicate) and converts
@@ -344,12 +362,6 @@ Other objects
in *items*. The C arguments must correspond to the individual format units in
*items*. Format units for sequences may be nested.
-It is possible to pass "long" integers (integers whose value exceeds the
-platform's :c:macro:`LONG_MAX`) however no proper range checking is done --- the
-most significant bits are silently truncated when the receiving field is too
-small to receive the value (actually, the semantics are inherited from downcasts
-in C --- your mileage may vary).
-
A few other characters have a meaning in a format string. These may not occur
inside nested parentheses. They are:
@@ -607,10 +619,10 @@ Building values
object of length 1.
``d`` (:class:`float`) [double]
- Convert a C :c:expr:`double` to a Python floating point number.
+ Convert a C :c:expr:`double` to a Python floating-point number.
``f`` (:class:`float`) [float]
- Convert a C :c:expr:`float` to a Python floating point number.
+ Convert a C :c:expr:`float` to a Python floating-point number.
``D`` (:class:`complex`) [Py_complex \*]
Convert a C :c:type:`Py_complex` structure to a Python complex number.
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
index 9500fe46..dc43a3d5 100644
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -244,7 +244,6 @@ The following fields are not influenced by *flags* and must always be filled in
with the correct values: :c:member:`~Py_buffer.obj`, :c:member:`~Py_buffer.buf`,
:c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`.
-
readonly, format
~~~~~~~~~~~~~~~~
@@ -253,7 +252,8 @@ readonly, format
Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
MUST provide a writable buffer or else report failure. Otherwise, the
exporter MAY provide either a read-only or writable buffer, but the choice
- MUST be consistent for all consumers.
+ MUST be consistent for all consumers. For example, :c:expr:`PyBUF_SIMPLE | PyBUF_WRITABLE`
+ can be used to request a simple writable buffer.
.. c:macro:: PyBUF_FORMAT
@@ -265,8 +265,9 @@ readonly, format
Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
can be used as a stand-alone flag to request a simple writable buffer.
-:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`.
-The latter already implies format ``B`` (unsigned bytes).
+:c:macro:`PyBUF_FORMAT` must be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`, because
+the latter already implies format ``B`` (unsigned bytes). :c:macro:`!PyBUF_FORMAT` cannot be
+used on its own.
shape, strides, suboffsets
diff --git a/Doc/c-api/bytearray.rst b/Doc/c-api/bytearray.rst
index 456f7d89..9045689a 100644
--- a/Doc/c-api/bytearray.rst
+++ b/Doc/c-api/bytearray.rst
@@ -42,17 +42,22 @@ Direct API functions
Return a new bytearray object from any object, *o*, that implements the
:ref:`buffer protocol `.
+ On failure, return ``NULL`` with an exception set.
+
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
- Create a new bytearray object from *string* and its length, *len*. On
- failure, ``NULL`` is returned.
+ Create a new bytearray object from *string* and its length, *len*.
+
+ On failure, return ``NULL`` with an exception set.
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
Concat bytearrays *a* and *b* and return a new bytearray with the result.
+ On failure, return ``NULL`` with an exception set.
+
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
diff --git a/Doc/c-api/cell.rst b/Doc/c-api/cell.rst
index f8cd0344..61eb994c 100644
--- a/Doc/c-api/cell.rst
+++ b/Doc/c-api/cell.rst
@@ -39,7 +39,8 @@ Cell objects are not likely to be useful elsewhere.
.. c:function:: PyObject* PyCell_Get(PyObject *cell)
- Return the contents of the cell *cell*.
+ Return the contents of the cell *cell*, which can be ``NULL``.
+ If *cell* is not a cell object, returns ``NULL`` with an exception set.
.. c:function:: PyObject* PyCell_GET(PyObject *cell)
@@ -52,8 +53,10 @@ Cell objects are not likely to be useful elsewhere.
Set the contents of the cell object *cell* to *value*. This releases the
reference to any current content of the cell. *value* may be ``NULL``. *cell*
- must be non-``NULL``; if it is not a cell object, ``-1`` will be returned. On
- success, ``0`` will be returned.
+ must be non-``NULL``.
+
+ On success, return ``0``.
+ If *cell* is not a cell object, set an exception and return ``-1``.
.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index f6fdd757..d7e89b73 100644
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -90,8 +90,8 @@ bound into a function.
Return the line number of the instruction that occurs on or before ``byte_offset`` and ends after it.
If you just need the line number of a frame, use :c:func:`PyFrame_GetLineNumber` instead.
- For efficiently iterating over the line numbers in a code object, use `the API described in PEP 626
- `_.
+ For efficiently iterating over the line numbers in a code object, use :pep:`the API described in PEP 626
+ <0626#out-of-process-debuggers-and-profilers>`.
.. c:function:: int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)
diff --git a/Doc/c-api/complex.rst b/Doc/c-api/complex.rst
index e3fd001c..77cb67d8 100644
--- a/Doc/c-api/complex.rst
+++ b/Doc/c-api/complex.rst
@@ -25,12 +25,16 @@ pointers. This is consistent throughout the API.
The C structure which corresponds to the value portion of a Python complex
number object. Most of the functions for dealing with complex number objects
- use structures of this type as input or output values, as appropriate. It is
- defined as::
+ use structures of this type as input or output values, as appropriate.
+
+ .. c:member:: double real
+ double imag
+
+ The structure is defined as::
typedef struct {
- double real;
- double imag;
+ double real;
+ double imag;
} Py_complex;
@@ -106,17 +110,22 @@ Complex Numbers as Python Objects
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
Create a new Python complex number object from a C :c:type:`Py_complex` value.
+ Return ``NULL`` with an exception set on error.
.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
+ Return ``NULL`` with an exception set on error.
.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
Return the real part of *op* as a C :c:expr:`double`.
+ Upon failure, this method returns ``-1.0`` with an exception set, so one
+ should call :c:func:`PyErr_Occurred` to check for errors.
+
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
@@ -131,8 +140,11 @@ Complex Numbers as Python Objects
method, this method will first be called to convert *op* to a Python complex
number object. If :meth:`!__complex__` is not defined then it falls back to
:meth:`~object.__float__`. If :meth:`!__float__` is not defined then it falls back
- to :meth:`~object.__index__`. Upon failure, this method returns ``-1.0`` as a real
- value.
+ to :meth:`~object.__index__`.
+
+ Upon failure, this method returns :c:type:`Py_complex`
+ with :c:member:`~Py_complex.real` set to ``-1.0`` and with an exception set, so one
+ should call :c:func:`PyErr_Occurred` to check for errors.
.. versionchanged:: 3.8
Use :meth:`~object.__index__` if available.
diff --git a/Doc/c-api/datetime.rst b/Doc/c-api/datetime.rst
index 97522da7..d2d4d530 100644
--- a/Doc/c-api/datetime.rst
+++ b/Doc/c-api/datetime.rst
@@ -318,10 +318,10 @@ Macros for the convenience of modules implementing the DB API:
.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
Create and return a new :class:`datetime.datetime` object given an argument
- tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp()`.
+ tuple suitable for passing to :meth:`datetime.datetime.fromtimestamp`.
.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
Create and return a new :class:`datetime.date` object given an argument
- tuple suitable for passing to :meth:`datetime.date.fromtimestamp()`.
+ tuple suitable for passing to :meth:`datetime.date.fromtimestamp`.
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 7ddecb24..e1fb8c89 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -34,7 +34,7 @@ propagated, additional calls into the Python/C API may not behave as intended
and may fail in mysterious ways.
.. note::
- The error indicator is **not** the result of :func:`sys.exc_info()`.
+ The error indicator is **not** the result of :func:`sys.exc_info`.
The former corresponds to an exception that is not yet caught (and is
therefore still propagating), while the latter returns an exception after
it is caught (and has therefore stopped propagating).
@@ -720,7 +720,7 @@ Exception Classes
This creates a class object derived from :exc:`Exception` (accessible in C as
:c:data:`PyExc_Exception`).
- The :attr:`!__module__` attribute of the new class is set to the first part (up
+ The :attr:`~type.__module__` attribute of the new class is set to the first part (up
to the last dot) of the *name* argument, and the class name is set to the last
part (after the last dot). The *base* argument can be used to specify alternate
base classes; it can either be only one class or a tuple of classes. The *dict*
diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index c4f53592..e9019a0d 100644
--- a/Doc/c-api/file.rst
+++ b/Doc/c-api/file.rst
@@ -65,9 +65,10 @@ the :mod:`io` APIs instead.
Overrides the normal behavior of :func:`io.open_code` to pass its parameter
through the provided handler.
- The handler is a function of type:
+ The *handler* is a function of type:
- .. c:type:: Py_OpenCodeHookFunction
+ .. c:namespace:: NULL
+ .. c:type:: PyObject * (*Py_OpenCodeHookFunction)(PyObject *, void *)
Equivalent of :c:expr:`PyObject *(\*)(PyObject *path,
void *userData)`, where *path* is guaranteed to be
diff --git a/Doc/c-api/float.rst b/Doc/c-api/float.rst
index 4f6ac0d8..1da37a5b 100644
--- a/Doc/c-api/float.rst
+++ b/Doc/c-api/float.rst
@@ -2,20 +2,20 @@
.. _floatobjects:
-Floating Point Objects
+Floating-Point Objects
======================
-.. index:: pair: object; floating point
+.. index:: pair: object; floating-point
.. c:type:: PyFloatObject
- This subtype of :c:type:`PyObject` represents a Python floating point object.
+ This subtype of :c:type:`PyObject` represents a Python floating-point object.
.. c:var:: PyTypeObject PyFloat_Type
- This instance of :c:type:`PyTypeObject` represents the Python floating point
+ This instance of :c:type:`PyTypeObject` represents the Python floating-point
type. This is the same object as :class:`float` in the Python layer.
@@ -45,7 +45,7 @@ Floating Point Objects
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
Return a C :c:expr:`double` representation of the contents of *pyfloat*. If
- *pyfloat* is not a Python floating point object but has a :meth:`~object.__float__`
+ *pyfloat* is not a Python floating-point object but has a :meth:`~object.__float__`
method, this method will first be called to convert *pyfloat* into a float.
If :meth:`!__float__` is not defined then it falls back to :meth:`~object.__index__`.
This method returns ``-1.0`` upon failure, so one should call
diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst
index e7fb5090..58792ede 100644
--- a/Doc/c-api/function.rst
+++ b/Doc/c-api/function.rst
@@ -145,12 +145,13 @@ There are a few functions specific to Python functions.
.. c:type:: PyFunction_WatchEvent
- Enumeration of possible function watcher events:
- - ``PyFunction_EVENT_CREATE``
- - ``PyFunction_EVENT_DESTROY``
- - ``PyFunction_EVENT_MODIFY_CODE``
- - ``PyFunction_EVENT_MODIFY_DEFAULTS``
- - ``PyFunction_EVENT_MODIFY_KWDEFAULTS``
+ Enumeration of possible function watcher events:
+
+ - ``PyFunction_EVENT_CREATE``
+ - ``PyFunction_EVENT_DESTROY``
+ - ``PyFunction_EVENT_MODIFY_CODE``
+ - ``PyFunction_EVENT_MODIFY_DEFAULTS``
+ - ``PyFunction_EVENT_MODIFY_KWDEFAULTS``
.. versionadded:: 3.12
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
index 380465b8..d6370bc9 100644
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -120,14 +120,14 @@ Importing Modules
such modules have no way to know that the module object is an unknown (and
probably damaged with respect to the module author's intents) state.
- The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
- not set already, with the appropriate values. The spec's loader will
- be set to the module's ``__loader__`` (if set) and to an instance of
- :class:`~importlib.machinery.SourceFileLoader` otherwise.
+ The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be
+ set, if not set already, with the appropriate values. The spec's loader
+ will be set to the module's :attr:`!__loader__` (if set) and to an instance
+ of :class:`~importlib.machinery.SourceFileLoader` otherwise.
- The module's :attr:`__file__` attribute will be set to the code object's
- :attr:`~codeobject.co_filename`. If applicable, :attr:`__cached__` will also
- be set.
+ The module's :attr:`~module.__file__` attribute will be set to the code
+ object's :attr:`~codeobject.co_filename`. If applicable,
+ :attr:`~module.__cached__` will also be set.
This function will reload the module if it was already imported. See
:c:func:`PyImport_ReloadModule` for the intended way to reload a module.
@@ -139,29 +139,29 @@ Importing Modules
:c:func:`PyImport_ExecCodeModuleWithPathnames`.
.. versionchanged:: 3.12
- The setting of :attr:`__cached__` and :attr:`__loader__` is
- deprecated. See :class:`~importlib.machinery.ModuleSpec` for
+ The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__`
+ is deprecated. See :class:`~importlib.machinery.ModuleSpec` for
alternatives.
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
- Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
- the module object is set to *pathname* if it is non-``NULL``.
+ Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__`
+ attribute of the module object is set to *pathname* if it is non-``NULL``.
See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
- Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
+ Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`~module.__cached__`
attribute of the module object is set to *cpathname* if it is
non-``NULL``. Of the three functions, this is the preferred one to use.
.. versionadded:: 3.3
.. versionchanged:: 3.12
- Setting :attr:`__cached__` is deprecated. See
+ Setting :attr:`~module.__cached__` is deprecated. See
:class:`~importlib.machinery.ModuleSpec` for alternatives.
@@ -174,7 +174,7 @@ Importing Modules
.. versionadded:: 3.2
.. versionchanged:: 3.3
- Uses :func:`!imp.source_from_cache()` in calculating the source path if
+ Uses :func:`!imp.source_from_cache` in calculating the source path if
only the bytecode path is provided.
.. versionchanged:: 3.12
No longer uses the removed :mod:`!imp` module.
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index a51f1da6..fcf3c10e 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -388,9 +388,16 @@ Initializing and finalizing the interpreter
:c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since
the last call to :c:func:`Py_Initialize`. Ideally, this frees all memory
allocated by the Python interpreter. This is a no-op when called for a second
- time (without calling :c:func:`Py_Initialize` again first). Normally the
- return value is ``0``. If there were errors during finalization
- (flushing buffered data), ``-1`` is returned.
+ time (without calling :c:func:`Py_Initialize` again first).
+
+ Since this is the reverse of :c:func:`Py_Initialize`, it should be called
+ in the same thread with the same interpreter active. That means
+ the main thread and the main interpreter.
+ This should never be called while :c:func:`Py_RunMain` is running.
+
+ Normally the return value is ``0``.
+ If there were errors during finalization (flushing buffered data),
+ ``-1`` is returned.
This function is provided for a number of reasons. An embedding application
might want to restart Python without having to restart the application itself.
@@ -485,7 +492,7 @@ Process-wide parameters
interpreter will change the contents of this storage.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_t *` string.
+ :c:expr:`wchar_t*` string.
.. deprecated:: 3.11
@@ -751,7 +758,7 @@ Process-wide parameters
directory (``"."``).
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_*` string.
+ :c:expr:`wchar_t*` string.
See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
members of the :ref:`Python Initialization Configuration `.
@@ -787,7 +794,7 @@ Process-wide parameters
:option:`-I`.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_*` string.
+ :c:expr:`wchar_t*` string.
See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
members of the :ref:`Python Initialization Configuration `.
@@ -813,7 +820,7 @@ Process-wide parameters
this storage.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
- :c:expr:`wchar_*` string.
+ :c:expr:`wchar_t*` string.
.. deprecated:: 3.11
@@ -1262,7 +1269,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyThreadState_DeleteCurrent(void)
Destroy the current thread state and release the global interpreter lock.
- Like :c:func:`PyThreadState_Delete`, the global interpreter lock need not
+ Like :c:func:`PyThreadState_Delete`, the global interpreter lock must
be held. The thread state must have been reset with a previous call
to :c:func:`PyThreadState_Clear`.
@@ -1637,7 +1644,11 @@ function. You can create and destroy them using the following functions:
.check_multi_interp_extensions = 1,
.gil = PyInterpreterConfig_OWN_GIL,
};
- PyThreadState *tstate = Py_NewInterpreterFromConfig(&config);
+ PyThreadState *tstate = NULL;
+ PyStatus status = Py_NewInterpreterFromConfig(&tstate, &config);
+ if (PyStatus_Exception(status)) {
+ Py_ExitStatusException(status);
+ }
Note that the config is used only briefly and does not get modified.
During initialization the config's values are converted into various
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index 7c5465b5..c586cfb3 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -311,7 +311,7 @@ PyPreConfig
* Set :c:member:`PyConfig.filesystem_encoding` to ``"mbcs"``,
* Set :c:member:`PyConfig.filesystem_errors` to ``"replace"``.
- Initialized the from :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
+ Initialized from the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
variable value.
Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for
@@ -499,7 +499,7 @@ PyConfig
The :c:func:`PyConfig_Read` function only parses
:c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
is set to ``2`` after arguments are parsed. Since Python arguments are
- strippped from :c:member:`PyConfig.argv`, parsing arguments twice would
+ stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
parse the application options as Python options.
:ref:`Preinitialize Python ` if needed.
@@ -1000,7 +1000,7 @@ PyConfig
The :c:func:`PyConfig_Read` function only parses
:c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
is set to ``2`` after arguments are parsed. Since Python arguments are
- strippped from :c:member:`PyConfig.argv`, parsing arguments twice would
+ stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
parse the application options as Python options.
Default: ``1`` in Python mode, ``0`` in isolated mode.
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 76ac8032..6e1cd1ec 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -135,6 +135,16 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
.. versionchanged:: 3.10
This function will no longer use :meth:`~object.__int__`.
+ .. c:namespace:: NULL
+
+ .. c:function:: long PyLong_AS_LONG(PyObject *obj)
+
+ A :term:`soft deprecated` alias.
+ Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
+ it can fail with :exc:`OverflowError` or another exception.
+
+ .. deprecated:: 3.14
+ The function is soft deprecated.
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
@@ -324,6 +334,17 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.
+.. c:function:: PyObject* PyLong_GetInfo(void)
+
+ On success, return a read only :term:`named tuple`, that holds
+ information about Python's internal representation of integers.
+ See :data:`sys.int_info` for description of individual fields.
+
+ On failure, return ``NULL`` with an exception set.
+
+ .. versionadded:: 3.1
+
+
.. c:function:: int PyUnstable_Long_IsCompact(const PyLongObject* op)
Return 1 if *op* is compact, 0 otherwise.
@@ -339,6 +360,9 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
Exactly what values are considered compact is an implementation detail
and is subject to change.
+ .. versionadded:: 3.12
+
+
.. c:function:: Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject* op)
If *op* is compact, as determined by :c:func:`PyUnstable_Long_IsCompact`,
@@ -346,3 +370,5 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
Otherwise, the return value is undefined.
+ .. versionadded:: 3.12
+
diff --git a/Doc/c-api/marshal.rst b/Doc/c-api/marshal.rst
index 489f1580..b9085ad3 100644
--- a/Doc/c-api/marshal.rst
+++ b/Doc/c-api/marshal.rst
@@ -15,7 +15,7 @@ Numeric values are stored with the least significant byte first.
The module supports two versions of the data format: version 0 is the
historical version, version 1 shares interned strings in the file, and upon
-unmarshalling. Version 2 uses a binary format for floating point numbers.
+unmarshalling. Version 2 uses a binary format for floating-point numbers.
``Py_MARSHAL_VERSION`` indicates the current file format (currently 2).
diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index f941f0c7..2afa760b 100644
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -37,16 +37,19 @@ Module Objects
single: __package__ (module attribute)
single: __loader__ (module attribute)
- Return a new module object with the :attr:`__name__` attribute set to *name*.
- The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
- :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
- to ``None``); the caller is responsible for providing a :attr:`__file__`
- attribute.
+ Return a new module object with :attr:`module.__name__` set to *name*.
+ The module's :attr:`!__name__`, :attr:`~module.__doc__`,
+ :attr:`~module.__package__` and :attr:`~module.__loader__` attributes are
+ filled in (all but :attr:`!__name__` are set to ``None``). The caller is
+ responsible for setting a :attr:`~module.__file__` attribute.
+
+ Return ``NULL`` with an exception set on error.
.. versionadded:: 3.3
.. versionchanged:: 3.4
- :attr:`__package__` and :attr:`__loader__` are set to ``None``.
+ :attr:`~module.__package__` and :attr:`~module.__loader__` are now set to
+ ``None``.
.. c:function:: PyObject* PyModule_New(const char *name)
@@ -75,8 +78,9 @@ Module Objects
single: __name__ (module attribute)
single: SystemError (built-in exception)
- Return *module*'s :attr:`__name__` value. If the module does not provide one,
- or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is returned.
+ Return *module*'s :attr:`~module.__name__` value. If the module does not
+ provide one, or if it is not a string, :exc:`SystemError` is raised and
+ ``NULL`` is returned.
.. versionadded:: 3.3
@@ -106,8 +110,8 @@ Module Objects
single: SystemError (built-in exception)
Return the name of the file from which *module* was loaded using *module*'s
- :attr:`__file__` attribute. If this is not defined, or if it is not a
- unicode string, raise :exc:`SystemError` and return ``NULL``; otherwise return
+ :attr:`~module.__file__` attribute. If this is not defined, or if it is not a
+ string, raise :exc:`SystemError` and return ``NULL``; otherwise return
a reference to a Unicode object.
.. versionadded:: 3.2
@@ -265,6 +269,8 @@ of the following two module creation functions:
API version *module_api_version*. If that version does not match the version
of the running interpreter, a :exc:`RuntimeWarning` is emitted.
+ Return ``NULL`` with an exception set on error.
+
.. note::
Most uses of this function should be using :c:func:`PyModule_Create`
@@ -338,7 +344,8 @@ The available slot types are:
The *value* pointer of this slot must point to a function of the signature:
.. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
- :noindex:
+ :no-index-entry:
+ :no-contents-entry:
The function receives a :py:class:`~importlib.machinery.ModuleSpec`
instance, as defined in :PEP:`451`, and the module definition.
@@ -373,7 +380,8 @@ The available slot types are:
The signature of the function is:
.. c:function:: int exec_module(PyObject* module)
- :noindex:
+ :no-index-entry:
+ :no-contents-entry:
If multiple ``Py_mod_exec`` slots are specified, they are processed in the
order they appear in the *m_slots* array.
@@ -407,7 +415,7 @@ The available slot types are:
in one module definition.
If ``Py_mod_multiple_interpreters`` is not specified, the import
- machinery defaults to ``Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED``.
+ machinery defaults to ``Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED``.
.. versionadded:: 3.12
@@ -436,6 +444,8 @@ objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
If that version does not match the version of the running interpreter,
a :exc:`RuntimeWarning` is emitted.
+ Return ``NULL`` with an exception set on error.
+
.. note::
Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec`
@@ -486,9 +496,6 @@ state:
On success, return ``0``. On error, raise an exception and return ``-1``.
- Return ``NULL`` if *value* is ``NULL``. It must be called with an exception
- raised in this case.
-
Example usage::
static int
@@ -503,6 +510,10 @@ state:
return res;
}
+ To be convenient, the function accepts ``NULL`` *value* with an exception
+ set. In this case, return ``-1`` and just leave the raised exception
+ unchanged.
+
The example can also be written without checking explicitly if *obj* is
``NULL``::
@@ -518,6 +529,14 @@ state:
Note that ``Py_XDECREF()`` should be used instead of ``Py_DECREF()`` in
this case, since *obj* can be ``NULL``.
+ The number of different *name* strings passed to this function
+ should be kept small, usually by only using statically allocated strings
+ as *name*.
+ For names that aren't known at compile time, prefer calling
+ :c:func:`PyUnicode_FromString` and :c:func:`PyObject_SetAttr` directly.
+ For more details, see :c:func:`PyUnicode_InternFromString`, which may be
+ used internally to create a key object.
+
.. versionadded:: 3.10
@@ -579,15 +598,23 @@ state:
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
Add an integer constant to *module* as *name*. This convenience function can be
- used from the module's initialization function. Return ``-1`` on error, ``0`` on
- success.
+ used from the module's initialization function.
+ Return ``-1`` with an exception set on error, ``0`` on success.
+
+ This is a convenience function that calls :c:func:`PyLong_FromLong` and
+ :c:func:`PyModule_AddObjectRef`; see their documentation for details.
.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
Add a string constant to *module* as *name*. This convenience function can be
used from the module's initialization function. The string *value* must be
- ``NULL``-terminated. Return ``-1`` on error, ``0`` on success.
+ ``NULL``-terminated.
+ Return ``-1`` with an exception set on error, ``0`` on success.
+
+ This is a convenience function that calls
+ :c:func:`PyUnicode_InternFromString` and :c:func:`PyModule_AddObjectRef`;
+ see their documentation for details.
.. c:macro:: PyModule_AddIntMacro(module, macro)
@@ -595,7 +622,7 @@ state:
Add an int constant to *module*. The name and the value are taken from
*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
constant *AF_INET* with the value of *AF_INET* to *module*.
- Return ``-1`` on error, ``0`` on success.
+ Return ``-1`` with an exception set on error, ``0`` on success.
.. c:macro:: PyModule_AddStringMacro(module, macro)
@@ -608,7 +635,7 @@ state:
The type object is finalized by calling internally :c:func:`PyType_Ready`.
The name of the type object is taken from the last component of
:c:member:`~PyTypeObject.tp_name` after dot.
- Return ``-1`` on error, ``0`` on success.
+ Return ``-1`` with an exception set on error, ``0`` on success.
.. versionadded:: 3.9
@@ -647,14 +674,14 @@ since multiple such modules can be created from a single definition.
The caller must hold the GIL.
- Return 0 on success or -1 on failure.
+ Return ``-1`` with an exception set on error, ``0`` on success.
.. versionadded:: 3.3
.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
Removes the module object created from *def* from the interpreter state.
- Return 0 on success or -1 on failure.
+ Return ``-1`` with an exception set on error, ``0`` on success.
The caller must hold the GIL.
diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst
index 13d3c5af..ad8b5935 100644
--- a/Doc/c-api/number.rst
+++ b/Doc/c-api/number.rst
@@ -51,8 +51,8 @@ Number Protocol
Return a reasonable approximation for the mathematical value of *o1* divided by
*o2*, or ``NULL`` on failure. The return value is "approximate" because binary
- floating point numbers are approximate; it is not possible to represent all real
- numbers in base two. This function can return a floating point value when
+ floating-point numbers are approximate; it is not possible to represent all real
+ numbers in base two. This function can return a floating-point value when
passed two integers. This is the equivalent of the Python expression ``o1 / o2``.
@@ -177,8 +177,8 @@ Number Protocol
Return a reasonable approximation for the mathematical value of *o1* divided by
*o2*, or ``NULL`` on failure. The return value is "approximate" because binary
- floating point numbers are approximate; it is not possible to represent all real
- numbers in base two. This function can return a floating point value when
+ floating-point numbers are approximate; it is not possible to represent all real
+ numbers in base two. This function can return a floating-point value when
passed two integers. The operation is done *in-place* when *o1* supports it.
This is the equivalent of the Python statement ``o1 /= o2``.
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 3cb65400..b7f1a549 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -107,6 +107,13 @@ Object Protocol
If *v* is ``NULL``, the attribute is deleted, but this feature is
deprecated in favour of using :c:func:`PyObject_DelAttrString`.
+ The number of different attribute names passed to this function
+ should be kept small, usually by using a statically allocated string
+ as *attr_name*.
+ For attribute names that aren't known at compile time, prefer calling
+ :c:func:`PyUnicode_FromString` and :c:func:`PyObject_SetAttr` directly.
+ For more details, see :c:func:`PyUnicode_InternFromString`, which may be
+ used internally to create a key object.
.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
@@ -132,6 +139,14 @@ Object Protocol
specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
rather than a :c:expr:`PyObject*`.
+ The number of different attribute names passed to this function
+ should be kept small, usually by using a statically allocated string
+ as *attr_name*.
+ For attribute names that aren't known at compile time, prefer calling
+ :c:func:`PyUnicode_FromString` and :c:func:`PyObject_DelAttr` directly.
+ For more details, see :c:func:`PyUnicode_InternFromString`, which may be
+ used internally to create a key object for lookup.
+
.. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context)
@@ -253,14 +268,14 @@ Object Protocol
The result will be ``1`` when at least one of the checks returns ``1``,
otherwise it will be ``0``.
- If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to
+ If *cls* has a :meth:`~type.__subclasscheck__` method, it will be called to
determine the subclass status as described in :pep:`3119`. Otherwise,
*derived* is a subclass of *cls* if it is a direct or indirect subclass,
- i.e. contained in ``cls.__mro__``.
+ i.e. contained in :attr:`cls.__mro__ `.
Normally only class objects, i.e. instances of :class:`type` or a derived
class, are considered classes. However, objects can override this by having
- a :attr:`~class.__bases__` attribute (which must be a tuple of base classes).
+ a :attr:`~type.__bases__` attribute (which must be a tuple of base classes).
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
@@ -272,15 +287,15 @@ Object Protocol
The result will be ``1`` when at least one of the checks returns ``1``,
otherwise it will be ``0``.
- If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to
+ If *cls* has a :meth:`~type.__instancecheck__` method, it will be called to
determine the subclass status as described in :pep:`3119`. Otherwise, *inst*
is an instance of *cls* if its class is a subclass of *cls*.
An instance *inst* can override what is considered its class by having a
- :attr:`~instance.__class__` attribute.
+ :attr:`~object.__class__` attribute.
An object *cls* can override if it is considered a class, and what its base
- classes are, by having a :attr:`~class.__bases__` attribute (which must be a tuple
+ classes are, by having a :attr:`~type.__bases__` attribute (which must be a tuple
of base classes).
@@ -378,6 +393,13 @@ Object Protocol
on failure. This is equivalent to the Python statement ``del o[key]``.
+.. c:function:: int PyObject_DelItemString(PyObject *o, const char *key)
+
+ This is the same as :c:func:`PyObject_DelItem`, but *key* is
+ specified as a :c:expr:`const char*` UTF-8 encoded bytes string,
+ rather than a :c:expr:`PyObject*`.
+
+
.. c:function:: PyObject* PyObject_Dir(PyObject *o)
This is equivalent to the Python expression ``dir(o)``, returning a (possibly
@@ -395,6 +417,12 @@ Object Protocol
iterated.
+.. c:function:: PyObject* PyObject_SelfIter(PyObject *obj)
+
+ This is equivalent to the Python ``__iter__(self): return self`` method.
+ It is intended for :term:`iterator` types, to be used in the :c:member:`PyTypeObject.tp_iter` slot.
+
+
.. c:function:: PyObject* PyObject_GetAIter(PyObject *o)
This is the equivalent to the Python expression ``aiter(o)``. Takes an
diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst
index a484fa44..158aa737 100644
--- a/Doc/c-api/refcounting.rst
+++ b/Doc/c-api/refcounting.rst
@@ -59,7 +59,7 @@ of Python objects.
``NULL``, use :c:func:`Py_XINCREF`.
Do not expect this function to actually modify *o* in any way.
- For at least `some objects `_,
+ For at least :pep:`some objects <0683>`,
this function has no effect.
.. versionchanged:: 3.12
@@ -125,7 +125,7 @@ of Python objects.
use :c:func:`Py_XDECREF`.
Do not expect this function to actually modify *o* in any way.
- For at least `some objects `_,
+ For at least :pep:`some objects <683>`,
this function has no effect.
.. warning::
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index 9e880c6b..76445045 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -23,7 +23,9 @@ Slice Objects
Return a new slice object with the given values. The *start*, *stop*, and
*step* parameters are used as the values of the slice object attributes of
the same names. Any of the values may be ``NULL``, in which case the
- ``None`` will be used for the corresponding attribute. Return ``NULL`` if
+ ``None`` will be used for the corresponding attribute.
+
+ Return ``NULL`` with an exception set if
the new object could not be allocated.
@@ -52,7 +54,7 @@ Slice Objects
of bounds indices are clipped in a manner consistent with the handling of
normal slices.
- Returns ``0`` on success and ``-1`` on error with exception set.
+ Return ``0`` on success and ``-1`` on error with an exception set.
.. note::
This function is considered not safe for resizable sequences.
@@ -95,7 +97,7 @@ Slice Objects
``PY_SSIZE_T_MIN`` to ``PY_SSIZE_T_MIN``, and silently boost the step
values less than ``-PY_SSIZE_T_MAX`` to ``-PY_SSIZE_T_MAX``.
- Return ``-1`` on error, ``0`` on success.
+ Return ``-1`` with an exception set on error, ``0`` on success.
.. versionadded:: 3.6.1
@@ -116,6 +118,12 @@ Ellipsis Object
^^^^^^^^^^^^^^^
+.. c:var:: PyTypeObject PyEllipsis_Type
+
+ The type of Python :const:`Ellipsis` object. Same as :class:`types.EllipsisType`
+ in the Python layer.
+
+
.. c:var:: PyObject *Py_Ellipsis
The Python ``Ellipsis`` object. This object has no methods. Like
diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
index 5b9e4387..124e58cf 100644
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -66,7 +66,7 @@ Limited C API
Python 3.2 introduced the *Limited API*, a subset of Python's C API.
Extensions that only use the Limited API can be
-compiled once and work with multiple versions of Python.
+compiled once and be loaded on multiple versions of Python.
Contents of the Limited API are :ref:`listed below `.
.. c:macro:: Py_LIMITED_API
@@ -76,7 +76,7 @@ Contents of the Limited API are :ref:`listed below `.
Define ``Py_LIMITED_API`` to the value of :c:macro:`PY_VERSION_HEX`
corresponding to the lowest Python version your extension supports.
- The extension will work without recompilation with all Python 3 releases
+ The extension will be ABI-compatible with all Python 3 releases
from the specified one onward, and can use Limited API introduced up to that
version.
@@ -94,7 +94,15 @@ Stable ABI
----------
To enable this, Python provides a *Stable ABI*: a set of symbols that will
-remain compatible across Python 3.x versions.
+remain ABI-compatible across Python 3.x versions.
+
+.. note::
+
+ The Stable ABI prevents ABI issues, like linker errors due to missing
+ symbols or data corruption due to changes in structure layouts or function
+ signatures.
+ However, other changes in Python can change the *behavior* of extensions.
+ See Python's Backwards Compatibility Policy (:pep:`387`) for details.
The Stable ABI contains symbols exposed in the :ref:`Limited API
`, but also other ones – for example, functions necessary to
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index 36a0abce..56ef8460 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -63,6 +63,11 @@ under :ref:`reference counting `.
See documentation of :c:type:`PyVarObject` above.
+.. c:var:: PyTypeObject PyBaseObject_Type
+
+ The base class of all other objects, the same as :class:`object` in Python.
+
+
.. c:function:: int Py_Is(PyObject *x, PyObject *y)
Test if the *x* object is the *y* object, the same as ``x is y`` in Python.
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index e0186c1f..e20c5a66 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -33,12 +33,14 @@ Tuple Objects
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
- Return a new tuple object of size *len*, or ``NULL`` on failure.
+ Return a new tuple object of size *len*,
+ or ``NULL`` with an exception set on failure.
.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
- Return a new tuple object of size *n*, or ``NULL`` on failure. The tuple values
+ Return a new tuple object of size *n*,
+ or ``NULL`` with an exception set on failure. The tuple values
are initialized to the subsequent *n* C arguments pointing to Python objects.
``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
@@ -46,12 +48,12 @@ Tuple Objects
.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
Take a pointer to a tuple object, and return the size of that tuple.
+ On error, return ``-1`` and with an exception set.
.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
- Return the size of the tuple *p*, which must be non-``NULL`` and point to a tuple;
- no error checking is performed.
+ Like :c:func:`PyTuple_Size`, but without error checking.
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
@@ -74,8 +76,10 @@ Tuple Objects
.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
Return the slice of the tuple pointed to by *p* between *low* and *high*,
- or ``NULL`` on failure. This is the equivalent of the Python expression
- ``p[low:high]``. Indexing from the end of the tuple is not supported.
+ or ``NULL`` with an exception set on failure.
+
+ This is the equivalent of the Python expression ``p[low:high]``.
+ Indexing from the end of the tuple is not supported.
.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
@@ -132,6 +136,8 @@ type.
Create a new struct sequence type from the data in *desc*, described below. Instances
of the resulting type can be created with :c:func:`PyStructSequence_New`.
+ Return ``NULL`` with an exception set on failure.
+
.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
@@ -140,8 +146,8 @@ type.
.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
- The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
- failure.
+ Like :c:func:`PyStructSequence_InitType`, but returns ``0`` on success
+ and ``-1`` with an exception set on failure.
.. versionadded:: 3.4
@@ -152,7 +158,8 @@ type.
.. c:member:: const char *name
- Name of the struct sequence type.
+ Fully qualified name of the type; null-terminated UTF-8 encoded.
+ The name must contain the module name.
.. c:member:: const char *doc
@@ -198,6 +205,8 @@ type.
Creates an instance of *type*, which must have been created with
:c:func:`PyStructSequence_NewType`.
+ Return ``NULL`` with an exception set on failure.
+
.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index 5aaa8147..241450a7 100644
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -53,7 +53,8 @@ Type Objects
.. c:function:: PyObject* PyType_GetDict(PyTypeObject* type)
Return the type object's internal namespace, which is otherwise only
- exposed via a read-only proxy (``cls.__dict__``). This is a
+ exposed via a read-only proxy (:attr:`cls.__dict__ `).
+ This is a
replacement for accessing :c:member:`~PyTypeObject.tp_dict` directly.
The returned dictionary must be treated as read-only.
@@ -140,7 +141,7 @@ Type Objects
Return true if *a* is a subtype of *b*.
This function only checks for actual subtypes, which means that
- :meth:`~class.__subclasscheck__` is not called on *b*. Call
+ :meth:`~type.__subclasscheck__` is not called on *b*. Call
:c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
would do.
@@ -174,14 +175,15 @@ Type Objects
.. c:function:: PyObject* PyType_GetName(PyTypeObject *type)
- Return the type's name. Equivalent to getting the type's ``__name__`` attribute.
+ Return the type's name. Equivalent to getting the type's
+ :attr:`~type.__name__` attribute.
.. versionadded:: 3.11
.. c:function:: PyObject* PyType_GetQualName(PyTypeObject *type)
Return the type's qualified name. Equivalent to getting the
- type's ``__qualname__`` attribute.
+ type's :attr:`~type.__qualname__` attribute.
.. versionadded:: 3.11
@@ -395,6 +397,9 @@ The following functions and structs are used to create
class need *in addition* to the superclass.
Use :c:func:`PyObject_GetTypeData` to get a pointer to subclass-specific
memory reserved this way.
+ For negative :c:member:`!basicsize`, Python will insert padding when
+ needed to meet :c:member:`~PyTypeObject.tp_basicsize`'s alignment
+ requirements.
.. versionchanged:: 3.12
@@ -463,19 +468,19 @@ The following functions and structs are used to create
The following “offset” fields cannot be set using :c:type:`PyType_Slot`:
- * :c:member:`~PyTypeObject.tp_weaklistoffset`
- (use :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead if possible)
- * :c:member:`~PyTypeObject.tp_dictoffset`
- (use :c:macro:`Py_TPFLAGS_MANAGED_DICT` instead if possible)
- * :c:member:`~PyTypeObject.tp_vectorcall_offset`
- (use ``"__vectorcalloffset__"`` in
- :ref:`PyMemberDef `)
+ * :c:member:`~PyTypeObject.tp_weaklistoffset`
+ (use :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead if possible)
+ * :c:member:`~PyTypeObject.tp_dictoffset`
+ (use :c:macro:`Py_TPFLAGS_MANAGED_DICT` instead if possible)
+ * :c:member:`~PyTypeObject.tp_vectorcall_offset`
+ (use ``"__vectorcalloffset__"`` in
+ :ref:`PyMemberDef `)
- If it is not possible to switch to a ``MANAGED`` flag (for example,
- for vectorcall or to support Python older than 3.12), specify the
- offset in :c:member:`Py_tp_members `.
- See :ref:`PyMemberDef documentation `
- for details.
+ If it is not possible to switch to a ``MANAGED`` flag (for example,
+ for vectorcall or to support Python older than 3.12), specify the
+ offset in :c:member:`Py_tp_members `.
+ See :ref:`PyMemberDef documentation `
+ for details.
The following fields cannot be set at all when creating a heap type:
@@ -495,14 +500,13 @@ The following functions and structs are used to create
To avoid issues, use the *bases* argument of
:c:func:`PyType_FromSpecWithBases` instead.
- .. versionchanged:: 3.9
+ .. versionchanged:: 3.9
+ Slots in :c:type:`PyBufferProcs` may be set in the unlimited API.
- Slots in :c:type:`PyBufferProcs` may be set in the unlimited API.
-
- .. versionchanged:: 3.11
- :c:member:`~PyBufferProcs.bf_getbuffer` and
- :c:member:`~PyBufferProcs.bf_releasebuffer` are now available
- under the :ref:`limited API `.
+ .. versionchanged:: 3.11
+ :c:member:`~PyBufferProcs.bf_getbuffer` and
+ :c:member:`~PyBufferProcs.bf_releasebuffer` are now available
+ under the :ref:`limited API `.
.. c:member:: void *pfunc
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index f6d865f2..5bb8f3d5 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -2,8 +2,8 @@
.. _type-structs:
-Type Objects
-============
+Type Object Structures
+======================
Perhaps one of the most important structures of the Python object system is the
structure that defines a new type: the :c:type:`PyTypeObject` structure. Type
@@ -355,7 +355,7 @@ slot typedefs
+-----------------------------+-----------------------------+----------------------+
| :c:type:`newfunc` | .. line-block:: | :c:type:`PyObject` * |
| | | |
-| | :c:type:`PyObject` * | |
+| | :c:type:`PyTypeObject` * | |
| | :c:type:`PyObject` * | |
| | :c:type:`PyObject` * | |
+-----------------------------+-----------------------------+----------------------+
@@ -473,7 +473,7 @@ PyTypeObject Definition
-----------------------
The structure definition for :c:type:`PyTypeObject` can be found in
-:file:`Include/object.h`. For convenience of reference, this repeats the
+:file:`Include/cpython/object.h`. For convenience of reference, this repeats the
definition found there:
.. XXX Drop this?
@@ -559,6 +559,9 @@ PyVarObject Slots
initialized to zero. For :ref:`dynamically allocated type objects
`, this field has a special internal meaning.
+ This field should be accessed using the :c:func:`Py_SIZE()` and
+ :c:func:`Py_SET_SIZE()` macros.
+
**Inheritance:**
This field is not inherited by subtypes.
@@ -589,12 +592,12 @@ and :c:data:`PyType_Type` effectively act as defaults.)
For :ref:`statically allocated type objects `,
the *tp_name* field should contain a dot.
- Everything before the last dot is made accessible as the :attr:`__module__`
+ Everything before the last dot is made accessible as the :attr:`~type.__module__`
attribute, and everything after the last dot is made accessible as the
- :attr:`~definition.__name__` attribute.
+ :attr:`~type.__name__` attribute.
If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the
- :attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined
+ :attr:`~type.__name__` attribute, and the :attr:`~type.__module__` attribute is undefined
(unless explicitly set in the dictionary, as explained above). This means your
type will be impossible to pickle. Additionally, it will not be listed in
module documentations created with pydoc.
@@ -609,47 +612,86 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: Py_ssize_t PyTypeObject.tp_basicsize
- Py_ssize_t PyTypeObject.tp_itemsize
+ Py_ssize_t PyTypeObject.tp_itemsize
These fields allow calculating the size in bytes of instances of the type.
There are two kinds of types: types with fixed-length instances have a zero
- :c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length instances have a non-zero
- :c:member:`~PyTypeObject.tp_itemsize` field. For a type with fixed-length instances, all
- instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`.
+ :c:member:`!tp_itemsize` field, types with variable-length instances have a non-zero
+ :c:member:`!tp_itemsize` field. For a type with fixed-length instances, all
+ instances have the same size, given in :c:member:`!tp_basicsize`.
+ (Exceptions to this rule can be made using
+ :c:func:`PyUnstable_Object_GC_NewWithExtraData`.)
For a type with variable-length instances, the instances must have an
- :c:member:`~PyVarObject.ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
- times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of
- N is typically stored in the instance's :c:member:`~PyVarObject.ob_size` field. There are
- exceptions: for example, ints use a negative :c:member:`~PyVarObject.ob_size` to indicate a
- negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
- :c:member:`~PyVarObject.ob_size` field in the instance layout doesn't mean that the instance
- structure is variable-length (for example, the structure for the list type has
- fixed-length instances, yet those instances have a meaningful :c:member:`~PyVarObject.ob_size`
- field).
-
- The basic size includes the fields in the instance declared by the macro
- :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to
- declare the instance struct) and this in turn includes the :c:member:`~PyObject._ob_prev` and
- :c:member:`~PyObject._ob_next` fields if they are present. This means that the only correct
- way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the
- ``sizeof`` operator on the struct used to declare the instance layout.
- The basic size does not include the GC header size.
+ :c:member:`~PyVarObject.ob_size` field, and the instance size is
+ :c:member:`!tp_basicsize` plus N times :c:member:`!tp_itemsize`,
+ where N is the "length" of the object.
+
+ Functions like :c:func:`PyObject_NewVar` will take the value of N as an
+ argument, and store in the instance's :c:member:`~PyVarObject.ob_size` field.
+ Note that the :c:member:`~PyVarObject.ob_size` field may later be used for
+ other purposes. For example, :py:type:`int` instances use the bits of
+ :c:member:`~PyVarObject.ob_size` in an implementation-defined
+ way; the underlying storage and its size should be acessed using
+ :c:func:`PyLong_Export`.
- A note about alignment: if the variable items require a particular alignment,
- this should be taken care of by the value of :c:member:`~PyTypeObject.tp_basicsize`. Example:
- suppose a type implements an array of ``double``. :c:member:`~PyTypeObject.tp_itemsize` is
- ``sizeof(double)``. It is the programmer's responsibility that
- :c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
- alignment requirement for ``double``).
+ .. note::
- For any type with variable-length instances, this field must not be ``NULL``.
+ The :c:member:`~PyVarObject.ob_size` field should be accessed using
+ the :c:func:`Py_SIZE()` and :c:func:`Py_SET_SIZE()` macros.
+
+ Also, the presence of an :c:member:`~PyVarObject.ob_size` field in the
+ instance layout doesn't mean that the instance structure is variable-length.
+ For example, the :py:type:`list` type has fixed-length instances, yet those
+ instances have a :c:member:`~PyVarObject.ob_size` field.
+ (As with :py:type:`int`, avoid reading lists' :c:member:`!ob_size` directly.
+ Call :c:func:`PyList_Size` instead.)
+
+ The :c:member:`!tp_basicsize` includes size needed for data of the type's
+ :c:member:`~PyTypeObject.tp_base`, plus any extra data needed
+ by each instance.
+
+ The correct way to set :c:member:`!tp_basicsize` is to use the
+ ``sizeof`` operator on the struct used to declare the instance layout.
+ This struct must include the struct used to declare the base type.
+ In other words, :c:member:`!tp_basicsize` must be greater than or equal
+ to the base's :c:member:`!tp_basicsize`.
+
+ Since every type is a subtype of :py:type:`object`, this struct must
+ include :c:type:`PyObject` or :c:type:`PyVarObject` (depending on
+ whether :c:member:`~PyVarObject.ob_size` should be included). These are
+ usually defined by the macro :c:macro:`PyObject_HEAD` or
+ :c:macro:`PyObject_VAR_HEAD`, respectively.
+
+ The basic size does not include the GC header size, as that header is not
+ part of :c:macro:`PyObject_HEAD`.
+
+ For cases where struct used to declare the base type is unknown,
+ see :c:member:`PyType_Spec.basicsize` and :c:func:`PyType_FromMetaclass`.
+
+ Notes about alignment:
+
+ - :c:member:`!tp_basicsize` must be a multiple of ``_Alignof(PyObject)``.
+ When using ``sizeof`` on a ``struct`` that includes
+ :c:macro:`PyObject_HEAD`, as recommended, the compiler ensures this.
+ When not using a C ``struct``, or when using compiler
+ extensions like ``__attribute__((packed))``, it is up to you.
+ - If the variable items require a particular alignment,
+ :c:member:`!tp_basicsize` and :c:member:`!tp_itemsize` must each be a
+ multiple of that alignment.
+ For example, if a type's variable part stores a ``double``, it is
+ your responsibility that both fields are a multiple of
+ ``_Alignof(double)``.
**Inheritance:**
- These fields are inherited separately by subtypes. If the base type has a
- non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to set
+ These fields are inherited separately by subtypes.
+ (That is, if the field is set to zero, :c:func:`PyType_Ready` will copy
+ the value from the base type, indicating that the instances do not
+ need additional storage.)
+
+ If the base type has a non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to set
:c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a subtype (though this
depends on the implementation of the base type).
@@ -704,6 +746,19 @@ and :c:data:`PyType_Type` effectively act as defaults.)
Py_DECREF(tp);
}
+ .. warning::
+
+ In a garbage collected Python, :c:member:`!tp_dealloc` may be called from
+ any Python thread, not just the thread which created the object (if the
+ object becomes part of a refcount cycle, that cycle might be collected by
+ a garbage collection on any thread). This is not a problem for Python
+ API calls, since the thread on which :c:member:`!tp_dealloc` is called
+ will own the Global Interpreter Lock (GIL). However, if the object being
+ destroyed in turn destroys objects from some other C or C++ library, care
+ should be taken to ensure that destroying those objects on the thread
+ which called :c:member:`!tp_dealloc` will not violate any assumptions of
+ the library.
+
**Inheritance:**
@@ -1149,7 +1204,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:macro:: Py_TPFLAGS_MANAGED_DICT
- This bit indicates that instances of the class have a ``__dict__``
+ This bit indicates that instances of the class have a `~object.__dict__`
attribute, and that the space for the dictionary is managed by the VM.
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
@@ -1350,8 +1405,8 @@ and :c:data:`PyType_Type` effectively act as defaults.)
.. c:member:: const char* PyTypeObject.tp_doc
An optional pointer to a NUL-terminated C string giving the docstring for this
- type object. This is exposed as the :attr:`__doc__` attribute on the type and
- instances of the type.
+ type object. This is exposed as the :attr:`~type.__doc__` attribute on the
+ type and instances of the type.
**Inheritance:**
@@ -1584,7 +1639,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
weak references to the type object itself.
It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
- :c:member:`~PyTypeObject.tp_weaklist`.
+ :c:member:`~PyTypeObject.tp_weaklistoffset`.
**Inheritance:**
@@ -1596,7 +1651,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
**Default:**
If the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit is set in the
- :c:member:`~PyTypeObject.tp_dict` field, then
+ :c:member:`~PyTypeObject.tp_flags` field, then
:c:member:`~PyTypeObject.tp_weaklistoffset` will be set to a negative value,
to indicate that it is unsafe to use this field.
@@ -1808,7 +1863,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
dictionary, so it is may be more efficient to call :c:func:`PyObject_GetAttr`
when accessing an attribute on the object.
- It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` bit and
+ It is an error to set both the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit and
:c:member:`~PyTypeObject.tp_dictoffset`.
**Inheritance:**
@@ -2028,7 +2083,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
A collection of subclasses. Internal use only. May be an invalid pointer.
To get a list of subclasses, call the Python method
- :py:meth:`~class.__subclasses__`.
+ :py:meth:`~type.__subclasses__`.
.. versionchanged:: 3.12
@@ -2101,17 +2156,6 @@ and :c:data:`PyType_Type` effectively act as defaults.)
PyErr_Restore(error_type, error_value, error_traceback);
}
- Also, note that, in a garbage collected Python,
- :c:member:`~PyTypeObject.tp_dealloc` may be called from
- any Python thread, not just the thread which created the object (if the object
- becomes part of a refcount cycle, that cycle might be collected by a garbage
- collection on any thread). This is not a problem for Python API calls, since
- the thread on which tp_dealloc is called will own the Global Interpreter Lock
- (GIL). However, if the object being destroyed in turn destroys objects from some
- other C or C++ library, care should be taken to ensure that destroying those
- objects on the thread which called tp_dealloc will not violate any assumptions
- of the library.
-
**Inheritance:**
This field is inherited by subtypes.
@@ -2191,7 +2235,7 @@ This is done by filling a :c:type:`PyType_Spec` structure and calling
.. _number-structs:
Number Object Structures
-========================
+------------------------
.. sectionauthor:: Amaury Forgeot d'Arc
@@ -2305,7 +2349,7 @@ Number Object Structures
.. _mapping-structs:
Mapping Object Structures
-=========================
+-------------------------
.. sectionauthor:: Amaury Forgeot d'Arc
@@ -2342,7 +2386,7 @@ Mapping Object Structures
.. _sequence-structs:
Sequence Object Structures
-==========================
+--------------------------
.. sectionauthor:: Amaury Forgeot d'Arc
@@ -2422,7 +2466,7 @@ Sequence Object Structures
.. _buffer-structs:
Buffer Object Structures
-========================
+------------------------
.. sectionauthor:: Greg J. Stein
.. sectionauthor:: Benjamin Peterson
@@ -2517,7 +2561,7 @@ Buffer Object Structures
Async Object Structures
-=======================
+-----------------------
.. sectionauthor:: Yury Selivanov
@@ -2585,7 +2629,7 @@ Async Object Structures
.. _slot-typedefs:
Slot Type typedefs
-==================
+------------------
.. c:type:: PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems)
@@ -2608,7 +2652,7 @@ Slot Type typedefs
See :c:member:`~PyTypeObject.tp_free`.
-.. c:type:: PyObject *(*newfunc)(PyObject *, PyObject *, PyObject *)
+.. c:type:: PyObject *(*newfunc)(PyTypeObject *, PyObject *, PyObject *)
See :c:member:`~PyTypeObject.tp_new`.
@@ -2694,7 +2738,7 @@ Slot Type typedefs
.. _typedef-examples:
Examples
-========
+--------
The following are simple examples of Python type definitions. They
include common usage you may encounter. Some demonstrate tricky corner
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 54a006c0..cce15b70 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -254,13 +254,8 @@ the Python configuration.
.. c:function:: int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)
- Return ``1`` or ``0`` depending on whether *ch* is a printable character.
- Nonprintable characters are those characters defined in the Unicode character
- database as "Other" or "Separator", excepting the ASCII space (0x20) which is
- considered printable. (Note that printable characters in this context are
- those which should not be escaped when :func:`repr` is invoked on a string.
- It has no bearing on the handling of strings written to :data:`sys.stdout` or
- :data:`sys.stderr`.)
+ Return ``1`` or ``0`` depending on whether *ch* is a printable character,
+ in the sense of :meth:`str.isprintable`.
These APIs can be used for fast direct character conversions:
@@ -345,6 +340,8 @@ APIs:
This is the recommended way to allocate a new Unicode object. Objects
created using this function are not resizable.
+ On error, set an exception and return ``NULL``.
+
.. versionadded:: 3.3
@@ -594,10 +591,21 @@ APIs:
decref'ing the returned objects.
+.. c:function:: const char* PyUnicode_GetDefaultEncoding(void)
+
+ Return the name of the default string encoding, ``"utf-8"``.
+ See :func:`sys.getdefaultencoding`.
+
+ The returned string does not need to be freed, and is valid
+ until interpreter shutdown.
+
+
.. c:function:: Py_ssize_t PyUnicode_GetLength(PyObject *unicode)
Return the length of the Unicode object, in code points.
+ On error, set an exception and return ``-1``.
+
.. versionadded:: 3.3
@@ -641,6 +649,8 @@ APIs:
not out of bounds, and that the object can be modified safely (i.e. that it
its reference count is one).
+ Return ``0`` on success, ``-1`` on error with an exception set.
+
.. versionadded:: 3.3
@@ -650,6 +660,8 @@ APIs:
Unicode object and the index is not out of bounds, in contrast to
:c:func:`PyUnicode_READ_CHAR`, which performs no error checking.
+ Return character on success, ``-1`` on error with an exception set.
+
.. versionadded:: 3.3
@@ -658,6 +670,7 @@ APIs:
Return a substring of *unicode*, from character index *start* (included) to
character index *end* (excluded). Negative indices are not supported.
+ On error, set an exception and return ``NULL``.
.. versionadded:: 3.3
@@ -761,16 +774,25 @@ Functions encoding to and decoding from the :term:`filesystem encoding and
error handler` (:pep:`383` and :pep:`529`).
To encode file names to :class:`bytes` during argument parsing, the ``"O&"``
-converter should be used, passing :c:func:`PyUnicode_FSConverter` as the
+converter should be used, passing :c:func:`!PyUnicode_FSConverter` as the
conversion function:
.. c:function:: int PyUnicode_FSConverter(PyObject* obj, void* result)
- ParseTuple converter: encode :class:`str` objects -- obtained directly or
+ :ref:`PyArg_Parse\* converter `: encode :class:`str` objects -- obtained directly or
through the :class:`os.PathLike` interface -- to :class:`bytes` using
:c:func:`PyUnicode_EncodeFSDefault`; :class:`bytes` objects are output as-is.
- *result* must be a :c:expr:`PyBytesObject*` which must be released when it is
- no longer used.
+ *result* must be an address of a C variable of type :c:expr:`PyObject*`
+ (or :c:expr:`PyBytesObject*`).
+ On success, set the variable to a new :term:`strong reference` to
+ a :ref:`bytes object ` which must be released
+ when it is no longer used and return a non-zero value
+ (:c:macro:`Py_CLEANUP_SUPPORTED`).
+ Embedded null bytes are not allowed in the result.
+ On failure, return ``0`` with an exception set.
+
+ If *obj* is ``NULL``, the function releases a strong reference
+ stored in the variable referred by *result* and returns ``1``.
.. versionadded:: 3.1
@@ -778,16 +800,26 @@ conversion function:
Accepts a :term:`path-like object`.
To decode file names to :class:`str` during argument parsing, the ``"O&"``
-converter should be used, passing :c:func:`PyUnicode_FSDecoder` as the
+converter should be used, passing :c:func:`!PyUnicode_FSDecoder` as the
conversion function:
.. c:function:: int PyUnicode_FSDecoder(PyObject* obj, void* result)
- ParseTuple converter: decode :class:`bytes` objects -- obtained either
+ :ref:`PyArg_Parse\* converter `: decode :class:`bytes` objects -- obtained either
directly or indirectly through the :class:`os.PathLike` interface -- to
:class:`str` using :c:func:`PyUnicode_DecodeFSDefaultAndSize`; :class:`str`
- objects are output as-is. *result* must be a :c:expr:`PyUnicodeObject*` which
- must be released when it is no longer used.
+ objects are output as-is.
+ *result* must be an address of a C variable of type :c:expr:`PyObject*`
+ (or :c:expr:`PyUnicodeObject*`).
+ On success, set the variable to a new :term:`strong reference` to
+ a :ref:`Unicode object ` which must be released
+ when it is no longer used and return a non-zero value
+ (:c:macro:`Py_CLEANUP_SUPPORTED`).
+ Embedded null characters are not allowed in the result.
+ On failure, return ``0`` with an exception set.
+
+ If *obj* is ``NULL``, release the strong reference
+ to the object referred to by *result* and return ``1``.
.. versionadded:: 3.2
@@ -1004,6 +1036,15 @@ These are the UTF-8 codec APIs:
As :c:func:`PyUnicode_AsUTF8AndSize`, but does not store the size.
+ .. warning::
+
+ This function does not have any special behavior for
+ `null characters `_ embedded within
+ *unicode*. As a result, strings containing null characters will remain in the returned
+ string, which some C functions might interpret as the end of the string, leading to
+ truncation. If truncation is an issue, it is recommended to use :c:func:`PyUnicode_AsUTF8AndSize`
+ instead.
+
.. versionadded:: 3.3
.. versionchanged:: 3.7
@@ -1293,6 +1334,13 @@ the user settings on the machine running the codec.
in *consumed*.
+.. c:function:: PyObject* PyUnicode_DecodeCodePageStateful(int code_page, const char *str, \
+ Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
+
+ Similar to :c:func:`PyUnicode_DecodeMBCSStateful`, except uses the code page
+ specified by *code_page*.
+
+
.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
Encode a Unicode object using MBCS and return the result as Python bytes
@@ -1337,6 +1385,20 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
separator. At most *maxsplit* splits will be done. If negative, no limit is
set. Separators are not included in the resulting list.
+ On error, return ``NULL`` with an exception set.
+
+ Equivalent to :py:meth:`str.split`.
+
+
+.. c:function:: PyObject* PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)
+
+ Similar to :c:func:`PyUnicode_Split`, but splitting will be done beginning
+ at the end of the string.
+
+ On error, return ``NULL`` with an exception set.
+
+ Equivalent to :py:meth:`str.rsplit`.
+
.. c:function:: PyObject* PyUnicode_Splitlines(PyObject *unicode, int keepends)
@@ -1345,6 +1407,33 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
characters are not included in the resulting strings.
+.. c:function:: PyObject* PyUnicode_Partition(PyObject *unicode, PyObject *sep)
+
+ Split a Unicode string at the first occurrence of *sep*, and return
+ a 3-tuple containing the part before the separator, the separator itself,
+ and the part after the separator. If the separator is not found,
+ return a 3-tuple containing the string itself, followed by two empty strings.
+
+ *sep* must not be empty.
+
+ On error, return ``NULL`` with an exception set.
+
+ Equivalent to :py:meth:`str.partition`.
+
+
+.. c:function:: PyObject* PyUnicode_RPartition(PyObject *unicode, PyObject *sep)
+
+ Similar to :c:func:`PyUnicode_Partition`, but split a Unicode string at the
+ last occurrence of *sep*. If the separator is not found, return a 3-tuple
+ containing two empty strings, followed by the string itself.
+
+ *sep* must not be empty.
+
+ On error, return ``NULL`` with an exception set.
+
+ Equivalent to :py:meth:`str.rpartition`.
+
+
.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
Join a sequence of strings using the given *separator* and return the resulting
@@ -1452,15 +1541,35 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
existing interned string that is the same as :c:expr:`*p_unicode`, it sets :c:expr:`*p_unicode` to
it (releasing the reference to the old string object and creating a new
:term:`strong reference` to the interned string object), otherwise it leaves
- :c:expr:`*p_unicode` alone and interns it (creating a new :term:`strong reference`).
+ :c:expr:`*p_unicode` alone and interns it.
+
(Clarification: even though there is a lot of talk about references, think
- of this function as reference-neutral; you own the object after the call
- if and only if you owned it before the call.)
+ of this function as reference-neutral. You must own the object you pass in;
+ after the call you no longer own the passed-in reference, but you newly own
+ the result.)
+
+ This function never raises an exception.
+ On error, it leaves its argument unchanged without interning it.
+
+ Instances of subclasses of :py:class:`str` may not be interned, that is,
+ :c:expr:`PyUnicode_CheckExact(*p_unicode)` must be true. If it is not,
+ then -- as with any other error -- the argument is left unchanged.
+
+ Note that interned strings are not “immortal”.
+ You must keep a reference to the result to benefit from interning.
.. c:function:: PyObject* PyUnicode_InternFromString(const char *str)
A combination of :c:func:`PyUnicode_FromString` and
- :c:func:`PyUnicode_InternInPlace`, returning either a new Unicode string
- object that has been interned, or a new ("owned") reference to an earlier
- interned string object with the same value.
+ :c:func:`PyUnicode_InternInPlace`, meant for statically allocated strings.
+
+ Return a new ("owned") reference to either a new Unicode string object
+ that has been interned, or an earlier interned string object with the
+ same value.
+
+ Python may keep a reference to the result, or
+ prevent it from being garbage-collected promptly.
+ For interning an unbounded number of different strings, such as ones coming
+ from user input, prefer calling :c:func:`PyUnicode_FromString` and
+ :c:func:`PyUnicode_InternInPlace` directly.
diff --git a/Doc/conf.py b/Doc/conf.py
index e292bdd5..526df2da 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -8,35 +8,46 @@
import os
import sys
-import time
+from importlib import import_module
+from importlib.util import find_spec
+
+# Make our custom extensions available to Sphinx
sys.path.append(os.path.abspath('tools/extensions'))
sys.path.append(os.path.abspath('includes'))
+# Python specific content from Doc/Tools/extensions/pyspecific.py
from pyspecific import SOURCE_URI
# General configuration
# ---------------------
+# Our custom Sphinx extensions are found in Doc/Tools/extensions/
extensions = [
- 'asdl_highlight',
+ 'audit_events',
+ 'availability',
'c_annotations',
- 'escape4chm',
+ 'changes',
'glossary_search',
- 'peg_highlight',
+ 'implementation_detail',
+ 'issue_role',
+ 'lexers',
+ 'misc_news',
+ 'pydoc_topics',
'pyspecific',
'sphinx.ext.coverage',
'sphinx.ext.doctest',
'sphinx.ext.extlinks',
]
-# Skip if downstream redistributors haven't installed it
-try:
- import sphinxext.opengraph
-except ImportError:
- pass
-else:
- extensions.append('sphinxext.opengraph')
-
+# Skip if downstream redistributors haven't installed them
+_OPTIONAL_EXTENSIONS = ('sphinxext.opengraph',)
+for optional_ext in _OPTIONAL_EXTENSIONS:
+ try:
+ if find_spec(optional_ext) is not None:
+ extensions.append(optional_ext)
+ except (ImportError, ValueError):
+ pass
+del _OPTIONAL_EXTENSIONS
doctest_global_setup = '''
try:
@@ -44,7 +55,7 @@
except ImportError:
_tkinter = None
# Treat warnings as errors, done here to prevent warnings in Sphinx code from
-# causing spurious test failures.
+# causing spurious CPython test failures.
import warnings
warnings.simplefilter('error')
del warnings
@@ -54,35 +65,36 @@
# General substitutions.
project = 'Python'
-copyright = f"2001-{time.strftime('%Y')}, Python Software Foundation"
+copyright = "2001-%Y, Python Software Foundation"
# We look for the Include/patchlevel.h file in the current Python source tree
# and replace the values accordingly.
-import patchlevel
-version, release = patchlevel.get_version_info()
+# See Doc/tools/extensions/patchlevel.py
+version, release = import_module('patchlevel').get_version_info()
rst_epilog = f"""
.. |python_version_literal| replace:: ``Python {version}``
"""
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
+# There are two options for replacing |today|. Either, you set today to some
+# non-false value and use it.
today = ''
-# Else, today_fmt is used as the format for a strftime call.
+# Or else, today_fmt is used as the format for a strftime call.
today_fmt = '%B %d, %Y'
# By default, highlight as Python 3.
highlight_language = 'python3'
# Minimum version of sphinx required
-needs_sphinx = '4.2'
+# Keep this version in sync with ``Doc/requirements.txt``.
+needs_sphinx = '8.2.0'
# Create table of contents entries for domain objects (e.g. functions, classes,
# attributes, etc.). Default is True.
toc_object_entries = False
# Ignore any .rst files in the includes/ directory;
-# they're embedded in pages but not rendered individually.
+# they're embedded in pages but not rendered as individual pages.
# Ignore any .rst files in the venv/ directory.
exclude_patterns = ['includes/*.rst', 'venv/*', 'README.rst']
venvdir = os.getenv('VENVDIR')
@@ -166,6 +178,7 @@
('envvar', 'LC_TIME'),
('envvar', 'LINES'),
('envvar', 'LOGNAME'),
+ ('envvar', 'MANPAGER'),
('envvar', 'PAGER'),
('envvar', 'PATH'),
('envvar', 'PATHEXT'),
@@ -256,6 +269,9 @@
('c:data', 'PyExc_UnicodeWarning'),
('c:data', 'PyExc_UserWarning'),
('c:data', 'PyExc_Warning'),
+ # Undocumented public C macros
+ ('c:macro', 'Py_BUILD_ASSERT'),
+ ('c:macro', 'Py_BUILD_ASSERT_EXPR'),
# Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot
# be resolved, as the method is currently undocumented. For context, see
# https://github.com/python/cpython/pull/103289.
@@ -280,7 +296,8 @@
# Disable Docutils smartquotes for several translations
smartquotes_excludes = {
- 'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'], 'builders': ['man', 'text'],
+ 'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'],
+ 'builders': ['man', 'text'],
}
# Avoid a warning with Sphinx >= 4.0
@@ -289,23 +306,27 @@
# Allow translation of index directives
gettext_additional_targets = [
'index',
+ 'literal-block',
]
# Options for HTML output
# -----------------------
-# Use our custom theme.
+# Use our custom theme: https://github.com/python/python-docs-theme
html_theme = 'python_docs_theme'
+# Location of overrides for theme templates and static files
html_theme_path = ['tools']
html_theme_options = {
'collapsiblesidebar': True,
'issues_url': '/bugs.html',
'license_url': '/license.html',
- 'root_include_title': False # We use the version switcher instead.
+ 'root_include_title': False, # We use the version switcher instead.
}
if os.getenv("READTHEDOCS"):
- html_theme_options["hosted_on"] = 'Read the Docs'
+ html_theme_options["hosted_on"] = (
+ 'Read the Docs'
+ )
# Override stylesheet fingerprinting for Windows CHM htmlhelp to fix GH-91207
# https://github.com/python/cpython/issues/91207
@@ -319,17 +340,21 @@
# Deployment preview information
# (See .readthedocs.yml and https://docs.readthedocs.io/en/stable/reference/environment-variables.html)
-repository_url = os.getenv("READTHEDOCS_GIT_CLONE_URL")
+is_deployment_preview = os.getenv("READTHEDOCS_VERSION_TYPE") == "external"
+repository_url = os.getenv("READTHEDOCS_GIT_CLONE_URL", "")
+repository_url = repository_url.removesuffix(".git")
html_context = {
- "is_deployment_preview": os.getenv("READTHEDOCS_VERSION_TYPE") == "external",
- "repository_url": repository_url.removesuffix(".git") if repository_url else None,
- "pr_id": os.getenv("READTHEDOCS_VERSION")
+ "is_deployment_preview": is_deployment_preview,
+ "repository_url": repository_url or None,
+ "pr_id": os.getenv("READTHEDOCS_VERSION"),
+ "enable_analytics": os.getenv("PYTHON_DOCS_ENABLE_ANALYTICS"),
}
# This 'Last updated on:' timestamp is inserted at the bottom of every page.
-html_last_updated_fmt = time.strftime('%b %d, %Y (%H:%M UTC)', time.gmtime())
+html_last_updated_fmt = '%b %d, %Y (%H:%M UTC)'
+html_last_updated_use_utc = True
-# Path to find HTML templates.
+# Path to find HTML templates to override theme
templates_path = ['tools/templates']
# Custom sidebar templates, filenames relative to this file.
@@ -377,8 +402,8 @@
\let\endVerbatim=\endOriginalVerbatim
\setcounter{tocdepth}{2}
''',
- # The paper size ('letter' or 'a4').
- 'papersize': 'a4',
+ # The paper size ('letterpaper' or 'a4paper').
+ 'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
'pointsize': '10pt',
}
@@ -387,30 +412,70 @@
# (source start file, target name, title, author, document class [howto/manual]).
_stdauthor = 'Guido van Rossum and the Python development team'
latex_documents = [
- ('c-api/index', 'c-api.tex',
- 'The Python/C API', _stdauthor, 'manual'),
- ('extending/index', 'extending.tex',
- 'Extending and Embedding Python', _stdauthor, 'manual'),
- ('installing/index', 'installing.tex',
- 'Installing Python Modules', _stdauthor, 'manual'),
- ('library/index', 'library.tex',
- 'The Python Library Reference', _stdauthor, 'manual'),
- ('reference/index', 'reference.tex',
- 'The Python Language Reference', _stdauthor, 'manual'),
- ('tutorial/index', 'tutorial.tex',
- 'Python Tutorial', _stdauthor, 'manual'),
- ('using/index', 'using.tex',
- 'Python Setup and Usage', _stdauthor, 'manual'),
- ('faq/index', 'faq.tex',
- 'Python Frequently Asked Questions', _stdauthor, 'manual'),
- ('whatsnew/' + version, 'whatsnew.tex',
- 'What\'s New in Python', 'A. M. Kuchling', 'howto'),
+ ('c-api/index', 'c-api.tex', 'The Python/C API', _stdauthor, 'manual'),
+ (
+ 'extending/index',
+ 'extending.tex',
+ 'Extending and Embedding Python',
+ _stdauthor,
+ 'manual',
+ ),
+ (
+ 'installing/index',
+ 'installing.tex',
+ 'Installing Python Modules',
+ _stdauthor,
+ 'manual',
+ ),
+ (
+ 'library/index',
+ 'library.tex',
+ 'The Python Library Reference',
+ _stdauthor,
+ 'manual',
+ ),
+ (
+ 'reference/index',
+ 'reference.tex',
+ 'The Python Language Reference',
+ _stdauthor,
+ 'manual',
+ ),
+ (
+ 'tutorial/index',
+ 'tutorial.tex',
+ 'Python Tutorial',
+ _stdauthor,
+ 'manual',
+ ),
+ (
+ 'using/index',
+ 'using.tex',
+ 'Python Setup and Usage',
+ _stdauthor,
+ 'manual',
+ ),
+ (
+ 'faq/index',
+ 'faq.tex',
+ 'Python Frequently Asked Questions',
+ _stdauthor,
+ 'manual',
+ ),
+ (
+ 'whatsnew/' + version,
+ 'whatsnew.tex',
+ 'What\'s New in Python',
+ 'A. M. Kuchling',
+ 'howto',
+ ),
]
# Collect all HOWTOs individually
-latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex',
- '', _stdauthor, 'howto')
- for fn in os.listdir('howto')
- if fn.endswith('.rst') and fn != 'index.rst')
+latex_documents.extend(
+ ('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex', '', _stdauthor, 'howto')
+ for fn in os.listdir('howto')
+ if fn.endswith('.rst') and fn != 'index.rst'
+)
# Documents to append as an appendix to all manuals.
latex_appendices = ['glossary', 'about', 'license', 'copyright']
@@ -439,8 +504,7 @@
'test($|_)',
]
-coverage_ignore_classes = [
-]
+coverage_ignore_classes = []
# Glob patterns for C source files for C API coverage, relative to this directory.
coverage_c_path = [
@@ -457,7 +521,7 @@
# The coverage checker will ignore all C items whose names match these regexes
# (using re.match) -- the keys must be the same as in coverage_c_regexes.
coverage_ignore_c_items = {
-# 'cfunction': [...]
+ # 'cfunction': [...]
}
@@ -473,15 +537,19 @@
r'https://github.com/python/cpython/tree/.*': 'https://github.com/python/cpython/blob/.*',
# Intentional HTTP use at Misc/NEWS.d/3.5.0a1.rst
r'http://www.python.org/$': 'https://www.python.org/$',
- # Used in license page, keep as is
- r'https://www.zope.org/': r'https://www.zope.dev/',
# Microsoft's redirects to learn.microsoft.com
r'https://msdn.microsoft.com/.*': 'https://learn.microsoft.com/.*',
r'https://docs.microsoft.com/.*': 'https://learn.microsoft.com/.*',
r'https://go.microsoft.com/fwlink/\?LinkID=\d+': 'https://learn.microsoft.com/.*',
+ # Debian's man page redirects to its current stable version
+ r'https://manpages.debian.org/\w+\(\d(\w+)?\)': r'https://manpages.debian.org/\w+/[\w/\-\.]*\.\d(\w+)?\.en\.html',
# Language redirects
r'https://toml.io': 'https://toml.io/en/',
r'https://www.redhat.com': 'https://www.redhat.com/en',
+ # pypi.org project name normalization (upper to lowercase, underscore to hyphen)
+ r'https://pypi.org/project/[A-Za-z\d_\-\.]+/': r'https://pypi.org/project/[a-z\d\-\.]+/',
+ # Discourse title name expansion (text changes when title is edited)
+ r'https://discuss\.python\.org/t/\d+': r'https://discuss\.python\.org/t/.*/\d+',
# Other redirects
r'https://www.boost.org/libs/.+': r'https://www.boost.org/doc/libs/\d_\d+_\d/.+',
r'https://support.microsoft.com/en-us/help/\d+': 'https://support.microsoft.com/en-us/topic/.+',
@@ -515,26 +583,26 @@
# mapping unique short aliases to a base URL and a prefix.
# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
extlinks = {
- "cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
- "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
"pypi": ("https://pypi.org/project/%s/", "%s"),
"source": (SOURCE_URI, "%s"),
}
extlinks_detect_hardcoded_links = True
-# Options for extensions
-# ----------------------
+# Options for c_annotations extension
+# -----------------------------------
# Relative filename of the data files
refcount_file = 'data/refcounts.dat'
stable_abi_file = 'data/stable_abi.dat'
-# sphinxext-opengraph config
+# Options for sphinxext-opengraph
+# -------------------------------
+
ogp_site_url = 'https://docs.python.org/3/'
ogp_site_name = 'Python documentation'
ogp_image = '_static/og-image.png'
ogp_custom_meta_tags = [
- '',
- '',
- '',
+ '',
+ '',
+ '',
]
diff --git a/Doc/constraints.txt b/Doc/constraints.txt
index 16b735ea..29cd4be1 100644
--- a/Doc/constraints.txt
+++ b/Doc/constraints.txt
@@ -7,18 +7,18 @@
# Direct dependencies of Sphinx
babel<3
colorama<0.5
-imagesize<1.5
-Jinja2<3.2
-packaging<24
-Pygments>=2.16.1,<3
+imagesize<2
+Jinja2<4
+packaging<25
+Pygments<3
requests<3
snowballstemmer<3
-sphinxcontrib-applehelp<1.0.5
-sphinxcontrib-devhelp<1.0.6
-sphinxcontrib-htmlhelp<2.0.5
-sphinxcontrib-jsmath<1.1
-sphinxcontrib-qthelp<1.0.7
-sphinxcontrib-serializinghtml<1.1.10
+sphinxcontrib-applehelp<3
+sphinxcontrib-devhelp<3
+sphinxcontrib-htmlhelp<3
+sphinxcontrib-jsmath<2
+sphinxcontrib-qthelp<3
+sphinxcontrib-serializinghtml<3
# Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
-MarkupSafe<2.2
+MarkupSafe<3
diff --git a/Doc/contents.rst b/Doc/contents.rst
index 24ceacb0..b57f4b09 100644
--- a/Doc/contents.rst
+++ b/Doc/contents.rst
@@ -14,6 +14,7 @@
installing/index.rst
howto/index.rst
faq/index.rst
+ deprecations/index.rst
glossary.rst
about.rst
diff --git a/Doc/data/python3.12.abi b/Doc/data/python3.12.abi
index 95dfe64a..875e875a 100644
--- a/Doc/data/python3.12.abi
+++ b/Doc/data/python3.12.abi
@@ -1,26571 +1,23619 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index b5d95324..cb186b6d 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -180,7 +180,7 @@ PyCapsule_IsValid:const char*:name::
PyCapsule_New:PyObject*::+1:
PyCapsule_New:void*:pointer::
PyCapsule_New:const char *:name::
-PyCapsule_New::void (* destructor)(PyObject* )::
+PyCapsule_New:void (*)(PyObject *):destructor::
PyCapsule_SetContext:int:::
PyCapsule_SetContext:PyObject*:self:0:
@@ -349,11 +349,11 @@ PyComplex_CheckExact:int:::
PyComplex_CheckExact:PyObject*:p:0:
PyComplex_FromCComplex:PyObject*::+1:
-PyComplex_FromCComplex::Py_complex v::
+PyComplex_FromCComplex:Py_complex:v::
PyComplex_FromDoubles:PyObject*::+1:
-PyComplex_FromDoubles::double real::
-PyComplex_FromDoubles::double imag::
+PyComplex_FromDoubles:double:real::
+PyComplex_FromDoubles:double:imag::
PyComplex_ImagAsDouble:double:::
PyComplex_ImagAsDouble:PyObject*:op:0:
@@ -622,7 +622,9 @@ PyErr_GetExcInfo:PyObject**:pvalue:+1:
PyErr_GetExcInfo:PyObject**:ptraceback:+1:
PyErr_GetRaisedException:PyObject*::+1:
-PyErr_SetRaisedException::::
+
+PyErr_SetRaisedException:void:::
+PyErr_SetRaisedException:PyObject *:exc:0:stolen
PyErr_GivenExceptionMatches:int:::
PyErr_GivenExceptionMatches:PyObject*:given:0:
@@ -642,9 +644,9 @@ PyErr_NewExceptionWithDoc:PyObject*:dict:0:
PyErr_NoMemory:PyObject*::null:
PyErr_NormalizeException:void:::
-PyErr_NormalizeException:PyObject**:exc::???
-PyErr_NormalizeException:PyObject**:val::???
-PyErr_NormalizeException:PyObject**:tb::???
+PyErr_NormalizeException:PyObject**:exc:+1:???
+PyErr_NormalizeException:PyObject**:val:+1:???
+PyErr_NormalizeException:PyObject**:tb:+1:???
PyErr_Occurred:PyObject*::0:
@@ -1268,7 +1270,7 @@ PyMapping_GetItemString:const char*:key::
PyMapping_HasKey:int:::
PyMapping_HasKey:PyObject*:o:0:
-PyMapping_HasKey:PyObject*:key::
+PyMapping_HasKey:PyObject*:key:0:
PyMapping_HasKeyString:int:::
PyMapping_HasKeyString:PyObject*:o:0:
@@ -1428,7 +1430,7 @@ PyModule_GetState:void*:::
PyModule_GetState:PyObject*:module:0:
PyModule_New:PyObject*::+1:
-PyModule_New::char* name::
+PyModule_New:char*:name::
PyModule_NewObject:PyObject*::+1:
PyModule_NewObject:PyObject*:name:+1:
@@ -1438,7 +1440,7 @@ PyModule_SetDocString:PyObject*:module:0:
PyModule_SetDocString:const char*:docstring::
PyModuleDef_Init:PyObject*::0:
-PyModuleDef_Init:PyModuleDef*:def:0:
+PyModuleDef_Init:PyModuleDef*:def::
PyNumber_Absolute:PyObject*::+1:
PyNumber_Absolute:PyObject*:o:0:
@@ -1816,6 +1818,9 @@ PyObject_RichCompareBool:PyObject*:o1:0:
PyObject_RichCompareBool:PyObject*:o2:0:
PyObject_RichCompareBool:int:opid::
+PyObject_SelfIter:PyObject*::+1:
+PyObject_SelfIter:PyObject*:obj:0:
+
PyObject_SetAttr:int:::
PyObject_SetAttr:PyObject*:o:0:
PyObject_SetAttr:PyObject*:attr_name:0:
@@ -1950,10 +1955,10 @@ PyRun_StringFlags:PyObject*:locals:0:
PyRun_StringFlags:PyCompilerFlags*:flags::
PySeqIter_Check:int:::
-PySeqIter_Check::op::
+PySeqIter_Check:PyObject *:op:0:
PySeqIter_New:PyObject*::+1:
-PySeqIter_New:PyObject*:seq::
+PySeqIter_New:PyObject*:seq:0:
PySequence_Check:int:::
PySequence_Check:PyObject*:o:0:
@@ -2393,7 +2398,7 @@ PyUnicode_GET_DATA_SIZE:PyObject*:o:0:
PyUnicode_KIND:int:::
PyUnicode_KIND:PyObject*:o:0:
-PyUnicode_MAX_CHAR_VALUE::::
+PyUnicode_MAX_CHAR_VALUE:Py_UCS4:::
PyUnicode_MAX_CHAR_VALUE:PyObject*:o:0:
PyUnicode_AS_UNICODE:Py_UNICODE*:::
@@ -2480,7 +2485,7 @@ PyUnicode_FromWideChar:const wchar_t*:w::
PyUnicode_FromWideChar:Py_ssize_t:size::
PyUnicode_AsWideChar:Py_ssize_t:::
-PyUnicode_AsWideChar:PyObject*:*unicode:0:
+PyUnicode_AsWideChar:PyObject*:unicode:0:
PyUnicode_AsWideChar:wchar_t*:w::
PyUnicode_AsWideChar:Py_ssize_t:size::
@@ -2533,7 +2538,7 @@ PyUnicode_AsUTF8String:PyObject*:unicode:0:
PyUnicode_AsUTF8AndSize:const char*:::
PyUnicode_AsUTF8AndSize:PyObject*:unicode:0:
-PyUnicode_AsUTF8AndSize:Py_ssize_t*:size:0:
+PyUnicode_AsUTF8AndSize:Py_ssize_t*:size::
PyUnicode_AsUTF8:const char*:::
PyUnicode_AsUTF8:PyObject*:unicode:0:
@@ -2616,6 +2621,13 @@ PyUnicode_DecodeMBCSStateful:Py_ssize_t:size::
PyUnicode_DecodeMBCSStateful:const char*:errors::
PyUnicode_DecodeMBCSStateful:Py_ssize_t*:consumed::
+PyUnicode_DecodeCodePageStateful:PyObject*::+1:
+PyUnicode_DecodeCodePageStateful:int:code_page::
+PyUnicode_DecodeCodePageStateful:const char*:s::
+PyUnicode_DecodeCodePageStateful:Py_ssize_t:size::
+PyUnicode_DecodeCodePageStateful:const char*:errors::
+PyUnicode_DecodeCodePageStateful:Py_ssize_t*:consumed::
+
PyUnicode_EncodeCodePage:PyObject*::+1:
PyUnicode_EncodeCodePage:int:code_page::
PyUnicode_EncodeCodePage:PyObject*:unicode:0:
@@ -2628,13 +2640,26 @@ PyUnicode_Concat:PyObject*::+1:
PyUnicode_Concat:PyObject*:left:0:
PyUnicode_Concat:PyObject*:right:0:
+PyUnicode_Partition:PyObject*::+1:
+PyUnicode_Partition:PyObject*:unicode:0:
+PyUnicode_Partition:PyObject*:sep:0:
+
+PyUnicode_RPartition:PyObject*::+1:
+PyUnicode_RPartition:PyObject*:unicode:0:
+PyUnicode_RPartition:PyObject*:sep:0:
+
+PyUnicode_RSplit:PyObject*::+1:
+PyUnicode_RSplit:PyObject*:unicode:0:
+PyUnicode_RSplit:PyObject*:sep:0:
+PyUnicode_RSplit:Py_ssize_t:maxsplit::
+
PyUnicode_Split:PyObject*::+1:
-PyUnicode_Split:PyObject*:left:0:
-PyUnicode_Split:PyObject*:right:0:
+PyUnicode_Split:PyObject*:unicode:0:
+PyUnicode_Split:PyObject*:sep:0:
PyUnicode_Split:Py_ssize_t:maxsplit::
PyUnicode_Splitlines:PyObject*::+1:
-PyUnicode_Splitlines:PyObject*:s:0:
+PyUnicode_Splitlines:PyObject*:unicode:0:
PyUnicode_Splitlines:int:keepend::
PyUnicode_Translate:PyObject*::+1:
@@ -2730,6 +2755,9 @@ PyUnicode_FromFormatV:PyObject*::+1:
PyUnicode_FromFormatV:const char*:format::
PyUnicode_FromFormatV:va_list:args::
+PyUnicode_GetDefaultEncoding:const char*:::
+PyUnicode_GetDefaultEncoding::void::
+
PyUnicode_GetLength:Py_ssize_t:::
PyUnicode_GetLength:PyObject*:unicode:0:
@@ -2856,13 +2884,13 @@ PyUnicodeDecodeError_SetStart:PyObject*:exc:0:
PyUnicodeDecodeError_SetStart:Py_ssize_t:start::
PyWeakref_Check:int:::
-PyWeakref_Check:PyObject*:ob::
+PyWeakref_Check:PyObject*:ob:0:
PyWeakref_CheckProxy:int:::
-PyWeakref_CheckProxy:PyObject*:ob::
+PyWeakref_CheckProxy:PyObject*:ob:0:
PyWeakref_CheckRef:int:::
-PyWeakref_CheckRef:PyObject*:ob::
+PyWeakref_CheckRef:PyObject*:ob:0:
PyWeakref_GET_OBJECT:PyObject*::0:
PyWeakref_GET_OBJECT:PyObject*:ref:0:
diff --git a/Doc/data/stable_abi.dat b/Doc/data/stable_abi.dat
index f112d268..4aa2b351 100644
--- a/Doc/data/stable_abi.dat
+++ b/Doc/data/stable_abi.dat
@@ -1,868 +1,868 @@
role,name,added,ifdef_note,struct_abi_kind
macro,PY_VECTORCALL_ARGUMENTS_OFFSET,3.12,,
-function,PyAIter_Check,3.10,,
-function,PyArg_Parse,3.2,,
-function,PyArg_ParseTuple,3.2,,
-function,PyArg_ParseTupleAndKeywords,3.2,,
-function,PyArg_UnpackTuple,3.2,,
-function,PyArg_VaParse,3.2,,
-function,PyArg_VaParseTupleAndKeywords,3.2,,
-function,PyArg_ValidateKeywordArguments,3.2,,
-var,PyBaseObject_Type,3.2,,
-function,PyBool_FromLong,3.2,,
-var,PyBool_Type,3.2,,
-function,PyBuffer_FillContiguousStrides,3.11,,
-function,PyBuffer_FillInfo,3.11,,
-function,PyBuffer_FromContiguous,3.11,,
-function,PyBuffer_GetPointer,3.11,,
-function,PyBuffer_IsContiguous,3.11,,
-function,PyBuffer_Release,3.11,,
-function,PyBuffer_SizeFromFormat,3.11,,
-function,PyBuffer_ToContiguous,3.11,,
-var,PyByteArrayIter_Type,3.2,,
-function,PyByteArray_AsString,3.2,,
-function,PyByteArray_Concat,3.2,,
-function,PyByteArray_FromObject,3.2,,
-function,PyByteArray_FromStringAndSize,3.2,,
-function,PyByteArray_Resize,3.2,,
-function,PyByteArray_Size,3.2,,
-var,PyByteArray_Type,3.2,,
-var,PyBytesIter_Type,3.2,,
-function,PyBytes_AsString,3.2,,
-function,PyBytes_AsStringAndSize,3.2,,
-function,PyBytes_Concat,3.2,,
-function,PyBytes_ConcatAndDel,3.2,,
-function,PyBytes_DecodeEscape,3.2,,
-function,PyBytes_FromFormat,3.2,,
-function,PyBytes_FromFormatV,3.2,,
-function,PyBytes_FromObject,3.2,,
-function,PyBytes_FromString,3.2,,
-function,PyBytes_FromStringAndSize,3.2,,
-function,PyBytes_Repr,3.2,,
-function,PyBytes_Size,3.2,,
-var,PyBytes_Type,3.2,,
+func,PyAIter_Check,3.10,,
+func,PyArg_Parse,3.2,,
+func,PyArg_ParseTuple,3.2,,
+func,PyArg_ParseTupleAndKeywords,3.2,,
+func,PyArg_UnpackTuple,3.2,,
+func,PyArg_VaParse,3.2,,
+func,PyArg_VaParseTupleAndKeywords,3.2,,
+func,PyArg_ValidateKeywordArguments,3.2,,
+data,PyBaseObject_Type,3.2,,
+func,PyBool_FromLong,3.2,,
+data,PyBool_Type,3.2,,
+func,PyBuffer_FillContiguousStrides,3.11,,
+func,PyBuffer_FillInfo,3.11,,
+func,PyBuffer_FromContiguous,3.11,,
+func,PyBuffer_GetPointer,3.11,,
+func,PyBuffer_IsContiguous,3.11,,
+func,PyBuffer_Release,3.11,,
+func,PyBuffer_SizeFromFormat,3.11,,
+func,PyBuffer_ToContiguous,3.11,,
+data,PyByteArrayIter_Type,3.2,,
+func,PyByteArray_AsString,3.2,,
+func,PyByteArray_Concat,3.2,,
+func,PyByteArray_FromObject,3.2,,
+func,PyByteArray_FromStringAndSize,3.2,,
+func,PyByteArray_Resize,3.2,,
+func,PyByteArray_Size,3.2,,
+data,PyByteArray_Type,3.2,,
+data,PyBytesIter_Type,3.2,,
+func,PyBytes_AsString,3.2,,
+func,PyBytes_AsStringAndSize,3.2,,
+func,PyBytes_Concat,3.2,,
+func,PyBytes_ConcatAndDel,3.2,,
+func,PyBytes_DecodeEscape,3.2,,
+func,PyBytes_FromFormat,3.2,,
+func,PyBytes_FromFormatV,3.2,,
+func,PyBytes_FromObject,3.2,,
+func,PyBytes_FromString,3.2,,
+func,PyBytes_FromStringAndSize,3.2,,
+func,PyBytes_Repr,3.2,,
+func,PyBytes_Size,3.2,,
+data,PyBytes_Type,3.2,,
type,PyCFunction,3.2,,
type,PyCFunctionWithKeywords,3.2,,
-function,PyCFunction_Call,3.2,,
-function,PyCFunction_GetFlags,3.2,,
-function,PyCFunction_GetFunction,3.2,,
-function,PyCFunction_GetSelf,3.2,,
-function,PyCFunction_New,3.4,,
-function,PyCFunction_NewEx,3.2,,
-var,PyCFunction_Type,3.2,,
-function,PyCMethod_New,3.9,,
-function,PyCallIter_New,3.2,,
-var,PyCallIter_Type,3.2,,
-function,PyCallable_Check,3.2,,
+func,PyCFunction_Call,3.2,,
+func,PyCFunction_GetFlags,3.2,,
+func,PyCFunction_GetFunction,3.2,,
+func,PyCFunction_GetSelf,3.2,,
+func,PyCFunction_New,3.4,,
+func,PyCFunction_NewEx,3.2,,
+data,PyCFunction_Type,3.2,,
+func,PyCMethod_New,3.9,,
+func,PyCallIter_New,3.2,,
+data,PyCallIter_Type,3.2,,
+func,PyCallable_Check,3.2,,
type,PyCapsule_Destructor,3.2,,
-function,PyCapsule_GetContext,3.2,,
-function,PyCapsule_GetDestructor,3.2,,
-function,PyCapsule_GetName,3.2,,
-function,PyCapsule_GetPointer,3.2,,
-function,PyCapsule_Import,3.2,,
-function,PyCapsule_IsValid,3.2,,
-function,PyCapsule_New,3.2,,
-function,PyCapsule_SetContext,3.2,,
-function,PyCapsule_SetDestructor,3.2,,
-function,PyCapsule_SetName,3.2,,
-function,PyCapsule_SetPointer,3.2,,
-var,PyCapsule_Type,3.2,,
-var,PyClassMethodDescr_Type,3.2,,
-function,PyCodec_BackslashReplaceErrors,3.2,,
-function,PyCodec_Decode,3.2,,
-function,PyCodec_Decoder,3.2,,
-function,PyCodec_Encode,3.2,,
-function,PyCodec_Encoder,3.2,,
-function,PyCodec_IgnoreErrors,3.2,,
-function,PyCodec_IncrementalDecoder,3.2,,
-function,PyCodec_IncrementalEncoder,3.2,,
-function,PyCodec_KnownEncoding,3.2,,
-function,PyCodec_LookupError,3.2,,
-function,PyCodec_NameReplaceErrors,3.7,,
-function,PyCodec_Register,3.2,,
-function,PyCodec_RegisterError,3.2,,
-function,PyCodec_ReplaceErrors,3.2,,
-function,PyCodec_StreamReader,3.2,,
-function,PyCodec_StreamWriter,3.2,,
-function,PyCodec_StrictErrors,3.2,,
-function,PyCodec_Unregister,3.10,,
-function,PyCodec_XMLCharRefReplaceErrors,3.2,,
-function,PyComplex_FromDoubles,3.2,,
-function,PyComplex_ImagAsDouble,3.2,,
-function,PyComplex_RealAsDouble,3.2,,
-var,PyComplex_Type,3.2,,
-function,PyDescr_NewClassMethod,3.2,,
-function,PyDescr_NewGetSet,3.2,,
-function,PyDescr_NewMember,3.2,,
-function,PyDescr_NewMethod,3.2,,
-var,PyDictItems_Type,3.2,,
-var,PyDictIterItem_Type,3.2,,
-var,PyDictIterKey_Type,3.2,,
-var,PyDictIterValue_Type,3.2,,
-var,PyDictKeys_Type,3.2,,
-function,PyDictProxy_New,3.2,,
-var,PyDictProxy_Type,3.2,,
-var,PyDictRevIterItem_Type,3.8,,
-var,PyDictRevIterKey_Type,3.8,,
-var,PyDictRevIterValue_Type,3.8,,
-var,PyDictValues_Type,3.2,,
-function,PyDict_Clear,3.2,,
-function,PyDict_Contains,3.2,,
-function,PyDict_Copy,3.2,,
-function,PyDict_DelItem,3.2,,
-function,PyDict_DelItemString,3.2,,
-function,PyDict_GetItem,3.2,,
-function,PyDict_GetItemString,3.2,,
-function,PyDict_GetItemWithError,3.2,,
-function,PyDict_Items,3.2,,
-function,PyDict_Keys,3.2,,
-function,PyDict_Merge,3.2,,
-function,PyDict_MergeFromSeq2,3.2,,
-function,PyDict_New,3.2,,
-function,PyDict_Next,3.2,,
-function,PyDict_SetItem,3.2,,
-function,PyDict_SetItemString,3.2,,
-function,PyDict_Size,3.2,,
-var,PyDict_Type,3.2,,
-function,PyDict_Update,3.2,,
-function,PyDict_Values,3.2,,
-var,PyEllipsis_Type,3.2,,
-var,PyEnum_Type,3.2,,
-function,PyErr_BadArgument,3.2,,
-function,PyErr_BadInternalCall,3.2,,
-function,PyErr_CheckSignals,3.2,,
-function,PyErr_Clear,3.2,,
-function,PyErr_Display,3.2,,
-function,PyErr_DisplayException,3.12,,
-function,PyErr_ExceptionMatches,3.2,,
-function,PyErr_Fetch,3.2,,
-function,PyErr_Format,3.2,,
-function,PyErr_FormatV,3.5,,
-function,PyErr_GetExcInfo,3.7,,
-function,PyErr_GetHandledException,3.11,,
-function,PyErr_GetRaisedException,3.12,,
-function,PyErr_GivenExceptionMatches,3.2,,
-function,PyErr_NewException,3.2,,
-function,PyErr_NewExceptionWithDoc,3.2,,
-function,PyErr_NoMemory,3.2,,
-function,PyErr_NormalizeException,3.2,,
-function,PyErr_Occurred,3.2,,
-function,PyErr_Print,3.2,,
-function,PyErr_PrintEx,3.2,,
-function,PyErr_ProgramText,3.2,,
-function,PyErr_ResourceWarning,3.6,,
-function,PyErr_Restore,3.2,,
-function,PyErr_SetExcFromWindowsErr,3.7,on Windows,
-function,PyErr_SetExcFromWindowsErrWithFilename,3.7,on Windows,
-function,PyErr_SetExcFromWindowsErrWithFilenameObject,3.7,on Windows,
-function,PyErr_SetExcFromWindowsErrWithFilenameObjects,3.7,on Windows,
-function,PyErr_SetExcInfo,3.7,,
-function,PyErr_SetFromErrno,3.2,,
-function,PyErr_SetFromErrnoWithFilename,3.2,,
-function,PyErr_SetFromErrnoWithFilenameObject,3.2,,
-function,PyErr_SetFromErrnoWithFilenameObjects,3.7,,
-function,PyErr_SetFromWindowsErr,3.7,on Windows,
-function,PyErr_SetFromWindowsErrWithFilename,3.7,on Windows,
-function,PyErr_SetHandledException,3.11,,
-function,PyErr_SetImportError,3.7,,
-function,PyErr_SetImportErrorSubclass,3.6,,
-function,PyErr_SetInterrupt,3.2,,
-function,PyErr_SetInterruptEx,3.10,,
-function,PyErr_SetNone,3.2,,
-function,PyErr_SetObject,3.2,,
-function,PyErr_SetRaisedException,3.12,,
-function,PyErr_SetString,3.2,,
-function,PyErr_SyntaxLocation,3.2,,
-function,PyErr_SyntaxLocationEx,3.7,,
-function,PyErr_WarnEx,3.2,,
-function,PyErr_WarnExplicit,3.2,,
-function,PyErr_WarnFormat,3.2,,
-function,PyErr_WriteUnraisable,3.2,,
-function,PyEval_AcquireLock,3.2,,
-function,PyEval_AcquireThread,3.2,,
-function,PyEval_CallFunction,3.2,,
-function,PyEval_CallMethod,3.2,,
-function,PyEval_CallObjectWithKeywords,3.2,,
-function,PyEval_EvalCode,3.2,,
-function,PyEval_EvalCodeEx,3.2,,
-function,PyEval_EvalFrame,3.2,,
-function,PyEval_EvalFrameEx,3.2,,
-function,PyEval_GetBuiltins,3.2,,
-function,PyEval_GetFrame,3.2,,
-function,PyEval_GetFuncDesc,3.2,,
-function,PyEval_GetFuncName,3.2,,
-function,PyEval_GetGlobals,3.2,,
-function,PyEval_GetLocals,3.2,,
-function,PyEval_InitThreads,3.2,,
-function,PyEval_ReleaseLock,3.2,,
-function,PyEval_ReleaseThread,3.2,,
-function,PyEval_RestoreThread,3.2,,
-function,PyEval_SaveThread,3.2,,
-function,PyEval_ThreadsInitialized,3.2,,
-var,PyExc_ArithmeticError,3.2,,
-var,PyExc_AssertionError,3.2,,
-var,PyExc_AttributeError,3.2,,
-var,PyExc_BaseException,3.2,,
-var,PyExc_BaseExceptionGroup,3.11,,
-var,PyExc_BlockingIOError,3.7,,
-var,PyExc_BrokenPipeError,3.7,,
-var,PyExc_BufferError,3.2,,
-var,PyExc_BytesWarning,3.2,,
-var,PyExc_ChildProcessError,3.7,,
-var,PyExc_ConnectionAbortedError,3.7,,
-var,PyExc_ConnectionError,3.7,,
-var,PyExc_ConnectionRefusedError,3.7,,
-var,PyExc_ConnectionResetError,3.7,,
-var,PyExc_DeprecationWarning,3.2,,
-var,PyExc_EOFError,3.2,,
-var,PyExc_EncodingWarning,3.10,,
-var,PyExc_EnvironmentError,3.2,,
-var,PyExc_Exception,3.2,,
-var,PyExc_FileExistsError,3.7,,
-var,PyExc_FileNotFoundError,3.7,,
-var,PyExc_FloatingPointError,3.2,,
-var,PyExc_FutureWarning,3.2,,
-var,PyExc_GeneratorExit,3.2,,
-var,PyExc_IOError,3.2,,
-var,PyExc_ImportError,3.2,,
-var,PyExc_ImportWarning,3.2,,
-var,PyExc_IndentationError,3.2,,
-var,PyExc_IndexError,3.2,,
-var,PyExc_InterruptedError,3.7,,
-var,PyExc_IsADirectoryError,3.7,,
-var,PyExc_KeyError,3.2,,
-var,PyExc_KeyboardInterrupt,3.2,,
-var,PyExc_LookupError,3.2,,
-var,PyExc_MemoryError,3.2,,
-var,PyExc_ModuleNotFoundError,3.6,,
-var,PyExc_NameError,3.2,,
-var,PyExc_NotADirectoryError,3.7,,
-var,PyExc_NotImplementedError,3.2,,
-var,PyExc_OSError,3.2,,
-var,PyExc_OverflowError,3.2,,
-var,PyExc_PendingDeprecationWarning,3.2,,
-var,PyExc_PermissionError,3.7,,
-var,PyExc_ProcessLookupError,3.7,,
-var,PyExc_RecursionError,3.7,,
-var,PyExc_ReferenceError,3.2,,
-var,PyExc_ResourceWarning,3.7,,
-var,PyExc_RuntimeError,3.2,,
-var,PyExc_RuntimeWarning,3.2,,
-var,PyExc_StopAsyncIteration,3.7,,
-var,PyExc_StopIteration,3.2,,
-var,PyExc_SyntaxError,3.2,,
-var,PyExc_SyntaxWarning,3.2,,
-var,PyExc_SystemError,3.2,,
-var,PyExc_SystemExit,3.2,,
-var,PyExc_TabError,3.2,,
-var,PyExc_TimeoutError,3.7,,
-var,PyExc_TypeError,3.2,,
-var,PyExc_UnboundLocalError,3.2,,
-var,PyExc_UnicodeDecodeError,3.2,,
-var,PyExc_UnicodeEncodeError,3.2,,
-var,PyExc_UnicodeError,3.2,,
-var,PyExc_UnicodeTranslateError,3.2,,
-var,PyExc_UnicodeWarning,3.2,,
-var,PyExc_UserWarning,3.2,,
-var,PyExc_ValueError,3.2,,
-var,PyExc_Warning,3.2,,
-var,PyExc_WindowsError,3.7,on Windows,
-var,PyExc_ZeroDivisionError,3.2,,
-function,PyExceptionClass_Name,3.8,,
-function,PyException_GetArgs,3.12,,
-function,PyException_GetCause,3.2,,
-function,PyException_GetContext,3.2,,
-function,PyException_GetTraceback,3.2,,
-function,PyException_SetArgs,3.12,,
-function,PyException_SetCause,3.2,,
-function,PyException_SetContext,3.2,,
-function,PyException_SetTraceback,3.2,,
-function,PyFile_FromFd,3.2,,
-function,PyFile_GetLine,3.2,,
-function,PyFile_WriteObject,3.2,,
-function,PyFile_WriteString,3.2,,
-var,PyFilter_Type,3.2,,
-function,PyFloat_AsDouble,3.2,,
-function,PyFloat_FromDouble,3.2,,
-function,PyFloat_FromString,3.2,,
-function,PyFloat_GetInfo,3.2,,
-function,PyFloat_GetMax,3.2,,
-function,PyFloat_GetMin,3.2,,
-var,PyFloat_Type,3.2,,
+func,PyCapsule_GetContext,3.2,,
+func,PyCapsule_GetDestructor,3.2,,
+func,PyCapsule_GetName,3.2,,
+func,PyCapsule_GetPointer,3.2,,
+func,PyCapsule_Import,3.2,,
+func,PyCapsule_IsValid,3.2,,
+func,PyCapsule_New,3.2,,
+func,PyCapsule_SetContext,3.2,,
+func,PyCapsule_SetDestructor,3.2,,
+func,PyCapsule_SetName,3.2,,
+func,PyCapsule_SetPointer,3.2,,
+data,PyCapsule_Type,3.2,,
+data,PyClassMethodDescr_Type,3.2,,
+func,PyCodec_BackslashReplaceErrors,3.2,,
+func,PyCodec_Decode,3.2,,
+func,PyCodec_Decoder,3.2,,
+func,PyCodec_Encode,3.2,,
+func,PyCodec_Encoder,3.2,,
+func,PyCodec_IgnoreErrors,3.2,,
+func,PyCodec_IncrementalDecoder,3.2,,
+func,PyCodec_IncrementalEncoder,3.2,,
+func,PyCodec_KnownEncoding,3.2,,
+func,PyCodec_LookupError,3.2,,
+func,PyCodec_NameReplaceErrors,3.7,,
+func,PyCodec_Register,3.2,,
+func,PyCodec_RegisterError,3.2,,
+func,PyCodec_ReplaceErrors,3.2,,
+func,PyCodec_StreamReader,3.2,,
+func,PyCodec_StreamWriter,3.2,,
+func,PyCodec_StrictErrors,3.2,,
+func,PyCodec_Unregister,3.10,,
+func,PyCodec_XMLCharRefReplaceErrors,3.2,,
+func,PyComplex_FromDoubles,3.2,,
+func,PyComplex_ImagAsDouble,3.2,,
+func,PyComplex_RealAsDouble,3.2,,
+data,PyComplex_Type,3.2,,
+func,PyDescr_NewClassMethod,3.2,,
+func,PyDescr_NewGetSet,3.2,,
+func,PyDescr_NewMember,3.2,,
+func,PyDescr_NewMethod,3.2,,
+data,PyDictItems_Type,3.2,,
+data,PyDictIterItem_Type,3.2,,
+data,PyDictIterKey_Type,3.2,,
+data,PyDictIterValue_Type,3.2,,
+data,PyDictKeys_Type,3.2,,
+func,PyDictProxy_New,3.2,,
+data,PyDictProxy_Type,3.2,,
+data,PyDictRevIterItem_Type,3.8,,
+data,PyDictRevIterKey_Type,3.8,,
+data,PyDictRevIterValue_Type,3.8,,
+data,PyDictValues_Type,3.2,,
+func,PyDict_Clear,3.2,,
+func,PyDict_Contains,3.2,,
+func,PyDict_Copy,3.2,,
+func,PyDict_DelItem,3.2,,
+func,PyDict_DelItemString,3.2,,
+func,PyDict_GetItem,3.2,,
+func,PyDict_GetItemString,3.2,,
+func,PyDict_GetItemWithError,3.2,,
+func,PyDict_Items,3.2,,
+func,PyDict_Keys,3.2,,
+func,PyDict_Merge,3.2,,
+func,PyDict_MergeFromSeq2,3.2,,
+func,PyDict_New,3.2,,
+func,PyDict_Next,3.2,,
+func,PyDict_SetItem,3.2,,
+func,PyDict_SetItemString,3.2,,
+func,PyDict_Size,3.2,,
+data,PyDict_Type,3.2,,
+func,PyDict_Update,3.2,,
+func,PyDict_Values,3.2,,
+data,PyEllipsis_Type,3.2,,
+data,PyEnum_Type,3.2,,
+func,PyErr_BadArgument,3.2,,
+func,PyErr_BadInternalCall,3.2,,
+func,PyErr_CheckSignals,3.2,,
+func,PyErr_Clear,3.2,,
+func,PyErr_Display,3.2,,
+func,PyErr_DisplayException,3.12,,
+func,PyErr_ExceptionMatches,3.2,,
+func,PyErr_Fetch,3.2,,
+func,PyErr_Format,3.2,,
+func,PyErr_FormatV,3.5,,
+func,PyErr_GetExcInfo,3.7,,
+func,PyErr_GetHandledException,3.11,,
+func,PyErr_GetRaisedException,3.12,,
+func,PyErr_GivenExceptionMatches,3.2,,
+func,PyErr_NewException,3.2,,
+func,PyErr_NewExceptionWithDoc,3.2,,
+func,PyErr_NoMemory,3.2,,
+func,PyErr_NormalizeException,3.2,,
+func,PyErr_Occurred,3.2,,
+func,PyErr_Print,3.2,,
+func,PyErr_PrintEx,3.2,,
+func,PyErr_ProgramText,3.2,,
+func,PyErr_ResourceWarning,3.6,,
+func,PyErr_Restore,3.2,,
+func,PyErr_SetExcFromWindowsErr,3.7,on Windows,
+func,PyErr_SetExcFromWindowsErrWithFilename,3.7,on Windows,
+func,PyErr_SetExcFromWindowsErrWithFilenameObject,3.7,on Windows,
+func,PyErr_SetExcFromWindowsErrWithFilenameObjects,3.7,on Windows,
+func,PyErr_SetExcInfo,3.7,,
+func,PyErr_SetFromErrno,3.2,,
+func,PyErr_SetFromErrnoWithFilename,3.2,,
+func,PyErr_SetFromErrnoWithFilenameObject,3.2,,
+func,PyErr_SetFromErrnoWithFilenameObjects,3.7,,
+func,PyErr_SetFromWindowsErr,3.7,on Windows,
+func,PyErr_SetFromWindowsErrWithFilename,3.7,on Windows,
+func,PyErr_SetHandledException,3.11,,
+func,PyErr_SetImportError,3.7,,
+func,PyErr_SetImportErrorSubclass,3.6,,
+func,PyErr_SetInterrupt,3.2,,
+func,PyErr_SetInterruptEx,3.10,,
+func,PyErr_SetNone,3.2,,
+func,PyErr_SetObject,3.2,,
+func,PyErr_SetRaisedException,3.12,,
+func,PyErr_SetString,3.2,,
+func,PyErr_SyntaxLocation,3.2,,
+func,PyErr_SyntaxLocationEx,3.7,,
+func,PyErr_WarnEx,3.2,,
+func,PyErr_WarnExplicit,3.2,,
+func,PyErr_WarnFormat,3.2,,
+func,PyErr_WriteUnraisable,3.2,,
+func,PyEval_AcquireLock,3.2,,
+func,PyEval_AcquireThread,3.2,,
+func,PyEval_CallFunction,3.2,,
+func,PyEval_CallMethod,3.2,,
+func,PyEval_CallObjectWithKeywords,3.2,,
+func,PyEval_EvalCode,3.2,,
+func,PyEval_EvalCodeEx,3.2,,
+func,PyEval_EvalFrame,3.2,,
+func,PyEval_EvalFrameEx,3.2,,
+func,PyEval_GetBuiltins,3.2,,
+func,PyEval_GetFrame,3.2,,
+func,PyEval_GetFuncDesc,3.2,,
+func,PyEval_GetFuncName,3.2,,
+func,PyEval_GetGlobals,3.2,,
+func,PyEval_GetLocals,3.2,,
+func,PyEval_InitThreads,3.2,,
+func,PyEval_ReleaseLock,3.2,,
+func,PyEval_ReleaseThread,3.2,,
+func,PyEval_RestoreThread,3.2,,
+func,PyEval_SaveThread,3.2,,
+func,PyEval_ThreadsInitialized,3.2,,
+data,PyExc_ArithmeticError,3.2,,
+data,PyExc_AssertionError,3.2,,
+data,PyExc_AttributeError,3.2,,
+data,PyExc_BaseException,3.2,,
+data,PyExc_BaseExceptionGroup,3.11,,
+data,PyExc_BlockingIOError,3.7,,
+data,PyExc_BrokenPipeError,3.7,,
+data,PyExc_BufferError,3.2,,
+data,PyExc_BytesWarning,3.2,,
+data,PyExc_ChildProcessError,3.7,,
+data,PyExc_ConnectionAbortedError,3.7,,
+data,PyExc_ConnectionError,3.7,,
+data,PyExc_ConnectionRefusedError,3.7,,
+data,PyExc_ConnectionResetError,3.7,,
+data,PyExc_DeprecationWarning,3.2,,
+data,PyExc_EOFError,3.2,,
+data,PyExc_EncodingWarning,3.10,,
+data,PyExc_EnvironmentError,3.2,,
+data,PyExc_Exception,3.2,,
+data,PyExc_FileExistsError,3.7,,
+data,PyExc_FileNotFoundError,3.7,,
+data,PyExc_FloatingPointError,3.2,,
+data,PyExc_FutureWarning,3.2,,
+data,PyExc_GeneratorExit,3.2,,
+data,PyExc_IOError,3.2,,
+data,PyExc_ImportError,3.2,,
+data,PyExc_ImportWarning,3.2,,
+data,PyExc_IndentationError,3.2,,
+data,PyExc_IndexError,3.2,,
+data,PyExc_InterruptedError,3.7,,
+data,PyExc_IsADirectoryError,3.7,,
+data,PyExc_KeyError,3.2,,
+data,PyExc_KeyboardInterrupt,3.2,,
+data,PyExc_LookupError,3.2,,
+data,PyExc_MemoryError,3.2,,
+data,PyExc_ModuleNotFoundError,3.6,,
+data,PyExc_NameError,3.2,,
+data,PyExc_NotADirectoryError,3.7,,
+data,PyExc_NotImplementedError,3.2,,
+data,PyExc_OSError,3.2,,
+data,PyExc_OverflowError,3.2,,
+data,PyExc_PendingDeprecationWarning,3.2,,
+data,PyExc_PermissionError,3.7,,
+data,PyExc_ProcessLookupError,3.7,,
+data,PyExc_RecursionError,3.7,,
+data,PyExc_ReferenceError,3.2,,
+data,PyExc_ResourceWarning,3.7,,
+data,PyExc_RuntimeError,3.2,,
+data,PyExc_RuntimeWarning,3.2,,
+data,PyExc_StopAsyncIteration,3.7,,
+data,PyExc_StopIteration,3.2,,
+data,PyExc_SyntaxError,3.2,,
+data,PyExc_SyntaxWarning,3.2,,
+data,PyExc_SystemError,3.2,,
+data,PyExc_SystemExit,3.2,,
+data,PyExc_TabError,3.2,,
+data,PyExc_TimeoutError,3.7,,
+data,PyExc_TypeError,3.2,,
+data,PyExc_UnboundLocalError,3.2,,
+data,PyExc_UnicodeDecodeError,3.2,,
+data,PyExc_UnicodeEncodeError,3.2,,
+data,PyExc_UnicodeError,3.2,,
+data,PyExc_UnicodeTranslateError,3.2,,
+data,PyExc_UnicodeWarning,3.2,,
+data,PyExc_UserWarning,3.2,,
+data,PyExc_ValueError,3.2,,
+data,PyExc_Warning,3.2,,
+data,PyExc_WindowsError,3.7,on Windows,
+data,PyExc_ZeroDivisionError,3.2,,
+func,PyExceptionClass_Name,3.8,,
+func,PyException_GetArgs,3.12,,
+func,PyException_GetCause,3.2,,
+func,PyException_GetContext,3.2,,
+func,PyException_GetTraceback,3.2,,
+func,PyException_SetArgs,3.12,,
+func,PyException_SetCause,3.2,,
+func,PyException_SetContext,3.2,,
+func,PyException_SetTraceback,3.2,,
+func,PyFile_FromFd,3.2,,
+func,PyFile_GetLine,3.2,,
+func,PyFile_WriteObject,3.2,,
+func,PyFile_WriteString,3.2,,
+data,PyFilter_Type,3.2,,
+func,PyFloat_AsDouble,3.2,,
+func,PyFloat_FromDouble,3.2,,
+func,PyFloat_FromString,3.2,,
+func,PyFloat_GetInfo,3.2,,
+func,PyFloat_GetMax,3.2,,
+func,PyFloat_GetMin,3.2,,
+data,PyFloat_Type,3.2,,
type,PyFrameObject,3.2,,opaque
-function,PyFrame_GetCode,3.10,,
-function,PyFrame_GetLineNumber,3.10,,
-function,PyFrozenSet_New,3.2,,
-var,PyFrozenSet_Type,3.2,,
-function,PyGC_Collect,3.2,,
-function,PyGC_Disable,3.10,,
-function,PyGC_Enable,3.10,,
-function,PyGC_IsEnabled,3.10,,
-function,PyGILState_Ensure,3.2,,
-function,PyGILState_GetThisThreadState,3.2,,
-function,PyGILState_Release,3.2,,
+func,PyFrame_GetCode,3.10,,
+func,PyFrame_GetLineNumber,3.10,,
+func,PyFrozenSet_New,3.2,,
+data,PyFrozenSet_Type,3.2,,
+func,PyGC_Collect,3.2,,
+func,PyGC_Disable,3.10,,
+func,PyGC_Enable,3.10,,
+func,PyGC_IsEnabled,3.10,,
+func,PyGILState_Ensure,3.2,,
+func,PyGILState_GetThisThreadState,3.2,,
+func,PyGILState_Release,3.2,,
type,PyGILState_STATE,3.2,,
type,PyGetSetDef,3.2,,full-abi
-var,PyGetSetDescr_Type,3.2,,
-function,PyImport_AddModule,3.2,,
-function,PyImport_AddModuleObject,3.7,,
-function,PyImport_AppendInittab,3.2,,
-function,PyImport_ExecCodeModule,3.2,,
-function,PyImport_ExecCodeModuleEx,3.2,,
-function,PyImport_ExecCodeModuleObject,3.7,,
-function,PyImport_ExecCodeModuleWithPathnames,3.2,,
-function,PyImport_GetImporter,3.2,,
-function,PyImport_GetMagicNumber,3.2,,
-function,PyImport_GetMagicTag,3.2,,
-function,PyImport_GetModule,3.8,,
-function,PyImport_GetModuleDict,3.2,,
-function,PyImport_Import,3.2,,
-function,PyImport_ImportFrozenModule,3.2,,
-function,PyImport_ImportFrozenModuleObject,3.7,,
-function,PyImport_ImportModule,3.2,,
-function,PyImport_ImportModuleLevel,3.2,,
-function,PyImport_ImportModuleLevelObject,3.7,,
-function,PyImport_ImportModuleNoBlock,3.2,,
-function,PyImport_ReloadModule,3.2,,
-function,PyIndex_Check,3.8,,
+data,PyGetSetDescr_Type,3.2,,
+func,PyImport_AddModule,3.2,,
+func,PyImport_AddModuleObject,3.7,,
+func,PyImport_AppendInittab,3.2,,
+func,PyImport_ExecCodeModule,3.2,,
+func,PyImport_ExecCodeModuleEx,3.2,,
+func,PyImport_ExecCodeModuleObject,3.7,,
+func,PyImport_ExecCodeModuleWithPathnames,3.2,,
+func,PyImport_GetImporter,3.2,,
+func,PyImport_GetMagicNumber,3.2,,
+func,PyImport_GetMagicTag,3.2,,
+func,PyImport_GetModule,3.8,,
+func,PyImport_GetModuleDict,3.2,,
+func,PyImport_Import,3.2,,
+func,PyImport_ImportFrozenModule,3.2,,
+func,PyImport_ImportFrozenModuleObject,3.7,,
+func,PyImport_ImportModule,3.2,,
+func,PyImport_ImportModuleLevel,3.2,,
+func,PyImport_ImportModuleLevelObject,3.7,,
+func,PyImport_ImportModuleNoBlock,3.2,,
+func,PyImport_ReloadModule,3.2,,
+func,PyIndex_Check,3.8,,
type,PyInterpreterState,3.2,,opaque
-function,PyInterpreterState_Clear,3.2,,
-function,PyInterpreterState_Delete,3.2,,
-function,PyInterpreterState_Get,3.9,,
-function,PyInterpreterState_GetDict,3.8,,
-function,PyInterpreterState_GetID,3.7,,
-function,PyInterpreterState_New,3.2,,
-function,PyIter_Check,3.8,,
-function,PyIter_Next,3.2,,
-function,PyIter_Send,3.10,,
-var,PyListIter_Type,3.2,,
-var,PyListRevIter_Type,3.2,,
-function,PyList_Append,3.2,,
-function,PyList_AsTuple,3.2,,
-function,PyList_GetItem,3.2,,
-function,PyList_GetSlice,3.2,,
-function,PyList_Insert,3.2,,
-function,PyList_New,3.2,,
-function,PyList_Reverse,3.2,,
-function,PyList_SetItem,3.2,,
-function,PyList_SetSlice,3.2,,
-function,PyList_Size,3.2,,
-function,PyList_Sort,3.2,,
-var,PyList_Type,3.2,,
+func,PyInterpreterState_Clear,3.2,,
+func,PyInterpreterState_Delete,3.2,,
+func,PyInterpreterState_Get,3.9,,
+func,PyInterpreterState_GetDict,3.8,,
+func,PyInterpreterState_GetID,3.7,,
+func,PyInterpreterState_New,3.2,,
+func,PyIter_Check,3.8,,
+func,PyIter_Next,3.2,,
+func,PyIter_Send,3.10,,
+data,PyListIter_Type,3.2,,
+data,PyListRevIter_Type,3.2,,
+func,PyList_Append,3.2,,
+func,PyList_AsTuple,3.2,,
+func,PyList_GetItem,3.2,,
+func,PyList_GetSlice,3.2,,
+func,PyList_Insert,3.2,,
+func,PyList_New,3.2,,
+func,PyList_Reverse,3.2,,
+func,PyList_SetItem,3.2,,
+func,PyList_SetSlice,3.2,,
+func,PyList_Size,3.2,,
+func,PyList_Sort,3.2,,
+data,PyList_Type,3.2,,
type,PyLongObject,3.2,,opaque
-var,PyLongRangeIter_Type,3.2,,
-function,PyLong_AsDouble,3.2,,
-function,PyLong_AsLong,3.2,,
-function,PyLong_AsLongAndOverflow,3.2,,
-function,PyLong_AsLongLong,3.2,,
-function,PyLong_AsLongLongAndOverflow,3.2,,
-function,PyLong_AsSize_t,3.2,,
-function,PyLong_AsSsize_t,3.2,,
-function,PyLong_AsUnsignedLong,3.2,,
-function,PyLong_AsUnsignedLongLong,3.2,,
-function,PyLong_AsUnsignedLongLongMask,3.2,,
-function,PyLong_AsUnsignedLongMask,3.2,,
-function,PyLong_AsVoidPtr,3.2,,
-function,PyLong_FromDouble,3.2,,
-function,PyLong_FromLong,3.2,,
-function,PyLong_FromLongLong,3.2,,
-function,PyLong_FromSize_t,3.2,,
-function,PyLong_FromSsize_t,3.2,,
-function,PyLong_FromString,3.2,,
-function,PyLong_FromUnsignedLong,3.2,,
-function,PyLong_FromUnsignedLongLong,3.2,,
-function,PyLong_FromVoidPtr,3.2,,
-function,PyLong_GetInfo,3.2,,
-var,PyLong_Type,3.2,,
-var,PyMap_Type,3.2,,
-function,PyMapping_Check,3.2,,
-function,PyMapping_GetItemString,3.2,,
-function,PyMapping_HasKey,3.2,,
-function,PyMapping_HasKeyString,3.2,,
-function,PyMapping_Items,3.2,,
-function,PyMapping_Keys,3.2,,
-function,PyMapping_Length,3.2,,
-function,PyMapping_SetItemString,3.2,,
-function,PyMapping_Size,3.2,,
-function,PyMapping_Values,3.2,,
-function,PyMem_Calloc,3.7,,
-function,PyMem_Free,3.2,,
-function,PyMem_Malloc,3.2,,
-function,PyMem_Realloc,3.2,,
+data,PyLongRangeIter_Type,3.2,,
+func,PyLong_AsDouble,3.2,,
+func,PyLong_AsLong,3.2,,
+func,PyLong_AsLongAndOverflow,3.2,,
+func,PyLong_AsLongLong,3.2,,
+func,PyLong_AsLongLongAndOverflow,3.2,,
+func,PyLong_AsSize_t,3.2,,
+func,PyLong_AsSsize_t,3.2,,
+func,PyLong_AsUnsignedLong,3.2,,
+func,PyLong_AsUnsignedLongLong,3.2,,
+func,PyLong_AsUnsignedLongLongMask,3.2,,
+func,PyLong_AsUnsignedLongMask,3.2,,
+func,PyLong_AsVoidPtr,3.2,,
+func,PyLong_FromDouble,3.2,,
+func,PyLong_FromLong,3.2,,
+func,PyLong_FromLongLong,3.2,,
+func,PyLong_FromSize_t,3.2,,
+func,PyLong_FromSsize_t,3.2,,
+func,PyLong_FromString,3.2,,
+func,PyLong_FromUnsignedLong,3.2,,
+func,PyLong_FromUnsignedLongLong,3.2,,
+func,PyLong_FromVoidPtr,3.2,,
+func,PyLong_GetInfo,3.2,,
+data,PyLong_Type,3.2,,
+data,PyMap_Type,3.2,,
+func,PyMapping_Check,3.2,,
+func,PyMapping_GetItemString,3.2,,
+func,PyMapping_HasKey,3.2,,
+func,PyMapping_HasKeyString,3.2,,
+func,PyMapping_Items,3.2,,
+func,PyMapping_Keys,3.2,,
+func,PyMapping_Length,3.2,,
+func,PyMapping_SetItemString,3.2,,
+func,PyMapping_Size,3.2,,
+func,PyMapping_Values,3.2,,
+func,PyMem_Calloc,3.7,,
+func,PyMem_Free,3.2,,
+func,PyMem_Malloc,3.2,,
+func,PyMem_Realloc,3.2,,
type,PyMemberDef,3.2,,full-abi
-var,PyMemberDescr_Type,3.2,,
-function,PyMember_GetOne,3.2,,
-function,PyMember_SetOne,3.2,,
-function,PyMemoryView_FromBuffer,3.11,,
-function,PyMemoryView_FromMemory,3.7,,
-function,PyMemoryView_FromObject,3.2,,
-function,PyMemoryView_GetContiguous,3.2,,
-var,PyMemoryView_Type,3.2,,
+data,PyMemberDescr_Type,3.2,,
+func,PyMember_GetOne,3.2,,
+func,PyMember_SetOne,3.2,,
+func,PyMemoryView_FromBuffer,3.11,,
+func,PyMemoryView_FromMemory,3.7,,
+func,PyMemoryView_FromObject,3.2,,
+func,PyMemoryView_GetContiguous,3.2,,
+data,PyMemoryView_Type,3.2,,
type,PyMethodDef,3.2,,full-abi
-var,PyMethodDescr_Type,3.2,,
+data,PyMethodDescr_Type,3.2,,
type,PyModuleDef,3.2,,full-abi
type,PyModuleDef_Base,3.2,,full-abi
-function,PyModuleDef_Init,3.5,,
-var,PyModuleDef_Type,3.5,,
-function,PyModule_AddFunctions,3.7,,
-function,PyModule_AddIntConstant,3.2,,
-function,PyModule_AddObject,3.2,,
-function,PyModule_AddObjectRef,3.10,,
-function,PyModule_AddStringConstant,3.2,,
-function,PyModule_AddType,3.10,,
-function,PyModule_Create2,3.2,,
-function,PyModule_ExecDef,3.7,,
-function,PyModule_FromDefAndSpec2,3.7,,
-function,PyModule_GetDef,3.2,,
-function,PyModule_GetDict,3.2,,
-function,PyModule_GetFilename,3.2,,
-function,PyModule_GetFilenameObject,3.2,,
-function,PyModule_GetName,3.2,,
-function,PyModule_GetNameObject,3.7,,
-function,PyModule_GetState,3.2,,
-function,PyModule_New,3.2,,
-function,PyModule_NewObject,3.7,,
-function,PyModule_SetDocString,3.7,,
-var,PyModule_Type,3.2,,
-function,PyNumber_Absolute,3.2,,
-function,PyNumber_Add,3.2,,
-function,PyNumber_And,3.2,,
-function,PyNumber_AsSsize_t,3.2,,
-function,PyNumber_Check,3.2,,
-function,PyNumber_Divmod,3.2,,
-function,PyNumber_Float,3.2,,
-function,PyNumber_FloorDivide,3.2,,
-function,PyNumber_InPlaceAdd,3.2,,
-function,PyNumber_InPlaceAnd,3.2,,
-function,PyNumber_InPlaceFloorDivide,3.2,,
-function,PyNumber_InPlaceLshift,3.2,,
-function,PyNumber_InPlaceMatrixMultiply,3.7,,
-function,PyNumber_InPlaceMultiply,3.2,,
-function,PyNumber_InPlaceOr,3.2,,
-function,PyNumber_InPlacePower,3.2,,
-function,PyNumber_InPlaceRemainder,3.2,,
-function,PyNumber_InPlaceRshift,3.2,,
-function,PyNumber_InPlaceSubtract,3.2,,
-function,PyNumber_InPlaceTrueDivide,3.2,,
-function,PyNumber_InPlaceXor,3.2,,
-function,PyNumber_Index,3.2,,
-function,PyNumber_Invert,3.2,,
-function,PyNumber_Long,3.2,,
-function,PyNumber_Lshift,3.2,,
-function,PyNumber_MatrixMultiply,3.7,,
-function,PyNumber_Multiply,3.2,,
-function,PyNumber_Negative,3.2,,
-function,PyNumber_Or,3.2,,
-function,PyNumber_Positive,3.2,,
-function,PyNumber_Power,3.2,,
-function,PyNumber_Remainder,3.2,,
-function,PyNumber_Rshift,3.2,,
-function,PyNumber_Subtract,3.2,,
-function,PyNumber_ToBase,3.2,,
-function,PyNumber_TrueDivide,3.2,,
-function,PyNumber_Xor,3.2,,
-function,PyOS_AfterFork,3.2,on platforms with fork(),
-function,PyOS_AfterFork_Child,3.7,on platforms with fork(),
-function,PyOS_AfterFork_Parent,3.7,on platforms with fork(),
-function,PyOS_BeforeFork,3.7,on platforms with fork(),
-function,PyOS_CheckStack,3.7,on platforms with USE_STACKCHECK,
-function,PyOS_FSPath,3.6,,
-var,PyOS_InputHook,3.2,,
-function,PyOS_InterruptOccurred,3.2,,
-function,PyOS_double_to_string,3.2,,
-function,PyOS_getsig,3.2,,
-function,PyOS_mystricmp,3.2,,
-function,PyOS_mystrnicmp,3.2,,
-function,PyOS_setsig,3.2,,
+func,PyModuleDef_Init,3.5,,
+data,PyModuleDef_Type,3.5,,
+func,PyModule_AddFunctions,3.7,,
+func,PyModule_AddIntConstant,3.2,,
+func,PyModule_AddObject,3.2,,
+func,PyModule_AddObjectRef,3.10,,
+func,PyModule_AddStringConstant,3.2,,
+func,PyModule_AddType,3.10,,
+func,PyModule_Create2,3.2,,
+func,PyModule_ExecDef,3.7,,
+func,PyModule_FromDefAndSpec2,3.7,,
+func,PyModule_GetDef,3.2,,
+func,PyModule_GetDict,3.2,,
+func,PyModule_GetFilename,3.2,,
+func,PyModule_GetFilenameObject,3.2,,
+func,PyModule_GetName,3.2,,
+func,PyModule_GetNameObject,3.7,,
+func,PyModule_GetState,3.2,,
+func,PyModule_New,3.2,,
+func,PyModule_NewObject,3.7,,
+func,PyModule_SetDocString,3.7,,
+data,PyModule_Type,3.2,,
+func,PyNumber_Absolute,3.2,,
+func,PyNumber_Add,3.2,,
+func,PyNumber_And,3.2,,
+func,PyNumber_AsSsize_t,3.2,,
+func,PyNumber_Check,3.2,,
+func,PyNumber_Divmod,3.2,,
+func,PyNumber_Float,3.2,,
+func,PyNumber_FloorDivide,3.2,,
+func,PyNumber_InPlaceAdd,3.2,,
+func,PyNumber_InPlaceAnd,3.2,,
+func,PyNumber_InPlaceFloorDivide,3.2,,
+func,PyNumber_InPlaceLshift,3.2,,
+func,PyNumber_InPlaceMatrixMultiply,3.7,,
+func,PyNumber_InPlaceMultiply,3.2,,
+func,PyNumber_InPlaceOr,3.2,,
+func,PyNumber_InPlacePower,3.2,,
+func,PyNumber_InPlaceRemainder,3.2,,
+func,PyNumber_InPlaceRshift,3.2,,
+func,PyNumber_InPlaceSubtract,3.2,,
+func,PyNumber_InPlaceTrueDivide,3.2,,
+func,PyNumber_InPlaceXor,3.2,,
+func,PyNumber_Index,3.2,,
+func,PyNumber_Invert,3.2,,
+func,PyNumber_Long,3.2,,
+func,PyNumber_Lshift,3.2,,
+func,PyNumber_MatrixMultiply,3.7,,
+func,PyNumber_Multiply,3.2,,
+func,PyNumber_Negative,3.2,,
+func,PyNumber_Or,3.2,,
+func,PyNumber_Positive,3.2,,
+func,PyNumber_Power,3.2,,
+func,PyNumber_Remainder,3.2,,
+func,PyNumber_Rshift,3.2,,
+func,PyNumber_Subtract,3.2,,
+func,PyNumber_ToBase,3.2,,
+func,PyNumber_TrueDivide,3.2,,
+func,PyNumber_Xor,3.2,,
+func,PyOS_AfterFork,3.2,on platforms with fork(),
+func,PyOS_AfterFork_Child,3.7,on platforms with fork(),
+func,PyOS_AfterFork_Parent,3.7,on platforms with fork(),
+func,PyOS_BeforeFork,3.7,on platforms with fork(),
+func,PyOS_CheckStack,3.7,on platforms with USE_STACKCHECK,
+func,PyOS_FSPath,3.6,,
+data,PyOS_InputHook,3.2,,
+func,PyOS_InterruptOccurred,3.2,,
+func,PyOS_double_to_string,3.2,,
+func,PyOS_getsig,3.2,,
+func,PyOS_mystricmp,3.2,,
+func,PyOS_mystrnicmp,3.2,,
+func,PyOS_setsig,3.2,,
type,PyOS_sighandler_t,3.2,,
-function,PyOS_snprintf,3.2,,
-function,PyOS_string_to_double,3.2,,
-function,PyOS_strtol,3.2,,
-function,PyOS_strtoul,3.2,,
-function,PyOS_vsnprintf,3.2,,
+func,PyOS_snprintf,3.2,,
+func,PyOS_string_to_double,3.2,,
+func,PyOS_strtol,3.2,,
+func,PyOS_strtoul,3.2,,
+func,PyOS_vsnprintf,3.2,,
type,PyObject,3.2,,members
member,PyObject.ob_refcnt,3.2,,
member,PyObject.ob_type,3.2,,
-function,PyObject_ASCII,3.2,,
-function,PyObject_AsCharBuffer,3.2,,
-function,PyObject_AsFileDescriptor,3.2,,
-function,PyObject_AsReadBuffer,3.2,,
-function,PyObject_AsWriteBuffer,3.2,,
-function,PyObject_Bytes,3.2,,
-function,PyObject_Call,3.2,,
-function,PyObject_CallFunction,3.2,,
-function,PyObject_CallFunctionObjArgs,3.2,,
-function,PyObject_CallMethod,3.2,,
-function,PyObject_CallMethodObjArgs,3.2,,
-function,PyObject_CallNoArgs,3.10,,
-function,PyObject_CallObject,3.2,,
-function,PyObject_Calloc,3.7,,
-function,PyObject_CheckBuffer,3.11,,
-function,PyObject_CheckReadBuffer,3.2,,
-function,PyObject_ClearWeakRefs,3.2,,
-function,PyObject_CopyData,3.11,,
-function,PyObject_DelItem,3.2,,
-function,PyObject_DelItemString,3.2,,
-function,PyObject_Dir,3.2,,
-function,PyObject_Format,3.2,,
-function,PyObject_Free,3.2,,
-function,PyObject_GC_Del,3.2,,
-function,PyObject_GC_IsFinalized,3.9,,
-function,PyObject_GC_IsTracked,3.9,,
-function,PyObject_GC_Track,3.2,,
-function,PyObject_GC_UnTrack,3.2,,
-function,PyObject_GenericGetAttr,3.2,,
-function,PyObject_GenericGetDict,3.10,,
-function,PyObject_GenericSetAttr,3.2,,
-function,PyObject_GenericSetDict,3.7,,
-function,PyObject_GetAIter,3.10,,
-function,PyObject_GetAttr,3.2,,
-function,PyObject_GetAttrString,3.2,,
-function,PyObject_GetBuffer,3.11,,
-function,PyObject_GetItem,3.2,,
-function,PyObject_GetIter,3.2,,
-function,PyObject_GetTypeData,3.12,,
-function,PyObject_HasAttr,3.2,,
-function,PyObject_HasAttrString,3.2,,
-function,PyObject_Hash,3.2,,
-function,PyObject_HashNotImplemented,3.2,,
-function,PyObject_Init,3.2,,
-function,PyObject_InitVar,3.2,,
-function,PyObject_IsInstance,3.2,,
-function,PyObject_IsSubclass,3.2,,
-function,PyObject_IsTrue,3.2,,
-function,PyObject_Length,3.2,,
-function,PyObject_Malloc,3.2,,
-function,PyObject_Not,3.2,,
-function,PyObject_Realloc,3.2,,
-function,PyObject_Repr,3.2,,
-function,PyObject_RichCompare,3.2,,
-function,PyObject_RichCompareBool,3.2,,
-function,PyObject_SelfIter,3.2,,
-function,PyObject_SetAttr,3.2,,
-function,PyObject_SetAttrString,3.2,,
-function,PyObject_SetItem,3.2,,
-function,PyObject_Size,3.2,,
-function,PyObject_Str,3.2,,
-function,PyObject_Type,3.2,,
-function,PyObject_Vectorcall,3.12,,
-function,PyObject_VectorcallMethod,3.12,,
-var,PyProperty_Type,3.2,,
-var,PyRangeIter_Type,3.2,,
-var,PyRange_Type,3.2,,
-var,PyReversed_Type,3.2,,
-function,PySeqIter_New,3.2,,
-var,PySeqIter_Type,3.2,,
-function,PySequence_Check,3.2,,
-function,PySequence_Concat,3.2,,
-function,PySequence_Contains,3.2,,
-function,PySequence_Count,3.2,,
-function,PySequence_DelItem,3.2,,
-function,PySequence_DelSlice,3.2,,
-function,PySequence_Fast,3.2,,
-function,PySequence_GetItem,3.2,,
-function,PySequence_GetSlice,3.2,,
-function,PySequence_In,3.2,,
-function,PySequence_InPlaceConcat,3.2,,
-function,PySequence_InPlaceRepeat,3.2,,
-function,PySequence_Index,3.2,,
-function,PySequence_Length,3.2,,
-function,PySequence_List,3.2,,
-function,PySequence_Repeat,3.2,,
-function,PySequence_SetItem,3.2,,
-function,PySequence_SetSlice,3.2,,
-function,PySequence_Size,3.2,,
-function,PySequence_Tuple,3.2,,
-var,PySetIter_Type,3.2,,
-function,PySet_Add,3.2,,
-function,PySet_Clear,3.2,,
-function,PySet_Contains,3.2,,
-function,PySet_Discard,3.2,,
-function,PySet_New,3.2,,
-function,PySet_Pop,3.2,,
-function,PySet_Size,3.2,,
-var,PySet_Type,3.2,,
-function,PySlice_AdjustIndices,3.7,,
-function,PySlice_GetIndices,3.2,,
-function,PySlice_GetIndicesEx,3.2,,
-function,PySlice_New,3.2,,
-var,PySlice_Type,3.2,,
-function,PySlice_Unpack,3.7,,
-function,PyState_AddModule,3.3,,
-function,PyState_FindModule,3.2,,
-function,PyState_RemoveModule,3.3,,
+func,PyObject_ASCII,3.2,,
+func,PyObject_AsCharBuffer,3.2,,
+func,PyObject_AsFileDescriptor,3.2,,
+func,PyObject_AsReadBuffer,3.2,,
+func,PyObject_AsWriteBuffer,3.2,,
+func,PyObject_Bytes,3.2,,
+func,PyObject_Call,3.2,,
+func,PyObject_CallFunction,3.2,,
+func,PyObject_CallFunctionObjArgs,3.2,,
+func,PyObject_CallMethod,3.2,,
+func,PyObject_CallMethodObjArgs,3.2,,
+func,PyObject_CallNoArgs,3.10,,
+func,PyObject_CallObject,3.2,,
+func,PyObject_Calloc,3.7,,
+func,PyObject_CheckBuffer,3.11,,
+func,PyObject_CheckReadBuffer,3.2,,
+func,PyObject_ClearWeakRefs,3.2,,
+func,PyObject_CopyData,3.11,,
+func,PyObject_DelItem,3.2,,
+func,PyObject_DelItemString,3.2,,
+func,PyObject_Dir,3.2,,
+func,PyObject_Format,3.2,,
+func,PyObject_Free,3.2,,
+func,PyObject_GC_Del,3.2,,
+func,PyObject_GC_IsFinalized,3.9,,
+func,PyObject_GC_IsTracked,3.9,,
+func,PyObject_GC_Track,3.2,,
+func,PyObject_GC_UnTrack,3.2,,
+func,PyObject_GenericGetAttr,3.2,,
+func,PyObject_GenericGetDict,3.10,,
+func,PyObject_GenericSetAttr,3.2,,
+func,PyObject_GenericSetDict,3.7,,
+func,PyObject_GetAIter,3.10,,
+func,PyObject_GetAttr,3.2,,
+func,PyObject_GetAttrString,3.2,,
+func,PyObject_GetBuffer,3.11,,
+func,PyObject_GetItem,3.2,,
+func,PyObject_GetIter,3.2,,
+func,PyObject_GetTypeData,3.12,,
+func,PyObject_HasAttr,3.2,,
+func,PyObject_HasAttrString,3.2,,
+func,PyObject_Hash,3.2,,
+func,PyObject_HashNotImplemented,3.2,,
+func,PyObject_Init,3.2,,
+func,PyObject_InitVar,3.2,,
+func,PyObject_IsInstance,3.2,,
+func,PyObject_IsSubclass,3.2,,
+func,PyObject_IsTrue,3.2,,
+func,PyObject_Length,3.2,,
+func,PyObject_Malloc,3.2,,
+func,PyObject_Not,3.2,,
+func,PyObject_Realloc,3.2,,
+func,PyObject_Repr,3.2,,
+func,PyObject_RichCompare,3.2,,
+func,PyObject_RichCompareBool,3.2,,
+func,PyObject_SelfIter,3.2,,
+func,PyObject_SetAttr,3.2,,
+func,PyObject_SetAttrString,3.2,,
+func,PyObject_SetItem,3.2,,
+func,PyObject_Size,3.2,,
+func,PyObject_Str,3.2,,
+func,PyObject_Type,3.2,,
+func,PyObject_Vectorcall,3.12,,
+func,PyObject_VectorcallMethod,3.12,,
+data,PyProperty_Type,3.2,,
+data,PyRangeIter_Type,3.2,,
+data,PyRange_Type,3.2,,
+data,PyReversed_Type,3.2,,
+func,PySeqIter_New,3.2,,
+data,PySeqIter_Type,3.2,,
+func,PySequence_Check,3.2,,
+func,PySequence_Concat,3.2,,
+func,PySequence_Contains,3.2,,
+func,PySequence_Count,3.2,,
+func,PySequence_DelItem,3.2,,
+func,PySequence_DelSlice,3.2,,
+func,PySequence_Fast,3.2,,
+func,PySequence_GetItem,3.2,,
+func,PySequence_GetSlice,3.2,,
+func,PySequence_In,3.2,,
+func,PySequence_InPlaceConcat,3.2,,
+func,PySequence_InPlaceRepeat,3.2,,
+func,PySequence_Index,3.2,,
+func,PySequence_Length,3.2,,
+func,PySequence_List,3.2,,
+func,PySequence_Repeat,3.2,,
+func,PySequence_SetItem,3.2,,
+func,PySequence_SetSlice,3.2,,
+func,PySequence_Size,3.2,,
+func,PySequence_Tuple,3.2,,
+data,PySetIter_Type,3.2,,
+func,PySet_Add,3.2,,
+func,PySet_Clear,3.2,,
+func,PySet_Contains,3.2,,
+func,PySet_Discard,3.2,,
+func,PySet_New,3.2,,
+func,PySet_Pop,3.2,,
+func,PySet_Size,3.2,,
+data,PySet_Type,3.2,,
+func,PySlice_AdjustIndices,3.7,,
+func,PySlice_GetIndices,3.2,,
+func,PySlice_GetIndicesEx,3.2,,
+func,PySlice_New,3.2,,
+data,PySlice_Type,3.2,,
+func,PySlice_Unpack,3.7,,
+func,PyState_AddModule,3.3,,
+func,PyState_FindModule,3.2,,
+func,PyState_RemoveModule,3.3,,
type,PyStructSequence_Desc,3.2,,full-abi
type,PyStructSequence_Field,3.2,,full-abi
-function,PyStructSequence_GetItem,3.2,,
-function,PyStructSequence_New,3.2,,
-function,PyStructSequence_NewType,3.2,,
-function,PyStructSequence_SetItem,3.2,,
-var,PyStructSequence_UnnamedField,3.11,,
-var,PySuper_Type,3.2,,
-function,PySys_AddWarnOption,3.2,,
-function,PySys_AddWarnOptionUnicode,3.2,,
-function,PySys_AddXOption,3.7,,
-function,PySys_FormatStderr,3.2,,
-function,PySys_FormatStdout,3.2,,
-function,PySys_GetObject,3.2,,
-function,PySys_GetXOptions,3.7,,
-function,PySys_HasWarnOptions,3.2,,
-function,PySys_ResetWarnOptions,3.2,,
-function,PySys_SetArgv,3.2,,
-function,PySys_SetArgvEx,3.2,,
-function,PySys_SetObject,3.2,,
-function,PySys_SetPath,3.2,,
-function,PySys_WriteStderr,3.2,,
-function,PySys_WriteStdout,3.2,,
+func,PyStructSequence_GetItem,3.2,,
+func,PyStructSequence_New,3.2,,
+func,PyStructSequence_NewType,3.2,,
+func,PyStructSequence_SetItem,3.2,,
+data,PyStructSequence_UnnamedField,3.11,,
+data,PySuper_Type,3.2,,
+func,PySys_AddWarnOption,3.2,,
+func,PySys_AddWarnOptionUnicode,3.2,,
+func,PySys_AddXOption,3.7,,
+func,PySys_FormatStderr,3.2,,
+func,PySys_FormatStdout,3.2,,
+func,PySys_GetObject,3.2,,
+func,PySys_GetXOptions,3.7,,
+func,PySys_HasWarnOptions,3.2,,
+func,PySys_ResetWarnOptions,3.2,,
+func,PySys_SetArgv,3.2,,
+func,PySys_SetArgvEx,3.2,,
+func,PySys_SetObject,3.2,,
+func,PySys_SetPath,3.2,,
+func,PySys_WriteStderr,3.2,,
+func,PySys_WriteStdout,3.2,,
type,PyThreadState,3.2,,opaque
-function,PyThreadState_Clear,3.2,,
-function,PyThreadState_Delete,3.2,,
-function,PyThreadState_Get,3.2,,
-function,PyThreadState_GetDict,3.2,,
-function,PyThreadState_GetFrame,3.10,,
-function,PyThreadState_GetID,3.10,,
-function,PyThreadState_GetInterpreter,3.10,,
-function,PyThreadState_New,3.2,,
-function,PyThreadState_SetAsyncExc,3.2,,
-function,PyThreadState_Swap,3.2,,
-function,PyThread_GetInfo,3.3,,
-function,PyThread_ReInitTLS,3.2,,
-function,PyThread_acquire_lock,3.2,,
-function,PyThread_acquire_lock_timed,3.2,,
-function,PyThread_allocate_lock,3.2,,
-function,PyThread_create_key,3.2,,
-function,PyThread_delete_key,3.2,,
-function,PyThread_delete_key_value,3.2,,
-function,PyThread_exit_thread,3.2,,
-function,PyThread_free_lock,3.2,,
-function,PyThread_get_key_value,3.2,,
-function,PyThread_get_stacksize,3.2,,
-function,PyThread_get_thread_ident,3.2,,
-function,PyThread_get_thread_native_id,3.2,on platforms with native thread IDs,
-function,PyThread_init_thread,3.2,,
-function,PyThread_release_lock,3.2,,
-function,PyThread_set_key_value,3.2,,
-function,PyThread_set_stacksize,3.2,,
-function,PyThread_start_new_thread,3.2,,
-function,PyThread_tss_alloc,3.7,,
-function,PyThread_tss_create,3.7,,
-function,PyThread_tss_delete,3.7,,
-function,PyThread_tss_free,3.7,,
-function,PyThread_tss_get,3.7,,
-function,PyThread_tss_is_created,3.7,,
-function,PyThread_tss_set,3.7,,
-function,PyTraceBack_Here,3.2,,
-function,PyTraceBack_Print,3.2,,
-var,PyTraceBack_Type,3.2,,
-var,PyTupleIter_Type,3.2,,
-function,PyTuple_GetItem,3.2,,
-function,PyTuple_GetSlice,3.2,,
-function,PyTuple_New,3.2,,
-function,PyTuple_Pack,3.2,,
-function,PyTuple_SetItem,3.2,,
-function,PyTuple_Size,3.2,,
-var,PyTuple_Type,3.2,,
+func,PyThreadState_Clear,3.2,,
+func,PyThreadState_Delete,3.2,,
+func,PyThreadState_Get,3.2,,
+func,PyThreadState_GetDict,3.2,,
+func,PyThreadState_GetFrame,3.10,,
+func,PyThreadState_GetID,3.10,,
+func,PyThreadState_GetInterpreter,3.10,,
+func,PyThreadState_New,3.2,,
+func,PyThreadState_SetAsyncExc,3.2,,
+func,PyThreadState_Swap,3.2,,
+func,PyThread_GetInfo,3.3,,
+func,PyThread_ReInitTLS,3.2,,
+func,PyThread_acquire_lock,3.2,,
+func,PyThread_acquire_lock_timed,3.2,,
+func,PyThread_allocate_lock,3.2,,
+func,PyThread_create_key,3.2,,
+func,PyThread_delete_key,3.2,,
+func,PyThread_delete_key_value,3.2,,
+func,PyThread_exit_thread,3.2,,
+func,PyThread_free_lock,3.2,,
+func,PyThread_get_key_value,3.2,,
+func,PyThread_get_stacksize,3.2,,
+func,PyThread_get_thread_ident,3.2,,
+func,PyThread_get_thread_native_id,3.2,on platforms with native thread IDs,
+func,PyThread_init_thread,3.2,,
+func,PyThread_release_lock,3.2,,
+func,PyThread_set_key_value,3.2,,
+func,PyThread_set_stacksize,3.2,,
+func,PyThread_start_new_thread,3.2,,
+func,PyThread_tss_alloc,3.7,,
+func,PyThread_tss_create,3.7,,
+func,PyThread_tss_delete,3.7,,
+func,PyThread_tss_free,3.7,,
+func,PyThread_tss_get,3.7,,
+func,PyThread_tss_is_created,3.7,,
+func,PyThread_tss_set,3.7,,
+func,PyTraceBack_Here,3.2,,
+func,PyTraceBack_Print,3.2,,
+data,PyTraceBack_Type,3.2,,
+data,PyTupleIter_Type,3.2,,
+func,PyTuple_GetItem,3.2,,
+func,PyTuple_GetSlice,3.2,,
+func,PyTuple_New,3.2,,
+func,PyTuple_Pack,3.2,,
+func,PyTuple_SetItem,3.2,,
+func,PyTuple_Size,3.2,,
+data,PyTuple_Type,3.2,,
type,PyTypeObject,3.2,,opaque
-function,PyType_ClearCache,3.2,,
-function,PyType_FromMetaclass,3.12,,
-function,PyType_FromModuleAndSpec,3.10,,
-function,PyType_FromSpec,3.2,,
-function,PyType_FromSpecWithBases,3.3,,
-function,PyType_GenericAlloc,3.2,,
-function,PyType_GenericNew,3.2,,
-function,PyType_GetFlags,3.2,,
-function,PyType_GetModule,3.10,,
-function,PyType_GetModuleState,3.10,,
-function,PyType_GetName,3.11,,
-function,PyType_GetQualName,3.11,,
-function,PyType_GetSlot,3.4,,
-function,PyType_GetTypeDataSize,3.12,,
-function,PyType_IsSubtype,3.2,,
-function,PyType_Modified,3.2,,
-function,PyType_Ready,3.2,,
+func,PyType_ClearCache,3.2,,
+func,PyType_FromMetaclass,3.12,,
+func,PyType_FromModuleAndSpec,3.10,,
+func,PyType_FromSpec,3.2,,
+func,PyType_FromSpecWithBases,3.3,,
+func,PyType_GenericAlloc,3.2,,
+func,PyType_GenericNew,3.2,,
+func,PyType_GetFlags,3.2,,
+func,PyType_GetModule,3.10,,
+func,PyType_GetModuleState,3.10,,
+func,PyType_GetName,3.11,,
+func,PyType_GetQualName,3.11,,
+func,PyType_GetSlot,3.4,,
+func,PyType_GetTypeDataSize,3.12,,
+func,PyType_IsSubtype,3.2,,
+func,PyType_Modified,3.2,,
+func,PyType_Ready,3.2,,
type,PyType_Slot,3.2,,full-abi
type,PyType_Spec,3.2,,full-abi
-var,PyType_Type,3.2,,
-function,PyUnicodeDecodeError_Create,3.2,,
-function,PyUnicodeDecodeError_GetEncoding,3.2,,
-function,PyUnicodeDecodeError_GetEnd,3.2,,
-function,PyUnicodeDecodeError_GetObject,3.2,,
-function,PyUnicodeDecodeError_GetReason,3.2,,
-function,PyUnicodeDecodeError_GetStart,3.2,,
-function,PyUnicodeDecodeError_SetEnd,3.2,,
-function,PyUnicodeDecodeError_SetReason,3.2,,
-function,PyUnicodeDecodeError_SetStart,3.2,,
-function,PyUnicodeEncodeError_GetEncoding,3.2,,
-function,PyUnicodeEncodeError_GetEnd,3.2,,
-function,PyUnicodeEncodeError_GetObject,3.2,,
-function,PyUnicodeEncodeError_GetReason,3.2,,
-function,PyUnicodeEncodeError_GetStart,3.2,,
-function,PyUnicodeEncodeError_SetEnd,3.2,,
-function,PyUnicodeEncodeError_SetReason,3.2,,
-function,PyUnicodeEncodeError_SetStart,3.2,,
-var,PyUnicodeIter_Type,3.2,,
-function,PyUnicodeTranslateError_GetEnd,3.2,,
-function,PyUnicodeTranslateError_GetObject,3.2,,
-function,PyUnicodeTranslateError_GetReason,3.2,,
-function,PyUnicodeTranslateError_GetStart,3.2,,
-function,PyUnicodeTranslateError_SetEnd,3.2,,
-function,PyUnicodeTranslateError_SetReason,3.2,,
-function,PyUnicodeTranslateError_SetStart,3.2,,
-function,PyUnicode_Append,3.2,,
-function,PyUnicode_AppendAndDel,3.2,,
-function,PyUnicode_AsASCIIString,3.2,,
-function,PyUnicode_AsCharmapString,3.2,,
-function,PyUnicode_AsDecodedObject,3.2,,
-function,PyUnicode_AsDecodedUnicode,3.2,,
-function,PyUnicode_AsEncodedObject,3.2,,
-function,PyUnicode_AsEncodedString,3.2,,
-function,PyUnicode_AsEncodedUnicode,3.2,,
-function,PyUnicode_AsLatin1String,3.2,,
-function,PyUnicode_AsMBCSString,3.7,on Windows,
-function,PyUnicode_AsRawUnicodeEscapeString,3.2,,
-function,PyUnicode_AsUCS4,3.7,,
-function,PyUnicode_AsUCS4Copy,3.7,,
-function,PyUnicode_AsUTF16String,3.2,,
-function,PyUnicode_AsUTF32String,3.2,,
-function,PyUnicode_AsUTF8AndSize,3.10,,
-function,PyUnicode_AsUTF8String,3.2,,
-function,PyUnicode_AsUnicodeEscapeString,3.2,,
-function,PyUnicode_AsWideChar,3.2,,
-function,PyUnicode_AsWideCharString,3.7,,
-function,PyUnicode_BuildEncodingMap,3.2,,
-function,PyUnicode_Compare,3.2,,
-function,PyUnicode_CompareWithASCIIString,3.2,,
-function,PyUnicode_Concat,3.2,,
-function,PyUnicode_Contains,3.2,,
-function,PyUnicode_Count,3.2,,
-function,PyUnicode_Decode,3.2,,
-function,PyUnicode_DecodeASCII,3.2,,
-function,PyUnicode_DecodeCharmap,3.2,,
-function,PyUnicode_DecodeCodePageStateful,3.7,on Windows,
-function,PyUnicode_DecodeFSDefault,3.2,,
-function,PyUnicode_DecodeFSDefaultAndSize,3.2,,
-function,PyUnicode_DecodeLatin1,3.2,,
-function,PyUnicode_DecodeLocale,3.7,,
-function,PyUnicode_DecodeLocaleAndSize,3.7,,
-function,PyUnicode_DecodeMBCS,3.7,on Windows,
-function,PyUnicode_DecodeMBCSStateful,3.7,on Windows,
-function,PyUnicode_DecodeRawUnicodeEscape,3.2,,
-function,PyUnicode_DecodeUTF16,3.2,,
-function,PyUnicode_DecodeUTF16Stateful,3.2,,
-function,PyUnicode_DecodeUTF32,3.2,,
-function,PyUnicode_DecodeUTF32Stateful,3.2,,
-function,PyUnicode_DecodeUTF7,3.2,,
-function,PyUnicode_DecodeUTF7Stateful,3.2,,
-function,PyUnicode_DecodeUTF8,3.2,,
-function,PyUnicode_DecodeUTF8Stateful,3.2,,
-function,PyUnicode_DecodeUnicodeEscape,3.2,,
-function,PyUnicode_EncodeCodePage,3.7,on Windows,
-function,PyUnicode_EncodeFSDefault,3.2,,
-function,PyUnicode_EncodeLocale,3.7,,
-function,PyUnicode_FSConverter,3.2,,
-function,PyUnicode_FSDecoder,3.2,,
-function,PyUnicode_Find,3.2,,
-function,PyUnicode_FindChar,3.7,,
-function,PyUnicode_Format,3.2,,
-function,PyUnicode_FromEncodedObject,3.2,,
-function,PyUnicode_FromFormat,3.2,,
-function,PyUnicode_FromFormatV,3.2,,
-function,PyUnicode_FromObject,3.2,,
-function,PyUnicode_FromOrdinal,3.2,,
-function,PyUnicode_FromString,3.2,,
-function,PyUnicode_FromStringAndSize,3.2,,
-function,PyUnicode_FromWideChar,3.2,,
-function,PyUnicode_GetDefaultEncoding,3.2,,
-function,PyUnicode_GetLength,3.7,,
-function,PyUnicode_InternFromString,3.2,,
-function,PyUnicode_InternInPlace,3.2,,
-function,PyUnicode_IsIdentifier,3.2,,
-function,PyUnicode_Join,3.2,,
-function,PyUnicode_Partition,3.2,,
-function,PyUnicode_RPartition,3.2,,
-function,PyUnicode_RSplit,3.2,,
-function,PyUnicode_ReadChar,3.7,,
-function,PyUnicode_Replace,3.2,,
-function,PyUnicode_Resize,3.2,,
-function,PyUnicode_RichCompare,3.2,,
-function,PyUnicode_Split,3.2,,
-function,PyUnicode_Splitlines,3.2,,
-function,PyUnicode_Substring,3.7,,
-function,PyUnicode_Tailmatch,3.2,,
-function,PyUnicode_Translate,3.2,,
-var,PyUnicode_Type,3.2,,
-function,PyUnicode_WriteChar,3.7,,
+data,PyType_Type,3.2,,
+func,PyUnicodeDecodeError_Create,3.2,,
+func,PyUnicodeDecodeError_GetEncoding,3.2,,
+func,PyUnicodeDecodeError_GetEnd,3.2,,
+func,PyUnicodeDecodeError_GetObject,3.2,,
+func,PyUnicodeDecodeError_GetReason,3.2,,
+func,PyUnicodeDecodeError_GetStart,3.2,,
+func,PyUnicodeDecodeError_SetEnd,3.2,,
+func,PyUnicodeDecodeError_SetReason,3.2,,
+func,PyUnicodeDecodeError_SetStart,3.2,,
+func,PyUnicodeEncodeError_GetEncoding,3.2,,
+func,PyUnicodeEncodeError_GetEnd,3.2,,
+func,PyUnicodeEncodeError_GetObject,3.2,,
+func,PyUnicodeEncodeError_GetReason,3.2,,
+func,PyUnicodeEncodeError_GetStart,3.2,,
+func,PyUnicodeEncodeError_SetEnd,3.2,,
+func,PyUnicodeEncodeError_SetReason,3.2,,
+func,PyUnicodeEncodeError_SetStart,3.2,,
+data,PyUnicodeIter_Type,3.2,,
+func,PyUnicodeTranslateError_GetEnd,3.2,,
+func,PyUnicodeTranslateError_GetObject,3.2,,
+func,PyUnicodeTranslateError_GetReason,3.2,,
+func,PyUnicodeTranslateError_GetStart,3.2,,
+func,PyUnicodeTranslateError_SetEnd,3.2,,
+func,PyUnicodeTranslateError_SetReason,3.2,,
+func,PyUnicodeTranslateError_SetStart,3.2,,
+func,PyUnicode_Append,3.2,,
+func,PyUnicode_AppendAndDel,3.2,,
+func,PyUnicode_AsASCIIString,3.2,,
+func,PyUnicode_AsCharmapString,3.2,,
+func,PyUnicode_AsDecodedObject,3.2,,
+func,PyUnicode_AsDecodedUnicode,3.2,,
+func,PyUnicode_AsEncodedObject,3.2,,
+func,PyUnicode_AsEncodedString,3.2,,
+func,PyUnicode_AsEncodedUnicode,3.2,,
+func,PyUnicode_AsLatin1String,3.2,,
+func,PyUnicode_AsMBCSString,3.7,on Windows,
+func,PyUnicode_AsRawUnicodeEscapeString,3.2,,
+func,PyUnicode_AsUCS4,3.7,,
+func,PyUnicode_AsUCS4Copy,3.7,,
+func,PyUnicode_AsUTF16String,3.2,,
+func,PyUnicode_AsUTF32String,3.2,,
+func,PyUnicode_AsUTF8AndSize,3.10,,
+func,PyUnicode_AsUTF8String,3.2,,
+func,PyUnicode_AsUnicodeEscapeString,3.2,,
+func,PyUnicode_AsWideChar,3.2,,
+func,PyUnicode_AsWideCharString,3.7,,
+func,PyUnicode_BuildEncodingMap,3.2,,
+func,PyUnicode_Compare,3.2,,
+func,PyUnicode_CompareWithASCIIString,3.2,,
+func,PyUnicode_Concat,3.2,,
+func,PyUnicode_Contains,3.2,,
+func,PyUnicode_Count,3.2,,
+func,PyUnicode_Decode,3.2,,
+func,PyUnicode_DecodeASCII,3.2,,
+func,PyUnicode_DecodeCharmap,3.2,,
+func,PyUnicode_DecodeCodePageStateful,3.7,on Windows,
+func,PyUnicode_DecodeFSDefault,3.2,,
+func,PyUnicode_DecodeFSDefaultAndSize,3.2,,
+func,PyUnicode_DecodeLatin1,3.2,,
+func,PyUnicode_DecodeLocale,3.7,,
+func,PyUnicode_DecodeLocaleAndSize,3.7,,
+func,PyUnicode_DecodeMBCS,3.7,on Windows,
+func,PyUnicode_DecodeMBCSStateful,3.7,on Windows,
+func,PyUnicode_DecodeRawUnicodeEscape,3.2,,
+func,PyUnicode_DecodeUTF16,3.2,,
+func,PyUnicode_DecodeUTF16Stateful,3.2,,
+func,PyUnicode_DecodeUTF32,3.2,,
+func,PyUnicode_DecodeUTF32Stateful,3.2,,
+func,PyUnicode_DecodeUTF7,3.2,,
+func,PyUnicode_DecodeUTF7Stateful,3.2,,
+func,PyUnicode_DecodeUTF8,3.2,,
+func,PyUnicode_DecodeUTF8Stateful,3.2,,
+func,PyUnicode_DecodeUnicodeEscape,3.2,,
+func,PyUnicode_EncodeCodePage,3.7,on Windows,
+func,PyUnicode_EncodeFSDefault,3.2,,
+func,PyUnicode_EncodeLocale,3.7,,
+func,PyUnicode_FSConverter,3.2,,
+func,PyUnicode_FSDecoder,3.2,,
+func,PyUnicode_Find,3.2,,
+func,PyUnicode_FindChar,3.7,,
+func,PyUnicode_Format,3.2,,
+func,PyUnicode_FromEncodedObject,3.2,,
+func,PyUnicode_FromFormat,3.2,,
+func,PyUnicode_FromFormatV,3.2,,
+func,PyUnicode_FromObject,3.2,,
+func,PyUnicode_FromOrdinal,3.2,,
+func,PyUnicode_FromString,3.2,,
+func,PyUnicode_FromStringAndSize,3.2,,
+func,PyUnicode_FromWideChar,3.2,,
+func,PyUnicode_GetDefaultEncoding,3.2,,
+func,PyUnicode_GetLength,3.7,,
+func,PyUnicode_InternFromString,3.2,,
+func,PyUnicode_InternInPlace,3.2,,
+func,PyUnicode_IsIdentifier,3.2,,
+func,PyUnicode_Join,3.2,,
+func,PyUnicode_Partition,3.2,,
+func,PyUnicode_RPartition,3.2,,
+func,PyUnicode_RSplit,3.2,,
+func,PyUnicode_ReadChar,3.7,,
+func,PyUnicode_Replace,3.2,,
+func,PyUnicode_Resize,3.2,,
+func,PyUnicode_RichCompare,3.2,,
+func,PyUnicode_Split,3.2,,
+func,PyUnicode_Splitlines,3.2,,
+func,PyUnicode_Substring,3.7,,
+func,PyUnicode_Tailmatch,3.2,,
+func,PyUnicode_Translate,3.2,,
+data,PyUnicode_Type,3.2,,
+func,PyUnicode_WriteChar,3.7,,
type,PyVarObject,3.2,,members
member,PyVarObject.ob_base,3.2,,
member,PyVarObject.ob_size,3.2,,
-function,PyVectorcall_Call,3.12,,
-function,PyVectorcall_NARGS,3.12,,
+func,PyVectorcall_Call,3.12,,
+func,PyVectorcall_NARGS,3.12,,
type,PyWeakReference,3.2,,opaque
-function,PyWeakref_GetObject,3.2,,
-function,PyWeakref_NewProxy,3.2,,
-function,PyWeakref_NewRef,3.2,,
-var,PyWrapperDescr_Type,3.2,,
-function,PyWrapper_New,3.2,,
-var,PyZip_Type,3.2,,
-function,Py_AddPendingCall,3.2,,
-function,Py_AtExit,3.2,,
+func,PyWeakref_GetObject,3.2,,
+func,PyWeakref_NewProxy,3.2,,
+func,PyWeakref_NewRef,3.2,,
+data,PyWrapperDescr_Type,3.2,,
+func,PyWrapper_New,3.2,,
+data,PyZip_Type,3.2,,
+func,Py_AddPendingCall,3.2,,
+func,Py_AtExit,3.2,,
macro,Py_BEGIN_ALLOW_THREADS,3.2,,
macro,Py_BLOCK_THREADS,3.2,,
-function,Py_BuildValue,3.2,,
-function,Py_BytesMain,3.8,,
-function,Py_CompileString,3.2,,
-function,Py_DecRef,3.2,,
-function,Py_DecodeLocale,3.7,,
+func,Py_BuildValue,3.2,,
+func,Py_BytesMain,3.8,,
+func,Py_CompileString,3.2,,
+func,Py_DecRef,3.2,,
+func,Py_DecodeLocale,3.7,,
macro,Py_END_ALLOW_THREADS,3.2,,
-function,Py_EncodeLocale,3.7,,
-function,Py_EndInterpreter,3.2,,
-function,Py_EnterRecursiveCall,3.9,,
-function,Py_Exit,3.2,,
-function,Py_FatalError,3.2,,
-var,Py_FileSystemDefaultEncodeErrors,3.10,,
-var,Py_FileSystemDefaultEncoding,3.2,,
-function,Py_Finalize,3.2,,
-function,Py_FinalizeEx,3.6,,
-function,Py_GenericAlias,3.9,,
-var,Py_GenericAliasType,3.9,,
-function,Py_GetBuildInfo,3.2,,
-function,Py_GetCompiler,3.2,,
-function,Py_GetCopyright,3.2,,
-function,Py_GetExecPrefix,3.2,,
-function,Py_GetPath,3.2,,
-function,Py_GetPlatform,3.2,,
-function,Py_GetPrefix,3.2,,
-function,Py_GetProgramFullPath,3.2,,
-function,Py_GetProgramName,3.2,,
-function,Py_GetPythonHome,3.2,,
-function,Py_GetRecursionLimit,3.2,,
-function,Py_GetVersion,3.2,,
-var,Py_HasFileSystemDefaultEncoding,3.2,,
-function,Py_IncRef,3.2,,
-function,Py_Initialize,3.2,,
-function,Py_InitializeEx,3.2,,
-function,Py_Is,3.10,,
-function,Py_IsFalse,3.10,,
-function,Py_IsInitialized,3.2,,
-function,Py_IsNone,3.10,,
-function,Py_IsTrue,3.10,,
-function,Py_LeaveRecursiveCall,3.9,,
-function,Py_Main,3.2,,
-function,Py_MakePendingCalls,3.2,,
-function,Py_NewInterpreter,3.2,,
-function,Py_NewRef,3.10,,
-function,Py_ReprEnter,3.2,,
-function,Py_ReprLeave,3.2,,
-function,Py_SetPath,3.7,,
-function,Py_SetProgramName,3.2,,
-function,Py_SetPythonHome,3.2,,
-function,Py_SetRecursionLimit,3.2,,
+func,Py_EncodeLocale,3.7,,
+func,Py_EndInterpreter,3.2,,
+func,Py_EnterRecursiveCall,3.9,,
+func,Py_Exit,3.2,,
+func,Py_FatalError,3.2,,
+data,Py_FileSystemDefaultEncodeErrors,3.10,,
+data,Py_FileSystemDefaultEncoding,3.2,,
+func,Py_Finalize,3.2,,
+func,Py_FinalizeEx,3.6,,
+func,Py_GenericAlias,3.9,,
+data,Py_GenericAliasType,3.9,,
+func,Py_GetBuildInfo,3.2,,
+func,Py_GetCompiler,3.2,,
+func,Py_GetCopyright,3.2,,
+func,Py_GetExecPrefix,3.2,,
+func,Py_GetPath,3.2,,
+func,Py_GetPlatform,3.2,,
+func,Py_GetPrefix,3.2,,
+func,Py_GetProgramFullPath,3.2,,
+func,Py_GetProgramName,3.2,,
+func,Py_GetPythonHome,3.2,,
+func,Py_GetRecursionLimit,3.2,,
+func,Py_GetVersion,3.2,,
+data,Py_HasFileSystemDefaultEncoding,3.2,,
+func,Py_IncRef,3.2,,
+func,Py_Initialize,3.2,,
+func,Py_InitializeEx,3.2,,
+func,Py_Is,3.10,,
+func,Py_IsFalse,3.10,,
+func,Py_IsInitialized,3.2,,
+func,Py_IsNone,3.10,,
+func,Py_IsTrue,3.10,,
+func,Py_LeaveRecursiveCall,3.9,,
+func,Py_Main,3.2,,
+func,Py_MakePendingCalls,3.2,,
+func,Py_NewInterpreter,3.2,,
+func,Py_NewRef,3.10,,
+func,Py_ReprEnter,3.2,,
+func,Py_ReprLeave,3.2,,
+func,Py_SetPath,3.7,,
+func,Py_SetProgramName,3.2,,
+func,Py_SetPythonHome,3.2,,
+func,Py_SetRecursionLimit,3.2,,
type,Py_UCS4,3.2,,
macro,Py_UNBLOCK_THREADS,3.2,,
-var,Py_UTF8Mode,3.8,,
-function,Py_VaBuildValue,3.2,,
-var,Py_Version,3.11,,
-function,Py_XNewRef,3.10,,
+data,Py_UTF8Mode,3.8,,
+func,Py_VaBuildValue,3.2,,
+data,Py_Version,3.11,,
+func,Py_XNewRef,3.10,,
type,Py_buffer,3.11,,full-abi
type,Py_intptr_t,3.2,,
type,Py_ssize_t,3.2,,
diff --git a/Doc/deprecations/c-api-pending-removal-in-3.14.rst b/Doc/deprecations/c-api-pending-removal-in-3.14.rst
new file mode 100644
index 00000000..d16da66c
--- /dev/null
+++ b/Doc/deprecations/c-api-pending-removal-in-3.14.rst
@@ -0,0 +1,72 @@
+Pending Removal in Python 3.14
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The ``ma_version_tag`` field in :c:type:`PyDictObject` for extension modules
+ (:pep:`699`; :gh:`101193`).
+
+* Creating :c:data:`immutable types ` with mutable
+ bases (:gh:`95388`).
+
+* Functions to configure Python's initialization, deprecated in Python 3.11:
+
+ * :c:func:`!PySys_SetArgvEx()`:
+ Set :c:member:`PyConfig.argv` instead.
+ * :c:func:`!PySys_SetArgv()`:
+ Set :c:member:`PyConfig.argv` instead.
+ * :c:func:`!Py_SetProgramName()`:
+ Set :c:member:`PyConfig.program_name` instead.
+ * :c:func:`!Py_SetPythonHome()`:
+ Set :c:member:`PyConfig.home` instead.
+
+ The :c:func:`Py_InitializeFromConfig` API should be used with
+ :c:type:`PyConfig` instead.
+
+* Global configuration variables:
+
+ * :c:var:`Py_DebugFlag`:
+ Use :c:member:`PyConfig.parser_debug` instead.
+ * :c:var:`Py_VerboseFlag`:
+ Use :c:member:`PyConfig.verbose` instead.
+ * :c:var:`Py_QuietFlag`:
+ Use :c:member:`PyConfig.quiet` instead.
+ * :c:var:`Py_InteractiveFlag`:
+ Use :c:member:`PyConfig.interactive` instead.
+ * :c:var:`Py_InspectFlag`:
+ Use :c:member:`PyConfig.inspect` instead.
+ * :c:var:`Py_OptimizeFlag`:
+ Use :c:member:`PyConfig.optimization_level` instead.
+ * :c:var:`Py_NoSiteFlag`:
+ Use :c:member:`PyConfig.site_import` instead.
+ * :c:var:`Py_BytesWarningFlag`:
+ Use :c:member:`PyConfig.bytes_warning` instead.
+ * :c:var:`Py_FrozenFlag`:
+ Use :c:member:`PyConfig.pathconfig_warnings` instead.
+ * :c:var:`Py_IgnoreEnvironmentFlag`:
+ Use :c:member:`PyConfig.use_environment` instead.
+ * :c:var:`Py_DontWriteBytecodeFlag`:
+ Use :c:member:`PyConfig.write_bytecode` instead.
+ * :c:var:`Py_NoUserSiteDirectory`:
+ Use :c:member:`PyConfig.user_site_directory` instead.
+ * :c:var:`Py_UnbufferedStdioFlag`:
+ Use :c:member:`PyConfig.buffered_stdio` instead.
+ * :c:var:`Py_HashRandomizationFlag`:
+ Use :c:member:`PyConfig.use_hash_seed`
+ and :c:member:`PyConfig.hash_seed` instead.
+ * :c:var:`Py_IsolatedFlag`:
+ Use :c:member:`PyConfig.isolated` instead.
+ * :c:var:`Py_LegacyWindowsFSEncodingFlag`:
+ Use :c:member:`PyPreConfig.legacy_windows_fs_encoding` instead.
+ * :c:var:`Py_LegacyWindowsStdioFlag`:
+ Use :c:member:`PyConfig.legacy_windows_stdio` instead.
+ * :c:var:`!Py_FileSystemDefaultEncoding`:
+ Use :c:member:`PyConfig.filesystem_encoding` instead.
+ * :c:var:`!Py_HasFileSystemDefaultEncoding`:
+ Use :c:member:`PyConfig.filesystem_encoding` instead.
+ * :c:var:`!Py_FileSystemDefaultEncodeErrors`:
+ Use :c:member:`PyConfig.filesystem_errors` instead.
+ * :c:var:`!Py_UTF8Mode`:
+ Use :c:member:`PyPreConfig.utf8_mode` instead.
+ (see :c:func:`Py_PreInitialize`)
+
+ The :c:func:`Py_InitializeFromConfig` API should be used with
+ :c:type:`PyConfig` instead.
diff --git a/Doc/deprecations/c-api-pending-removal-in-3.15.rst b/Doc/deprecations/c-api-pending-removal-in-3.15.rst
new file mode 100644
index 00000000..cdfcb2f9
--- /dev/null
+++ b/Doc/deprecations/c-api-pending-removal-in-3.15.rst
@@ -0,0 +1,27 @@
+Pending Removal in Python 3.15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The bundled copy of ``libmpdecimal``.
+* The :c:func:`PyImport_ImportModuleNoBlock`:
+ Use :c:func:`PyImport_ImportModule` instead.
+* :c:func:`PyWeakref_GetObject` and :c:func:`PyWeakref_GET_OBJECT`:
+ Use :c:func:`!PyWeakref_GetRef` instead.
+* :c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro:
+ Use :c:type:`wchar_t` instead.
+* Python initialization functions:
+
+ * :c:func:`PySys_ResetWarnOptions`:
+ Clear :data:`sys.warnoptions` and :data:`!warnings.filters` instead.
+ * :c:func:`Py_GetExecPrefix`:
+ Get :data:`sys.exec_prefix` instead.
+ * :c:func:`Py_GetPath`:
+ Get :data:`sys.path` instead.
+ * :c:func:`Py_GetPrefix`:
+ Get :data:`sys.prefix` instead.
+ * :c:func:`Py_GetProgramFullPath`:
+ Get :data:`sys.executable` instead.
+ * :c:func:`Py_GetProgramName`:
+ Get :data:`sys.executable` instead.
+ * :c:func:`Py_GetPythonHome`:
+ Get :c:member:`PyConfig.home`
+ or the :envvar:`PYTHONHOME` environment variable instead.
diff --git a/Doc/deprecations/c-api-pending-removal-in-future.rst b/Doc/deprecations/c-api-pending-removal-in-future.rst
new file mode 100644
index 00000000..0c3ae52b
--- /dev/null
+++ b/Doc/deprecations/c-api-pending-removal-in-future.rst
@@ -0,0 +1,51 @@
+Pending Removal in Future Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following APIs are deprecated and will be removed,
+although there is currently no date scheduled for their removal.
+
+* :c:macro:`Py_TPFLAGS_HAVE_FINALIZE`:
+ Unneeded since Python 3.8.
+* :c:func:`PyErr_Fetch`:
+ Use :c:func:`PyErr_GetRaisedException` instead.
+* :c:func:`PyErr_NormalizeException`:
+ Use :c:func:`PyErr_GetRaisedException` instead.
+* :c:func:`PyErr_Restore`:
+ Use :c:func:`PyErr_SetRaisedException` instead.
+* :c:func:`PyModule_GetFilename`:
+ Use :c:func:`PyModule_GetFilenameObject` instead.
+* :c:func:`PyOS_AfterFork`:
+ Use :c:func:`PyOS_AfterFork_Child` instead.
+* :c:func:`PySlice_GetIndicesEx`:
+ Use :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` instead.
+* :c:func:`!PyUnicode_AsDecodedObject`:
+ Use :c:func:`PyCodec_Decode` instead.
+* :c:func:`!PyUnicode_AsDecodedUnicode`:
+ Use :c:func:`PyCodec_Decode` instead.
+* :c:func:`!PyUnicode_AsEncodedObject`:
+ Use :c:func:`PyCodec_Encode` instead.
+* :c:func:`!PyUnicode_AsEncodedUnicode`:
+ Use :c:func:`PyCodec_Encode` instead.
+* :c:func:`PyUnicode_READY`:
+ Unneeded since Python 3.12
+* :c:func:`!PyErr_Display`:
+ Use :c:func:`PyErr_DisplayException` instead.
+* :c:func:`!_PyErr_ChainExceptions`:
+ Use :c:func:`!_PyErr_ChainExceptions1` instead.
+* :c:member:`!PyBytesObject.ob_shash` member:
+ call :c:func:`PyObject_Hash` instead.
+* :c:member:`!PyDictObject.ma_version_tag` member.
+* Thread Local Storage (TLS) API:
+
+ * :c:func:`PyThread_create_key`:
+ Use :c:func:`PyThread_tss_alloc` instead.
+ * :c:func:`PyThread_delete_key`:
+ Use :c:func:`PyThread_tss_free` instead.
+ * :c:func:`PyThread_set_key_value`:
+ Use :c:func:`PyThread_tss_set` instead.
+ * :c:func:`PyThread_get_key_value`:
+ Use :c:func:`PyThread_tss_get` instead.
+ * :c:func:`PyThread_delete_key_value`:
+ Use :c:func:`PyThread_tss_delete` instead.
+ * :c:func:`PyThread_ReInitTLS`:
+ Unneeded since Python 3.7.
diff --git a/Doc/deprecations/index.rst b/Doc/deprecations/index.rst
new file mode 100644
index 00000000..aedea375
--- /dev/null
+++ b/Doc/deprecations/index.rst
@@ -0,0 +1,21 @@
+Deprecations
+============
+
+.. include:: pending-removal-in-3.13.rst
+
+.. include:: pending-removal-in-3.14.rst
+
+.. include:: pending-removal-in-3.15.rst
+
+.. include:: pending-removal-in-3.16.rst
+
+.. include:: pending-removal-in-future.rst
+
+C API Deprecations
+------------------
+
+.. include:: c-api-pending-removal-in-3.14.rst
+
+.. include:: c-api-pending-removal-in-3.15.rst
+
+.. include:: c-api-pending-removal-in-future.rst
diff --git a/Doc/deprecations/pending-removal-in-3.13.rst b/Doc/deprecations/pending-removal-in-3.13.rst
new file mode 100644
index 00000000..1c24b5b6
--- /dev/null
+++ b/Doc/deprecations/pending-removal-in-3.13.rst
@@ -0,0 +1,52 @@
+Pending Removal in Python 3.13
+------------------------------
+
+Modules (see :pep:`594`):
+
+* :mod:`aifc`
+* :mod:`audioop`
+* :mod:`cgi`
+* :mod:`cgitb`
+* :mod:`chunk`
+* :mod:`crypt`
+* :mod:`imghdr`
+* :mod:`mailcap`
+* :mod:`msilib`
+* :mod:`nis`
+* :mod:`nntplib`
+* :mod:`ossaudiodev`
+* :mod:`pipes`
+* :mod:`sndhdr`
+* :mod:`spwd`
+* :mod:`sunau`
+* :mod:`telnetlib`
+* :mod:`uu`
+* :mod:`xdrlib`
+
+Other modules:
+
+* :mod:`!lib2to3`, and the :program:`2to3` program (:gh:`84540`)
+
+APIs:
+
+* :class:`!configparser.LegacyInterpolation` (:gh:`90765`)
+* ``locale.resetlocale()`` (:gh:`90817`)
+* :meth:`!turtle.RawTurtle.settiltangle` (:gh:`50096`)
+* :func:`!unittest.findTestCases` (:gh:`50096`)
+* :func:`!unittest.getTestCaseNames` (:gh:`50096`)
+* :func:`!unittest.makeSuite` (:gh:`50096`)
+* :meth:`!unittest.TestProgram.usageExit` (:gh:`67048`)
+* :class:`!webbrowser.MacOSX` (:gh:`86421`)
+* :class:`classmethod` descriptor chaining (:gh:`89519`)
+* :mod:`importlib.resources` deprecated methods:
+
+ * ``contents()``
+ * ``is_resource()``
+ * ``open_binary()``
+ * ``open_text()``
+ * ``path()``
+ * ``read_binary()``
+ * ``read_text()``
+
+ Use :func:`importlib.resources.files` instead. Refer to `importlib-resources: Migrating from Legacy
+ `_ (:gh:`106531`)
diff --git a/Doc/deprecations/pending-removal-in-3.14.rst b/Doc/deprecations/pending-removal-in-3.14.rst
new file mode 100644
index 00000000..b506b0f0
--- /dev/null
+++ b/Doc/deprecations/pending-removal-in-3.14.rst
@@ -0,0 +1,108 @@
+Pending Removal in Python 3.14
+------------------------------
+
+* :mod:`argparse`: The *type*, *choices*, and *metavar* parameters
+ of :class:`!argparse.BooleanOptionalAction` are deprecated
+ and will be removed in 3.14.
+ (Contributed by Nikita Sobolev in :gh:`92248`.)
+
+* :mod:`ast`: The following features have been deprecated in documentation
+ since Python 3.8, now cause a :exc:`DeprecationWarning` to be emitted at
+ runtime when they are accessed or used, and will be removed in Python 3.14:
+
+ * :class:`!ast.Num`
+ * :class:`!ast.Str`
+ * :class:`!ast.Bytes`
+ * :class:`!ast.NameConstant`
+ * :class:`!ast.Ellipsis`
+
+ Use :class:`ast.Constant` instead.
+ (Contributed by Serhiy Storchaka in :gh:`90953`.)
+
+* :mod:`asyncio`:
+
+ * The child watcher classes :class:`~asyncio.MultiLoopChildWatcher`,
+ :class:`~asyncio.FastChildWatcher`, :class:`~asyncio.AbstractChildWatcher`
+ and :class:`~asyncio.SafeChildWatcher` are deprecated and
+ will be removed in Python 3.14.
+ (Contributed by Kumar Aditya in :gh:`94597`.)
+
+ * :func:`asyncio.set_child_watcher`, :func:`asyncio.get_child_watcher`,
+ :meth:`asyncio.AbstractEventLoopPolicy.set_child_watcher` and
+ :meth:`asyncio.AbstractEventLoopPolicy.get_child_watcher` are deprecated
+ and will be removed in Python 3.14.
+ (Contributed by Kumar Aditya in :gh:`94597`.)
+
+ * The :meth:`~asyncio.get_event_loop` method of the
+ default event loop policy now emits a :exc:`DeprecationWarning` if there
+ is no current event loop set and it decides to create one.
+ (Contributed by Serhiy Storchaka and Guido van Rossum in :gh:`100160`.)
+
+* :mod:`collections.abc`: Deprecated :class:`~collections.abc.ByteString`.
+ Prefer :class:`!Sequence` or :class:`~collections.abc.Buffer`.
+ For use in typing, prefer a union, like ``bytes | bytearray``,
+ or :class:`collections.abc.Buffer`.
+ (Contributed by Shantanu Jain in :gh:`91896`.)
+
+* :mod:`email`: Deprecated the *isdst* parameter in :func:`email.utils.localtime`.
+ (Contributed by Alan Williams in :gh:`72346`.)
+
+* :mod:`importlib`: ``__package__`` and ``__cached__`` will cease to be set or
+ taken into consideration by the import system (:gh:`97879`).
+
+* :mod:`importlib.abc` deprecated classes:
+
+ * :class:`!importlib.abc.ResourceReader`
+ * :class:`!importlib.abc.Traversable`
+ * :class:`!importlib.abc.TraversableResources`
+
+ Use :mod:`importlib.resources.abc` classes instead:
+
+ * :class:`importlib.resources.abc.Traversable`
+ * :class:`importlib.resources.abc.TraversableResources`
+
+ (Contributed by Jason R. Coombs and Hugo van Kemenade in :gh:`93963`.)
+
+* :mod:`itertools` had undocumented, inefficient, historically buggy,
+ and inconsistent support for copy, deepcopy, and pickle operations.
+ This will be removed in 3.14 for a significant reduction in code
+ volume and maintenance burden.
+ (Contributed by Raymond Hettinger in :gh:`101588`.)
+
+* :mod:`multiprocessing`: The default start method will change to a safer one on
+ Linux, BSDs, and other non-macOS POSIX platforms where ``'fork'`` is currently
+ the default (:gh:`84559`). Adding a runtime warning about this was deemed too
+ disruptive as the majority of code is not expected to care. Use the
+ :func:`~multiprocessing.get_context` or
+ :func:`~multiprocessing.set_start_method` APIs to explicitly specify when
+ your code *requires* ``'fork'``. See :ref:`multiprocessing-start-methods`.
+
+* :mod:`pathlib`: :meth:`~pathlib.PurePath.is_relative_to` and
+ :meth:`~pathlib.PurePath.relative_to`: passing additional arguments is
+ deprecated.
+
+* :mod:`pkgutil`: :func:`~pkgutil.find_loader` and :func:`~pkgutil.get_loader`
+ now raise :exc:`DeprecationWarning`;
+ use :func:`importlib.util.find_spec` instead.
+ (Contributed by Nikita Sobolev in :gh:`97850`.)
+
+* :mod:`pty`:
+
+ * ``master_open()``: use :func:`pty.openpty`.
+ * ``slave_open()``: use :func:`pty.openpty`.
+
+* :mod:`sqlite3`:
+
+ * :data:`~sqlite3.version` and :data:`~sqlite3.version_info`.
+
+ * :meth:`~sqlite3.Cursor.execute` and :meth:`~sqlite3.Cursor.executemany`
+ if :ref:`named placeholders ` are used and
+ *parameters* is a sequence instead of a :class:`dict`.
+
+* :mod:`typing`: :class:`~typing.ByteString`, deprecated since Python 3.9,
+ now causes a :exc:`DeprecationWarning` to be emitted when it is used.
+
+* :mod:`urllib`:
+ :class:`!urllib.parse.Quoter` is deprecated: it was not intended to be a
+ public API.
+ (Contributed by Gregory P. Smith in :gh:`88168`.)
diff --git a/Doc/deprecations/pending-removal-in-3.15.rst b/Doc/deprecations/pending-removal-in-3.15.rst
new file mode 100644
index 00000000..ec2ef655
--- /dev/null
+++ b/Doc/deprecations/pending-removal-in-3.15.rst
@@ -0,0 +1,77 @@
+Pending Removal in Python 3.15
+------------------------------
+
+* :class:`http.server.CGIHTTPRequestHandler` will be removed along with its
+ related ``--cgi`` flag to ``python -m http.server``. It was obsolete and
+ rarely used. No direct replacement exists. *Anything* is better than CGI
+ to interface a web server with a request handler.
+
+* :mod:`importlib`:
+
+ * ``load_module()`` method: use ``exec_module()`` instead.
+
+* :class:`locale`: :func:`locale.getdefaultlocale` was deprecated in Python 3.11
+ and originally planned for removal in Python 3.13 (:gh:`90817`),
+ but removal has been postponed to Python 3.15.
+ Use :func:`locale.setlocale`, :func:`locale.getencoding` and
+ :func:`locale.getlocale` instead.
+ (Contributed by Hugo van Kemenade in :gh:`111187`.)
+
+* :mod:`pathlib`:
+ :meth:`pathlib.PurePath.is_reserved` is deprecated and scheduled for
+ removal in Python 3.15. From Python 3.13 onwards, use ``os.path.isreserved``
+ to detect reserved paths on Windows.
+
+* :mod:`platform`:
+ :func:`~platform.java_ver` is deprecated and will be removed in 3.15.
+ It was largely untested, had a confusing API,
+ and was only useful for Jython support.
+ (Contributed by Nikita Sobolev in :gh:`116349`.)
+
+* :mod:`sysconfig`:
+
+ * The *check_home* argument of :func:`sysconfig.is_python_build` has been
+ deprecated since Python 3.12.
+
+* :mod:`threading`:
+ Passing any arguments to :func:`threading.RLock` is now deprecated.
+ C version allows any numbers of args and kwargs,
+ but they are just ignored. Python version does not allow any arguments.
+ All arguments will be removed from :func:`threading.RLock` in Python 3.15.
+ (Contributed by Nikita Sobolev in :gh:`102029`.)
+
+* :class:`typing.NamedTuple`:
+
+ * The undocumented keyword argument syntax for creating :class:`!NamedTuple` classes
+ (``NT = NamedTuple("NT", x=int)``) is deprecated, and will be disallowed in
+ 3.15. Use the class-based syntax or the functional syntax instead.
+
+* :mod:`types`:
+
+ * :class:`types.CodeType`: Accessing :attr:`~codeobject.co_lnotab` was
+ deprecated in :pep:`626`
+ since 3.10 and was planned to be removed in 3.12,
+ but it only got a proper :exc:`DeprecationWarning` in 3.12.
+ May be removed in 3.15.
+ (Contributed by Nikita Sobolev in :gh:`101866`.)
+
+* :mod:`typing`:
+
+ * When using the functional syntax to create a :class:`!NamedTuple` class, failing to
+ pass a value to the *fields* parameter (``NT = NamedTuple("NT")``) is
+ deprecated. Passing ``None`` to the *fields* parameter
+ (``NT = NamedTuple("NT", None)``) is also deprecated. Both will be
+ disallowed in Python 3.15. To create a :class:`!NamedTuple` class with 0 fields, use
+ ``class NT(NamedTuple): pass`` or ``NT = NamedTuple("NT", [])``.
+
+* :class:`typing.TypedDict`: When using the functional syntax to create a
+ :class:`!TypedDict` class, failing to pass a value to the *fields* parameter (``TD =
+ TypedDict("TD")``) is deprecated. Passing ``None`` to the *fields* parameter
+ (``TD = TypedDict("TD", None)``) is also deprecated. Both will be disallowed
+ in Python 3.15. To create a :class:`!TypedDict` class with 0 fields, use ``class
+ TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``.
+
+* :mod:`wave`: Deprecate the ``getmark()``, ``setmark()`` and ``getmarkers()``
+ methods of the :class:`wave.Wave_read` and :class:`wave.Wave_write` classes.
+ They will be removed in Python 3.15.
+ (Contributed by Victor Stinner in :gh:`105096`.)
diff --git a/Doc/deprecations/pending-removal-in-3.16.rst b/Doc/deprecations/pending-removal-in-3.16.rst
new file mode 100644
index 00000000..f59a4037
--- /dev/null
+++ b/Doc/deprecations/pending-removal-in-3.16.rst
@@ -0,0 +1,20 @@
+Pending Removal in Python 3.16
+------------------------------
+
+* The import system:
+
+ * Setting :attr:`~module.__loader__` on a module while
+ failing to set :attr:`__spec__.loader `
+ is deprecated. In Python 3.16, :attr:`!__loader__` will cease to be set or
+ taken into consideration by the import system or the standard library.
+
+* :mod:`array`:
+ :class:`array.array` ``'u'`` type (:c:type:`wchar_t`):
+ use the ``'w'`` type instead (``Py_UCS4``).
+
+* :mod:`builtins`:
+ ``~bool``, bitwise inversion on bool.
+
+* :mod:`symtable`:
+ Deprecate :meth:`symtable.Class.get_methods` due to the lack of interest.
+ (Contributed by Bénédikt Tran in :gh:`119698`.)
diff --git a/Doc/deprecations/pending-removal-in-future.rst b/Doc/deprecations/pending-removal-in-future.rst
new file mode 100644
index 00000000..826dcadf
--- /dev/null
+++ b/Doc/deprecations/pending-removal-in-future.rst
@@ -0,0 +1,148 @@
+Pending Removal in Future Versions
+----------------------------------
+
+The following APIs will be removed in the future,
+although there is currently no date scheduled for their removal.
+
+* :mod:`argparse`: Nesting argument groups and nesting mutually exclusive
+ groups are deprecated.
+
+* :mod:`array`'s ``'u'`` format code (:gh:`57281`)
+
+* :mod:`builtins`:
+
+ * ``bool(NotImplemented)``.
+ * Generators: ``throw(type, exc, tb)`` and ``athrow(type, exc, tb)``
+ signature is deprecated: use ``throw(exc)`` and ``athrow(exc)`` instead,
+ the single argument signature.
+ * Currently Python accepts numeric literals immediately followed by keywords,
+ for example ``0in x``, ``1or x``, ``0if 1else 2``. It allows confusing and
+ ambiguous expressions like ``[0x1for x in y]`` (which can be interpreted as
+ ``[0x1 for x in y]`` or ``[0x1f or x in y]``). A syntax warning is raised
+ if the numeric literal is immediately followed by one of keywords
+ :keyword:`and`, :keyword:`else`, :keyword:`for`, :keyword:`if`,
+ :keyword:`in`, :keyword:`is` and :keyword:`or`. In a future release it
+ will be changed to a syntax error. (:gh:`87999`)
+ * Support for ``__index__()`` and ``__int__()`` method returning non-int type:
+ these methods will be required to return an instance of a strict subclass of
+ :class:`int`.
+ * Support for ``__float__()`` method returning a strict subclass of
+ :class:`float`: these methods will be required to return an instance of
+ :class:`float`.
+ * Support for ``__complex__()`` method returning a strict subclass of
+ :class:`complex`: these methods will be required to return an instance of
+ :class:`complex`.
+ * Delegation of ``int()`` to ``__trunc__()`` method.
+ * Passing a complex number as the *real* or *imag* argument in the
+ :func:`complex` constructor is now deprecated; it should only be passed
+ as a single positional argument.
+ (Contributed by Serhiy Storchaka in :gh:`109218`.)
+
+* :mod:`calendar`: ``calendar.January`` and ``calendar.February`` constants are
+ deprecated and replaced by :data:`calendar.JANUARY` and
+ :data:`calendar.FEBRUARY`.
+ (Contributed by Prince Roshan in :gh:`103636`.)
+
+* :attr:`codeobject.co_lnotab`: use the :meth:`codeobject.co_lines` method
+ instead.
+
+* :mod:`datetime`:
+
+ * :meth:`~datetime.datetime.utcnow`:
+ use ``datetime.datetime.now(tz=datetime.UTC)``.
+ * :meth:`~datetime.datetime.utcfromtimestamp`:
+ use ``datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)``.
+
+* :mod:`gettext`: Plural value must be an integer.
+
+* :mod:`importlib`:
+
+ * :func:`~importlib.util.cache_from_source` *debug_override* parameter is
+ deprecated: use the *optimization* parameter instead.
+
+* :mod:`importlib.metadata`:
+
+ * ``EntryPoints`` tuple interface.
+ * Implicit ``None`` on return values.
+
+* :mod:`mailbox`: Use of StringIO input and text mode is deprecated, use
+ BytesIO and binary mode instead.
+
+* :mod:`os`: Calling :func:`os.register_at_fork` in multi-threaded process.
+
+* :class:`!pydoc.ErrorDuringImport`: A tuple value for *exc_info* parameter is
+ deprecated, use an exception instance.
+
+* :mod:`re`: More strict rules are now applied for numerical group references
+ and group names in regular expressions. Only sequence of ASCII digits is now
+ accepted as a numerical reference. The group name in bytes patterns and
+ replacement strings can now only contain ASCII letters and digits and
+ underscore.
+ (Contributed by Serhiy Storchaka in :gh:`91760`.)
+
+* :mod:`!sre_compile`, :mod:`!sre_constants` and :mod:`!sre_parse` modules.
+
+* :mod:`shutil`: :func:`~shutil.rmtree`'s *onerror* parameter is deprecated in
+ Python 3.12; use the *onexc* parameter instead.
+
+* :mod:`ssl` options and protocols:
+
+ * :class:`ssl.SSLContext` without protocol argument is deprecated.
+ * :class:`ssl.SSLContext`: :meth:`~ssl.SSLContext.set_npn_protocols` and
+ :meth:`!selected_npn_protocol` are deprecated: use ALPN
+ instead.
+ * ``ssl.OP_NO_SSL*`` options
+ * ``ssl.OP_NO_TLS*`` options
+ * ``ssl.PROTOCOL_SSLv3``
+ * ``ssl.PROTOCOL_TLS``
+ * ``ssl.PROTOCOL_TLSv1``
+ * ``ssl.PROTOCOL_TLSv1_1``
+ * ``ssl.PROTOCOL_TLSv1_2``
+ * ``ssl.TLSVersion.SSLv3``
+ * ``ssl.TLSVersion.TLSv1``
+ * ``ssl.TLSVersion.TLSv1_1``
+
+* :mod:`threading` methods:
+
+ * :meth:`!threading.Condition.notifyAll`: use :meth:`~threading.Condition.notify_all`.
+ * :meth:`!threading.Event.isSet`: use :meth:`~threading.Event.is_set`.
+ * :meth:`!threading.Thread.isDaemon`, :meth:`threading.Thread.setDaemon`:
+ use :attr:`threading.Thread.daemon` attribute.
+ * :meth:`!threading.Thread.getName`, :meth:`threading.Thread.setName`:
+ use :attr:`threading.Thread.name` attribute.
+ * :meth:`!threading.currentThread`: use :meth:`threading.current_thread`.
+ * :meth:`!threading.activeCount`: use :meth:`threading.active_count`.
+
+* :class:`typing.Text` (:gh:`92332`).
+
+* :class:`unittest.IsolatedAsyncioTestCase`: it is deprecated to return a value
+ that is not ``None`` from a test case.
+
+* :mod:`urllib.parse` deprecated functions: :func:`~urllib.parse.urlparse` instead
+
+ * ``splitattr()``
+ * ``splithost()``
+ * ``splitnport()``
+ * ``splitpasswd()``
+ * ``splitport()``
+ * ``splitquery()``
+ * ``splittag()``
+ * ``splittype()``
+ * ``splituser()``
+ * ``splitvalue()``
+ * ``to_bytes()``
+
+* :mod:`urllib.request`: :class:`~urllib.request.URLopener` and
+ :class:`~urllib.request.FancyURLopener` style of invoking requests is
+ deprecated. Use newer :func:`~urllib.request.urlopen` functions and methods.
+
+* :mod:`wsgiref`: ``SimpleHandler.stdout.write()`` should not do partial
+ writes.
+
+* :mod:`xml.etree.ElementTree`: Testing the truth value of an
+ :class:`~xml.etree.ElementTree.Element` is deprecated. In a future release it
+ will always return ``True``. Prefer explicit ``len(elem)`` or
+ ``elem is not None`` tests instead.
+
+* :meth:`zipimport.zipimporter.load_module` is deprecated:
+ use :meth:`~zipimport.zipimporter.exec_module` instead.
diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
index 4c7c7ec9..fca3ba90 100644
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -177,8 +177,8 @@ interesting part with respect to embedding Python starts with ::
After initializing the interpreter, the script is loaded using
:c:func:`PyImport_Import`. This routine needs a Python string as its argument,
-which is constructed using the :c:func:`PyUnicode_FromString` data conversion
-routine. ::
+which is constructed using the :c:func:`PyUnicode_DecodeFSDefault` data
+conversion routine. ::
pFunc = PyObject_GetAttrString(pModule, argv[2]);
/* pFunc is a new reference */
diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst
index cb553cc2..4ee78d28 100644
--- a/Doc/extending/newtypes.rst
+++ b/Doc/extending/newtypes.rst
@@ -296,7 +296,7 @@ An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table
descriptors that are used at runtime is that any attribute defined this way can
have an associated doc string simply by providing the text in the table. An
application can use the introspection API to retrieve the descriptor from the
-class object, and get the doc string using its :attr:`!__doc__` attribute.
+class object, and get the doc string using its :attr:`~type.__doc__` attribute.
As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :c:member:`~PyMethodDef.ml_name` value
of ``NULL`` is required.
diff --git a/Doc/extending/newtypes_tutorial.rst b/Doc/extending/newtypes_tutorial.rst
index c2bc5f69..c5ef1e55 100644
--- a/Doc/extending/newtypes_tutorial.rst
+++ b/Doc/extending/newtypes_tutorial.rst
@@ -144,7 +144,7 @@ only used for variable-sized objects and should otherwise be zero.
If you want your type to be subclassable from Python, and your type has the same
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
inheritance. A Python subclass of your type will have to list your type first
- in its :attr:`~class.__bases__`, or else it will not be able to call your type's
+ in its :attr:`~type.__bases__`, or else it will not be able to call your type's
:meth:`~object.__new__` method without getting an error. You can avoid this problem by
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
base type does. Most of the time, this will be true anyway, because either your
@@ -449,7 +449,7 @@ Further, the attributes can be deleted, setting the C pointers to ``NULL``. Eve
though we can make sure the members are initialized to non-``NULL`` values, the
members can be set to ``NULL`` if the attributes are deleted.
-We define a single method, :meth:`!Custom.name()`, that outputs the objects name as the
+We define a single method, :meth:`!Custom.name`, that outputs the objects name as the
concatenation of the first and last names. ::
static PyObject *
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index c8beb64e..e2710fab 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -70,7 +70,7 @@ operations. This means that as far as floating-point operations are concerned,
Python behaves like many popular languages including C and Java.
Many numbers that can be written easily in decimal notation cannot be expressed
-exactly in binary floating-point. For example, after::
+exactly in binary floating point. For example, after::
>>> x = 1.2
@@ -87,7 +87,7 @@ which is exactly::
The typical precision of 53 bits provides Python floats with 15--16
decimal digits of accuracy.
-For a fuller explanation, please see the :ref:`floating point arithmetic
+For a fuller explanation, please see the :ref:`floating-point arithmetic
` chapter in the Python tutorial.
@@ -328,7 +328,7 @@ Can Python be compiled to machine code, C or some other language?
-----------------------------------------------------------------
`Cython `_ compiles a modified version of Python with
-optional annotations into C extensions. `Nuitka `_ is
+optional annotations into C extensions. `Nuitka `_ is
an up-and-coming compiler of Python into C++ code, aiming to support the full
Python language.
@@ -345,7 +345,7 @@ to perform a garbage collection, obtain debugging statistics, and tune the
collector's parameters.
Other implementations (such as `Jython `_ or
-`PyPy `_), however, can rely on a different mechanism
+`PyPy `_), however, can rely on a different mechanism
such as a full-blown garbage collector. This difference can cause some
subtle porting problems if your Python code depends on the behavior of the
reference counting implementation.
diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst
index 1cff2c40..3147fda7 100644
--- a/Doc/faq/extending.rst
+++ b/Doc/faq/extending.rst
@@ -246,13 +246,12 @@ Then, when you run GDB:
I want to compile a Python module on my Linux system, but some files are missing. Why?
--------------------------------------------------------------------------------------
-Most packaged versions of Python don't include the
-:file:`/usr/lib/python2.{x}/config/` directory, which contains various files
+Most packaged versions of Python omit some files
required for compiling Python extensions.
-For Red Hat, install the python-devel RPM to get the necessary files.
+For Red Hat, install the python3-devel RPM to get the necessary files.
-For Debian, run ``apt-get install python-dev``.
+For Debian, run ``apt-get install python3-dev``.
How do I tell "incomplete input" from "invalid input"?
------------------------------------------------------
diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst
index eb859c5d..578777d7 100644
--- a/Doc/faq/general.rst
+++ b/Doc/faq/general.rst
@@ -309,10 +309,9 @@ guaranteed that interfaces will remain the same throughout a series of bugfix
releases.
The latest stable releases can always be found on the `Python download page
-`_. There are two production-ready versions
-of Python: 2.x and 3.x. The recommended version is 3.x, which is supported by
-most widely used libraries. Although 2.x is still widely used, `it is not
-maintained anymore `_.
+`_.
+Python 3.x is the recommended version and supported by most widely used libraries.
+Python 2.x :pep:`is not maintained anymore <373>`.
How many people are using Python?
---------------------------------
diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst
index ac10a04d..45fd7eb1 100644
--- a/Doc/faq/library.rst
+++ b/Doc/faq/library.rst
@@ -825,12 +825,12 @@ is simple::
import random
random.random()
-This returns a random floating point number in the range [0, 1).
+This returns a random floating-point number in the range [0, 1).
There are also many other specialized generators in this module, such as:
* ``randrange(a, b)`` chooses an integer in the range [a, b).
-* ``uniform(a, b)`` chooses a floating point number in the range [a, b).
+* ``uniform(a, b)`` chooses a floating-point number in the range [a, b).
* ``normalvariate(mean, sdev)`` samples the normal (Gaussian) distribution.
Some higher-level functions operate on sequences directly, such as:
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index f43f69b8..b7fc2f29 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -869,7 +869,7 @@ How do I convert a string to a number?
--------------------------------------
For integers, use the built-in :func:`int` type constructor, e.g. ``int('144')
-== 144``. Similarly, :func:`float` converts to floating-point,
+== 144``. Similarly, :func:`float` converts to a floating-point number,
e.g. ``float('144') == 144.0``.
By default, these interpret the number as decimal, so that ``int('0144') ==
@@ -986,8 +986,8 @@ There are various techniques.
f()
-Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?
--------------------------------------------------------------------------------------
+Is there an equivalent to Perl's ``chomp()`` for removing trailing newlines from strings?
+-----------------------------------------------------------------------------------------
You can use ``S.rstrip("\r\n")`` to remove all occurrences of any line
terminator from the end of the string ``S`` without removing other trailing
@@ -1005,23 +1005,23 @@ Since this is typically only desired when reading text one line at a time, using
``S.rstrip()`` this way works well.
-Is there a scanf() or sscanf() equivalent?
-------------------------------------------
+Is there a ``scanf()`` or ``sscanf()`` equivalent?
+--------------------------------------------------
Not as such.
For simple input parsing, the easiest approach is usually to split the line into
whitespace-delimited words using the :meth:`~str.split` method of string objects
and then convert decimal strings to numeric values using :func:`int` or
-:func:`float`. :meth:`!split()` supports an optional "sep" parameter which is useful
+:func:`float`. :meth:`!split` supports an optional "sep" parameter which is useful
if the line uses something other than whitespace as a separator.
For more complicated input parsing, regular expressions are more powerful
than C's ``sscanf`` and better suited for the task.
-What does 'UnicodeDecodeError' or 'UnicodeEncodeError' error mean?
--------------------------------------------------------------------
+What does ``UnicodeDecodeError`` or ``UnicodeEncodeError`` error mean?
+----------------------------------------------------------------------
See the :ref:`unicode-howto`.
@@ -1036,7 +1036,7 @@ A raw string ending with an odd number of backslashes will escape the string's q
>>> r'C:\this\will\not\work\'
File "", line 1
r'C:\this\will\not\work\'
- ^
+ ^
SyntaxError: unterminated string literal (detected at line 1)
There are several workarounds for this. One is to use regular strings and double
@@ -1613,9 +1613,16 @@ method too, and it must do so carefully. The basic implementation of
self.__dict__[name] = value
...
-Most :meth:`!__setattr__` implementations must modify
-:meth:`self.__dict__ ` to store
-local state for self without causing an infinite recursion.
+Many :meth:`~object.__setattr__` implementations call :meth:`!object.__setattr__` to set
+an attribute on self without causing infinite recursion::
+
+ class X:
+ def __setattr__(self, name, value):
+ # Custom logic here...
+ object.__setattr__(self, name, value)
+
+Alternatively, it is possible to set attributes by inserting
+entries into :attr:`self.__dict__ ` directly.
How do I call a method defined in a base class from a derived class that extends it?
@@ -1741,11 +1748,31 @@ but effective way to define class private variables. Any identifier of the form
is textually replaced with ``_classname__spam``, where ``classname`` is the
current class name with any leading underscores stripped.
-This doesn't guarantee privacy: an outside user can still deliberately access
-the "_classname__spam" attribute, and private values are visible in the object's
-``__dict__``. Many Python programmers never bother to use private variable
-names at all.
+The identifier can be used unchanged within the class, but to access it outside
+the class, the mangled name must be used:
+
+.. code-block:: python
+ class A:
+ def __one(self):
+ return 1
+ def two(self):
+ return 2 * self.__one()
+
+ class B(A):
+ def three(self):
+ return 3 * self._A__one()
+
+ four = 4 * A()._A__one()
+
+In particular, this does not guarantee privacy since an outside user can still
+deliberately access the private attribute; many Python programmers never bother
+to use private variable names at all.
+
+.. seealso::
+
+ The :ref:`private name mangling specifications `
+ for details and special cases.
My class defines __del__ but it is not called when I delete the object.
-----------------------------------------------------------------------
@@ -1841,15 +1868,15 @@ object identity is assured. Generally, there are three circumstances where
identity is guaranteed:
1) Assignments create new names but do not change object identity. After the
-assignment ``new = old``, it is guaranteed that ``new is old``.
+ assignment ``new = old``, it is guaranteed that ``new is old``.
2) Putting an object in a container that stores object references does not
-change object identity. After the list assignment ``s[0] = x``, it is
-guaranteed that ``s[0] is x``.
+ change object identity. After the list assignment ``s[0] = x``, it is
+ guaranteed that ``s[0] is x``.
3) If an object is a singleton, it means that only one instance of that object
-can exist. After the assignments ``a = None`` and ``b = None``, it is
-guaranteed that ``a is b`` because ``None`` is a singleton.
+ can exist. After the assignments ``a = None`` and ``b = None``, it is
+ guaranteed that ``a is b`` because ``None`` is a singleton.
In most other circumstances, identity tests are inadvisable and equality tests
are preferred. In particular, identity tests should not be used to check
@@ -1879,28 +1906,30 @@ In the standard library code, you will see several common patterns for
correctly using identity tests:
1) As recommended by :pep:`8`, an identity test is the preferred way to check
-for ``None``. This reads like plain English in code and avoids confusion with
-other objects that may have boolean values that evaluate to false.
+ for ``None``. This reads like plain English in code and avoids confusion
+ with other objects that may have boolean values that evaluate to false.
2) Detecting optional arguments can be tricky when ``None`` is a valid input
-value. In those situations, you can create a singleton sentinel object
-guaranteed to be distinct from other objects. For example, here is how
-to implement a method that behaves like :meth:`dict.pop`::
+ value. In those situations, you can create a singleton sentinel object
+ guaranteed to be distinct from other objects. For example, here is how
+ to implement a method that behaves like :meth:`dict.pop`:
+
+ .. code-block:: python
- _sentinel = object()
+ _sentinel = object()
- def pop(self, key, default=_sentinel):
- if key in self:
- value = self[key]
- del self[key]
- return value
- if default is _sentinel:
- raise KeyError(key)
- return default
+ def pop(self, key, default=_sentinel):
+ if key in self:
+ value = self[key]
+ del self[key]
+ return value
+ if default is _sentinel:
+ raise KeyError(key)
+ return default
3) Container implementations sometimes need to augment equality tests with
-identity tests. This prevents the code from being confused by objects such as
-``float('NaN')`` that are not equal to themselves.
+ identity tests. This prevents the code from being confused by objects
+ such as ``float('NaN')`` that are not equal to themselves.
For example, here is the implementation of
:meth:`!collections.abc.Sequence.__contains__`::
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index d1745bf5..76a85610 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -118,7 +118,7 @@ Glossary
:keyword:`yield` expression.
Each :keyword:`yield` temporarily suspends processing, remembering the
- location execution state (including local variables and pending
+ execution state (including local variables and pending
try-statements). When the *asynchronous generator iterator* effectively
resumes with another awaitable returned by :meth:`~object.__anext__`, it
picks up where it left off. See :pep:`492` and :pep:`525`.
@@ -350,7 +350,7 @@ Glossary
docstring
A string literal which appears as the first expression in a class,
function or module. While ignored when the suite is executed, it is
- recognized by the compiler and put into the :attr:`!__doc__` attribute
+ recognized by the compiler and put into the :attr:`~definition.__doc__` attribute
of the enclosing class, function or module. Since it is available via
introspection, it is the canonical place for documentation of the
object.
@@ -437,7 +437,7 @@ Glossary
` for use with :data:`sys.meta_path`, and :term:`path
entry finders ` for use with :data:`sys.path_hooks`.
- See :ref:`importsystem` and :mod:`importlib` for much more detail.
+ See :ref:`finders-and-loaders` and :mod:`importlib` for much more detail.
floor division
Mathematical division that rounds down to nearest integer. The floor
@@ -505,7 +505,7 @@ Glossary
An object created by a :term:`generator` function.
Each :keyword:`yield` temporarily suspends processing, remembering the
- location execution state (including local variables and pending
+ execution state (including local variables and pending
try-statements). When the *generator iterator* resumes, it picks up where
it left off (in contrast to functions which start fresh on every
invocation).
@@ -591,6 +591,14 @@ Glossary
:ref:`idle` is a basic editor and interpreter environment
which ships with the standard distribution of Python.
+ immortal
+ *Immortal objects* are a CPython implementation detail introduced
+ in :pep:`683`.
+
+ If an object is immortal, its :term:`reference count` is never modified,
+ and therefore it is never deallocated while the interpreter is running.
+ For example, :const:`True` and :const:`None` are immortal in CPython.
+
immutable
An object with a fixed value. Immutable objects include numbers, strings and
tuples. Such an object cannot be altered. A new object has to
@@ -648,7 +656,7 @@ Glossary
iterables include all sequence types (such as :class:`list`, :class:`str`,
and :class:`tuple`) and some non-sequence types like :class:`dict`,
:term:`file objects `, and objects of any classes you define
- with an :meth:`~iterator.__iter__` method or with a
+ with an :meth:`~object.__iter__` method or with a
:meth:`~object.__getitem__` method
that implements :term:`sequence` semantics.
@@ -726,6 +734,10 @@ Glossary
thread removes *key* from *mapping* after the test, but before the lookup.
This issue can be solved with locks or by using the EAFP approach.
+ lexical analyzer
+
+ Formal name for the *tokenizer*; see :term:`token`.
+
list
A built-in Python :term:`sequence`. Despite its name it is more akin
to an array in other languages than to a linked list since access to
@@ -740,10 +752,15 @@ Glossary
processed.
loader
- An object that loads a module. It must define a method named
- :meth:`load_module`. A loader is typically returned by a
- :term:`finder`. See :pep:`302` for details and
- :class:`importlib.abc.Loader` for an :term:`abstract base class`.
+ An object that loads a module.
+ It must define the :meth:`!exec_module` and :meth:`!create_module` methods
+ to implement the :class:`~importlib.abc.Loader` interface.
+ A loader is typically returned by a :term:`finder`.
+ See also:
+
+ * :ref:`finders-and-loaders`
+ * :class:`importlib.abc.Loader`
+ * :pep:`302`
locale encoding
On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
@@ -813,6 +830,8 @@ Glossary
A namespace containing the import-related information used to load a
module. An instance of :class:`importlib.machinery.ModuleSpec`.
+ See also :ref:`module-specs`.
+
MRO
See :term:`method resolution order`.
@@ -858,11 +877,16 @@ Glossary
modules, respectively.
namespace package
- A :pep:`420` :term:`package` which serves only as a container for
- subpackages. Namespace packages may have no physical representation,
+ A :term:`package` which serves only as a container for subpackages.
+ Namespace packages may have no physical representation,
and specifically are not like a :term:`regular package` because they
have no ``__init__.py`` file.
+ Namespace packages allow several individually installable packages to have a common parent package.
+ Otherwise, it is recommended to use a :term:`regular package`.
+
+ For more information, see :pep:`420` and :ref:`reference-namespace-package`.
+
See also :term:`module`.
nested scope
@@ -1098,7 +1122,7 @@ Glossary
:class:`tuple`, and :class:`bytes`. Note that :class:`dict` also
supports :meth:`~object.__getitem__` and :meth:`!__len__`, but is considered a
mapping rather than a sequence because the lookups use arbitrary
- :term:`immutable` keys rather than integers.
+ :term:`hashable` keys rather than integers.
The :class:`collections.abc.Sequence` abstract base class
defines a much richer interface that goes beyond just
@@ -1126,6 +1150,17 @@ Glossary
when several are given, such as in ``variable_name[1:3:5]``. The bracket
(subscript) notation uses :class:`slice` objects internally.
+ soft deprecated
+ A soft deprecated API should not be used in new code,
+ but it is safe for already existing code to use it.
+ The API remains documented and tested, but will not be enhanced further.
+
+ Soft deprecation, unlike normal deprecation, does not plan on removing the API
+ and will not emit warnings.
+
+ See `PEP 387: Soft Deprecation
+ `_.
+
special method
.. index:: pair: special; method
@@ -1181,6 +1216,17 @@ Glossary
See also :term:`binary file` for a file object able to read and write
:term:`bytes-like objects `.
+ token
+
+ A small unit of source code, generated by the
+ :ref:`lexical analyzer ` (also called the *tokenizer*).
+ Names, numbers, strings, operators,
+ newlines and similar are represented by tokens.
+
+ The :mod:`tokenize` module exposes Python's lexical analyzer.
+ The :mod:`token` module contains information on the various types
+ of tokens.
+
triple-quoted string
A string which is bound by three instances of either a quotation mark
(") or an apostrophe ('). While they don't provide any functionality
@@ -1193,7 +1239,7 @@ Glossary
type
The type of a Python object determines what kind of object it is; every
object has a type. An object's type is accessible as its
- :attr:`~instance.__class__` attribute or can be retrieved with
+ :attr:`~object.__class__` attribute or can be retrieved with
``type(obj)``.
type alias
diff --git a/Doc/howto/annotations.rst b/Doc/howto/annotations.rst
index be8c7e6c..174078b8 100644
--- a/Doc/howto/annotations.rst
+++ b/Doc/howto/annotations.rst
@@ -102,9 +102,9 @@ Your code will have to have a separate code path if the object
you're examining is a class (``isinstance(o, type)``).
In that case, best practice relies on an implementation detail
of Python 3.9 and before: if a class has annotations defined,
-they are stored in the class's ``__dict__`` dictionary. Since
+they are stored in the class's :attr:`~type.__dict__` dictionary. Since
the class may or may not have annotations defined, best practice
-is to call the ``get`` method on the class dict.
+is to call the :meth:`~dict.get` method on the class dict.
To put it all together, here is some sample code that safely
accesses the ``__annotations__`` attribute on an arbitrary
@@ -121,8 +121,8 @@ the type of ``ann`` using :func:`isinstance` before further
examination.
Note that some exotic or malformed type objects may not have
-a ``__dict__`` attribute, so for extra safety you may also wish
-to use :func:`getattr` to access ``__dict__``.
+a :attr:`~type.__dict__` attribute, so for extra safety you may also wish
+to use :func:`getattr` to access :attr:`!__dict__`.
Manually Un-Stringizing Stringized Annotations
diff --git a/Doc/howto/argparse-optparse.rst b/Doc/howto/argparse-optparse.rst
new file mode 100644
index 00000000..cef2d893
--- /dev/null
+++ b/Doc/howto/argparse-optparse.rst
@@ -0,0 +1,55 @@
+.. currentmodule:: argparse
+
+.. _upgrading-optparse-code:
+
+==========================
+Upgrading optparse code
+==========================
+
+Originally, the :mod:`argparse` module had attempted to maintain compatibility
+with :mod:`optparse`. However, :mod:`optparse` was difficult to extend
+transparently, particularly with the changes required to support
+``nargs=`` specifiers and better usage messages. When most everything in
+:mod:`optparse` had either been copy-pasted over or monkey-patched, it no
+longer seemed practical to try to maintain the backwards compatibility.
+
+The :mod:`argparse` module improves on the :mod:`optparse`
+module in a number of ways including:
+
+* Handling positional arguments.
+* Supporting subcommands.
+* Allowing alternative option prefixes like ``+`` and ``/``.
+* Handling zero-or-more and one-or-more style arguments.
+* Producing more informative usage messages.
+* Providing a much simpler interface for custom ``type`` and ``action``.
+
+A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
+
+* Replace all :meth:`optparse.OptionParser.add_option` calls with
+ :meth:`ArgumentParser.add_argument` calls.
+
+* Replace ``(options, args) = parser.parse_args()`` with ``args =
+ parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
+ calls for the positional arguments. Keep in mind that what was previously
+ called ``options``, now in the :mod:`argparse` context is called ``args``.
+
+* Replace :meth:`optparse.OptionParser.disable_interspersed_args`
+ by using :meth:`~ArgumentParser.parse_intermixed_args` instead of
+ :meth:`~ArgumentParser.parse_args`.
+
+* Replace callback actions and the ``callback_*`` keyword arguments with
+ ``type`` or ``action`` arguments.
+
+* Replace string names for ``type`` keyword arguments with the corresponding
+ type objects (e.g. int, float, complex, etc).
+
+* Replace :class:`optparse.Values` with :class:`Namespace` and
+ :exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
+ :exc:`ArgumentError`.
+
+* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
+ the standard Python syntax to use dictionaries to format strings, that is,
+ ``%(default)s`` and ``%(prog)s``.
+
+* Replace the OptionParser constructor ``version`` argument with a call to
+ ``parser.add_argument('--version', action='version', version='')``.
diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index ae5bab90..ac2a0465 100644
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -841,6 +841,53 @@ translated messages.
To translate your own strings in the :mod:`argparse` output, use :mod:`gettext`.
+Custom type converters
+======================
+
+The :mod:`argparse` module allows you to specify custom type converters for
+your command-line arguments. This allows you to modify user input before it's
+stored in the :class:`argparse.Namespace`. This can be useful when you need to
+pre-process the input before it is used in your program.
+
+When using a custom type converter, you can use any callable that takes a
+single string argument (the argument value) and returns the converted value.
+However, if you need to handle more complex scenarios, you can use a custom
+action class with the **action** parameter instead.
+
+For example, let's say you want to handle arguments with different prefixes and
+process them accordingly::
+
+ import argparse
+
+ parser = argparse.ArgumentParser(prefix_chars='-+')
+
+ parser.add_argument('-a', metavar='', action='append',
+ type=lambda x: ('-', x))
+ parser.add_argument('+a', metavar='', action='append',
+ type=lambda x: ('+', x))
+
+ args = parser.parse_args()
+ print(args)
+
+Output:
+
+.. code-block:: shell-session
+
+ $ python prog.py -a value1 +a value2
+ Namespace(a=[('-', 'value1'), ('+', 'value2')])
+
+In this example, we:
+
+* Created a parser with custom prefix characters using the ``prefix_chars``
+ parameter.
+
+* Defined two arguments, ``-a`` and ``+a``, which used the ``type`` parameter to
+ create custom type converters to store the value in a tuple with the prefix.
+
+Without the custom type converters, the arguments would have treated the ``-a``
+and ``+a`` as the same argument, which would have been undesirable. By using custom
+type converters, we were able to differentiate between the two arguments.
+
Conclusion
==========
diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst
index 330402d1..ac73fcb3 100644
--- a/Doc/howto/descriptor.rst
+++ b/Doc/howto/descriptor.rst
@@ -42,7 +42,7 @@ add new capabilities one by one.
Simple example: A descriptor that returns a constant
----------------------------------------------------
-The :class:`Ten` class is a descriptor whose :meth:`__get__` method always
+The :class:`!Ten` class is a descriptor whose :meth:`~object.__get__` method always
returns the constant ``10``:
.. testcode::
@@ -120,10 +120,10 @@ different, updated answers each time::
2
Besides showing how descriptors can run computations, this example also
-reveals the purpose of the parameters to :meth:`__get__`. The *self*
+reveals the purpose of the parameters to :meth:`~object.__get__`. The *self*
parameter is *size*, an instance of *DirectorySize*. The *obj* parameter is
either *g* or *s*, an instance of *Directory*. It is the *obj* parameter that
-lets the :meth:`__get__` method learn the target directory. The *objtype*
+lets the :meth:`~object.__get__` method learn the target directory. The *objtype*
parameter is the class *Directory*.
@@ -133,7 +133,7 @@ Managed attributes
A popular use for descriptors is managing access to instance data. The
descriptor is assigned to a public attribute in the class dictionary while the
actual data is stored as a private attribute in the instance dictionary. The
-descriptor's :meth:`__get__` and :meth:`__set__` methods are triggered when
+descriptor's :meth:`~object.__get__` and :meth:`~object.__set__` methods are triggered when
the public attribute is accessed.
In the following example, *age* is the public attribute and *_age* is the
@@ -215,9 +215,9 @@ Customized names
When a class uses descriptors, it can inform each descriptor about which
variable name was used.
-In this example, the :class:`Person` class has two descriptor instances,
-*name* and *age*. When the :class:`Person` class is defined, it makes a
-callback to :meth:`__set_name__` in *LoggedAccess* so that the field names can
+In this example, the :class:`!Person` class has two descriptor instances,
+*name* and *age*. When the :class:`!Person` class is defined, it makes a
+callback to :meth:`~object.__set_name__` in *LoggedAccess* so that the field names can
be recorded, giving each descriptor its own *public_name* and *private_name*:
.. testcode::
@@ -253,8 +253,8 @@ be recorded, giving each descriptor its own *public_name* and *private_name*:
def birthday(self):
self.age += 1
-An interactive session shows that the :class:`Person` class has called
-:meth:`__set_name__` so that the field names would be recorded. Here
+An interactive session shows that the :class:`!Person` class has called
+:meth:`~object.__set_name__` so that the field names would be recorded. Here
we call :func:`vars` to look up the descriptor without triggering it:
.. doctest::
@@ -294,10 +294,10 @@ The two *Person* instances contain only the private names:
Closing thoughts
----------------
-A :term:`descriptor` is what we call any object that defines :meth:`__get__`,
-:meth:`__set__`, or :meth:`__delete__`.
+A :term:`descriptor` is what we call any object that defines :meth:`~object.__get__`,
+:meth:`~object.__set__`, or :meth:`~object.__delete__`.
-Optionally, descriptors can have a :meth:`__set_name__` method. This is only
+Optionally, descriptors can have a :meth:`~object.__set_name__` method. This is only
used in cases where a descriptor needs to know either the class where it was
created or the name of class variable it was assigned to. (This method, if
present, is called even if the class is not a descriptor.)
@@ -337,7 +337,7 @@ any data, it verifies that the new value meets various type and range
restrictions. If those restrictions aren't met, it raises an exception to
prevent data corruption at its source.
-This :class:`Validator` class is both an :term:`abstract base class` and a
+This :class:`!Validator` class is both an :term:`abstract base class` and a
managed attribute descriptor:
.. testcode::
@@ -360,8 +360,8 @@ managed attribute descriptor:
def validate(self, value):
pass
-Custom validators need to inherit from :class:`Validator` and must supply a
-:meth:`validate` method to test various restrictions as needed.
+Custom validators need to inherit from :class:`!Validator` and must supply a
+:meth:`!validate` method to test various restrictions as needed.
Custom validators
@@ -369,13 +369,13 @@ Custom validators
Here are three practical data validation utilities:
-1) :class:`OneOf` verifies that a value is one of a restricted set of options.
+1) :class:`!OneOf` verifies that a value is one of a restricted set of options.
-2) :class:`Number` verifies that a value is either an :class:`int` or
+2) :class:`!Number` verifies that a value is either an :class:`int` or
:class:`float`. Optionally, it verifies that a value is between a given
minimum or maximum.
-3) :class:`String` verifies that a value is a :class:`str`. Optionally, it
+3) :class:`!String` verifies that a value is a :class:`str`. Optionally, it
validates a given minimum or maximum length. It can validate a
user-defined `predicate
`_ as well.
@@ -498,8 +498,8 @@ Definition and introduction
---------------------------
In general, a descriptor is an attribute value that has one of the methods in
-the descriptor protocol. Those methods are :meth:`__get__`, :meth:`__set__`,
-and :meth:`__delete__`. If any of those methods are defined for an
+the descriptor protocol. Those methods are :meth:`~object.__get__`, :meth:`~object.__set__`,
+and :meth:`~object.__delete__`. If any of those methods are defined for an
attribute, it is said to be a :term:`descriptor`.
The default behavior for attribute access is to get, set, or delete the
@@ -513,7 +513,7 @@ were defined.
Descriptors are a powerful, general purpose protocol. They are the mechanism
behind properties, methods, static methods, class methods, and
-:func:`super()`. They are used throughout Python itself. Descriptors
+:func:`super`. They are used throughout Python itself. Descriptors
simplify the underlying C code and offer a flexible set of new tools for
everyday Python programs.
@@ -531,8 +531,8 @@ That is all there is to it. Define any of these methods and an object is
considered a descriptor and can override default behavior upon being looked up
as an attribute.
-If an object defines :meth:`__set__` or :meth:`__delete__`, it is considered
-a data descriptor. Descriptors that only define :meth:`__get__` are called
+If an object defines :meth:`~object.__set__` or :meth:`~object.__delete__`, it is considered
+a data descriptor. Descriptors that only define :meth:`~object.__get__` are called
non-data descriptors (they are often used for methods but other uses are
possible).
@@ -542,9 +542,9 @@ has an entry with the same name as a data descriptor, the data descriptor
takes precedence. If an instance's dictionary has an entry with the same
name as a non-data descriptor, the dictionary entry takes precedence.
-To make a read-only data descriptor, define both :meth:`__get__` and
-:meth:`__set__` with the :meth:`__set__` raising an :exc:`AttributeError` when
-called. Defining the :meth:`__set__` method with an exception raising
+To make a read-only data descriptor, define both :meth:`~object.__get__` and
+:meth:`~object.__set__` with the :meth:`~object.__set__` raising an :exc:`AttributeError` when
+called. Defining the :meth:`~object.__set__` method with an exception raising
placeholder is enough to make it a data descriptor.
@@ -559,8 +559,8 @@ attribute access.
The expression ``obj.x`` looks up the attribute ``x`` in the chain of
namespaces for ``obj``. If the search finds a descriptor outside of the
-instance ``__dict__``, its :meth:`__get__` method is invoked according to the
-precedence rules listed below.
+instance :attr:`~object.__dict__`, its :meth:`~object.__get__` method is
+invoked according to the precedence rules listed below.
The details of invocation depend on whether ``obj`` is an object, class, or
instance of super.
@@ -571,7 +571,7 @@ Invocation from an instance
Instance lookup scans through a chain of namespaces giving data descriptors
the highest priority, followed by instance variables, then non-data
-descriptors, then class variables, and lastly :meth:`__getattr__` if it is
+descriptors, then class variables, and lastly :meth:`~object.__getattr__` if it is
provided.
If a descriptor is found for ``a.x``, then it is invoked with:
@@ -716,12 +716,12 @@ a pure Python equivalent:
>>> object_getattribute(u2, 'x') == u2.x == (D1, u2, U2)
True
-Note, there is no :meth:`__getattr__` hook in the :meth:`__getattribute__`
-code. That is why calling :meth:`__getattribute__` directly or with
-``super().__getattribute__`` will bypass :meth:`__getattr__` entirely.
+Note, there is no :meth:`~object.__getattr__` hook in the :meth:`~object.__getattribute__`
+code. That is why calling :meth:`~object.__getattribute__` directly or with
+``super().__getattribute__`` will bypass :meth:`~object.__getattr__` entirely.
Instead, it is the dot operator and the :func:`getattr` function that are
-responsible for invoking :meth:`__getattr__` whenever :meth:`__getattribute__`
+responsible for invoking :meth:`~object.__getattr__` whenever :meth:`~object.__getattribute__`
raises an :exc:`AttributeError`. Their logic is encapsulated in a helper
function:
@@ -773,8 +773,8 @@ Invocation from a class
-----------------------
The logic for a dotted lookup such as ``A.x`` is in
-:meth:`type.__getattribute__`. The steps are similar to those for
-:meth:`object.__getattribute__` but the instance dictionary lookup is replaced
+:meth:`!type.__getattribute__`. The steps are similar to those for
+:meth:`!object.__getattribute__` but the instance dictionary lookup is replaced
by a search through the class's :term:`method resolution order`.
If a descriptor is found, it is invoked with ``desc.__get__(None, A)``.
@@ -786,8 +786,8 @@ The full C implementation can be found in :c:func:`!type_getattro` and
Invocation from super
---------------------
-The logic for super's dotted lookup is in the :meth:`__getattribute__` method for
-object returned by :class:`super()`.
+The logic for super's dotted lookup is in the :meth:`~object.__getattribute__` method for
+object returned by :func:`super`.
A dotted lookup such as ``super(A, obj).m`` searches ``obj.__class__.__mro__``
for the base class ``B`` immediately following ``A`` and then returns
@@ -803,21 +803,21 @@ The full C implementation can be found in :c:func:`!super_getattro` in
Summary of invocation logic
---------------------------
-The mechanism for descriptors is embedded in the :meth:`__getattribute__()`
+The mechanism for descriptors is embedded in the :meth:`~object.__getattribute__`
methods for :class:`object`, :class:`type`, and :func:`super`.
The important points to remember are:
-* Descriptors are invoked by the :meth:`__getattribute__` method.
+* Descriptors are invoked by the :meth:`~object.__getattribute__` method.
* Classes inherit this machinery from :class:`object`, :class:`type`, or
:func:`super`.
-* Overriding :meth:`__getattribute__` prevents automatic descriptor calls
+* Overriding :meth:`~object.__getattribute__` prevents automatic descriptor calls
because all the descriptor logic is in that method.
-* :meth:`object.__getattribute__` and :meth:`type.__getattribute__` make
- different calls to :meth:`__get__`. The first includes the instance and may
+* :meth:`!object.__getattribute__` and :meth:`!type.__getattribute__` make
+ different calls to :meth:`~object.__get__`. The first includes the instance and may
include the class. The second puts in ``None`` for the instance and always
includes the class.
@@ -832,16 +832,16 @@ Automatic name notification
Sometimes it is desirable for a descriptor to know what class variable name it
was assigned to. When a new class is created, the :class:`type` metaclass
scans the dictionary of the new class. If any of the entries are descriptors
-and if they define :meth:`__set_name__`, that method is called with two
+and if they define :meth:`~object.__set_name__`, that method is called with two
arguments. The *owner* is the class where the descriptor is used, and the
*name* is the class variable the descriptor was assigned to.
The implementation details are in :c:func:`!type_new` and
:c:func:`!set_names` in :source:`Objects/typeobject.c`.
-Since the update logic is in :meth:`type.__new__`, notifications only take
+Since the update logic is in :meth:`!type.__new__`, notifications only take
place at the time of class creation. If descriptors are added to the class
-afterwards, :meth:`__set_name__` will need to be called manually.
+afterwards, :meth:`~object.__set_name__` will need to be called manually.
ORM example
@@ -870,7 +870,7 @@ care of lookups or updates:
conn.execute(self.store, [value, obj.key])
conn.commit()
-We can use the :class:`Field` class to define `models
+We can use the :class:`!Field` class to define `models
`_ that describe the schema for
each table in a database:
@@ -1150,7 +1150,7 @@ to wrap access to the value attribute in a property data descriptor:
self.recalc()
return self._value
-Either the built-in :func:`property` or our :func:`Property` equivalent would
+Either the built-in :func:`property` or our :func:`!Property` equivalent would
work in this example.
@@ -1183,7 +1183,7 @@ roughly equivalent to:
return func(obj, *args, **kwargs)
To support automatic creation of methods, functions include the
-:meth:`__get__` method for binding methods during attribute access. This
+:meth:`~object.__get__` method for binding methods during attribute access. This
means that functions are non-data descriptors that return bound methods
during dotted lookup from an instance. Here's how it works:
@@ -1215,19 +1215,19 @@ The function has a :term:`qualified name` attribute to support introspection:
'D.f'
Accessing the function through the class dictionary does not invoke
-:meth:`__get__`. Instead, it just returns the underlying function object::
+:meth:`~object.__get__`. Instead, it just returns the underlying function object::
>>> D.__dict__['f']
-Dotted access from a class calls :meth:`__get__` which just returns the
+Dotted access from a class calls :meth:`~object.__get__` which just returns the
underlying function unchanged::
>>> D.f
The interesting behavior occurs during dotted access from an instance. The
-dotted lookup calls :meth:`__get__` which returns a bound method object::
+dotted lookup calls :meth:`~object.__get__` which returns a bound method object::
>>> d = D()
>>> d.f
@@ -1252,7 +1252,7 @@ Kinds of methods
Non-data descriptors provide a simple mechanism for variations on the usual
patterns of binding functions into methods.
-To recap, functions have a :meth:`__get__` method so that they can be converted
+To recap, functions have a :meth:`~object.__get__` method so that they can be converted
to a method when accessed as attributes. The non-data descriptor transforms an
``obj.f(*args)`` call into ``f(obj, *args)``. Calling ``cls.f(*args)``
becomes ``f(*args)``.
@@ -1682,7 +1682,7 @@ by member descriptors:
'Emulate member_repr() in Objects/descrobject.c'
return f''
-The :meth:`type.__new__` method takes care of adding member objects to class
+The :meth:`!type.__new__` method takes care of adding member objects to class
variables:
.. testcode::
@@ -1733,7 +1733,7 @@ Python:
)
super().__delattr__(name)
-To use the simulation in a real class, just inherit from :class:`Object` and
+To use the simulation in a real class, just inherit from :class:`!Object` and
set the :term:`metaclass` to :class:`Type`:
.. testcode::
diff --git a/Doc/howto/enum.rst b/Doc/howto/enum.rst
index ffdafb74..3743e681 100644
--- a/Doc/howto/enum.rst
+++ b/Doc/howto/enum.rst
@@ -1,3 +1,5 @@
+.. _enum-howto:
+
==========
Enum HOWTO
==========
@@ -7,7 +9,7 @@ Enum HOWTO
.. currentmodule:: enum
An :class:`Enum` is a set of symbolic names bound to unique values. They are
-similar to global variables, but they offer a more useful :func:`repr()`,
+similar to global variables, but they offer a more useful :func:`repr`,
grouping, type-safety, and a few other features.
They are most useful when you have a variable that can take one of a limited
@@ -62,12 +64,12 @@ The *type* of an enumeration member is the enum it belongs to::
>>> isinstance(Weekday.FRIDAY, Weekday)
True
-Enum members have an attribute that contains just their :attr:`name`::
+Enum members have an attribute that contains just their :attr:`!name`::
>>> print(Weekday.TUESDAY.name)
TUESDAY
-Likewise, they have an attribute for their :attr:`value`::
+Likewise, they have an attribute for their :attr:`!value`::
>>> Weekday.WEDNESDAY.value
@@ -75,17 +77,18 @@ Likewise, they have an attribute for their :attr:`value`::
Unlike many languages that treat enumerations solely as name/value pairs,
Python Enums can have behavior added. For example, :class:`datetime.date`
-has two methods for returning the weekday: :meth:`weekday` and :meth:`isoweekday`.
+has two methods for returning the weekday:
+:meth:`~datetime.date.weekday` and :meth:`~datetime.date.isoweekday`.
The difference is that one of them counts from 0-6 and the other from 1-7.
-Rather than keep track of that ourselves we can add a method to the :class:`Weekday`
-enum to extract the day from the :class:`date` instance and return the matching
+Rather than keep track of that ourselves we can add a method to the :class:`!Weekday`
+enum to extract the day from the :class:`~datetime.date` instance and return the matching
enum member::
@classmethod
def from_date(cls, date):
return cls(date.isoweekday())
-The complete :class:`Weekday` enum now looks like this::
+The complete :class:`!Weekday` enum now looks like this::
>>> class Weekday(Enum):
... MONDAY = 1
@@ -108,7 +111,7 @@ Now we can find out what today is! Observe::
Of course, if you're reading this on some other day, you'll see that day instead.
-This :class:`Weekday` enum is great if our variable only needs one day, but
+This :class:`!Weekday` enum is great if our variable only needs one day, but
what if we need several? Maybe we're writing a function to plot chores during
a week, and don't want to use a :class:`list` -- we could use a different type
of :class:`Enum`::
@@ -126,7 +129,7 @@ of :class:`Enum`::
We've changed two things: we're inherited from :class:`Flag`, and the values are
all powers of 2.
-Just like the original :class:`Weekday` enum above, we can have a single selection::
+Just like the original :class:`!Weekday` enum above, we can have a single selection::
>>> first_week_day = Weekday.MONDAY
>>> first_week_day
@@ -165,7 +168,7 @@ And a function to display the chores for a given day::
answer SO questions
In cases where the actual values of the members do not matter, you can save
-yourself some work and use :func:`auto()` for the values::
+yourself some work and use :func:`auto` for the values::
>>> from enum import auto
>>> class Weekday(Flag):
@@ -201,7 +204,7 @@ If you want to access enum members by *name*, use item access::
>>> Color['GREEN']
-If you have an enum member and need its :attr:`name` or :attr:`value`::
+If you have an enum member and need its :attr:`!name` or :attr:`!value`::
>>> member = Color.RED
>>> member.name
@@ -282,7 +285,7 @@ If the exact value is unimportant you can use :class:`auto`::
>>> [member.value for member in Color]
[1, 2, 3]
-The values are chosen by :func:`_generate_next_value_`, which can be
+The values are chosen by :func:`~Enum._generate_next_value_`, which can be
overridden::
>>> class AutoName(Enum):
@@ -301,7 +304,7 @@ overridden::
.. note::
- The :meth:`_generate_next_value_` method must be defined before any members.
+ The :meth:`~Enum._generate_next_value_` method must be defined before any members.
Iteration
---------
@@ -422,18 +425,18 @@ Then::
The rules for what is allowed are as follows: names that start and end with
a single underscore are reserved by enum and cannot be used; all other
attributes defined within an enumeration will become members of this
-enumeration, with the exception of special methods (:meth:`__str__`,
-:meth:`__add__`, etc.), descriptors (methods are also descriptors), and
-variable names listed in :attr:`_ignore_`.
+enumeration, with the exception of special methods (:meth:`~object.__str__`,
+:meth:`~object.__add__`, etc.), descriptors (methods are also descriptors), and
+variable names listed in :attr:`~Enum._ignore_`.
-Note: if your enumeration defines :meth:`__new__` and/or :meth:`__init__`,
+Note: if your enumeration defines :meth:`~object.__new__` and/or :meth:`~object.__init__`,
any value(s) given to the enum member will be passed into those methods.
See `Planet`_ for an example.
.. note::
- The :meth:`__new__` method, if defined, is used during creation of the Enum
- members; it is then replaced by Enum's :meth:`__new__` which is used after
+ The :meth:`~object.__new__` method, if defined, is used during creation of the Enum
+ members; it is then replaced by Enum's :meth:`~object.__new__` which is used after
class creation for lookup of existing members. See :ref:`new-vs-init` for
more details.
@@ -525,7 +528,7 @@ from that module.
nested in other classes.
It is possible to modify how enum members are pickled/unpickled by defining
-:meth:`__reduce_ex__` in the enumeration class. The default method is by-value,
+:meth:`~object.__reduce_ex__` in the enumeration class. The default method is by-value,
but enums with complicated values may want to use by-name::
>>> import enum
@@ -561,7 +564,7 @@ values. The last two options enable assigning arbitrary values to
enumerations; the others auto-assign increasing integers starting with 1 (use
the ``start`` parameter to specify a different starting value). A
new class derived from :class:`Enum` is returned. In other words, the above
-assignment to :class:`Animal` is equivalent to::
+assignment to :class:`!Animal` is equivalent to::
>>> class Animal(Enum):
... ANT = 1
@@ -589,7 +592,7 @@ The solution is to specify the module name explicitly as follows::
the source, pickling will be disabled.
The new pickle protocol 4 also, in some circumstances, relies on
-:attr:`~definition.__qualname__` being set to the location where pickle will be able
+:attr:`~type.__qualname__` being set to the location where pickle will be able
to find the class. For example, if the class was made available in class
SomeData in the global scope::
@@ -872,7 +875,7 @@ simple to implement independently::
pass
This demonstrates how similar derived enumerations can be defined; for example
-a :class:`FloatEnum` that mixes in :class:`float` instead of :class:`int`.
+a :class:`!FloatEnum` that mixes in :class:`float` instead of :class:`int`.
Some rules:
@@ -886,32 +889,32 @@ Some rules:
additional type, all the members must have values of that type, e.g.
:class:`int` above. This restriction does not apply to mix-ins which only
add methods and don't specify another type.
-4. When another data type is mixed in, the :attr:`value` attribute is *not the
+4. When another data type is mixed in, the :attr:`~Enum.value` attribute is *not the
same* as the enum member itself, although it is equivalent and will compare
equal.
-5. A ``data type`` is a mixin that defines :meth:`__new__`, or a
+5. A ``data type`` is a mixin that defines :meth:`~object.__new__`, or a
:class:`~dataclasses.dataclass`
6. %-style formatting: ``%s`` and ``%r`` call the :class:`Enum` class's
- :meth:`__str__` and :meth:`__repr__` respectively; other codes (such as
+ :meth:`~object.__str__` and :meth:`~object.__repr__` respectively; other codes (such as
``%i`` or ``%h`` for IntEnum) treat the enum member as its mixed-in type.
7. :ref:`Formatted string literals `, :meth:`str.format`,
- and :func:`format` will use the enum's :meth:`__str__` method.
+ and :func:`format` will use the enum's :meth:`~object.__str__` method.
.. note::
Because :class:`IntEnum`, :class:`IntFlag`, and :class:`StrEnum` are
designed to be drop-in replacements for existing constants, their
- :meth:`__str__` method has been reset to their data types'
- :meth:`__str__` method.
+ :meth:`~object.__str__` method has been reset to their data types'
+ :meth:`~object.__str__` method.
.. _new-vs-init:
-When to use :meth:`__new__` vs. :meth:`__init__`
-------------------------------------------------
+When to use :meth:`~object.__new__` vs. :meth:`~object.__init__`
+----------------------------------------------------------------
-:meth:`__new__` must be used whenever you want to customize the actual value of
+:meth:`~object.__new__` must be used whenever you want to customize the actual value of
the :class:`Enum` member. Any other modifications may go in either
-:meth:`__new__` or :meth:`__init__`, with :meth:`__init__` being preferred.
+:meth:`~object.__new__` or :meth:`~object.__init__`, with :meth:`~object.__init__` being preferred.
For example, if you want to pass several items to the constructor, but only
want one of them to be the value::
@@ -950,28 +953,28 @@ Finer Points
Supported ``__dunder__`` names
""""""""""""""""""""""""""""""
-:attr:`__members__` is a read-only ordered mapping of ``member_name``:``member``
+:attr:`~enum.EnumType.__members__` is a read-only ordered mapping of ``member_name``:``member``
items. It is only available on the class.
-:meth:`__new__`, if specified, must create and return the enum members; it is
-also a very good idea to set the member's :attr:`_value_` appropriately. Once
+:meth:`~object.__new__`, if specified, must create and return the enum members; it is
+also a very good idea to set the member's :attr:`~Enum._value_` appropriately. Once
all the members are created it is no longer used.
Supported ``_sunder_`` names
""""""""""""""""""""""""""""
-- ``_name_`` -- name of the member
-- ``_value_`` -- value of the member; can be set / modified in ``__new__``
+- :attr:`~Enum._name_` -- name of the member
+- :attr:`~Enum._value_` -- value of the member; can be set / modified in ``__new__``
-- ``_missing_`` -- a lookup function used when a value is not found; may be
+- :meth:`~Enum._missing_` -- a lookup function used when a value is not found; may be
overridden
-- ``_ignore_`` -- a list of names, either as a :class:`list` or a :class:`str`,
+- :attr:`~Enum._ignore_` -- a list of names, either as a :class:`list` or a :class:`str`,
that will not be transformed into members, and will be removed from the final
class
-- ``_order_`` -- used in Python 2/3 code to ensure member order is consistent
+- :attr:`~Enum._order_` -- used in Python 2/3 code to ensure member order is consistent
(class attribute, removed during class creation)
-- ``_generate_next_value_`` -- used by the `Functional API`_ and by
+- :meth:`~Enum._generate_next_value_` -- used by the `Functional API`_ and by
:class:`auto` to get an appropriate value for an enum member; may be
overridden
@@ -986,7 +989,7 @@ Supported ``_sunder_`` names
.. versionadded:: 3.6 ``_missing_``, ``_order_``, ``_generate_next_value_``
.. versionadded:: 3.7 ``_ignore_``
-To help keep Python 2 / Python 3 code in sync an :attr:`_order_` attribute can
+To help keep Python 2 / Python 3 code in sync an :attr:`~Enum._order_` attribute can
be provided. It will be checked against the actual order of the enumeration
and raise an error if the two do not match::
@@ -1004,7 +1007,7 @@ and raise an error if the two do not match::
.. note::
- In Python 2 code the :attr:`_order_` attribute is necessary as definition
+ In Python 2 code the :attr:`~Enum._order_` attribute is necessary as definition
order is lost before it can be recorded.
@@ -1129,6 +1132,14 @@ the following are true:
>>> (Color.RED | Color.GREEN).name
'RED|GREEN'
+ >>> class Perm(IntFlag):
+ ... R = 4
+ ... W = 2
+ ... X = 1
+ ...
+ >>> (Perm.R & Perm.W).name is None # effectively Perm(0)
+ True
+
- multi-bit flags, aka aliases, can be returned from operations::
>>> Color.RED | Color.BLUE
@@ -1185,12 +1196,12 @@ Enum Classes
^^^^^^^^^^^^
The :class:`EnumType` metaclass is responsible for providing the
-:meth:`__contains__`, :meth:`__dir__`, :meth:`__iter__` and other methods that
+:meth:`~object.__contains__`, :meth:`~object.__dir__`, :meth:`~object.__iter__` and other methods that
allow one to do things with an :class:`Enum` class that fail on a typical
class, such as ``list(Color)`` or ``some_enum_var in Color``. :class:`EnumType` is
responsible for ensuring that various other methods on the final :class:`Enum`
-class are correct (such as :meth:`__new__`, :meth:`__getnewargs__`,
-:meth:`__str__` and :meth:`__repr__`).
+class are correct (such as :meth:`~object.__new__`, :meth:`~object.__getnewargs__`,
+:meth:`~object.__str__` and :meth:`~object.__repr__`).
Flag Classes
^^^^^^^^^^^^
@@ -1205,7 +1216,7 @@ Enum Members (aka instances)
The most interesting thing about enum members is that they are singletons.
:class:`EnumType` creates them all while it is creating the enum class itself,
-and then puts a custom :meth:`__new__` in place to ensure that no new ones are
+and then puts a custom :meth:`~object.__new__` in place to ensure that no new ones are
ever instantiated by returning only the existing member instances.
Flag Members
@@ -1253,7 +1264,7 @@ is. There are several ways to define this type of simple enumeration:
- use instances of :class:`auto` for the value
- use instances of :class:`object` as the value
- use a descriptive string as the value
-- use a tuple as the value and a custom :meth:`__new__` to replace the
+- use a tuple as the value and a custom :meth:`~object.__new__` to replace the
tuple with an :class:`int` value
Using any of these methods signifies to the user that these values are not
@@ -1289,7 +1300,7 @@ Using :class:`object` would look like::
>
This is also a good example of why you might want to write your own
-:meth:`__repr__`::
+:meth:`~object.__repr__`::
>>> class Color(Enum):
... RED = object()
@@ -1317,10 +1328,10 @@ Using a string as the value would look like::
-Using a custom :meth:`__new__`
-""""""""""""""""""""""""""""""
+Using a custom :meth:`~object.__new__`
+""""""""""""""""""""""""""""""""""""""
-Using an auto-numbering :meth:`__new__` would look like::
+Using an auto-numbering :meth:`~object.__new__` would look like::
>>> class AutoNumber(Enum):
... def __new__(cls):
@@ -1366,8 +1377,8 @@ to handle any extra arguments::
.. note::
- The :meth:`__new__` method, if defined, is used during creation of the Enum
- members; it is then replaced by Enum's :meth:`__new__` which is used after
+ The :meth:`~object.__new__` method, if defined, is used during creation of the Enum
+ members; it is then replaced by Enum's :meth:`~object.__new__` which is used after
class creation for lookup of existing members.
.. warning::
@@ -1450,7 +1461,7 @@ alias::
Planet
^^^^^^
-If :meth:`__new__` or :meth:`__init__` is defined, the value of the enum member
+If :meth:`~object.__new__` or :meth:`~object.__init__` is defined, the value of the enum member
will be passed to those methods::
>>> class Planet(Enum):
@@ -1481,7 +1492,7 @@ will be passed to those methods::
TimePeriod
^^^^^^^^^^
-An example to show the :attr:`_ignore_` attribute in use::
+An example to show the :attr:`~Enum._ignore_` attribute in use::
>>> from datetime import timedelta
>>> class Period(timedelta, Enum):
diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst
index b0f9d22d..1f0608fb 100644
--- a/Doc/howto/functional.rst
+++ b/Doc/howto/functional.rst
@@ -1,3 +1,5 @@
+.. _functional-howto:
+
********************************
Functional Programming HOWTO
********************************
diff --git a/Doc/howto/gdb_helpers.rst b/Doc/howto/gdb_helpers.rst
index 53bbf7dd..98ce813c 100644
--- a/Doc/howto/gdb_helpers.rst
+++ b/Doc/howto/gdb_helpers.rst
@@ -180,7 +180,7 @@ regular machine-level integer::
(gdb) p some_python_integer
$4 = 42
-The internal structure can be revealed with a cast to :c:expr:`PyLongObject *`:
+The internal structure can be revealed with a cast to :c:expr:`PyLongObject *`::
(gdb) p *(PyLongObject*)some_python_integer
$5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size = 1},
diff --git a/Doc/howto/index.rst b/Doc/howto/index.rst
index 9c8458f2..98364aaf 100644
--- a/Doc/howto/index.rst
+++ b/Doc/howto/index.rst
@@ -2,16 +2,14 @@
Python HOWTOs
***************
-Python HOWTOs are documents that cover a single, specific topic,
-and attempt to cover it fairly completely. Modelled on the Linux
-Documentation Project's HOWTO collection, this collection is an
+Python HOWTOs are documents that cover a specific topic in-depth.
+Modeled on the Linux Documentation Project's HOWTO collection, this collection is an
effort to foster documentation that's more detailed than the
Python Library Reference.
-Currently, the HOWTOs are:
-
.. toctree::
:maxdepth: 1
+ :hidden:
cporting.rst
curses.rst
@@ -33,3 +31,32 @@ Currently, the HOWTOs are:
annotations.rst
isolating-extensions.rst
mro.rst
+
+General:
+
+* :ref:`annotations-howto`
+* :ref:`argparse-tutorial`
+* :ref:`descriptorhowto`
+* :ref:`enum-howto`
+* :ref:`functional-howto`
+* :ref:`ipaddress-howto`
+* :ref:`logging-howto`
+* :ref:`logging-cookbook`
+* :ref:`regex-howto`
+* :ref:`sortinghowto`
+* :ref:`unicode-howto`
+* :ref:`urllib-howto`
+
+Advanced development:
+
+* :ref:`curses-howto`
+* :ref:`isolating-extensions-howto`
+* :ref:`python_2.3_mro`
+* :ref:`socket-howto`
+* :ref:`cporting-howto`
+
+Debugging and profiling:
+
+* :ref:`gdb`
+* :ref:`instrumentation`
+* :ref:`perf_profiling`
diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst
index 9c99fcec..6e03ef20 100644
--- a/Doc/howto/instrumentation.rst
+++ b/Doc/howto/instrumentation.rst
@@ -307,7 +307,7 @@ Available static markers
.. object:: gc__start(int generation)
Fires when the Python interpreter starts a garbage collection cycle.
- ``arg0`` is the generation to scan, like :func:`gc.collect()`.
+ ``arg0`` is the generation to scan, like :func:`gc.collect`.
.. object:: gc__done(long collected)
diff --git a/Doc/howto/isolating-extensions.rst b/Doc/howto/isolating-extensions.rst
index e35855de..a636e06b 100644
--- a/Doc/howto/isolating-extensions.rst
+++ b/Doc/howto/isolating-extensions.rst
@@ -339,7 +339,7 @@ That is, heap types should:
- Define a traverse function using ``Py_tp_traverse``, which
visits the type (e.g. using ``Py_VISIT(Py_TYPE(self))``).
-Please refer to the the documentation of
+Please refer to the documentation of
:c:macro:`Py_TPFLAGS_HAVE_GC` and :c:member:`~PyTypeObject.tp_traverse`
for additional considerations.
diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst
index 06a1ec18..b6835404 100644
--- a/Doc/howto/logging-cookbook.rst
+++ b/Doc/howto/logging-cookbook.rst
@@ -825,9 +825,9 @@ To test these files, do the following in a POSIX environment:
which will lead to records being written to the log.
#. Inspect the log files in the :file:`run` subdirectory. You should see the
- most recent log lines in files matching the pattern :file:`app.log*`. They won't be in
- any particular order, since they have been handled concurrently by different
- worker processes in a non-deterministic way.
+ most recent log lines in files matching the pattern :file:`app.log*`. They
+ won't be in any particular order, since they have been handled concurrently
+ by different worker processes in a non-deterministic way.
#. You can shut down the listener and the web application by running
``venv/bin/supervisorctl -c supervisor.conf shutdown``.
@@ -835,6 +835,19 @@ To test these files, do the following in a POSIX environment:
You may need to tweak the configuration files in the unlikely event that the
configured ports clash with something else in your test environment.
+The default configuration uses a TCP socket on port 9020. You can use a Unix
+Domain socket instead of a TCP socket by doing the following:
+
+#. In :file:`listener.json`, add a ``socket`` key with the path to the domain
+ socket you want to use. If this key is present, the listener listens on the
+ corresponding domain socket and not on a TCP socket (the ``port`` key is
+ ignored).
+
+#. In :file:`webapp.json`, change the socket handler configuration dictionary
+ so that the ``host`` value is the path to the domain socket, and set the
+ ``port`` value to ``null``.
+
+
.. currentmodule:: logging
.. _context-info:
@@ -4022,7 +4035,7 @@ As you can see, this output isn't ideal. That's because the underlying code
which writes to ``sys.stderr`` makes multiple writes, each of which results in a
separate logged line (for example, the last three lines above). To get around
this problem, you need to buffer things and only output log lines when newlines
-are seen. Let's use a slghtly better implementation of ``LoggerWriter``:
+are seen. Let's use a slightly better implementation of ``LoggerWriter``:
.. code-block:: python
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index 877cb243..597de77a 100644
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -1,3 +1,5 @@
+.. _logging-howto:
+
=============
Logging HOWTO
=============
@@ -381,8 +383,52 @@ Logging Flow
The flow of log event information in loggers and handlers is illustrated in the
following diagram.
-.. image:: logging_flow.png
- :class: invert-in-dark-mode
+.. only:: not html
+
+ .. image:: logging_flow.*
+
+.. raw:: html
+ :file: logging_flow.svg
+
+.. raw:: html
+
+
Loggers
^^^^^^^
diff --git a/Doc/howto/logging_flow.png b/Doc/howto/logging_flow.png
index d65e597f..d60ed7c0 100644
Binary files a/Doc/howto/logging_flow.png and b/Doc/howto/logging_flow.png differ
diff --git a/Doc/howto/logging_flow.svg b/Doc/howto/logging_flow.svg
new file mode 100644
index 00000000..4974994a
--- /dev/null
+++ b/Doc/howto/logging_flow.svg
@@ -0,0 +1,327 @@
+
diff --git a/Doc/howto/mro.rst b/Doc/howto/mro.rst
index f44b4f98..0872bedc 100644
--- a/Doc/howto/mro.rst
+++ b/Doc/howto/mro.rst
@@ -335,7 +335,7 @@ E is more specialized than C, even if it is in a higher level.
A lazy programmer can obtain the MRO directly from Python 2.2, since in
this case it coincides with the Python 2.3 linearization. It is enough
-to invoke the .mro() method of class A:
+to invoke the :meth:`~type.mro` method of class A:
>>> A.mro() # doctest: +NORMALIZE_WHITESPACE
[, , ,
@@ -398,7 +398,7 @@ with inheritance diagram
We see that class G inherits from F and E, with F *before* E: therefore
we would expect the attribute *G.remember2buy* to be inherited by
-*F.rembermer2buy* and not by *E.remember2buy*: nevertheless Python 2.2
+*F.remember2buy* and not by *E.remember2buy*: nevertheless Python 2.2
gives
>>> G.remember2buy # doctest: +SKIP
diff --git a/Doc/includes/email-alternative.py b/Doc/includes/email-alternative.py
index df7ca6f3..953ba063 100644
--- a/Doc/includes/email-alternative.py
+++ b/Doc/includes/email-alternative.py
@@ -36,7 +36,7 @@
recipie
déjeuner.
-
+