dependenpy ¤

Bases: RootNode, NodeMixin, PrintMixin

DSM-capable class.

Technically speaking, a DSM instance is not a real DSM but more a tree representing the Python packages structure. However, it has the necessary methods to build a real DSM in the form of a square matrix, a dictionary or a tree-map.

Parameters:

• *packages ¤

  (str, default: () ) –

  List of packages to search for.

• build_tree ¤

  (bool, default: True ) –

  Auto-build the tree or not.

• build_dependencies ¤

  (bool, default: True ) –

  Auto-build the dependencies or not.

• enforce_init ¤

  (bool, default: True ) –

  If True, only treat directories if they contain an __init__.py file.

Methods:

• __bool__ –

  Node as Boolean.

• __contains__ –

  Get result of _contains, cache it and return it.

• __getitem__ –

  Return the corresponding Package or Module object.

• as_dict –

  Return the dependencies as a dictionary.

• as_graph –

  Create a graph with self as node, cache it, return it.

• as_matrix –

  Create a matrix with self as node, cache it, return it.

• as_treemap –

  Return the dependencies as a TreeMap.

• build_dependencies –

  Recursively build the dependencies for sub-modules and sub-packages.

• build_tree –

  Build the Python packages tree.

• get –

  Get item through __getitem__ and cache the result.

• get_target –

  Get the result of _get_target, cache it and return it.

• print –

  Print the object in a file or on standard output by default.

• print_graph –

  Print the graph for self's nodes.

• print_matrix –

  Print the matrix for self's nodes.

• print_treemap –

  Print the matrix for self's nodes.

Attributes:

• base_packages (tuple[str, ...]) –

  Packages initially specified.

• empty (bool) –

  Whether the node has neither modules nor packages.

• enforce_init (bool) –

  Whether to enforce the presence of __init__.py files.

• finder (Finder) –

  Finder instance for locating packages and modules.

• isdsm (bool) –

  Inherited from NodeMixin. Always True.

• ismodule (bool) –

  Property to check if object is instance of Module.

• ispackage (bool) –

  Property to check if object is instance of Package.

• modules (list[Module]) –

  List of modules contained in the node.

• not_found (list[str]) –

  List of packages that were not found.

• packages (list[Package]) –

  List of packages contained in the node.

• specs (list[PackageSpec]) –

  List of package specifications found.

• submodules (list[Module]) –

  Property to return all sub-modules of the node, recursively.

 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100

def __init__(
    self,
    *packages: str,
    build_tree: bool = True,
    build_dependencies: bool = True,
    enforce_init: bool = True,
):
    """Initialization method.

    Parameters:
        *packages: List of packages to search for.
        build_tree: Auto-build the tree or not.
        build_dependencies: Auto-build the dependencies or not.
        enforce_init: If True, only treat directories if they contain an `__init__.py` file.
    """
    self.base_packages: tuple[str, ...] = packages
    """Packages initially specified."""
    self.finder: Finder = Finder()
    """Finder instance for locating packages and modules."""
    self.specs: list[PackageSpec] = []
    """List of package specifications found."""
    self.not_found: list[str] = []
    """List of packages that were not found."""
    self.enforce_init: bool = enforce_init
    """Whether to enforce the presence of `__init__.py` files."""

    specs = []
    for package in packages:
        spec = self.finder.find(package, enforce_init=enforce_init)
        if spec:
            specs.append(spec)
        else:
            self.not_found.append(package)

    if not specs:
        print("** dependenpy: DSM empty.", file=sys.stderr)  # noqa: T201

    self.specs = PackageSpec.combine(specs)

    for module in self.not_found:
        print(f"** dependenpy: Not found: {module}.", file=sys.stderr)  # noqa: T201

    super().__init__(build_tree)

    if build_tree and build_dependencies:
        self.build_dependencies()

base_packages: tuple[str, ...] = packages

empty: bool

enforce_init: bool = enforce_init

finder: Finder = Finder()

isdsm: bool

ismodule: bool

ispackage: bool

modules: list[Module] = []

not_found: list[str] = []

packages: list[Package] = []

specs: list[PackageSpec] = PackageSpec.combine(specs)

submodules: list[Module]

__bool__() -> bool

124
125
126
127
128
129
130

