<commit_before>.. _special-methods:

Special Methods of Extension Types
===================================

This page describes the special methods currently supported by Cython extension
types. A complete list of all the special methods appears in the table at the
bottom. Some of these methods behave differently from their Python
counterparts or have no direct Python counterparts, and require special
mention.

.. Note::

    Everything said on this page applies only to extension types, defined
    with the :keyword:`cdef` class statement. It doesn't apply to classes defined with the
    Python :keyword:`class` statement, where the normal Python rules apply.

.. _declaration:

Declaration
------------
Special methods of extension types must be declared with :keyword:`def`, not
:keyword:`cdef`. This does not impact their performance--Python uses different
calling conventions to invoke these special methods.

.. _docstrings:

Docstrings
-----------

Currently, docstrings are not fully supported in some special methods of extension
types. You can place a docstring in the source to serve as a comment, but it
won't show up in the corresponding :attr:`__doc__` attribute at run time. (This
seems to be is a Python limitation -- there's nowhere in the `PyTypeObject`
data structure to put such docstrings.)


.. _initialisation_methods:

Initialisation methods: :meth:`__cinit__` and :meth:`__init__`
---------------------------------------------------------------
There are two methods concerned with initialising the object, the normal Python
:meth:`__init__` method and a special :meth:`__cinit__` method where basic
C level initialisation can be performed.

The main difference between the two is when they are called.
The :meth:`__cinit__` method is guaranteed to be called as part of the object
allocation, but before the object is fully initialised.  Specifically, methods
and object attributes that belong to subclasses or that were overridden by
subclasses may not have been initialised at all yet and must not be used by
:meth:`__cinit__` in a base class.  Note that the object allocation in Python
clears all fields and sets them to zero (or ``NULL``).  Cython additionally
takes responsibility of setting all object attributes to ``None``, but again,
this may not yet have been done for the attributes defined or overridden by
subclasses.  If your object needs anything more than this basic attribute
clearing in order to get into a correct and safe state, :meth:`__cinit__`
may be a good place to do it.

The :meth:`__init__` method, on the other hand, works exactly like in Python.
It is called after allocation and basic initialisation of the object, including
the complete inheritance chain.
By the time :meth:`__init__` is called, the object is a fully valid Python object
and all operations are safe.  Any initialisation which cannot safely be done in
the :meth:`__cinit__` method should be done in the :meth:`__init__` method.
However, as in Python, it is the responsibility of the subclasses to call up the
hierarchy and make sure that the :meth:`__init__` methods in the base class are
called correctly.  If a subclass forgets (or refuses) to call the :meth:`__init__`
method of one of its base classes, that method will not be called.
Also, if the object gets created by calling directly its :meth:`__new__` method
(as opposed to calling the class itself), then none of the :meth:`__init__`
methods will be called.

The :meth:`__cinit__` method is where you should perform basic C-level
initialisation of the object, possibly including allocation of any C data
structures that your object will own.  In contrast to :meth:`__init__`,
your :meth:`__cinit__` method is guaranteed to be called exactly once.

If your extension type has a base type, any existing :meth:`__cinit__` methods in
the base type hierarchy are automatically called before your :meth:`__cinit__`
method.  You cannot explicitly call the inherited :meth:`__cinit__` methods, and the
base types are free to choose whether they implement :meth:`__cinit__` at all.
If you need to pass a modified argument list to the base type, you will have to do
the relevant part of the initialisation in the :meth:`__init__` method instead,
where the normal rules for calling inherited methods apply.

