similarity module¶

Binary similarity providers, session graphs, result resolution, and rendering. (Ultimate Only)

Class	Description
`binaryninja.similarity.CoreSimilarityProvider`	A similarity provider implemented by the core or a native plugin.
`binaryninja.similarity.CoreSimilarityProviderType`	A similarity provider type implemented by the core or a native plugin.
`binaryninja.similarity.CoreSimilaritySessionGraphReceiver`	A session graph receiver implemented by the core or a native plugin.
`binaryninja.similarity.CoreSimilaritySessionReceiver`	A session receiver implemented by the core or a native plugin.
`binaryninja.similarity.CoreSimilaritySessionResolver`	A resolver implemented by the core or a native plugin.
`binaryninja.similarity.CoreSimilaritySessionResolverType`	A resolver type implemented by the core or a native plugin.
`binaryninja.similarity.DiffRenderer`	Renders functions with similarity range annotations.
`binaryninja.similarity.SimilarityEntityInfo`	The type, address, and display name of a session entity.
`binaryninja.similarity.SimilarityEntityRef`	Identifies an entity within a session node.
`binaryninja.similarity.SimilarityProvider`	Visits session nodes and produces similarity results.
`binaryninja.similarity.SimilarityProviderResults`	Writes results for one provider visit.
`binaryninja.similarity.SimilarityProviderType`	Creates similarity providers with the given settings.
`binaryninja.similarity.SimilarityRangeAnnotation`	An added, removed, or changed address range `[start, end)`.
`binaryninja.similarity.SimilarityRenderContext`	Holds views used to display a similarity result.
`binaryninja.similarity.SimilarityResult`	A match produced by a provider.
`binaryninja.similarity.SimilaritySession`	Runs similarity providers and resolvers over a graph of binaries.
`binaryninja.similarity.SimilaritySessionCompletion`	Tracks stop requests, progress, and timing for a session run.
`binaryninja.similarity.SimilaritySessionCompletionQuery`	Chooses which session completion data to read or update.
`binaryninja.similarity.SimilaritySessionGraph`	A graph that controls node processing order and cannot contain cycles.
`binaryninja.similarity.SimilaritySessionGraphReceiver`	Receives notifications after nodes or edges are added to or removed from a session graph.
`binaryninja.similarity.SimilaritySessionNode`	The main unit of similarity processing.
`binaryninja.similarity.SimilaritySessionReceiver`	Receives session-start and entity-update notifications.
`binaryninja.similarity.SimilaritySessionResolver`	Selects provider results to apply to session entities.
`binaryninja.similarity.SimilaritySessionResolverType`	Creates resolvers with the given settings.
`binaryninja.similarity.SimilarityView`	A graph or linear view produced for a similarity result.

CoreSimilarityProvider¶

class CoreSimilarityProvider[source]¶

Bases: SimilarityProvider

A similarity provider implemented by the core or a native plugin.

CoreSimilarityProviderType¶

class CoreSimilarityProviderType[source]¶

Bases: SimilarityProviderType

A similarity provider type implemented by the core or a native plugin.

create(settings_obj: Settings) → SimilarityProvider | None[source]¶

Create a provider using settings_obj, or return None. Returns None outside Ultimate.

Parameters:: settings_obj (Settings)
Return type:: SimilarityProvider | None

get_default_settings() → Settings | None[source]¶

Return settings used to configure new providers.

Return type:: Settings | None

CoreSimilaritySessionGraphReceiver¶

class CoreSimilaritySessionGraphReceiver[source]¶

Bases: SimilaritySessionGraphReceiver

A session graph receiver implemented by the core or a native plugin.

CoreSimilaritySessionReceiver¶

class CoreSimilaritySessionReceiver[source]¶

Bases: SimilaritySessionReceiver

A session receiver implemented by the core or a native plugin.

CoreSimilaritySessionResolver¶

class CoreSimilaritySessionResolver[source]¶

Bases: SimilaritySessionResolver

A resolver implemented by the core or a native plugin.

CoreSimilaritySessionResolverType¶

class CoreSimilaritySessionResolverType[source]¶

Bases: SimilaritySessionResolverType

A resolver type implemented by the core or a native plugin.

create(session: SimilaritySession, settings_obj: Settings) → SimilaritySessionResolver | None[source]¶

