@react-native-ohos/react-native-mmkv 3.3.1-rc.1

package/harmony/reactNativeMMKV/src/main/cpp/MMKV/Python/pybind11/docs/conf.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+#
+# pybind11 documentation build configuration file, created by
+# sphinx-quickstart on Sun Oct 11 19:23:48 2015.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+DIR = Path(__file__).parent.resolve()
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "breathe",
+    "sphinx_copybutton",
+    "sphinxcontrib.rsvgconverter",
+    "sphinxcontrib.moderncmakedomain",
+]
+
+breathe_projects = {"pybind11": ".build/doxygenxml/"}
+breathe_default_project = "pybind11"
+breathe_domain_by_extension = {"h": "cpp"}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = [".templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = ".rst"
+
+# The encoding of source files.
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+project = "pybind11"
+copyright = "2017, Wenzel Jakob"
+author = "Wenzel Jakob"
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+
+# Read the listed version
+with open("../pybind11/_version.py") as f:
+    code = compile(f.read(), "../pybind11/_version.py", "exec")
+loc = {}
+exec(code, loc)
+
+# The full version, including alpha/beta/rc tags.
+version = loc["__version__"]
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = [".build", "release.rst"]
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+default_role = "any"
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+# pygments_style = 'monokai'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+html_theme = "furo"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<version> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_css_files = [
+    "css/custom.css",
+]
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+# html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_domain_indices = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
+# html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+# html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+# html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "pybind11doc"
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_engine = "pdflatex"
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
+    #
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
+    #
+    # Additional stuff for the LaTeX preamble.
+    # remove blank pages (between the title page and the TOC, etc.)
+    "classoptions": ",openany,oneside",
+    "preamble": r"""
+\usepackage{fontawesome}
+\usepackage{textgreek}
+\DeclareUnicodeCharacter{00A0}{}
+\DeclareUnicodeCharacter{2194}{\faArrowsH}
+\DeclareUnicodeCharacter{1F382}{\faBirthdayCake}
+\DeclareUnicodeCharacter{1F355}{\faAdjust}
+\DeclareUnicodeCharacter{0301}{'}
+\DeclareUnicodeCharacter{03C0}{\textpi}
+
+""",
+    # Latex figure (float) alignment
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, "pybind11.tex", "pybind11 Documentation", "Wenzel Jakob", "manual"),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = 'pybind11-logo.png'
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [(master_doc, "pybind11", "pybind11 Documentation", [author], 1)]
+
+# If true, show URL addresses after external links.
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "pybind11",
+        "pybind11 Documentation",
+        author,
+        "pybind11",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
+]
+
+# Documents to append as an appendix to all manuals.
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+# texinfo_no_detailmenu = False
+
+primary_domain = "cpp"
+highlight_language = "cpp"
+
+
+def generate_doxygen_xml(app):
+    build_dir = os.path.join(app.confdir, ".build")
+    if not os.path.exists(build_dir):
+        os.mkdir(build_dir)
+
+    try:
+        subprocess.call(["doxygen", "--version"])
+        retcode = subprocess.call(["doxygen"], cwd=app.confdir)
+        if retcode < 0:
+            sys.stderr.write(f"doxygen error code: {-retcode}\n")
+    except OSError as e:
+        sys.stderr.write(f"doxygen execution failed: {e}\n")
+
+
+def prepare(app):
+    with open(DIR.parent / "README.rst") as f:
+        contents = f.read()
+
+    if app.builder.name == "latex":
+        # Remove badges and stuff from start
+        contents = contents[contents.find(r".. start") :]
+
+        # Filter out section titles for index.rst for LaTeX
+        contents = re.sub(r"^(.*)\n[-~]{3,}$", r"**\1**", contents, flags=re.MULTILINE)
+
+    with open(DIR / "readme.rst", "w") as f:
+        f.write(contents)
+
+
+def clean_up(app, exception):  # noqa: ARG001
+    (DIR / "readme.rst").unlink()
+
+
+def setup(app):
+    # Add hook for building doxygen xml when needed
+    app.connect("builder-inited", generate_doxygen_xml)
+
+    # Copy the readme in
+    app.connect("builder-inited", prepare)
+
+    # Clean up the generated readme
+    app.connect("build-finished", clean_up)

