Source code for qbindiff.types

# Copyright 2023 Quarkslab
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Contains all the type alias/definitions used by the module

This module contains all definitions of the type aliases and the generic enums
used by qbindiff.
"""

from __future__ import annotations
from collections.abc import Iterable
from typing import Any, TypeAlias, Protocol, TYPE_CHECKING

import numpy
from pathlib import Path
from scipy.sparse import csr_matrix, csr_array
from collections import namedtuple
import enum_tools.documentation
from enum import IntEnum

from qbindiff.abstract import GenericGraph

if TYPE_CHECKING:
    from qbindiff import Program

FeatureValue: TypeAlias = float | dict[str, float]
"""
Type of a feature value.
"""

Positive: TypeAlias = float
"""
Float greater than zero
"""

Ratio: TypeAlias = float
"""
Float bewteen 0 and 1
"""

Idx: TypeAlias = int
"""
An integer representing an index in a matrix.
"""

Addr: TypeAlias = int
"""
An integer representing an address within a program
"""

Item: TypeAlias = Any
"""
Item, entity being matched. The only constraint is to be hashable
"""

Anchors: TypeAlias = list[tuple[Item, Item]]
"""
Pair of lists of user defined index correspondences. Default None.
"""

RawMapping: TypeAlias = tuple[list[Idx], list[Idx]]
"""
Pair of lists of indexes that are mapped together.
"""

Match = namedtuple("Match", "primary secondary similarity confidence squares")
"""
Match represent the matching between two functions and can hold the similarity between the two
"""


ExtendedMapping: TypeAlias = Iterable[tuple[Item, Item, float, int]]
"""
An extended version of RawMapping with two more lists recording pairing similarity and induced number of squares.
"""

Dtype: TypeAlias = numpy.dtype
"""
Numpy data type
"""

Vector: TypeAlias = numpy.ndarray
"""
Arbitrary d-Dimensional array. Used to represent a vector.
"""

Matrix: TypeAlias = numpy.ndarray
"""
Arbitrary nxd-Dimensional array. Used to represent a matrix.
"""

FeatureVectors: TypeAlias = numpy.ndarray
"""
Float nxd-Dimensional array. Each n rows is represented as a dimensionnal feature vector.
"""

AdjacencyMatrix: TypeAlias = numpy.ndarray
"""
Boolean nxn-Dimensional array. It's the adjacency matrix representation of the graph.
"""

SimMatrix: TypeAlias = numpy.ndarray
"""
Float nxm-Dimensional array. Records the pairwise similarity scores between nodes of both graphs to diff.
"""

SparseMatrix: TypeAlias = csr_matrix
"""
Float nxm-Dimensional array. A sparse version of the above SimMatrix
"""

Graph: TypeAlias = GenericGraph
"""
A generic Graph, iterable over the nodes
"""

SparseVector: TypeAlias = csr_array
"""
Float n-Dimensional sparse array.
"""

PathLike: TypeAlias = str | Path
"""
Path
"""


[docs] class GenericPass(Protocol): """Callback function type for Passes""" def __call__( self, sim_matrix: SimMatrix, primary: Program, secondary: Program, primary_mapping: dict[Any, int], secondary_mapping: dict[Any, int], **kwargs, ) -> None: """Execute the pass that operates on the similarity matrix inplace""" raise NotImplementedError()
[docs] @enum_tools.documentation.document_enum class Distance(IntEnum): """ Enum of different (supported) distances used to compute the similarity matrix based on chosen features. """ canberra = 0 # doc: canberra distance euclidean = 1 # doc: euclidean distance cosine = 2 # doc: cosine distance jaccard_strong = 3 # doc: custom distance