Create a resolver for session using settings_obj, or return None.

Parameters:

session (SimilaritySession)
settings_obj (Settings)

Return type:

SimilaritySessionResolver | None

get_default_settings() → Settings | None[source]¶

Return settings used to configure new resolvers.

Return type:: Settings | None

DiffRenderer¶

class DiffRenderer[source]¶

Bases: object

Renders functions with similarity range annotations.

__init__(handle: LP_BNDiffRenderer | None = None)[source]¶

Parameters:: handle (LP_BNDiffRenderer | None)

add_range_annotation(annotation: SimilarityRangeAnnotation) → None[source]¶

Add an annotation to subsequent renders.

Note

Empty ranges are ignored.

Parameters:: annotation (SimilarityRangeAnnotation)
Return type:: None

render(context: SimilarityRenderContext, source: Function, entity: SimilarityEntityRef | None = None) → None[source]¶

Render graph and linear views for source.

Parameters:

context (SimilarityRenderContext)
source (Function)
entity (SimilarityEntityRef | None)

Return type:

None

render_flow_graph(context: SimilarityRenderContext, group: str, graph: FlowGraph, entity: SimilarityEntityRef | None = None) → None[source]¶

Render an annotated flow graph into context.

Parameters:

context (SimilarityRenderContext)
group (str)
graph (FlowGraph)
entity (SimilarityEntityRef | None)

Return type:

None

render_linear_view(context: SimilarityRenderContext, group: str, data: BinaryView, linear_view: LinearViewObject, entity: SimilarityEntityRef | None = None) → None[source]¶

Render an annotated linear view into context.

Parameters:

context (SimilarityRenderContext)
group (str)
data (BinaryView)
linear_view (LinearViewObject)
entity (SimilarityEntityRef | None)

Return type:

None

SimilarityEntityInfo¶

class SimilarityEntityInfo[source]¶

Bases: object

The type, address, and display name of a session entity.

__init__(type: SimilarityEntityType, address: int, name: str = '') → None¶

Parameters:

type (SimilarityEntityType)
address (int)
name (str)

Return type:

None

address: int¶

name: str = ''¶

type: SimilarityEntityType¶

SimilarityEntityRef¶

class SimilarityEntityRef[source]¶

Bases: object

Identifies an entity within a session node.

__init__(node_id: int, entity_id: int) → None¶

Parameters:

node_id (int)
entity_id (int)

Return type:

None

entity_id: int¶

node_id: int¶

SimilarityProvider¶

class SimilarityProvider[source]¶

Bases: object

Visits session nodes and produces similarity results.

Implementations must be thread-safe. Callbacks may overlap across nodes and sessions. Visits made by a session keep the visited node and both edge endpoints active. Direct calls must provide active views.

__init__(provider_type: SimilarityProviderType | None = None, handle: LP_BNSimilarityProvider | None = None)[source]¶

Parameters:

provider_type (SimilarityProviderType | None)
handle (LP_BNSimilarityProvider | None)

apply(node: SimilaritySessionNode, entity: int, result: int) → SimilarityApplyStatus[source]¶

Call the provider’s apply hook for result.

Parameters:

node (SimilaritySessionNode)
entity (int)
result (int)

Return type:

SimilarityApplyStatus

get_name(node: SimilaritySessionNode, entity: int, result: int) → str | None[source]¶

Return the display name of result.

Parameters:

node (SimilaritySessionNode)
entity (int)
result (int)

Return type:

str | None

perform_apply(node: SimilaritySessionNode, entity: int, result: int) → SimilarityApplyStatus[source]¶

Transfer typical metadata from the result target. Overrides can call this before adding provider metadata.

Parameters:

node (SimilaritySessionNode)
entity (int)
result (int)

Return type:

SimilarityApplyStatus

perform_get_name(node: SimilaritySessionNode, entity: int, result: int) → str | None[source]¶

Return a display name for result.

Parameters:

node (SimilaritySessionNode)
entity (int)
result (int)

Return type:

str | None

perform_render(node: SimilaritySessionNode, entity: int, context: SimilarityRenderContext, result: int) → None[source]¶

Add views for result to context.

Parameters:

node (SimilaritySessionNode)
entity (int)
context (SimilarityRenderContext)
result (int)

