"""
This type stub file was generated by pyright.
"""

from ..._ffi.object import ObjectBase, register_object

__all__ = ['random_walk', 'random_walk_with_restart', 'bipartite_single_sided_random_walk_with_restart', 'metapath_random_walk']
@register_object('sampler.RandomWalkTraces')
class RandomWalkTraces(ObjectBase):
    ...


def random_walk(g, seeds, num_traces, num_hops):
    """**DEPRECATED**: please use :func:`dgl.sampling.random_walk` instead.

    Batch-generate random walk traces on given graph with the same length.

    Parameters
    ----------
    g : DGLGraphStale
        The graph.
    seeds : Tensor
        The node ID tensor from which the random walk traces starts.
    num_traces : int
        Number of traces to generate for each seed.
    num_hops : int
        Number of hops for each trace.

    Returns
    -------
    traces : Tensor
        A 3-dimensional node ID tensor with shape

            (num_seeds, num_traces, num_hops + 1)

        traces[i, j, 0] are always starting nodes (i.e. seed[i]).
    """
    ...

def random_walk_with_restart(g, seeds, restart_prob, max_nodes_per_seed, max_visit_counts=..., max_frequent_visited_nodes=...): # -> list[Unknown]:
    """**DEPRECATED**: please use :func:`dgl.sampling.random_walk` instead.

    Batch-generate random walk traces on given graph with restart probability.

    Parameters
    ----------
    g : DGLGraphStale
        The graph.
    seeds : Tensor
        The node ID tensor from which the random walk traces starts.
    restart_prob : float
        Probability to stop a random walk after each step.
    max_nodes_per_seed : int
        Stop generating traces for a seed if the total number of nodes
        visited exceeds this number. [1]
    max_visit_counts : int, optional
    max_frequent_visited_nodes : int, optional
        Alternatively, stop generating traces for a seed if no less than
        ``max_frequent_visited_nodes`` are visited no less than
        ``max_visit_counts`` times.  [1]

    Returns
    -------
    traces : list[list[Tensor]]
        traces[i][j] is the j-th trace generated for i-th seed.

    Notes
    -----
    The traces does **not** include the seed nodes themselves.

    Reference
    ---------
    [1] Eksombatchai et al., 2017 https://arxiv.org/abs/1711.07601
    """
    ...

def bipartite_single_sided_random_walk_with_restart(g, seeds, restart_prob, max_nodes_per_seed, max_visit_counts=..., max_frequent_visited_nodes=...): # -> list[Unknown]:
    """**DEPRECATED**: please use :func:`dgl.sampling.random_walk` instead.

    Batch-generate random walk traces on given graph with restart probability.

    The graph must be a bipartite graph.

    A single random walk step involves two normal steps, so that the "visited"
    nodes always stay on the same side. [1]

    Parameters
    ----------
    g : DGLGraphStale
        The graph.
    seeds : Tensor
        The node ID tensor from which the random walk traces starts.
    restart_prob : float
        Probability to stop a random walk after each step.
    max_nodes_per_seed : int
        Stop generating traces for a seed if the total number of nodes
        visited exceeds this number. [1]
    max_visit_counts : int, optional
    max_frequent_visited_nodes : int, optional
        Alternatively, stop generating traces for a seed if no less than
        ``max_frequent_visited_nodes`` are visited no less than
        ``max_visit_counts`` times.  [1]

    Returns
    -------
    traces : list[list[Tensor]]
        traces[i][j] is the j-th trace generated for i-th seed.

    Notes
    -----
    The current implementation does not ensure that the graph is a bipartite
    graph.

    The traces does **not** include the seed nodes themselves.

    Reference
    ---------
    [1] Eksombatchai et al., 2017 https://arxiv.org/abs/1711.07601
    """
    ...

def metapath_random_walk(hg, etypes, seeds, num_traces): # -> list[Unknown]:
    """**DEPRECATED**: please use :func:`dgl.sampling.random_walk` instead.

    For a single seed node, ``num_traces`` traces would be generated.  A trace would

    1. Start from the given seed and set ``t`` to 0.
    2. Pick and traverse along edge type ``etypes[t % len(etypes)]`` from the current node.
    3. If no edge can be found, halt.  Otherwise, increment ``t`` and go to step 2.

    Parameters
    ----------
    hg : DGLHeteroGraph
        The heterogeneous graph.
    etypes : list[str or tuple of str]
        Metapath, specified as a list of edge types.
        The beginning and ending node type must be the same.
    seeds : Tensor
        The seed nodes.  Node type is the same as the beginning node type of metapath.
    num_traces : int
        The number of traces

    Returns
    -------
    traces : list[list[Tensor]]
        traces[i][j] is the j-th trace generated for i-th seed.
        traces[i][j][k] would have node type the same as the destination node type of edge
        type ``etypes[k % len(etypes)]``

    Notes
    -----
    The traces does **not** include the seed nodes themselves.
    """
    ...