def __bool__(self) -> bool:
    """Node as Boolean.

    Returns:
        Result of node.empty.
    """
    return bool(self.modules or self.packages)

__contains__(item: Package | Module) -> bool

85
86
87
88
89
90
91
92
93
94
95
96

def __contains__(self, item: Package | Module) -> bool:
    """Get result of _contains, cache it and return it.

    Parameters:
        item: A package or module.

    Returns:
        True if self contains item, False otherwise.
    """
    if item not in self._contains_cache:
        self._contains_cache[item] = self._contains(item)
    return self._contains_cache[item]

__getitem__(item: str) -> Package | Module

 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

def __getitem__(self, item: str) -> Package | Module:
    """Return the corresponding Package or Module object.

    Parameters:
        item: Name of the package/module, dot-separated.

    Raises:
        KeyError: When the package or module cannot be found.

    Returns:
        The corresponding object.
    """
    depth = item.count(".") + 1
    parts = item.split(".", 1)
    for module in self.modules:
        if parts[0] == module.name and depth == 1:
            return module
    for package in self.packages:
        if parts[0] == package.name:
            if depth == 1:
                return package
            obj = package.get(parts[1])
            if obj:
                return obj
    raise KeyError(item)

as_dict() -> dict

318
319
320
321
322
323
324
325
326
327
328

def as_dict(self) -> dict:
    """Return the dependencies as a dictionary.

    Returns:
        Dictionary of dependencies.
    """
    return {
        "name": str(self),
        "modules": [module.as_dict() for module in self.modules],
        "packages": [package.as_dict() for package in self.packages],
    }

as_graph(depth: int = 0) -> Graph

330
331
332
333
334
335
336
337
338
339
340
341

def as_graph(self, depth: int = 0) -> Graph:
    """Create a graph with self as node, cache it, return it.

    Parameters:
        depth: Depth of the graph.

    Returns:
        An instance of Graph.
    """
    if depth not in self._graph_cache:
        self._graph_cache[depth] = Graph(self, depth=depth)  # ty:ignore[invalid-argument-type]
    return self._graph_cache[depth]

as_matrix(depth: int = 0) -> Matrix

343
344
345
346
347
348
349
350
351
352
353
354

def as_matrix(self, depth: int = 0) -> Matrix:
    """Create a matrix with self as node, cache it, return it.

    Parameters:
        depth: Depth of the matrix.

    Returns:
        An instance of Matrix.
    """
    if depth not in self._matrix_cache:
        self._matrix_cache[depth] = Matrix(self, depth=depth)  # ty:ignore[invalid-argument-type]
    return self._matrix_cache[depth]

as_treemap() -> TreeMap

356
357
358
359
360
361
362
363
364

def as_treemap(self) -> TreeMap:
    """Return the dependencies as a TreeMap.

    Returns:
        An instance of TreeMap.
    """
    if not self._treemap_cache:
        self._treemap_cache = TreeMap(self)
    return self._treemap_cache

build_dependencies() -> None

235
236
237
238
239
240
241
242
243
244

def build_dependencies(self) -> None:
    """Recursively build the dependencies for sub-modules and sub-packages.

    Iterate on node's modules then packages and call their
    build_dependencies methods.
    """
    for module in self.modules:
        module.build_dependencies()
    for package in self.packages:
        package.build_dependencies()

build_tree() -> None

115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

def build_tree(self) -> None:
    """Build the Python packages tree."""
    for spec in self.specs:
        if spec.ismodule:
            self.modules.append(Module(spec.name, spec.path, dsm=self))
        else:
            self.packages.append(
                Package(
                    spec.name,
                    spec.path,
                    dsm=self,
                    limit_to=spec.limit_to,
                    build_tree=True,
                    build_dependencies=False,
                    enforce_init=self.enforce_init,
                ),
            )

get(item: str) -> Package | Module

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

def get(self, item: str) -> Package | Module:
    """Get item through `__getitem__` and cache the result.

    Parameters:
        item: Name of package or module.

    Returns:
        The corresponding object.
    """
    if item not in self._item_cache:
        try:
            obj = self.__getitem__(item)
        except KeyError:
            obj = None
        self._item_cache[item] = obj
    return self._item_cache[item]

get_target(target: str) -> Package | Module

191
192
193
194
195
196
197
198
199
200
201
202