Any arguments passed to the constructor will be passed to both the
:meth:`__cinit__` method and the :meth:`__init__` method.  If you anticipate
subclassing your extension type, you may find it useful to give the
:meth:`__cinit__` method `*` and `**` arguments so that it can accept and
ignore arbitrary extra arguments, since the arguments that are passed through
the hierarchy during allocation cannot be changed by subclasses.
Alternatively, as a convenience, if you declare your :meth:`__cinit__`` method
to take no arguments (other than self) it will simply ignore any extra arguments
passed to the constructor without complaining about the signature mismatch.

..  Note::

    All constructor arguments will be passed as Python objects.
    This implies that non-convertible C types such as pointers or C++ objects
    cannot be passed into the constructor, neither from Python nor from Cython code.
    If this is needed, use a factory function or method instead that handles the
    object initialisation.
    It often helps to directly call the :meth:`__new__` method in this function to
    explicitly bypass the call to the :meth:`__init__` constructor.

    See :ref:`existing-pointers-instantiation` for an example.

.. [#] https://docs.python.org/reference/datamodel.html#object.__new__

<commit_msg>docs: Fix a typo.<commit_after>.. _special-methods:

Special Methods of Extension Types
===================================

This page describes the special methods currently supported by Cython extension
types. A complete list of all the special methods appears in the table at the
bottom. Some of these methods behave differently from their Python
counterparts or have no direct Python counterparts, and require special
mention.

.. Note::

    Everything said on this page applies only to extension types, defined
    with the :keyword:`cdef` class statement. It doesn't apply to classes defined with the
    Python :keyword:`class` statement, where the normal Python rules apply.

.. _declaration:

Declaration
------------
Special methods of extension types must be declared with :keyword:`def`, not
:keyword:`cdef`. This does not impact their performance--Python uses different
calling conventions to invoke these special methods.

.. _docstrings:

Docstrings
-----------

Currently, docstrings are not fully supported in some special methods of extension
types. You can place a docstring in the source to serve as a comment, but it
won't show up in the corresponding :attr:`__doc__` attribute at run time. (This
seems to be is a Python limitation -- there's nowhere in the `PyTypeObject`
data structure to put such docstrings.)


.. _initialisation_methods:

Initialisation methods: :meth:`__cinit__` and :meth:`__init__`
---------------------------------------------------------------
There are two methods concerned with initialising the object, the normal Python
:meth:`__init__` method and a special :meth:`__cinit__` method where basic
C level initialisation can be performed.

The main difference between the two is when they are called.
The :meth:`__cinit__` method is guaranteed to be called as part of the object
allocation, but before the object is fully initialised.  Specifically, methods
and object attributes that belong to subclasses or that were overridden by
subclasses may not have been initialised at all yet and must not be used by
:meth:`__cinit__` in a base class.  Note that the object allocation in Python
clears all fields and sets them to zero (or ``NULL``).  Cython additionally
takes responsibility of setting all object attributes to ``None``, but again,
this may not yet have been done for the attributes defined or overridden by
subclasses.  If your object needs anything more than this basic attribute
clearing in order to get into a correct and safe state, :meth:`__cinit__`
may be a good place to do it.

The :meth:`__init__` method, on the other hand, works exactly like in Python.
It is called after allocation and basic initialisation of the object, including
the complete inheritance chain.
By the time :meth:`__init__` is called, the object is a fully valid Python object
and all operations are safe.  Any initialisation which cannot safely be done in
the :meth:`__cinit__` method should be done in the :meth:`__init__` method.
However, as in Python, it is the responsibility of the subclasses to call up the
hierarchy and make sure that the :meth:`__init__` methods in the base class are
called correctly.  If a subclass forgets (or refuses) to call the :meth:`__init__`
method of one of its base classes, that method will not be called.
Also, if the object gets created by calling directly its :meth:`__new__` method
(as opposed to calling the class itself), then none of the :meth:`__init__`
methods will be called.

The :meth:`__cinit__` method is where you should perform basic C-level
initialisation of the object, possibly including allocation of any C data
structures that your object will own.  In contrast to :meth:`__init__`,
your :meth:`__cinit__` method is guaranteed to be called exactly once.

If your extension type has a base type, any existing :meth:`__cinit__` methods in
the base type hierarchy are automatically called before your :meth:`__cinit__`
method.  You cannot explicitly call the inherited :meth:`__cinit__` methods, and the
base types are free to choose whether they implement :meth:`__cinit__` at all.
If you need to pass a modified argument list to the base type, you will have to do
the relevant part of the initialisation in the :meth:`__init__` method instead,
where the normal rules for calling inherited methods apply.

Any arguments passed to the constructor will be passed to both the
:meth:`__cinit__` method and the :meth:`__init__` method.  If you anticipate
subclassing your extension type, you may find it useful to give the
:meth:`__cinit__` method `*` and `**` arguments so that it can accept and
ignore arbitrary extra arguments, since the arguments that are passed through
the hierarchy during allocation cannot be changed by subclasses.
Alternatively, as a convenience, if you declare your :meth:`__cinit__` method
to take no arguments (other than self) it will simply ignore any extra arguments
passed to the constructor without complaining about the signature mismatch.

..  Note::

    All constructor arguments will be passed as Python objects.
    This implies that non-convertible C types such as pointers or C++ objects
    cannot be passed into the constructor, neither from Python nor from Cython code.
    If this is needed, use a factory function or method instead that handles the
    object initialisation.
    It often helps to directly call the :meth:`__new__` method in this function to
    explicitly bypass the call to the :meth:`__init__` constructor.

    See :ref:`existing-pointers-instantiation` for an example.

.. [#] https://docs.python.org/reference/datamodel.html#object.__new__


{'fraction_non_alphanumeric': 0.07362784471218206, 'fraction_numerical': 0.0, 'mean_word_length': 4.369429803545759, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '510413', 'n_tokens_mistral': 2808, 'n_tokens_neox': 2692, 'n_words': 1605}