Archan

基于DSM数据对您的架构强度进行分析。

Archan是一个Python模块，根据设计结构矩阵（DSM）数据分析您的项目架构强度。

Archan是一个Python模块，根据Jerome H. Saltzer和Michael D. Schroeder撰写的"计算机系统中信息保护"中描述的一些标准分析您的项目架构强度。

功能

• 可直接在命令行使用。
• 支持插件。例如，在dependenpy中查看Provider插件。您还可以查看使用Archan的Django应用django-meerkat。
• 可通过命令行或配置文件（YAML格式）配置。
• 从标准输入读取DSM数据。

安装

使用pip

pip install archan

使用pipx

python3.8 -m pip install --user pipx
pipx install archan

用法

Archan定义了三个主要类：分析器、提供者和检查器。提供者是一个对象，它将生成数据并以DSM（设计结构矩阵）的形式返回。检查器是一个对象，它将根据某些标准分析此DSM，并返回一个状态码，表示是否验证了这些标准。分析器只是提供者和检查器的组合，以运行分析测试套件。

在命令行中

示例

$ archan -h
usage: archan [-c FILE] [-h] [-i FILE] [-l] [--no-color] [--no-config] [-v]

Analysis of your architecture strength based on DSM data

optional arguments:
    -c FILE, --config FILE  Configuration file to use.
    -h, --help              Show this help message and exit.
    -i FILE, --input FILE   Input file containing CSV data.
    -l, --list-plugins      Show the available plugins. Default: false.
    --no-color              Do not use colors. Default: false.
    --no-config             Do not load configuration from file. Default: false.
    -v, --version           Show the current version of the program and exit.

# See a list of all supported Archan plugins
archan --list-plugins

# Archan can locate the configuration file automatically (See the Configuration section)
archan
# or a specific configuration can be specified
archan --config my_config.yml

# Archan can load DSM data in CSV format such as the output from dependenpy (install separately)
dependenpy pytest --format=csv --output pytest_dsm.csv

# Read CSV data from file (No configuration)
archan --no-config --input pytest_dsm.csv
# or read CSV data from STDIN
dependenpy pytest --format=csv | archan --no-config

配置

Archan应用以下方法查找配置文件文件夹

1. 读取当前目录中.configconfig文件的全部内容，以获取配置目录的路径，
2. 如果当前目录中存在config文件夹，则使用该文件夹，
3. 使用当前目录。

然后，它将搜索以下命名的配置文件

1. archan.yml
2. archan.yaml
3. .archan.yml
4. .archan.yaml

配置文件的格式如下

analyzers: [list of strings and/or dict]
  - identifier: [optional string]
      name: [string]
      description: [string]
      providers: [string or list]
        - provider.Name: [as string or dict]
            provider_arguments: as key value pairs
      checkers: [string or list]
        - checker.Name: [as string or dict]
            checker_arguments: as key value pairs

这意味着您可以写

analyzers:
  # a first analyzer with one provider and several checker
  - name: My first analyzer
      description: Optional description
      providers: just.UseThisProvider
      checkers:
        - and.ThisChecker
        - and.ThisOtherChecker:
            which: has
            some: arguments
  # a second analyzer with several providers and one checker
  - name: My second analyzer
      providers:
        - use.ThisProvider
      checkers: and.ThisChecker
  # a third analyzer, using its name directly
  - some.Analyzer

每个检查器都支持一个ignore参数，设置为True或False（默认）。如果设置为True，则检查将不会使测试套件失败。

您可以在不同的分析器中重用相同的提供者和检查器，它们将作为不同的对象实例化，并且不会相互干扰。

例如，请参阅Archan自己的配置文件。

要获取当前环境中可用的插件列表，请运行archan --list-plugins或archan -l。

编写插件

插件发现

您可以编写三种类型的插件：分析器、提供者和检查器。您的插件不需要是一个可安装的包。它只需要在您的当前Python路径中可用。然而，如果您希望它被Archan自动发现，您将必须通过pip或简单地使用python setup.py install命令或等效命令使其可安装。