def get_target(self, target: str) -> Package | Module:
    """Get the result of _get_target, cache it and return it.

    Parameters:
        target: Target to find.

    Returns:
        Package containing target or corresponding module.
    """
    if target not in self._target_cache:
        self._target_cache[target] = self._get_target(target)
    return self._target_cache[target]

print(
    format: str | None = TEXT,
    output: IO = stdout,
    **kwargs: Any,
) -> None

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

def print(self, format: str | None = TEXT, output: IO = sys.stdout, **kwargs: Any) -> None:  # noqa: A002
    """Print the object in a file or on standard output by default.

    Parameters:
        format: Output format (csv, json or text).
        output: Descriptor to an opened file (default to standard output).
        **kwargs: Additional arguments.
    """
    if format is None:
        format = TEXT

    if format != TEXT:
        kwargs.pop("zero", "")

    if format == TEXT:
        print(self._to_text(**kwargs), file=output)
    elif format == CSV:
        print(self._to_csv(**kwargs), file=output)
    elif format == JSON:
        print(self._to_json(**kwargs), file=output)

print_graph(
    format: str | None = None,
    output: IO = stdout,
    depth: int = 0,
    **kwargs: Any,
) -> None

246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262

def print_graph(
    self,
    format: str | None = None,  # noqa: A002
    output: IO = sys.stdout,
    depth: int = 0,
    **kwargs: Any,
) -> None:
    """Print the graph for self's nodes.

    Parameters:
        format: Output format (csv, json or text).
        output: File descriptor on which to write.
        depth: Depth of the graph.
        **kwargs: Additional keyword arguments passed to `graph.print`.
    """
    graph = self.as_graph(depth=depth)
    graph.print(format=format, output=output, **kwargs)

print_matrix(
    format: str | None = None,
    output: IO = stdout,
    depth: int = 0,
    **kwargs: Any,
) -> None

264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280

def print_matrix(
    self,
    format: str | None = None,  # noqa: A002
    output: IO = sys.stdout,
    depth: int = 0,
    **kwargs: Any,
) -> None:
    """Print the matrix for self's nodes.

    Parameters:
        format: Output format (csv, json or text).
        output: File descriptor on which to write.
        depth: Depth of the matrix.
        **kwargs: Additional keyword arguments passed to `matrix.print`.
    """
    matrix = self.as_matrix(depth=depth)
    matrix.print(format=format, output=output, **kwargs)

print_treemap(
    format: str | None = None,
    output: IO = stdout,
    **kwargs: Any,
) -> None

282
283
284
285
286
287
288
289
290
291

def print_treemap(self, format: str | None = None, output: IO = sys.stdout, **kwargs: Any) -> None:  # noqa: A002
    """Print the matrix for self's nodes.

    Parameters:
        format: Output format (csv, json or text).
        output: File descriptor on which to write.
        **kwargs: Additional keyword arguments passed to `treemap.print`.
    """
    treemap = self.as_treemap()
    treemap.print(format=format, output=output, **kwargs)

Dependency class.

Represent a dependency from a module to another.

Parameters:

• source ¤

  (Module) –

  Source Module.

• lineno ¤

  (int) –

  Number of line at which import statement occurs.

• target ¤

  (str | Module | Package) –

  The target node.

• what ¤

  (str | None, default: None ) –

  What is imported (optional).

Attributes:

• external (bool) –

  Property to tell if the dependency's target is a valid node.

• lineno –

  Line number of the import statement.

• source –

  Source module.

• target –

  Target module or package.

• what –

  What is imported (optional).

441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457

def __init__(self, source: Module, lineno: int, target: str | Module | Package, what: str | None = None) -> None:
    """Initialization method.

    Parameters:
        source: Source Module.
        lineno: Number of line at which import statement occurs.
        target: The target node.
        what: What is imported (optional).
    """
    self.source = source
    """Source module."""
    self.lineno = lineno
    """Line number of the import statement."""
    self.target = target
    """Target module or package."""
    self.what = what
    """What is imported (optional)."""

external: bool

lineno = lineno

source = source

target = target

what = what

Edge class. Used in Graph class.

Parameters:

• vertex_out ¤

  (Vertex) –

  source vertex (edge going out).

• vertex_in ¤

  (Vertex) –

  target vertex (edge going in).

• weight ¤

  (int, default: 1 ) –

  weight of the edge.

