.. _sp-title:

Stored Procedure API
-------------------------

Describes how to access the data available when executing as a stored procedure or trigger.

.. toctree::
   :maxdepth: 2
   :caption: Stored Procedure API Module
.. automodule:: tgdb.storedproc
   :members:
   :no-special-members:


Notes About Stored Procedures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Not necessarily all of the functionality/syntactical sugar provided by the client-facing API are allowed when executing\
the server environment. Due to these restrictions, writing a stored procedure or trigger requires slightly more\
verbose syntax. The below are the

.. default-domain:: py

.. _sp-tgent:

.. class:: TGEntity

    Acts as a Python wrapper for a database entity.

    :canonical: tgdb.model.TGEntity

    .. method:: setAttribute(attr_name: str, value: typing.Any) -> None

        Sets the attribute with attribute descriptor named by the ``attr_name`` parameter to the value described by the\
        parameter ``value``.

        :param attr_name: The name of the attribute descriptor to set the value on this entity. Must be a valid\
           attribute descriptor name.
        :type attr_name: str
        :param value: The new value of the attribute on this entity. Must have a legal conversion from the Python\
           object to the attribute descriptor type.
        :type value: typing.Any
        :returns: Nothing
        :rtype: None

    .. method:: getAttribute(attr_name: str) -> typing.Any

        Gets the attribute value specified by the ``attr_name`` parameter.

        :param attr_name: The name of the attribute descriptor to get the value on this entity. Must be a valid \
            attribute descriptor name.
        :type attr_name: str
        :returns: The value for the attribute. Will match up with the canonical type of the database in a Python \
            environment (i.e. if the attribute descriptor is a ``double``, then the returned type will be a Python \
            ``float``).
        :rtype: typing.Any

    .. method:: getEntityKind() -> int

        Gets the entity kind as an integer. Can use :py:meth:`fromKindId()<tgdb.model.TGEntityKind.fromKindId>` to get \
        the :py:class:`TGEntityKind<tgdb.model.TGEntityKind>`.

        :returns: The entity kind as an integer.
        :rtype: int

.. _sp-tgnode:

.. class:: TGNode

    Acts as a Python wrapper for a database node. Will extend the :ref:`Stored Procedure Entity<sp-tgent>`. Supports \
    the __hash__, __neq__, and __eq__ builtin Python methods which are useful for using this class as elements in a set \
    or as the key elements in a dictionary.

    :canonical: tgdb.model.TGNode

    .. method:: getNodeType() -> str

        Gets the node's type's name.

        :returns: The name of this node's nodetype.
        :rtype: str

    .. method:: getEdges() -> typing.Iterable[tgdb.model.TGEdge]

        Gets the edges that are incident on this node.

        :returns: The edges incident on this node.
        :rtype: typing.Iterable[tgdb.model.TGEdge]

    .. method:: addEdge(toNode: TGNode, direction: tgdb.model.DirectionType = tgdb.model.DirectionType.Directed,\
                    edgetype: typing.Optional[str] = None) -> TGEdge

        Adds a new edge to this node (as the ``from`` node if ``direction`` type is \
        :py:obj:`directed<tgdb.model.DirectionType.Directed>`), with the other node set to the ``toNode`` parameter, \
        and the edgetype of the new edge is set to the edgetype with the same name as the ``edgetype`` parameter.

        :param toNode: The other node. Will be the ``to`` node if the ``direction`` parameter is \
            :py:obj:`directed<tgdb.model.DirectionType.Directed>`.
        :type toNode: tgdb.storedproc.TGNode
        :param direction: The direction for this node. Only need to set when not setting the ``edgetype`` parameter.
        :type direction: tgdb.model.DirectionType
        :param edgetype: The edgetype of the new edge. Must be a valid edgetype name that is already registered in the \
            database.
        :type edgetype: typing.Optional[str]
        :returns: The new edge.
        :rtype: tgdb.storedproc.TGEdge

.. _sp-tgedge:

.. class:: TGEdge

    Acts as a Python wrapper for a database edge. Will extend the :ref:`Stored Procedure Entity<sp-tgent>`. Supports \
    the __hash__, __neq__, and __eq__ builtin Python methods which are useful for using this class as elements in a set \
    or as the key elements in a dictionary.

    :canonical: tgdb.model.TGEdge

    .. method:: getEdgeType() -> str

        Gets the edge's type's name.

        :returns: The name of this edge's edgetype.
        :rtype: str

    .. method:: getVertices() -> typing.Tuple[tgdb.storedproc.TGNode, tgdb.storedproc.TGNode]

        Gets this edge's incident nodes.

        :returns: The edge's incident nodes.
        :rtype: typing.Tuple[tgdb.storedproc.TGNode, tgdb.storedproc.TGNode]

    .. method:: getDirection() -> int:

        Gets the direction for this edge. Can be converted to a :py:class:`DirectionType<tgdb.model.DirectionType>` by \
        using :py:meth:`fromId()<tgdb.model.DirectionType.fromId>`.

        :returns: The edge's direction.
        :rtype: int

.. _sp-tgkey:

.. class:: TGKey

    Acts as a Python wrapper for a database key. Will extend the :ref:`Stored Procedure Entity<sp-tgent>`. Supports \
    the __setitem__ and __delitem__ builtin Python methods which are useful for using the bracket notation to set \
    attribute values.

    :canonical: tgdb.model.TGKey