\chapter{The Verilog and AST Frontends} \label{chapter:verilog} This chapter provides an overview of the implementation of the Yosys Verilog and AST frontends. The Verilog frontend reads Verilog-2005 code and creates an abstract syntax tree (AST) representation of the input. This AST representation is then passed to the AST frontend that converts it to RTLIL data, as illustrated in Fig.~\ref{fig:Verilog_flow}. \begin{figure}[b!] \hfil \begin{tikzpicture} \tikzstyle{process} = [draw, fill=green!10, rectangle, minimum height=3em, minimum width=10em, node distance=5em, font={\ttfamily}] \tikzstyle{data} = [draw, fill=blue!10, ellipse, minimum height=3em, minimum width=7em, node distance=5em, font={\ttfamily}] \node[data] (n1) {Verilog Source}; \node[process] (n2) [below of=n1] {Verilog Frontend}; \node[data] (n3) [below of=n2] {AST}; \node[process] (n4) [below of=n3] {AST Frontend}; \node[data] (n5) [below of=n4] {RTLIL}; \draw[-latex] (n1) -- (n2); \draw[-latex] (n2) -- (n3); \draw[-latex] (n3) -- (n4); \draw[-latex] (n4) -- (n5); \tikzstyle{details} = [draw, fill=yellow!5, rectangle, node distance=6cm, font={\ttfamily}] \node[details] (d1) [right of=n2] {\begin{minipage}{5cm} \hfil \begin{tikzpicture} \tikzstyle{subproc} = [draw, fill=green!10, rectangle, minimum height=2em, minimum width=10em, node distance=3em, font={\ttfamily}] \node (s0) {}; \node[subproc] (s1) [below of=s0] {Preprocessor}; \node[subproc] (s2) [below of=s1] {Lexer}; \node[subproc] (s3) [below of=s2] {Parser}; \node[node distance=3em] (s4) [below of=s3] {}; \draw[-latex] (s0) -- (s1); \draw[-latex] (s1) -- (s2); \draw[-latex] (s2) -- (s3); \draw[-latex] (s3) -- (s4); \end{tikzpicture} \end{minipage}}; \draw[dashed] (n2.north east) -- (d1.north west); \draw[dashed] (n2.south east) -- (d1.south west); \node[details] (d2) [right of=n4] {\begin{minipage}{5cm} \hfil \begin{tikzpicture} \tikzstyle{subproc} = [draw, fill=green!10, rectangle, minimum height=2em, minimum width=10em, node distance=3em, font={\ttfamily}] \node (s0) {}; \node[subproc] (s1) [below of=s0] {Simplifier}; \node[subproc] (s2) [below of=s1] {RTLIL Generator}; \node[node distance=3em] (s3) [below of=s2] {}; \draw[-latex] (s0) -- (s1); \draw[-latex] (s1) -- (s2); \draw[-latex] (s2) -- (s3); \end{tikzpicture} \end{minipage}}; \draw[dashed] (n4.north east) -- (d2.north west); \draw[dashed] (n4.south east) -- (d2.south west); \end{tikzpicture} \caption{Simplified Verilog to RTLIL data flow} \label{fig:Verilog_flow} \end{figure} \section{Transforming Verilog to AST} The {\it Verilog frontend} converts the Verilog sources to an internal AST representation that closely resembles the structure of the original Verilog code. The Verilog frontend consists of three components, the {\it Preprocessor}, the {\it Lexer} and the {\it Parser}. The source code to the Verilog frontend can be found in {\tt frontends/verilog/} in the Yosys source tree. \subsection{The Verilog Preprocessor} The Verilog preprocessor scans over the Verilog source code and interprets some of the Verilog compiler directives such as \lstinline[language=Verilog]{`include}, \lstinline[language=Verilog]{`define} and \lstinline[language=Verilog]{`ifdef}. It is implemented as a C++ function that is passed a file descriptor as input and returns the pre-processed Verilog code as a \lstinline[language=C++]{std::string}. The source code to the Verilog Preprocessor can be found in {\tt frontends/verilog/preproc.cc} in the Yosys source tree. \subsection{The Verilog Lexer} \begin{sloppypar} The Verilog Lexer is written using the lexer generator {\it flex} \citeweblink{flex}. Its source code can be found in {\tt frontends/verilog/verilog\_lexer.l} in the Yosys source tree. The lexer does little more than identifying all keywords and literals recognised by the Yosys Verilog frontend. \end{sloppypar} The lexer keeps track of the current location in the Verilog source code using some global variables. These variables are used by the constructor of AST nodes to annotate each node with the source code location it originated from. \begin{sloppypar} Finally the lexer identifies and handles special comments such as ``\lstinline[language=Verilog]{// synopsys translate_off}'' and ``\lstinline[language=Verilog]{// synopsys full_case}''. (It is recommended to use \lstinline[language=Verilog]{`ifdef} constructs instead of the Synsopsys translate\_on/off comments and attributes such as \lstinline[language=Verilog]{(* full_case *)} over ``\lstinline[language=Verilog]{// synopsys full_case}'' whenever possible.) \end{sloppypar} \subsection{The Verilog Parser} The Verilog Parser is written using the parser generator {\it bison} \citeweblink{bison}. Its source code can be found in {\tt frontends/verilog/verilog\_parser.y} in the Yosys source tree. It generates an AST using the \lstinline[language=C++]{AST::AstNode} data structure defined in {\tt frontends/ast/ast.h}. An \lstinline[language=C++]{AST::AstNode} object has the following properties: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{table}[b!] \hfil \begin{tabular}{>{\raggedright\arraybackslash}p{7cm}>{\raggedright\arraybackslash}p{8cm}} AST Node Type & Corresponding Verilog Construct \\ \hline \hline \arrayrulecolor{gray} {\tt AST\_NONE} & This Node type should never be used. \\ \hline % {\tt AST\_DESIGN} & This node type is used for the top node of the AST tree. It has no corresponding Verilog construct. \\ \hline % {\tt AST\_MODULE}, {\tt AST\_TASK}, {\tt AST\_FUNCTION} & \lstinline[language=Verilog];module;, \lstinline[language=Verilog];task; and \lstinline[language=Verilog];function; \\ \hline % {\tt AST\_WIRE} & \lstinline[language=Verilog];input;, \lstinline[language=Verilog];output;, \lstinline[language=Verilog];wire;, \lstinline[language=Verilog];reg; and \lstinline[language=Verilog];integer; \\ \hline % {\tt AST\_MEMORY} & Verilog Arrays \\ \hline % {\tt AST\_AUTOWIRE} & Created by the simplifier when an undeclared signal name is used. \\ \hline % {\tt AST\_PARAMETER}, {\tt AST\_LOCALPARAM} & \lstinline[language=Verilog];parameter; and \lstinline[language=Verilog];localparam; \\ \hline % {\tt AST\_PARASET} & Parameter set in cell instantiation \\ \hline % {\tt AST\_ARGUMENT} & Port connection in cell instantiation \\ \hline % {\tt AST\_RANGE} & Bit-Index in a signal or element index in array \\ \hline % {\tt AST\_CONSTANT} & A literal value \\ \hline % {\tt AST\_CELLTYPE} & The type of cell in cell instantiation \\ \hline % {\tt AST\_IDENTIFIER} & An Identifier (signal name in expression or cell/task/etc. name in other contexts) \\ \hline % {\tt AST\_PREFIX} & Construct an identifier in the form {\tt [].} (used only in advanced generate constructs) \\ \hline % {\tt AST\_FCALL}, {\tt AST\_TCALL} & Call to function or task \\ \hline % {\tt AST\_TO\_SIGNED}, {\tt AST\_TO\_UNSIGNED} & The \lstinline[language=Verilog];$signed(); and \lstinline[language=Verilog];$unsigned(); functions \\ \hline \end{tabular} \caption{AST node types with their corresponding Verilog constructs. \\ (continued on next page)} \label{tab:Verilog_AstNodeType} \end{table} \begin{table}[t!] \ContinuedFloat \hfil \begin{tabular}{>{\raggedright\arraybackslash}p{7cm}>{\raggedright\arraybackslash}p{8cm}} AST Node Type & Corresponding Verilog Construct \\ \hline \hline \arrayrulecolor{gray} {\tt AST\_CONCAT} {\tt AST\_REPLICATE} & The \lstinline[language=Verilog];{...}; and \lstinline[language=Verilog];{...{...}}; operators \\ \hline % {\tt AST\_BIT\_NOT}, {\tt AST\_BIT\_AND}, {\tt AST\_BIT\_OR}, {\tt AST\_BIT\_XOR}, {\tt AST\_BIT\_XNOR} & The bitwise operators \break \lstinline[language=Verilog];~;, \lstinline[language=Verilog];&;, \lstinline[language=Verilog];|;, \lstinline[language=Verilog];^; and \lstinline[language=Verilog];~^; \\ \hline % {\tt AST\_REDUCE\_AND}, {\tt AST\_REDUCE\_OR}, {\tt AST\_REDUCE\_XOR}, {\tt AST\_REDUCE\_XNOR} & The unary reduction operators \break \lstinline[language=Verilog];~;, \lstinline[language=Verilog];&;, \lstinline[language=Verilog];|;, \lstinline[language=Verilog];^; and \lstinline[language=Verilog];~^; \\ \hline % {\tt AST\_REDUCE\_BOOL} & Conversion from multi-bit value to boolean value (equivalent to {\tt AST\_REDUCE\_OR}) \\ \hline % {\tt AST\_SHIFT\_LEFT}, {\tt AST\_SHIFT\_RIGHT}, {\tt AST\_SHIFT\_SLEFT}, {\tt AST\_SHIFT\_SRIGHT} & The shift operators \break \lstinline[language=Verilog];<<;, \lstinline[language=Verilog];>>;, \lstinline[language=Verilog];<<<; and \lstinline[language=Verilog];>>>; \\ \hline % {\tt AST\_LT}, {\tt AST\_LE}, {\tt AST\_EQ}, {\tt AST\_NE}, {\tt AST\_GE}, {\tt AST\_GT} & The relational operators \break \lstinline[language=Verilog];<;, \lstinline[language=Verilog];<=;, \lstinline[language=Verilog];==;, \lstinline[language=Verilog];!=;, \lstinline[language=Verilog];>=; and \lstinline[language=Verilog];>; \\ \hline % {\tt AST\_ADD}, {\tt AST\_SUB}, {\tt AST\_MUL}, {\tt AST\_DIV}, {\tt AST\_MOD}, {\tt AST\_POW} & The binary operators \break \lstinline[language=Verilog];+;, \lstinline[language=Verilog];-;, \lstinline[language=Verilog];*;, \lstinline[language=Verilog];/;, \lstinline[language=Verilog];%; and \lstinline[language=Verilog];**; \\ \hline % {\tt AST\_POS}, {\tt AST\_NEG} & The prefix operators \lstinline[language=Verilog];+; and \lstinline[language=Verilog];-; \\ \hline % {\tt AST\_LOGIC\_AND}, {\tt AST\_LOGIC\_OR}, {\tt AST\_LOGIC\_NOT} & The logic operators \lstinline[language=Verilog];&&;, \lstinline[language=Verilog];||; and \lstinline[language=Verilog];!; \\ \hline % {\tt AST\_TERNARY} & The ternary \lstinline[language=Verilog];?:;-operator \\ \hline % {\tt AST\_MEMRD} {\tt AST\_MEMWR} & Read and write memories. These nodes are generated by the AST simplifier for writes/reads to/from Verilog arrays. \\ \hline % {\tt AST\_ASSIGN} & An \lstinline[language=Verilog];assign; statement \\ \hline % {\tt AST\_CELL} & A cell instantiation \\ \hline % {\tt AST\_PRIMITIVE} & A primitive cell (\lstinline[language=Verilog];and;, \lstinline[language=Verilog];nand;, \lstinline[language=Verilog];or;, etc.) \\ \hline % {\tt AST\_ALWAYS}, {\tt AST\_INITIAL} & Verilog \lstinline[language=Verilog];always;- and \lstinline[language=Verilog];initial;-blocks \\ \hline % {\tt AST\_BLOCK} & A \lstinline[language=Verilog];begin;-\lstinline[language=Verilog];end;-block \\ \hline % {\tt AST\_ASSIGN\_EQ}. {\tt AST\_ASSIGN\_LE} & Blocking (\lstinline[language=Verilog];=;) and nonblocking (\lstinline[language=Verilog];<=;) assignments within an \lstinline[language=Verilog];always;- or \lstinline[language=Verilog];initial;-block \\ \hline % {\tt AST\_CASE}. {\tt AST\_COND}, {\tt AST\_DEFAULT} & The \lstinline[language=Verilog];case; (\lstinline[language=Verilog];if;) statements, conditions within a case and the default case respectively \\ \hline % {\tt AST\_FOR} & A \lstinline[language=Verilog];for;-loop with an \lstinline[language=Verilog];always;- or \lstinline[language=Verilog];initial;-block \\ \hline % {\tt AST\_GENVAR}, {\tt AST\_GENBLOCK}, {\tt AST\_GENFOR}, {\tt AST\_GENIF} & The \lstinline[language=Verilog];genvar; and \lstinline[language=Verilog];generate; keywords and \lstinline[language=Verilog];for; and \lstinline[language=Verilog];if; within a generate block. \\ \hline % {\tt AST\_POSEDGE}, {\tt AST\_NEGEDGE}, {\tt AST\_EDGE} & Event conditions for \lstinline[language=Verilog];always; blocks. \\ \hline \end{tabular} \caption{AST node types with their corresponding Verilog constructs. \\ (continuation from previous page)} \label{tab:Verilog_AstNodeTypeCont} \end{table} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{itemize} \item {\bf The node type} \\ This enum (\lstinline[language=C++]{AST::AstNodeType}) specifies the role of the node. Table~\ref{tab:Verilog_AstNodeType} contains a list of all node types. \item {\bf The child nodes} \\ This is a list of pointers to all children in the abstract syntax tree. \item {\bf Attributes} \\ As almost every AST node might have Verilog attributes assigned to it, the \lstinline[language=C++]{AST::AstNode} has direct support for attributes. Note that the attribute values are again AST nodes. \item {\bf Node content} \\ Each node might have additional content data. A series of member variables exist to hold such data. For example the member \lstinline[language=C++]{std::string str} can hold a string value and is used e.g.~in the {\tt AST\_IDENTIFIER} node type to store the identifier name. \item {\bf Source code location} \\ Each \lstinline[language=C++]{AST::AstNode} is automatically annotated with the current source code location by the \lstinline[language=C++]{AST::AstNode} constructor. It is stored in the \lstinline[language=C++]{std::string filename} and \lstinline[language=C++]{int linenum} member variables. \end{itemize} The \lstinline[language=C++]{AST::AstNode} constructor can be called with up to two child nodes that are automatically added to the list of child nodes for the new object. This simplifies the creation of AST nodes for simple expressions a bit. For example the bison code for parsing multiplications: \begin{lstlisting}[numbers=left,frame=single] basic_expr '*' attr basic_expr { $$ = new AstNode(AST_MUL, $1, $4); append_attr($$, $3); } | \end{lstlisting} The generated AST data structure is then passed directly to the AST frontend that performs the actual conversion to RTLIL. Note that the Yosys command {\tt read\_verilog} provides the options {\tt -yydebug} and {\tt -dump\_ast} that can be used to print the parse tree or abstract syntax tree respectively. \section{Transforming AST to RTLIL} The {\it AST Frontend} converts a set of modules in AST representation to modules in RTLIL representation and adds them to the current design. This is done in two steps: {\it simplification} and {\it RTLIL generation}. The source code to the AST frontend can be found in {\tt frontends/ast/} in the Yosys source tree. \subsection{AST Simplification} A full-featured AST is too complex to be transformed into RTLIL directly. Therefore it must first be brought into a simpler form. This is done by calling the \lstinline[language=C++]{AST::AstNode::simplify()} method of all {\tt AST\_MODULE} nodes in the AST. This initiates a recursive process that performs the following transformations on the AST data structure: \begin{itemize} \item Inline all task and function calls. \item Evaluate all \lstinline[language=Verilog]{generate}-s
Miscellaneous
#############

.. _macro_notes:

General notes regarding convenience macros
==========================================

pybind11 provides a few convenience macros such as
:func:`PYBIND11_DECLARE_HOLDER_TYPE` and ``PYBIND11_OVERRIDE_*``. Since these
are "just" macros that are evaluated in the preprocessor (which has no concept
of types), they *will* get confused by commas in a template argument; for
example, consider:

.. code-block:: cpp

    PYBIND11_OVERRIDE(MyReturnType<T1, T2>, Class<T3, T4>, func)

The limitation of the C preprocessor interprets this as five arguments (with new
arguments beginning after each comma) rather than three.  To get around this,
there are two alternatives: you can use a type alias, or you can wrap the type
using the ``PYBIND11_TYPE`` macro:

.. code-block:: cpp

    // Version 1: using a type alias
    using ReturnType = MyReturnType<T1, T2>;
    using ClassType = Class<T3, T4>;
    PYBIND11_OVERRIDE(ReturnType, ClassType, func);

    // Version 2: using the PYBIND11_TYPE macro:
    PYBIND11_OVERRIDE(PYBIND11_TYPE(MyReturnType<T1, T2>),
                      PYBIND11_TYPE(Class<T3, T4>), func)

The ``PYBIND11_MAKE_OPAQUE`` macro does *not* require the above workarounds.

.. _gil:

Global Interpreter Lock (GIL)
=============================

When calling a C++ function from Python, the GIL is always held.
The classes :class:`gil_scoped_release` and :class:`gil_scoped_acquire` can be
used to acquire and release the global interpreter lock in the body of a C++
function call. In this way, long-running C++ code can be parallelized using
multiple Python threads. Taking :ref:`overriding_virtuals` as an example, this
could be realized as follows (important changes highlighted):

.. code-block:: cpp
    :emphasize-lines: 8,9,31,32

    class PyAnimal : public Animal {
    public:
        /* Inherit the constructors */
        using Animal::Animal;

        /* Trampoline (need one for each virtual function) */
        std::string go(int n_times) {
            /* Acquire GIL before calling Python code */
            py::gil_scoped_acquire acquire;

            PYBIND11_OVERRIDE_PURE(
                std::string, /* Return type */
                Animal,      /* Parent class */
                go,          /* Name of function */
                n_times      /* Argument(s) */
            );
        }
    };

    PYBIND11_MODULE(example, m) {
        py::class_<Animal, PyAnimal> animal(m, "Animal");
        animal
            .def(py::init<>())
            .def("go", &Animal::go);

        py::class_<Dog>(m, "Dog", animal)
            .def(py::init<>());

        m.def("call_go", [](Animal *animal) -> std::string {
            /* Release GIL before calling into (potentially long-running) C++ code */
            py::gil_scoped_release release;
            return call_go(animal);
        });
    }

The ``call_go`` wrapper can also be simplified using the `call_guard` policy
(see :ref:`call_policies`) which yields the same result:

.. code-block:: cpp

    m.def("call_go", &call_go, py::call_guard<py::gil_scoped_release>());


Binding sequence data types, iterators, the slicing protocol, etc.
==================================================================

Please refer to the supplemental example for details.

.. seealso::

    The file :file:`tests/test_sequences_and_iterators.cpp` contains a
    complete example that shows how to bind a sequence data type, including
    length queries (``__len__``), iterators (``__iter__``), the slicing
    protocol and other kinds of useful operations.


Partitioning code over multiple extension modules
=================================================

It's straightforward to split binding code over multiple extension modules,
while referencing types that are declared elsewhere. Everything "just" works
without any special precautions. One exception to this rule occurs when
extending a type declared in another extension module. Recall the basic example
from Section :ref:`inheritance`.

.. code-block:: cpp

    py::class_<Pet> pet(m, "Pet");
    pet.def(py::init<const std::string &>())
       .def_readwrite("name", &Pet::name);

    py::class_<Dog>(m, "Dog", pet /* <- specify parent */)
        .def(py::init<const std::string &>())
        .def("bark", &Dog::bark);

Suppose now that ``Pet`` bindings are defined in a module named ``basic``,
whereas the ``Dog`` bindings are defined somewhere else. The challenge is of
course that the variable ``pet`` is not available anymore though it is needed
to indicate the inheritance relationship to the constructor of ``class_<Dog>``.
However, it can be acquired as follows:

.. code-block:: cpp

    py::object pet = (py::object) py::module_::import("basic").attr("Pet");

    py::class_<Dog>(m, "Dog", pet)
        .def(py::init<const std::string &>())
        .def("bark", &Dog::bark);

Alternatively, you can specify the base class as a template parameter option to
``class_``, which performs an automated lookup of the corresponding Python
type. Like the above code, however, this also requires invoking the ``import``
function once to ensure that the pybind11 binding code of the module ``basic``
has been executed:

.. code-block:: cpp

    py::module_::import("basic");

    py::class_<Dog, Pet>(m, "Dog")
        .def(py::init<const std::string &>())
        .def("bark", &Dog::bark);

Naturally, both methods will fail when there are cyclic dependencies.

Note that pybind11 code compiled with hidden-by-default symbol visibility (e.g.
via the command line flag ``-fvisibility=hidden`` on GCC/Clang), which is
required for proper pybind11 functionality, can interfere with the ability to
access types defined in another extension module.  Working around this requires
manually exporting types that are accessed by multiple extension modules;
pybind11 provides a macro to do just this:

.. code-block:: cpp

    class PYBIND11_EXPORT Dog : public Animal {
        ...
    };

Note also that it is possible (although would rarely be required) to share arbitrary
C++ objects between extension modules at runtime. Internal library data is shared
between modules using capsule machinery [#f6]_ which can be also utilized for
storing, modifying and accessing user-defined data. Note that an extension module
will "see" other extensions' data if and only if they were built with the same
pybind11 version. Consider the following example:

.. code-block:: cpp

    auto data = reinterpret_cast<MyData *>(py::get_shared_data("mydata"));
    if (!data)
        data = static_cast<MyData *>(py::set_shared_data("mydata", new MyData(42)));

If the above snippet was used in several separately compiled extension modules,
the first one to be imported would create a ``MyData`` instance and associate
a ``"mydata"`` key with a pointer to it. Extensions that are imported later
would be then able to access the data behind the same pointer.

.. [#f6] https://docs.python.org/3/extending/extending.html#using-capsules

Module Destructors
==================

pybind11 does not provide an explicit mechanism to invoke cleanup code at
module destruction time. In rare cases where such functionality is required, it
is possible to emulate it using Python capsules or weak references with a
destruction callback.

.. code-block:: cpp

    auto cleanup_callback = []() {
        // perform cleanup here -- this function is called with the GIL held
    };

    m.add_object("_cleanup", py::capsule(cleanup_callback));

This approach has the potential downside that instances of classes exposed
within the module may still be alive when the cleanup callback is invoked
(whether this is acceptable will generally depend on the application).

Alternatively, the capsule may also be stashed within a type object, which
ensures that it not called before all instances of that type have been
collected:

.. code-block:: cpp

    auto cleanup_callback = []() { /* ... */ };
    m.attr("BaseClass").attr("_cleanup") = py::capsule(cleanup_callback);

Both approaches also expose a potentially dangerous ``_cleanup`` attribute in
Python, which may be undesirable from an API standpoint (a premature explicit
call from Python might lead to undefined behavior). Yet another approach that
avoids this issue involves weak reference with a cleanup callback:

.. code-block:: cpp

    // Register a callback function that is invoked when the BaseClass object is collected
    py::cpp_function cleanup_callback(
        [](py::handle weakref) {
            // perform cleanup here -- this function is called with the GIL held

            weakref.dec_ref(); // release weak reference
        }
    );

    // Create a weak reference with a cleanup callback and initially leak it
    (void) py::weakref(m.attr("BaseClass"), cleanup_callback).release();

.. note::

    PyPy does not garbage collect objects when the interpreter exits. An alternative
    approach (which also works on CPython) is to use the :py:mod:`atexit` module [#f7]_,
    for example:

    .. code-block:: cpp

        auto atexit = py::module_::import("atexit");
        atexit.attr("register")(py::cpp_function([]() {
            // perform cleanup here -- this function is called with the GIL held
        }));

    .. [#f7] https://docs.python.org/3/library/atexit.html


Generating documentation using Sphinx
=====================================

Sphinx [#f4]_ has the ability to inspect the signatures and documentation
strings in pybind11-based extension modules to automatically generate beautiful
documentation in a variety formats. The python_example repository [#f5]_ contains a
simple example repository which uses this approach.

There are two potential gotchas when using this approach: first, make sure that
the resulting strings do not contain any :kbd:`TAB` characters, which break the
docstring parsing routines. You may want to use C++11 raw string literals,
which are convenient for multi-line comments. Conveniently, any excess
indentation will be automatically be removed by Sphinx. However, for this to
work, it is important that all lines are indented consistently, i.e.:

.. code-block:: cpp

    // ok
    m.def("foo", &foo, R"mydelimiter(
        The foo function

        Parameters
        ----------
    )mydelimiter");

    // *not ok*
    m.def("foo", &foo, R"mydelimiter(The foo function

        Parameters
        ----------
    )mydelimiter");

By default, pybind11 automatically generates and prepends a signature to the docstring of a function
registered with ``module_::def()`` and ``class_::def()``. Sometimes this
behavior is not desirable, because you want to provide your own signature or remove
the docstring completely to exclude the function from the Sphinx documentation.
The class ``options`` allows you to selectively suppress auto-generated signatures:

.. code-block:: cpp

    PYBIND11_MODULE(example, m) {
        py::options options;
        options.disable_function_signatures();

        m.def("add", [](int a, int b) { return a + b; }, "A function which adds two numbers");
    }

Note that changes to the settings affect only function bindings created during the
lifetime of the ``options`` instance. When it goes out of scope at the end of the module's init function,
the default settings are restored to prevent unwanted side effects.

.. [#f4] http://www.sphinx-doc.org
.. [#f5] http://github.com/pybind/python_example

.. _avoiding-cpp-types-in-docstrings:

Avoiding C++ types in docstrings
================================

Docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called.
At this point parameter and return types should be known to pybind11.
If a custom type is not exposed yet through a ``py::class_`` constructor or a custom type caster,
its C++ type name will be used instead to generate the signature in the docstring:

.. code-block:: text

     |  __init__(...)
     |      __init__(self: example.Foo, arg0: ns::Bar) -> None
                                              ^^^^^^^


This limitation can be circumvented by ensuring that C++ classes are registered with pybind11
before they are used as a parameter or return type of a function:

.. code-block:: cpp

    PYBIND11_MODULE(example, m) {

        auto pyFoo = py::class_<ns::Foo>(m, "Foo");
        auto pyBar = py::class_<ns::Bar>(m, "Bar");

        pyFoo.def(py::init<const ns::Bar&>());
        pyBar.def(py::init<const ns::Foo&>());
    }
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-22 05:20:23 +0000