package/harmony/reactNativeMMKV/src/main/cpp/MMKV/Python/pybind11/docs/faq.rst

@@ -0,0 +1,308 @@
+Frequently asked questions
+##########################
+
+"ImportError: dynamic module does not define init function"
+===========================================================
+
+1. Make sure that the name specified in PYBIND11_MODULE is identical to the
+filename of the extension library (without suffixes such as ``.so``).
+
+2. If the above did not fix the issue, you are likely using an incompatible
+version of Python that does not match what you compiled with.
+
+"Symbol not found: ``__Py_ZeroStruct`` / ``_PyInstanceMethod_Type``"
+========================================================================
+
+See the first answer.
+
+"SystemError: dynamic module not initialized properly"
+======================================================
+
+See the first answer.
+
+The Python interpreter immediately crashes when importing my module
+===================================================================
+
+See the first answer.
+
+.. _faq_reference_arguments:
+
+Limitations involving reference arguments
+=========================================
+
+In C++, it's fairly common to pass arguments using mutable references or
+mutable pointers, which allows both read and write access to the value
+supplied by the caller. This is sometimes done for efficiency reasons, or to
+realize functions that have multiple return values. Here are two very basic
+examples:
+
+.. code-block:: cpp
+
+    void increment(int &i) { i++; }
+    void increment_ptr(int *i) { (*i)++; }
+
+In Python, all arguments are passed by reference, so there is no general
+issue in binding such code from Python.
+
+However, certain basic Python types (like ``str``, ``int``, ``bool``,
+``float``, etc.) are **immutable**. This means that the following attempt
+to port the function to Python doesn't have the same effect on the value
+provided by the caller -- in fact, it does nothing at all.
+
+.. code-block:: python
+
+    def increment(i):
+        i += 1  # nope..
+
+pybind11 is also affected by such language-level conventions, which means that
+binding ``increment`` or ``increment_ptr`` will also create Python functions
+that don't modify their arguments.
+
+Although inconvenient, one workaround is to encapsulate the immutable types in
+a custom type that does allow modifications.
+
+An other alternative involves binding a small wrapper lambda function that
+returns a tuple with all output arguments (see the remainder of the
+documentation for examples on binding lambda functions). An example:
+
+.. code-block:: cpp
+
+    int foo(int &i) { i++; return 123; }
+
+and the binding code
+
+.. code-block:: cpp
+
+   m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); });
+
+
+How can I reduce the build time?
+================================
+
+It's good practice to split binding code over multiple files, as in the
+following example:
+
+:file:`example.cpp`:
+
+.. code-block:: cpp
+
+    void init_ex1(py::module_ &);
+    void init_ex2(py::module_ &);
+    /* ... */
+
+    PYBIND11_MODULE(example, m) {
+        init_ex1(m);
+        init_ex2(m);
+        /* ... */
+    }
+
+:file:`ex1.cpp`:
+
+.. code-block:: cpp
+
+    void init_ex1(py::module_ &m) {
+        m.def("add", [](int a, int b) { return a + b; });
+    }
+
+:file:`ex2.cpp`:
+
+.. code-block:: cpp
+
+    void init_ex2(py::module_ &m) {
+        m.def("sub", [](int a, int b) { return a - b; });
+    }
+
+:command:`python`:
+
+.. code-block:: pycon
+
+    >>> import example
+    >>> example.add(1, 2)
+    3
+    >>> example.sub(1, 1)
+    0
+
+As shown above, the various ``init_ex`` functions should be contained in
+separate files that can be compiled independently from one another, and then
+linked together into the same final shared object.  Following this approach
+will:
+
+1. reduce memory requirements per compilation unit.
+
+2. enable parallel builds (if desired).
+
+3. allow for faster incremental builds. For instance, when a single class
+   definition is changed, only a subset of the binding code will generally need
+   to be recompiled.
+
+"recursive template instantiation exceeded maximum depth of 256"
+================================================================
+
+If you receive an error about excessive recursive template evaluation, try
+specifying a larger value, e.g. ``-ftemplate-depth=1024`` on GCC/Clang. The
+culprit is generally the generation of function signatures at compile time
+using C++14 template metaprogramming.
+
+.. _`faq:hidden_visibility`:
+
+"'SomeClass' declared with greater visibility than the type of its field 'SomeClass::member' [-Wattributes]"
+============================================================================================================
+
+This error typically indicates that you are compiling without the required
+``-fvisibility`` flag.  pybind11 code internally forces hidden visibility on
+all internal code, but if non-hidden (and thus *exported*) code attempts to
+include a pybind type (for example, ``py::object`` or ``py::list``) you can run
+into this warning.
+
+To avoid it, make sure you are specifying ``-fvisibility=hidden`` when
+compiling pybind code.
+
+As to why ``-fvisibility=hidden`` is necessary, because pybind modules could
+have been compiled under different versions of pybind itself, it is also
+important that the symbols defined in one module do not clash with the
+potentially-incompatible symbols defined in another.  While Python extension
+modules are usually loaded with localized symbols (under POSIX systems
+typically using ``dlopen`` with the ``RTLD_LOCAL`` flag), this Python default
+can be changed, but even if it isn't it is not always enough to guarantee
+complete independence of the symbols involved when not using
+``-fvisibility=hidden``.
+
+Additionally, ``-fvisibility=hidden`` can deliver considerably binary size
+savings. (See the following section for more details.)
+
+
+.. _`faq:symhidden`:
+
+How can I create smaller binaries?
+==================================
+
+To do its job, pybind11 extensively relies on a programming technique known as
+*template metaprogramming*, which is a way of performing computation at compile
+time using type information. Template metaprogramming usually instantiates code
+involving significant numbers of deeply nested types that are either completely
+removed or reduced to just a few instructions during the compiler's optimization
+phase. However, due to the nested nature of these types, the resulting symbol
+names in the compiled extension library can be extremely long. For instance,
+the included test suite contains the following symbol:
+
+.. only:: html
+
+    .. code-block:: none
+
+        _​_​Z​N​8​p​y​b​i​n​d​1​1​1​2​c​p​p​_​f​u​n​c​t​i​o​n​C​1​I​v​8​E​x​a​m​p​l​e​2​J​R​N​S​t​3​_​_​1​6​v​e​c​t​o​r​I​N​S​3​_​1​2​b​a​s​i​c​_​s​t​r​i​n​g​I​w​N​S​3​_​1​1​c​h​a​r​_​t​r​a​i​t​s​I​w​E​E​N​S​3​_​9​a​l​l​o​c​a​t​o​r​I​w​E​E​E​E​N​S​8​_​I​S​A​_​E​E​E​E​E​J​N​S​_​4​n​a​m​e​E​N​S​_​7​s​i​b​l​i​n​g​E​N​S​_​9​i​s​_​m​e​t​h​o​d​E​A​2​8​_​c​E​E​E​M​T​0​_​F​T​_​D​p​T​1​_​E​D​p​R​K​T​2​_
+
+.. only:: not html
+
+    .. code-block:: cpp
+
+        __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
+
+which is the mangled form of the following function type:
+
+.. code-block:: cpp
+
+    pybind11::cpp_function::cpp_function<void, Example2, std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&), pybind11::name const&, pybind11::sibling const&, pybind11::is_method const&, char const (&) [28])
+
+The memory needed to store just the mangled name of this function (196 bytes)
+is larger than the actual piece of code (111 bytes) it represents! On the other
+hand, it's silly to even give this function a name -- after all, it's just a
+tiny cog in a bigger piece of machinery that is not exposed to the outside
+world. So we'll generally only want to export symbols for those functions which
+are actually called from the outside.
+
+This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC
+and Clang, which sets the default symbol visibility to *hidden*, which has a
+tremendous impact on the final binary size of the resulting extension library.
+(On Visual Studio, symbols are already hidden by default, so nothing needs to
+be done there.)
+
+In addition to decreasing binary size, ``-fvisibility=hidden`` also avoids
+potential serious issues when loading multiple modules and is required for
+proper pybind operation.  See the previous FAQ entry for more details.
+
+How can I properly handle Ctrl-C in long-running functions?
+===========================================================
+
+Ctrl-C is received by the Python interpreter, and holds it until the GIL
+is released, so a long-running function won't be interrupted.
+
+To interrupt from inside your function, you can use the ``PyErr_CheckSignals()``
+function, that will tell if a signal has been raised on the Python side.  This
+function merely checks a flag, so its impact is negligible. When a signal has
+been received, you must either explicitly interrupt execution by throwing
+``py::error_already_set`` (which will propagate the existing
+``KeyboardInterrupt``), or clear the error (which you usually will not want):
+
+.. code-block:: cpp
+
+    PYBIND11_MODULE(example, m)
+    {
+        m.def("long running_func", []()
+        {
+            for (;;) {
+                if (PyErr_CheckSignals() != 0)
+                    throw py::error_already_set();
+                // Long running iteration
+            }
+        });
+    }
+
+CMake doesn't detect the right Python version
+=============================================
+
+The CMake-based build system will try to automatically detect the installed
+version of Python and link against that. When this fails, or when there are
+multiple versions of Python and it finds the wrong one, delete
+``CMakeCache.txt`` and then add ``-DPYTHON_EXECUTABLE=$(which python)`` to your
+CMake configure line. (Replace ``$(which python)`` with a path to python if
+your prefer.)
+
+You can alternatively try ``-DPYBIND11_FINDPYTHON=ON``, which will activate the
+new CMake FindPython support instead of pybind11's custom search. Requires
+CMake 3.12+, and 3.15+ or 3.18.2+ are even better. You can set this in your
+``CMakeLists.txt`` before adding or finding pybind11, as well.
+
+Inconsistent detection of Python version in CMake and pybind11
+==============================================================
+
+The functions ``find_package(PythonInterp)`` and ``find_package(PythonLibs)``
+provided by CMake for Python version detection are modified by pybind11 due to
+unreliability and limitations that make them unsuitable for pybind11's needs.
+Instead pybind11 provides its own, more reliable Python detection CMake code.
+Conflicts can arise, however, when using pybind11 in a project that *also* uses
+the CMake Python detection in a system with several Python versions installed.
+
+This difference may cause inconsistencies and errors if *both* mechanisms are
+used in the same project.
+
+There are three possible solutions:
+
+1. Avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)``
+   from CMake and rely on pybind11 in detecting Python version. If this is not
+   possible, the CMake machinery should be called *before* including pybind11.
+2. Set ``PYBIND11_FINDPYTHON`` to ``True`` or use ``find_package(Python
+   COMPONENTS Interpreter Development)`` on modern CMake (3.12+, 3.15+ better,
+   3.18.2+ best). Pybind11 in these cases uses the new CMake FindPython instead
+   of the old, deprecated search tools, and these modules are much better at
+   finding the correct Python. If FindPythonLibs/Interp are not available
+   (CMake 3.27+), then this will be ignored and FindPython will be used.
+3. Set ``PYBIND11_NOPYTHON`` to ``TRUE``. Pybind11 will not search for Python.
+   However, you will have to use the target-based system, and do more setup
+   yourself, because it does not know about or include things that depend on
+   Python, like ``pybind11_add_module``. This might be ideal for integrating
+   into an existing system, like scikit-build's Python helpers.
+
+How to cite this project?
+=========================
+
+We suggest the following BibTeX template to cite pybind11 in scientific
+discourse:
+
+.. code-block:: bash
+
+    @misc{pybind11,
+       author = {Wenzel Jakob and Jason Rhinelander and Dean Moldovan},
+       year = {2017},
+       note = {https://github.com/pybind/pybind11},
+       title = {pybind11 -- Seamless operability between C++11 and Python}
+    }