Methods:

• go_from –

  Tell the edge to go out from this vertex.

• go_in –

  Tell the edge to go into this vertex.

Attributes:

• vertex_in (Vertex | None) –

  Incoming vertex.

• vertex_out (Vertex | None) –

  Outgoing vertex.

• weight –

  Weight of the edge.

271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286

def __init__(self, vertex_out: Vertex, vertex_in: Vertex, weight: int = 1) -> None:
    """Initialization method.

    Parameters:
        vertex_out (Vertex): source vertex (edge going out).
        vertex_in (Vertex): target vertex (edge going in).
        weight (int): weight of the edge.
    """
    self.vertex_out: Vertex | None = None
    """Outgoing vertex."""
    self.vertex_in: Vertex | None = None
    """Incoming vertex."""
    self.weight = weight
    """Weight of the edge."""
    self.go_from(vertex_out)
    self.go_in(vertex_in)

vertex_in: Vertex | None = None

vertex_out: Vertex | None = None

weight = weight

go_from(vertex: Vertex) -> None

291
292
293
294
295
296
297
298
299
300

def go_from(self, vertex: Vertex) -> None:
    """Tell the edge to go out from this vertex.

    Parameters:
        vertex (Vertex): vertex to go from.
    """
    if self.vertex_out:
        self.vertex_out.edges_out.remove(self)
    self.vertex_out = vertex
    vertex.edges_out.add(self)

go_in(vertex: Vertex) -> None

302
303
304
305
306
307
308
309
310
311

def go_in(self, vertex: Vertex) -> None:
    """Tell the edge to go into this vertex.

    Parameters:
        vertex (Vertex): vertex to go into.
    """
    if self.vertex_in:
        self.vertex_in.edges_in.remove(self)
    self.vertex_in = vertex
    vertex.edges_in.add(self)

Main package finder class.

Initialize it with a list of package finder classes (not instances).

Parameters:

• finders ¤

  (list[type] | None, default: None ) –

  list of package finder classes (not instances) in a specific order. Default: [LocalPackageFinder, InstalledPackageFinder].

Methods:

• find –

  Find a package using package finders.

Attributes:

• finders (list[PackageFinder]) –

  Selected finders.

171
172
173
174
175
176
177
178
179
180
181
182
183
184

def __init__(self, finders: list[type] | None = None):
    """Initialization method.

    Parameters:
        finders: list of package finder classes (not instances) in a specific
            order. Default: [LocalPackageFinder, InstalledPackageFinder].
    """
    self.finders: list[PackageFinder]
    """Selected finders."""
    if finders is None:
        finder_instances = [LocalPackageFinder(), InstalledPackageFinder()]
    else:
        finder_instances = [finder() for finder in finders]
    self.finders = finder_instances  # ty:ignore[invalid-assignment]

finders: list[PackageFinder] = finder_instances

find(package: str, **kwargs: Any) -> PackageSpec | None

186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202

def find(self, package: str, **kwargs: Any) -> PackageSpec | None:
    """Find a package using package finders.

    Return the first package found.

    Parameters:
        package: package to find.
        **kwargs: additional keyword arguments used by finders.

    Returns:
        Package spec or None.
    """
    for finder in self.finders:
        package_spec = finder.find(package, **kwargs)
        if package_spec:
            return package_spec
    return None

Bases: PrintMixin

Graph class.

A class to build a graph given a list of nodes. After instantiation, it has two attributes: vertices, the set of nodes, and edges, the set of edges.

An intermediary matrix is built to ease the creation of the graph.

Parameters:

• *nodes ¤

  (list of DSM/Package/Module, default: () ) –

  the nodes on which to build the graph.

• depth ¤

  (int, default: 0 ) –

  the depth of the intermediary matrix. See the documentation for Matrix class.

Methods:

• print –

  Print the object in a file or on standard output by default.

Attributes:

• edges –

  Set of edges in the graph.

• vertices –

  Set of vertices in the graph.

322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344

