edgegraph.traversal.helpers.ineighbors

Contents

edgegraph.traversal.helpers.ineighbors#

edgegraph.traversal.helpers.ineighbors(vert, direction_sensitive=0, unknown_handling=2, filterfunc=None)#

Identify the neighbors of a given vertex (generator).

This function checks the edges associated with the given vertex, identifies the vertices on the other end of those edges, and returns them. It respects edge directionality if/when necessary, and can handle arbitrary edge types given they are subclasses of either DirectedEdge or UnDirectedEdge.

For example, with the given graph:

object v1 object v2 object v3 object v4 v1 --> v2 v1 --> v3 v2 --> v3 v3 --> v4 v4 --> v1

the function would operate as:

>>> list(ineighbors(v1))
[v2, v3]
>>> list(ineighbors(v1, direction_sensitive=DIR_SENS_FORWARD))
[v2, v3, v4]
>>> list(ineighbors(v4))
[v1]
>>> list(ineighbors(v4, direction_sensitive=DIR_SENS_ANY))
[v1, v3]

If supplied, the filterfunc argument should be to a callable object (function or otherwise) that will return either True or False. This function is used to determine if a given vertex should be included in the returned neighbors. It must have the following signature:

edgegraph.traversal.helpers.filterfunc(e, v2)

Determines if a given vertex (v2) should be included in the neighbors of v. Because v2 may be reachable from v1 via multiple edges, the edge currently being considered is given as well.

Parameters:

  • e – The edge connecting v1 to v2.

  • v2 – The vertex under consideration.

Returns:

Whether or not v2 should be considered a neighbor of v, when reached via e.

For example, one may wish to only consider vertices if a given attribute meets some criteria:

>>> list(ineighbors(v1))
[v2, v3]
>>> list(ineighbors(v1, filterfunc=lambda e, v2: v2.i >= 3))
[v3]

Note

The filterfunc parameter operates in addition to the direction_sensitive parameter!

See also

If you find yourself calling this function a lot on vertices that haven’t changed nieghbors, you may wish to read about Vertex neighbor caching. This technique allows this function to work in tandem with the Vertex class to cache neighbor lookups in a safe manner, drastically improving performance in some scenarios.

Parameters:

  • vert (Vertex) – The vertex to identify neighbors of.

  • direction_sensitive (int) – How to handle directional edges as they are encountered. DIR_SENS_FORWARD will indicates “normal” usages, where edges will only be followed outwards from the given vertex. DIR_SENS_ANY will follow any edge, regardless of whether it points to or from this vertex. DIR_SENS_BACKWARD will follow only edges inbound to this vertex.

  • unknown_handling (int) – What to do with edges whose class is not recognized (not a subclass / instance of either DirectedEdge or UnDirectedEdge). Options are LNK_UNKNOWN_NONNEIGHBOR to treat unknown edges as non-neighbors, LNK_UNKNOWN_NEIGHBOR to treat unknown edges as neighbors, or LNK_UNKNOWN_ERROR to raise a NotImplementedError if such an edge is encountered.

  • filterfunc (Callable | None) – Callable object to determine whether the given edge / vertex should be included in the neighbors output.

Raises:

NotImplementedError – if kwarg unknown_handling is set to LNK_UNKNOWN_ERROR and an unknown edge class is enountered.

Returns:

A generator object which yields Vertex objects representing neighbors of the specified vertex.

Return type:

Generator[Vertex, None, None]

Contents