Return type:

None

perform_update_settings(settings_obj: Settings) → bool[source]¶

Replace this provider’s settings only if they are valid.

Return False without changing the current settings when the new settings are invalid or updates are not supported. Use SimilaritySession.update_provider_settings so affected entities are scheduled again.

Parameters:: settings_obj (Settings)
Return type:: bool

perform_visit_node(node: SimilaritySessionNode, results: SimilarityProviderResults, completion: SimilaritySessionCompletion) → bool | None[source]¶

Visit a node and write results for it, returning False to discard the visit.

Process node.scheduled_entities. Omitted results are removed for those entities only.

Parameters:

node (SimilaritySessionNode)
results (SimilarityProviderResults)
completion (SimilaritySessionCompletion)

Return type:

bool | None

perform_visit_node_edge(from_node: SimilaritySessionNode, to_node: SimilaritySessionNode, results: SimilarityProviderResults, completion: SimilaritySessionCompletion) → bool | None[source]¶

Visit an edge and write results for it, returning False to discard the visit.

Parameters:

from_node (SimilaritySessionNode)
to_node (SimilaritySessionNode)
results (SimilarityProviderResults)
completion (SimilaritySessionCompletion)

Return type:

bool | None

render(node: SimilaritySessionNode, entity: int, context: SimilarityRenderContext, result: int) → None[source]¶

Add views for result to context.

Parameters:

node (SimilaritySessionNode)
entity (int)
context (SimilarityRenderContext)
result (int)

Return type:

None

visit_node(node: SimilaritySessionNode, completion: SimilaritySessionCompletion) → None[source]¶

Perform a complete visit of node. The core manages the result updates.

Parameters:

node (SimilaritySessionNode)
completion (SimilaritySessionCompletion)

Return type:

None

visit_node_edge(from_node: SimilaritySessionNode, to_node: SimilaritySessionNode, completion: SimilaritySessionCompletion) → None[source]¶

Perform a complete visit of the edge from from_node to to_node.

Parameters:

from_node (SimilaritySessionNode)
to_node (SimilaritySessionNode)
completion (SimilaritySessionCompletion)

Return type:

None

property id: int¶: This provider’s ID.

property type: SimilarityProviderType¶: The type that created this provider.

SimilarityProviderResults¶

class SimilarityProviderResults[source]¶

Bases: object

Writes results for one provider visit.

Only use an instance during the provider callback that received it. A successful visit replaces earlier results for the same provider and node or edge. Results for unscheduled entities remain unchanged.

__init__(handle: LP_BNSimilarityProviderResults)[source]¶

Parameters:: handle (LP_BNSimilarityProviderResults)

add_result(source: SimilarityEntityRef, target: SimilarityEntityRef, similarity: int, confidence: int) → int[source]¶

Add a result for a scheduled entity and return its ID, or zero on failure.

The ID is unique within the node. A later visit replaces the result and gives it a new ID.

Parameters:

source (SimilarityEntityRef)
target (SimilarityEntityRef)
similarity (int)
confidence (int)

Return type:

int

property handle¶

SimilarityProviderType¶

class SimilarityProviderType[source]¶

Bases: object

Creates similarity providers with the given settings.

__init__(handle: LP_BNSimilarityProviderType | None = None)[source]¶

Parameters:: handle (LP_BNSimilarityProviderType | None)

create(settings_obj: Settings) → SimilarityProvider | None[source]¶

Create a provider using settings_obj, or return None. Custom types must override this method.

Parameters:: settings_obj (Settings)
Return type:: SimilarityProvider | None

get_default_settings() → Settings | None[source]¶

Return settings used to configure new providers.

Return type:: Settings | None

register() → None[source]¶

Register this provider type for the process lifetime.

Return type:: None

description = None¶

name = None¶

SimilarityRangeAnnotation¶

class SimilarityRangeAnnotation[source]¶

Bases: object

An added, removed, or changed address range [start, end).

__init__(start: int, end: int, type: SimilarityAnnotationType) → None¶

Parameters:

start (int)
end (int)
type (SimilarityAnnotationType)

Return type:

None

end: int¶

start: int¶

type: SimilarityAnnotationType¶

SimilarityRenderContext¶

class SimilarityRenderContext[source]¶