def __init__(self, *nodes: DSM | Package | Module, depth: int = 0) -> None:
    """Initialization method.

    An intermediary matrix is built to ease the creation of the graph.

    Parameters:
        *nodes (list of DSM/Package/Module):
            the nodes on which to build the graph.
        depth (int): the depth of the intermediary matrix. See
            the documentation for Matrix class.
    """
    self.edges = set()
    """Set of edges in the graph."""
    vertices = []
    matrix = Matrix(*nodes, depth=depth)
    for key in matrix.keys:
        vertices.append(Vertex(key))  # noqa: PERF401
    for line_index, line in enumerate(matrix.data):
        for col_index, cell in enumerate(line):
            if cell > 0:
                self.edges.add(Edge(vertices[line_index], vertices[col_index], weight=cell))
    self.vertices = set(vertices)
    """Set of vertices in the graph."""

edges = set()

vertices = set(vertices)

print(
    format: str | None = TEXT,
    output: IO = stdout,
    **kwargs: Any,
) -> None

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

def print(self, format: str | None = TEXT, output: IO = sys.stdout, **kwargs: Any) -> None:  # noqa: A002
    """Print the object in a file or on standard output by default.

    Parameters:
        format: Output format (csv, json or text).
        output: Descriptor to an opened file (default to standard output).
        **kwargs: Additional arguments.
    """
    if format is None:
        format = TEXT

    if format != TEXT:
        kwargs.pop("zero", "")

    if format == TEXT:
        print(self._to_text(**kwargs), file=output)
    elif format == CSV:
        print(self._to_csv(**kwargs), file=output)
    elif format == JSON:
        print(self._to_json(**kwargs), file=output)

Bases: PackageFinder

Finder to find installed Python packages using importlib.

Methods:

• find –

  Find method.

find(package: str, **kwargs: Any) -> PackageSpec | None

135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

def find(self, package: str, **kwargs: Any) -> PackageSpec | None:  # noqa: ARG002
    """Find method.

    Parameters:
        package: package to find.
        **kwargs: additional keyword arguments.

    Returns:
        Package spec or None.
    """
    spec = find_spec(package)
    if spec is None:
        return None
    if "." in package:
        package, rest = package.split(".", 1)
        limit = [rest]
        spec = find_spec(package)
    else:
        limit = []
    if spec is not None:
        if spec.submodule_search_locations:
            path = spec.submodule_search_locations[0]
        elif spec.origin and spec.origin != "built-in":
            path = spec.origin
        else:
            return None
        return PackageSpec(spec.name, path, limit)
    return None

Bases: Provider

Dependenpy provider for Archan.

Methods:

• get_data –

  Provide matrix data for internal dependencies in a set of packages.

Attributes:

• argument_list –

  List of arguments for the provider.

• description –

  Description of the provider.

• identifier –

  Identifier of the provider.

• name –

  Name of the provider.

argument_list = (
    archan.Argument(
        "packages",
        list,
        "The list of packages to check for.",
    ),
    archan.Argument(
        "enforce_init",
        bool,
        default=True,
        description="Whether to assert presence of __init__.py files in directories.",
    ),
    archan.Argument(
        "depth", int, "The depth of the matrix to generate."
    ),
)

description = "Provide matrix data about internal dependencies in a set of packages."

identifier = 'dependenpy.InternalDependencies'

name = 'Internal Dependencies'

get_data(
    packages: list[str],
    enforce_init: bool = True,
    depth: int | None = None,
) -> DSM

54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

def get_data(
    self,
    packages: list[str],
    enforce_init: bool = True,  # noqa: FBT001,FBT002
    depth: int | None = None,
) -> archan.DSM:
    """Provide matrix data for internal dependencies in a set of packages.

    Parameters:
        packages: The list of packages to check for.
        enforce_init: Whether to assert presence of __init__.py files in directories.
        depth: The depth of the matrix to generate.

    Returns:
        Instance of archan DSM.
    """
    dsm = DependenpyDSM(*packages, enforce_init=enforce_init)
    if depth is None:
        depth = guess_depth(packages)
    matrix = dsm.as_matrix(depth=depth)
    return archan.DesignStructureMatrix(data=matrix.data, entities=matrix.keys)

Shared code between Package and Module.

Methods:

• absolute_name –

  Return the absolute name of the node.

Attributes:

• depth (int) –

  Property to tell the depth of the node in the tree.

• root (Package) –

  Property to return the root of this node.

370
371
372

def __init__(self):
    """Initialization method."""
    self._depth_cache = None

depth: int

root: Package

absolute_name(depth: int = 0) -> str

406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428