如果您决定为您的插件编写Python包，我建议您将其命名为archan-your-plugin以保持一致性。如果您计划将其与现有包中的其他代码一起使用，则只需保留其原始名称。

为了使您的插件可通过Archan发现，请在您的setup.py中使用archan入口点

from setuptools import setup

setup(
    ...,
    'entry_points': {
        'archan': [
            'mypackage.MyPlugin = mypackage.mymodule:MyPlugin',
        ]
    }

如果您使用Poetry构建您的包，请使用以下内容替代

[tool.poetry.plugins.archan]
"mypackage.MyPlugin" = "mkdocstrings.plugin:MkdocstringsPlugin"

入口点的名称应按惯例由小写包名、点和Python类名组成，尽管您可以将其命名为任何您想要的名字。请记住，这个名字将是配置文件中使用的名字。

还有一件好事是使插件仅通过其名称即可导入

import mypackage.MyPlugin

但再次强调，这只是一种约定。

插件类

您可以编写三种类型的插件：分析器、提供者和检查器。对于每一种，您都必须从相应的类继承

from archan import Analyzer, Provider, Checker

class MyAnalyzer(Analyzer): ...
class MyProvider(Provider): ...
class MyChecker(Checker): ...

提供者或检查器插件必须具有以下类属性

• 标识符：插件的标识符。它必须与入口点中的名称相同，以便显示其帮助时告诉如何调用它。
• 名称：插件的详细名称。
• 描述：一个描述它做什么的描述。
• （可选）参数：Argument实例的元组/列表。此参数仅用于显示有关插件的帮助信息。一个参数由一个名称、一个类型、一个描述和一个默认值组成。

from archan import Provider, Argument

class MyProvider(Provider):
    identifier = 'mypackage.MyProvider'
    name = 'This is my Provider'
    description = """
    Don't hesitate to use multi-line strings as the lines will be de-indented,
    concatenated again and wrapped to match the console width.

    Blank lines will be kept though, so the above line will not be removed.
    """

    arguments = (
        Argument('my_arg', int, 'This argument is useful.', 42),
        # don't forget the ending comma if you have just one   ^   argument
    )

此外，检查器插件应具有hint类属性（字符串）。提示描述了检查失败时应做什么。

目前，分析器插件只需具有providers和checkers类属性。

插件方法

提供者必须实现get_dsm(self, **kwargs)方法。该方法必须返回一个DSM实例。DSM由一个二维数组（矩阵）、一个字符串列表（矩阵的行/列的键或名称）以及可选的每个键（大小相同的列表）的类别组成。

from archan import DSM, Provider

class MyProvider(Provider):
    name = 'mypackage.MyProvider'

    def get_dsm(self, my_arg=42, **kwargs):
        # this is where you compute your stuff
        matrix_data = [...]
        entities = [...]
        categories = [...] or None
        # and return a DSM instance
        return DSM(matrix_data, entities, categories)

检查器必须实现check(self, dsm, **kwargs)方法。

from archan import DSM, Checker

class MyChecker(Checker):
    name = 'mypackage.MyChecker'

    def check(self, dsm, **kwargs):
        # this is where you check your stuff
        # with dsm.data, dsm.entities, dsm.categories, dsm.size (rows, columns)
        ...
        # and return True, False, or a constant from Checker: PASSED or FAILED
        # with an optional message
        return Checker.FAILED, 'too much issues in module XXX'

日志消息

每个插件实例都有一个可用的logger属性。使用它通过self.logger.debug、info、warning、error或critical记录消息。

可用的插件

以下是其他包中可用的插件列表。

通过搜索"archan-"来查看发布到PyPi的其他插件

提供者

• dependenpy.InternalDependencies：在一个包集中提供关于内部依赖的矩阵数据。使用pip install dependenpy进行安装。