Bases: object

Holds views used to display a similarity result.

__init__(handle: LP_BNSimilarityRenderContext | None = None)[source]¶

Parameters:: handle (LP_BNSimilarityRenderContext | None)

add_flow_graph(group: str, graph: FlowGraph, entity: SimilarityEntityRef | None = None) → None[source]¶

Add a flow graph to group.

Parameters:

group (str)
graph (FlowGraph)
entity (SimilarityEntityRef | None)

Return type:

None

add_linear_view(group: str, data: BinaryView, linear_view: LinearViewObject, entity: SimilarityEntityRef | None = None) → None[source]¶

Add a linear view backed by data to group.

Parameters:

group (str)
data (BinaryView)
linear_view (LinearViewObject)
entity (SimilarityEntityRef | None)

Return type:

None

property preferred_view_type: FunctionViewType¶: Function representation preferred by renderers writing to this context.

property views: List[SimilarityView]¶: Views in the order they were added.

SimilarityResult¶

class SimilarityResult[source]¶

Bases: object

A match produced by a provider.

Similarity and confidence range from 0 to 255, where 255 is strongest. Automatic metadata transfer requires target to identify an active function.

__init__(provider_id: int, similarity: int, confidence: int, target: SimilarityEntityRef) → None¶

Parameters:

provider_id (int)
similarity (int)
confidence (int)
target (SimilarityEntityRef)

Return type:

None

confidence: int¶: The provider’s confidence in the match.

provider_id: int¶: The provider which produced the match.

similarity: int¶: The similarity of the two entities.

target: SimilarityEntityRef¶: The matched entity, which may be used as the source for metadata transfer.

SimilaritySession¶

class SimilaritySession[source]¶

Bases: object

Runs similarity providers and resolvers over a graph of binaries.

__init__(handle: LP_BNSimilaritySession | None = None)[source]¶

Parameters:: handle (LP_BNSimilaritySession | None)

add_provider(provider: SimilarityProvider) → None[source]¶

Add a provider and schedule entities processed by earlier runs for the next run.

Note

Ignored while a run is active.

Parameters:: provider (SimilarityProvider)
Return type:: None

add_receiver(receiver: SimilaritySessionReceiver) → None[source]¶

Add a receiver. A running session keeps using the receiver list it started with.

Parameters:: receiver (SimilaritySessionReceiver)
Return type:: None

add_resolver(resolver: SimilaritySessionResolver) → bool[source]¶

Add a resolver and mark entities processed by earlier runs for resolution.

Note

Returns False during a run, for a duplicate, or for a resolver from another session.

Parameters:: resolver (SimilaritySessionResolver)
Return type:: bool

get_provider(id: int) → SimilarityProvider | None[source]¶

Return the provider with id.

Parameters:: id (int)
Return type:: SimilarityProvider | None

get_resolver(id: int) → SimilaritySessionResolver | None[source]¶

Return the resolver with id, if present.

Parameters:: id (int)
Return type:: SimilaritySessionResolver | None

remove_provider(provider: SimilarityProvider) → None[source]¶

Remove a provider, clear its results, and mark affected entities for resolution.

Note

Ignored while a run is active.

Parameters:: provider (SimilarityProvider)
Return type:: None

remove_receiver(receiver: SimilaritySessionReceiver) → None[source]¶

Remove a receiver. A running session keeps using the receiver list it started with.

Parameters:: receiver (SimilaritySessionReceiver)
Return type:: None

remove_resolver(resolver: SimilaritySessionResolver) → bool[source]¶

Remove a resolver.

Note

Returns False during a run, or if it is absent or belongs to another session.

Parameters:: resolver (SimilaritySessionResolver)
Return type:: bool

Start a background run with the current graph, providers, and resolvers.

Changes to them are ignored until the run finishes.

Note

Returns the active run’s completion state when already running.

Return type:: SimilaritySessionCompletion

update_provider_settings(provider: SimilarityProvider, settings_obj: Settings) → bool[source]¶

Update a provider already in the session and schedule previously processed entities again.

Returns False during a run, when the provider is absent, or when it rejects the settings.

Parameters:

provider (SimilarityProvider)
settings_obj (Settings)

Return type:

bool