def absolute_name(self, depth: int = 0) -> str:
    """Return the absolute name of the node.

    Concatenate names from root to self within depth.

    Parameters:
        depth: Maximum depth to go to.

    Returns:
        Absolute name of the node (until given depth is reached).
    """
    node: Package
    node, node_depth = self, self.depth  # ty:ignore[invalid-assignment]
    if depth < 1:
        depth = node_depth
    while node_depth > depth and node.package is not None:
        node = node.package
        node_depth -= 1
    names = []
    while node is not None:
        names.append(node.name)
        node = node.package  # ty:ignore[invalid-assignment]
    return ".".join(reversed(names))

Bases: PackageFinder

Finder to find local packages (directories on the disk).

Methods:

• find –

  Find method.

find(package: str, **kwargs: Any) -> PackageSpec | None

108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

def find(self, package: str, **kwargs: Any) -> PackageSpec | None:
    """Find method.

    Parameters:
        package: Package to find.
        **kwargs: Additional keyword arguments.

    Returns:
        Package spec or None.
    """
    if not exists(package):  # noqa: PTH110
        return None
    name, path = None, None
    enforce_init = kwargs.pop("enforce_init", True)
    if isdir(package):  # noqa: PTH112
        if isfile(join(package, "__init__.py")) or not enforce_init:  # noqa: PTH113, PTH118
            name, path = basename(package), package  # noqa: PTH119
    elif isfile(package) and package.endswith(".py"):  # noqa: PTH113
        name, path = splitext(basename(package))[0], package  # noqa: PTH119, PTH122
    if name and path:
        return PackageSpec(name, path)
    return None

Bases: PrintMixin

Matrix class.

A class to build a matrix given a list of nodes. After instantiation, it has two attributes: data, a 2-dimensions array, and keys, the names of the entities in the corresponding order.

Parameters:

• *nodes ¤

  (DSM | Package | Module, default: () ) –

  The nodes on which to build the matrix.

• depth ¤

  (int, default: 0 ) –

  The depth of the matrix. This depth is always absolute, meaning that building a matrix with a sub-package "A.B.C" and a depth of 1 will return a matrix of size 1, containing A only. To see the matrix for the sub-modules and sub-packages in C, you will have to give depth=4.

Methods:

• cast –

  Cast a set of keys and an array to a Matrix object.

• print –

  Print the object in a file or on standard output by default.

Attributes:

• data –

  The data of the matrix.

• keys –

  The keys of the matrix.

• size –

  The size of the matrix.

• total (int) –

  Return the total number of dependencies within this matrix.

 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100

def __init__(self, *nodes: DSM | Package | Module, depth: int = 0):
    """Initialization method.

    Parameters:
        *nodes: The nodes on which to build the matrix.
        depth: The depth of the matrix. This depth is always
            absolute, meaning that building a matrix with a sub-package
            "A.B.C" and a depth of 1 will return a matrix of size 1,
            containing A only. To see the matrix for the sub-modules and
            sub-packages in C, you will have to give depth=4.
    """
    modules: list[Module] = []
    for node in nodes:
        if node.ismodule:
            modules.append(node)  # ty:ignore[invalid-argument-type]
        elif node.ispackage or node.isdsm:
            modules.extend(node.submodules)  # ty:ignore[unresolved-attribute]

    if depth < 1:
        keys = modules
    else:
        keys = []
        for module in modules:
            if module.depth <= depth:
                keys.append(module)
                continue
            package = module.package
            while package.depth > depth and package.package and package not in nodes:  # ty:ignore[unresolved-attribute]
                package = package.package  # ty:ignore[unresolved-attribute]
            if package not in keys:
                keys.append(package)

    size = len(keys)
    data = [[0] * size for _ in range(size)]
    keys = sorted(keys, key=lambda key: key.absolute_name())  # ty:ignore[unresolved-attribute]

    if depth < 1:
        for index, key in enumerate(keys):
            key.index = index  # ty:ignore[invalid-assignment]
        for index, key in enumerate(keys):
            for dep in key.dependencies:  # ty:ignore[unresolved-attribute]
                if dep.external:
                    continue
                if dep.target.ismodule and dep.target in keys:  # ty:ignore[unresolved-attribute]
                    data[index][dep.target.index] += 1  # ty:ignore[unresolved-attribute]
                elif dep.target.ispackage:  # ty:ignore[unresolved-attribute]
                    init = dep.target.get("__init__")  # ty:ignore[unresolved-attribute]
                    if init is not None and init in keys:
                        data[index][init.index] += 1  # ty:ignore[unresolved-attribute]
    else:
        for row, row_key in enumerate(keys):
            for col, col_key in enumerate(keys):
                data[row][col] = row_key.cardinal(to=col_key)  # ty:ignore[invalid-argument-type,unresolved-attribute]

    self.size = size
    """The size of the matrix."""
    self.keys = [key.absolute_name() for key in keys]  # ty:ignore[unresolved-attribute]
    """The keys of the matrix."""
    self.data = data
    """The data of the matrix."""

data = data

keys = [key.absolute_name() for key in keys]

size = size

total: int

cast(keys: list[str], data: list[list[int]]) -> Matrix

102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

@staticmethod
def cast(keys: list[str], data: list[list[int]]) -> Matrix:
    """Cast a set of keys and an array to a Matrix object.

    Arguments:
        keys: The matrix keys.
        data: The matrix data.

    Returns:
        A new matrix.
    """
    matrix = Matrix()
    matrix.keys = copy.deepcopy(keys)
    matrix.data = copy.deepcopy(data)
    return matrix

print(
    format: str | None = TEXT,
    output: IO = stdout,
    **kwargs: Any,
) -> None

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

def print(self, format: str | None = TEXT, output: IO = sys.stdout, **kwargs: Any) -> None:  # noqa: A002
    """Print the object in a file or on standard output by default.

    Parameters:
        format: Output format (csv, json or text).
        output: Descriptor to an opened file (default to standard output).
        **kwargs: Additional arguments.
    """
    if format is None:
        format = TEXT

    if format != TEXT:
        kwargs.pop("zero", "")

    if format == TEXT:
        print(self._to_text(**kwargs), file=output)
    elif format == CSV:
        print(self._to_csv(**kwargs), file=output)
    elif format == JSON:
        print(self._to_json(**kwargs), file=output)

Bases: LeafNode, NodeMixin, PrintMixin

Module class.

This class represents a Python module (a Python file).

Parameters:

• name ¤

  (str) –

  Name of the module.

• path ¤

  (str) –

  Path to the module.

• dsm ¤

  (DSM | None, default: None ) –

  Parent DSM.

• package ¤

  (Package | None, default: None ) –

  Parent Package.

Methods:

• __contains__ –

  Whether given item is contained inside this module.

• absolute_name –

  Return the absolute name of the node.

• as_dict –

  Return the dependencies as a dictionary.

• build_dependencies –

  Build the dependencies for this module.

• cardinal –

  Return the number of dependencies of this module to the given node.

• get_imports –

  Return all the import statements given an AST body (AST nodes).

• parse_code –

  Read the source code and return all the import statements.

• print –

  Print the object in a file or on standard output by default.

Attributes:

• RECURSIVE_NODES –

  Nodes that can be recursive.

• dependencies (list[Dependency]) –

  List of dependencies.

• depth (int) –

  Property to tell the depth of the node in the tree.

• dsm –

  Parent DSM.

• isdsm (bool) –

  Property to check if object is instance of DSM.

• ismodule (bool) –

  Inherited from NodeMixin. Always True.

• ispackage (bool) –

  Property to check if object is instance of Package.

• name –

  Name of the module.

• package –

  Package to which the module belongs.

• path –

  Path to the module.

• root (Package) –

  Property to return the root of this node.

271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290

def __init__(self, name: str, path: str, dsm: DSM | None = None, package: Package | None = None) -> None:
    """Initialization method.

    Parameters:
        name: Name of the module.
        path: Path to the module.
        dsm: Parent DSM.
        package: Parent Package.
    """
    super().__init__()
    self.name = name
    """Name of the module."""
    self.path = path
    """Path to the module."""
    self.package = package
    """Package to which the module belongs."""
    self.dsm = dsm
    """Parent DSM."""
    self.dependencies: list[Dependency] = []
    """List of dependencies."""

RECURSIVE_NODES = (
    ast.ClassDef,
    ast.FunctionDef,
    ast.If,
    ast.IfExp,
    ast.Try,
    ast.With,
    ast.ExceptHandler,
)

dependencies: list[Dependency] = []