update_resolver_settings(resolver: SimilaritySessionResolver, settings_obj: Settings) → bool[source]¶

Update a resolver already in the session and mark previously processed entities for resolution.

Returns False during a run, when the resolver is absent or belongs to another session, or when it rejects the settings.

Parameters:

resolver (SimilaritySessionResolver)
settings_obj (Settings)

Return type:

bool

property graph: SimilaritySessionGraph¶: The session’s dependency graph.

property id: int¶: This session’s ID.

property providers: List[SimilarityProvider]¶: Providers in this session.

property receivers: List[SimilaritySessionReceiver]¶: Receivers in this session.

property resolvers: List[SimilaritySessionResolver]¶: Resolvers in this session.

SimilaritySessionCompletion¶

class SimilaritySessionCompletion[source]¶

Bases: object

Tracks stop requests, progress, and timing for a session run.

__init__(handle: LP_BNSimilaritySessionCompletion | None = None)[source]¶

Create an independent completion state, or wrap handle when provided.

Independent states are normally only needed when calling providers or resolvers directly.

Parameters:: handle (LP_BNSimilaritySessionCompletion | None)

get_progress(query: SimilaritySessionCompletionQuery) → float[source]¶

Return progress matching query from 0.0 to 1.0.

Parameters:: query (SimilaritySessionCompletionQuery)
Return type:: float

get_timing(query: SimilaritySessionCompletionQuery) → timedelta[source]¶

Return elapsed time matching query.

Parameters:: query (SimilaritySessionCompletionQuery)
Return type:: timedelta

request_stop() → None[source]¶

Ask the active run to stop.

Return type:: None

set_progress(query: SimilaritySessionCompletionQuery, progress: float) → None[source]¶

Increase provider or resolver progress for a node. Progress cannot decrease.

Note

Call this only from the provider or resolver selected by query.

Parameters:

query (SimilaritySessionCompletionQuery)
progress (float)

Return type:

None

property is_finished: bool¶: Whether the run has finished.

property is_stop_requested: bool¶: Whether the run has been asked to stop.

property progress: float¶: Overall progress from 0.0 to 1.0.

SimilaritySessionCompletionQuery¶

class SimilaritySessionCompletionQuery[source]¶

Bases: object

Chooses which session completion data to read or update.

A query cannot select both a provider and a resolver. Omitting all IDs selects the whole session.

__init__(node_id: int | None = None, provider_id: int | None = None, resolver_id: int | None = None) → None¶

Parameters:

node_id (int | None)
provider_id (int | None)
resolver_id (int | None)

Return type:

None

classmethod for_node(node_id: int) → SimilaritySessionCompletionQuery[source]¶

Select a node.

Parameters:: node_id (int)
Return type:: SimilaritySessionCompletionQuery

classmethod for_provider(provider_id: int) → SimilaritySessionCompletionQuery[source]¶

Select a provider across the session.

Parameters:: provider_id (int)
Return type:: SimilaritySessionCompletionQuery

classmethod for_resolver(resolver_id: int) → SimilaritySessionCompletionQuery[source]¶

Select a resolver across the session.

Parameters:: resolver_id (int)
Return type:: SimilaritySessionCompletionQuery

classmethod for_session() → SimilaritySessionCompletionQuery[source]¶

Select the whole session.

Return type:: SimilaritySessionCompletionQuery

with_provider(provider_id: int) → SimilaritySessionCompletionQuery[source]¶

Select a provider within the current selection.

Parameters:: provider_id (int)
Return type:: SimilaritySessionCompletionQuery

with_resolver(resolver_id: int) → SimilaritySessionCompletionQuery[source]¶

Select a resolver within the current selection.

Parameters:: resolver_id (int)
Return type:: SimilaritySessionCompletionQuery

node_id: int | None = None¶

provider_id: int | None = None¶

resolver_id: int | None = None¶

SimilaritySessionGraph¶

class SimilaritySessionGraph[source]¶

Bases: object

A graph that controls node processing order and cannot contain cycles.

Nodes and edges cannot be changed during a run. Methods with no return value ignore changes, while methods that return bool return False.

__init__(handle: LP_BNSimilaritySessionGraph)[source]¶

Parameters:: handle (LP_BNSimilaritySessionGraph)

add_edge(from_node: SimilaritySessionNode, to_node: SimilaritySessionNode) → bool[source]¶

Make to_node run after from_node.

Parameters:

from_node (SimilaritySessionNode)
to_node (SimilaritySessionNode)

Return type:

bool

add_node(node: SimilaritySessionNode) → None[source]¶

Add node, moving it unless either graph is currently running.

Parameters:: node (SimilaritySessionNode)
Return type:: None

add_receiver(receiver: SimilaritySessionGraphReceiver) → None[source]¶

Add a graph-change receiver.

Parameters:: receiver (SimilaritySessionGraphReceiver)
Return type:: None

get_node(id: int) → SimilaritySessionNode | None[source]¶

Return the node with id.

Parameters:: id (int)
Return type:: SimilaritySessionNode | None

get_schedule() → List[List[SimilaritySessionNode]][source]¶

Return groups of nodes in processing order. Nodes in the same group may run in parallel.

Return type:: List[List[SimilaritySessionNode]]

is_valid_edge(from_node: SimilaritySessionNode, to_node: SimilaritySessionNode) → bool[source]¶

Return whether an edge can be added without duplicating an edge or creating a cycle.

Parameters:

from_node (SimilaritySessionNode)
to_node (SimilaritySessionNode)

Return type:

bool

remove_edge(from_node: SimilaritySessionNode, to_node: SimilaritySessionNode) → bool[source]¶

Remove the edge from from_node to to_node.

Parameters:

from_node (SimilaritySessionNode)
to_node (SimilaritySessionNode)

Return type:

bool

remove_node(node: SimilaritySessionNode) → None[source]¶

Remove node and its edges from this graph.

Parameters:: node (SimilaritySessionNode)
Return type:: None

remove_receiver(receiver: SimilaritySessionGraphReceiver) → None[source]¶

Remove a graph-change receiver.

Parameters:: receiver (SimilaritySessionGraphReceiver)
Return type:: None

property nodes: List[SimilaritySessionNode]¶: Nodes in this graph.

property receivers: List[SimilaritySessionGraphReceiver]¶: Graph-change receivers currently registered with this graph.

SimilaritySessionGraphReceiver¶

class SimilaritySessionGraphReceiver[source]¶

Bases: object

Receives notifications after nodes or edges are added to or removed from a session graph.

__init__(handle: LP_BNSimilaritySessionGraphReceiver | None = None)[source]¶

Parameters:: handle (LP_BNSimilaritySessionGraphReceiver | None)

perform_on_graph_changed() → None[source]¶

Handle a node or edge being added to or removed from the graph.

Return type:: None

SimilaritySessionNode¶

class SimilaritySessionNode[source]¶

Bases: object

The main unit of similarity processing.

__init__(view: BinaryView | None = None, file: FileMetadata | None = None, handle: LP_BNSimilaritySessionNode | None = None)[source]¶

Parameters:

view (BinaryView | None)
file (FileMetadata | None)
handle (LP_BNSimilaritySessionNode | None)

add_scheduled_entity(id: int) → bool[source]¶

Schedule an entity for the next provider round.

Nodes initially schedule all available entities. The session consumes each scheduled batch before resolution; resolvers can call this method to request another round.

Parameters:: id (int)
Return type:: bool

clear_resolved_result(entity: int) → bool[source]¶

Clear the selected result for entity.

Parameters:: entity (int)
Return type:: bool

create_entity(info: SimilarityEntityInfo) → int[source]¶

Add an entity without scheduling it.

An existing entity with the same type and address is reused. A non-empty name refreshes its display name.

Parameters:: info (SimilarityEntityInfo)
Return type:: int

get_entity(id: int) → SimilarityEntityInfo | None[source]¶

Return information about an entity.

Parameters:: id (int)
Return type:: SimilarityEntityInfo | None

get_entity_function(id: int) → Function | None[source]¶

Return the function represented by an entity, if available.

Parameters:: id (int)
Return type:: Function | None

get_resolved_result(entity: int) → int | None[source]¶

Return the selected result for entity.

Parameters:: entity (int)
Return type:: int | None

get_result(result: int) → SimilarityResult | None[source]¶

Return a stored result by its ID, which is unique within the node.

Parameters:: result (int)
Return type:: SimilarityResult | None

get_results(entity: int) → List[int][source]¶

Return the result IDs for entity.

Parameters:: entity (int)
Return type:: List[int]

remove_entity(id: int) → bool[source]¶

Remove an entity, its schedule, its provider results, and its selected result.

To only unschedule it, use remove_scheduled_entity.

Parameters:: id (int)
Return type:: bool

remove_scheduled_entity(id: int) → bool[source]¶

Unschedule an entity without removing it.

To remove it, use remove_entity.

Parameters:: id (int)
Return type:: bool

set_resolved_result(entity: int, result: int) → bool[source]¶

Select one of entity’s results.

Parameters:

entity (int)
result (int)

Return type:

bool

property entities: List[int]¶: All entities, including entities used only as match targets.

property file: FileMetadata¶: The file backing this node.

property id: int¶: This node’s ID.

property incoming_edges: List[int]¶: IDs of nodes that must run before this node, in ascending order.

property incoming_nodes: List[SimilaritySessionNode]¶: Nodes that must run before this node, ordered by ID.

property load_options: Settings¶: Options used when opening this node’s view. Modify them before running the session.

property outgoing_edges: List[int]¶: IDs of nodes that depend on this node, in ascending order.

property outgoing_nodes: List[SimilaritySessionNode]¶: Nodes that depend on this node, ordered by ID.

property scheduled_entities: List[int]¶: Entities waiting for provider processing.

property view: BinaryView | None¶

The open view, if one is available.

A file-backed node’s view may be unavailable outside a session run. The session closes it when the run no longer needs it.

SimilaritySessionReceiver¶

class SimilaritySessionReceiver[source]¶

Bases: object

Receives session-start and entity-update notifications.

perform_on_start is called before SimilaritySession.run returns. Update callbacks run on workers and may overlap across nodes and sessions.

__init__(handle: LP_BNSimilaritySessionReceiver | None = None)[source]¶

Parameters:: handle (LP_BNSimilaritySessionReceiver | None)

perform_on_start(completion: SimilaritySessionCompletion) → None[source]¶

Handle the start of a session run.

This is mainly used to get the completion state for the run.

Parameters:: completion (SimilaritySessionCompletion)
Return type:: None

perform_on_update(node: SimilaritySessionNode, provider: SimilarityProvider, entities: List[int]) → None[source]¶

Handle entities whose provider results, resolution state, or applied metadata changed.

Custom receivers must override this method.

Parameters:

node (SimilaritySessionNode)
provider (SimilarityProvider)
entities (List[int])

Return type:

None

SimilaritySessionResolver¶

class SimilaritySessionResolver[source]¶

Bases: object

Selects provider results to apply to session entities.

Calls for nodes in the same processing group may run at the same time. Do not keep the session after a callback returns.

__init__(resolver_type: SimilaritySessionResolverType | None = None, session: SimilaritySession | None = None, handle: LP_BNSimilaritySessionResolver | None = None)[source]¶

Parameters:

resolver_type (SimilaritySessionResolverType | None)
session (SimilaritySession | None)
handle (LP_BNSimilaritySessionResolver | None)

perform_prepare_for_node(session: SimilaritySession, node: SimilaritySessionNode, completion: SimilaritySessionCompletion) → None[source]¶

Prepare node before its providers are visited.

This is useful for large graphs where views may be unavailable, but the resolver needs to change the scheduled entities or add entities itself.

Parameters:

session (SimilaritySession)
node (SimilaritySessionNode)
completion (SimilaritySessionCompletion)

Return type:

None

perform_resolve_for_node(session: SimilaritySession, node: SimilaritySessionNode, entities: List[int], completion: SimilaritySessionCompletion) → None[source]¶

Select results for node after its providers have run.

Call SimilaritySessionNode.set_resolved_result to select a result. Custom resolvers must override this method. Call SimilaritySessionNode.add_scheduled_entity to request another round.

Parameters:

session (SimilaritySession)
node (SimilaritySessionNode)
entities (List[int])
completion (SimilaritySessionCompletion)

Return type:

None

perform_update_settings(settings_obj: Settings) → bool[source]¶

Replace this resolver’s settings only if they are valid.

Return False without changing the current settings when the new settings are invalid or updates are not supported. Use SimilaritySession.update_resolver_settings so affected entities are resolved again.