Pytestarch

https://github.com/zyskarch/pytestarch
Admin
Test framework for software architecture based on imports between modules.
Tokens:4,734
Snippets:35
Trust Score:4.8
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Dependencies with Poetry

Source: https://github.com/zyskarch/pytestarch/blob/main/DEVELOPMENT.md

Installs project dependencies and creates a virtual environment using Poetry. Ensure Poetry is installed before running this command.

```bash
poetry install
```

--------------------------------

### Install Git Hooks with Pre-commit

Source: https://github.com/zyskarch/pytestarch/blob/main/DEVELOPMENT.md

Installs Git hooks managed by pre-commit, which includes tools like ruff and mypy for code linting and type checking. This ensures code quality before committing.

```bash
pre-commit install
```

--------------------------------

### Pytest Arch: Layer Import Rule Examples

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Provides examples of various layer import rules and their interpretations. These rules define how modules within different layers can import or be imported by modules in other layers, including exceptions.

```plaintext
Layer 1 should import Layer 2                       - 1+ module from Layer 1 imports 1+ module from Layer 2
Layer 1 should not import Layer 2                   - no module from Layer 1 imports any module from Layer 2
Layer 1 should only import Layer 2                  - 1+ module from Layer 1 imports 1+ module from Layer 2; no module from Layer 1 imports something, that is not in Layer 2

Layer 1 should import except Layer 2                - 1+ module from Layer 1 imports something, that is not in Layer 2
Layer 1 should not import except Layer 2            - no module from Layer 1 imports something, that is not in Layer 2
Layer 1 should only import except Layer 2           - 1+ module from Layer 1 imports something, that is not in Layer 2; no module from Layer 1 imports any module from Layer 2

Layer 1 should be imported by Layer 2               - 1+ module from Layer 2 imports 1+ module from Layer 1
Layer 1 should not be imported by Layer 2           - no module from Layer 1 imports any module from Layer 1
Layer 1 should only be imported by Layer 2          - 1+ module from Layer 2 imports 1+ module from Layer 1; no module imports something from Layer 1, that is not in Layer 2

Layer 1 should be imported except by Layer 2        - 1+ module imports something from Layer 1, that is not Layer 2
Layer 1 should not be imported except by Layer 2    - no module imports something from Layer 1, that is not Layer 2
Layer 1 should only be imported except by Layer 2   - 1+ module imports something from Layer 1, that is not Layer 2; no module from Layer 2 imports any module from Layer 1
```

--------------------------------

### PyTestArch Query Language Examples

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Illustrates various query patterns in PyTestArch, demonstrating how to express different types of module import relationships. These examples cover allowed imports, restricted imports, and exclusive imports, including the use of the 'except' keyword for more nuanced rules.

```plaintext
M1 should import_from M2
M1 should import_from except M2  # any import from M1 that isn't M2 (but M2 might be imported as well)
M1 should only import_from M2
M1 should only import_from except M2  # M2 cannot be imported by M1, min. 1 import needed
M1 should not import_from M2
M1 should not import_from except M2  # M1 does not have to import M2

M1 should be_imported_from M2
M1 should be_imported_from except M2  # any import of M1 that is not M2 (but M2 might import as well)
M1 should only be_imported_from M2
M1 should only be_imported_from except M2  # M2 cannot import M1, but min other module is importing M1
M1 should not be_imported_from M2
M1 should not be_imported_from except M2  # M1 does not have to be imported
```

--------------------------------

### Run Test Suite with Nox

Source: https://github.com/zyskarch/pytestarch/blob/main/DEVELOPMENT.md

Executes the project's test suite using Nox. This command is used to ensure all tests pass locally before submitting a Pull Request or relying on CI checks.

```bash
nox
```

--------------------------------

### Get Evaluable Architecture Representation

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/index.md

Creates an evaluable representation of Python source code for architectural rule checks. It scans files for imports and builds an internal representation. Requires the project root and source directory paths as input.

```python
from pytestarch import get_evaluable_architecture

evaluable = get_evaluable_architecture("/home/dummy/project", "/home/dummy/project/src")
```

--------------------------------

### Module Dependency Rule Example in Python

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/layer_architecture_checks.md

An example of a module dependency rule that attempts to specify layer-like behavior. This syntax is shown to be insufficient for layer-wide rules, as it requires specific modules (M and N) to import a specific module (O), rather than layer-level access.

```python
Rule()
    .modules_that()
    .are_named(["M", "N"])
    .should()
    .import_modules_that()
    .are_named("O")
```

--------------------------------

### PyTestArch: Batch Rule Definition with Multiple Modules

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/module_import_checks.md

This Python example illustrates how to apply architectural rules to multiple modules simultaneously. It shows a rule where modules '1' and '2' should only be imported by modules '3' and '4'. PyTestArch interprets this as independent rules for each module combination.

```python
modules_that() \
    .are_named(["1", "2"]) \
    .should_only() \
    .be_imported_by_modules_that() \
    .are_named(["3", "4"])
```

--------------------------------

### Define Architectural Rule (Python)

Source: https://github.com/zyskarch/pytestarch/blob/main/README.md

Defines an architectural rule for code analysis. This example specifies that a module should not be imported by submodules of another module. Dependencies: pytestarch. Inputs: Module names. Outputs: A Rule object.

```python
from pytestarch import Rule

rule = (
    Rule() 
    .modules_that() 
    .are_named("project.src.moduleB") 
    .should_not() 
    .be_imported_by_modules_that() 
    .are_sub_modules_of("project.src.moduleA") 
)
```

--------------------------------

### Example Usage of are_sub_modules_of Rule

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/module_import_checks.md

This example demonstrates how to use the `are_sub_modules_of` rule to enforce that modules within a specific package ('A') should only be imported by modules within another specific package ('B'). It also shows a failing case where a module named 'C' is imported by 'A2' but also by 'A'.

```python
from pytestarch import rule

rule.modules_that().are_sub_modules_of("A") \
    .should_only() \
    .be_imported_by_modules_that() \
    .are_sub_modules_of("B")

rule.modules_that().are_named("C") \
    .should_only() \
    .be_imported_by_modules_that() \
    .are_named("A2")
```

--------------------------------

### Get Evaluable Architecture with Exclusions - Python

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/general.md

This function retrieves an evaluable architecture representation from a specified module path. It supports regular expression-based exclusion patterns for files and directories, allowing users to fine-tune the analysis scope. Dependencies on external libraries can also be optionally excluded.

```python
from pytestarch import get_evaluable_architecture

# Example excluding files ending with '_test.py'
evaluable = get_evaluable_architecture("/home/my_project", "/home/my_project/src", regex_exclusions=(".*_test\.py"))

# Example excluding external libraries
evaluable_no_external = get_evaluable_architecture("/home/my_project", "/home/my_project/src", exclude_external_libraries=True)
```

--------------------------------

### Define Rule: Modules named 'B' should not be imported by modules except submodules of 'A'

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/module_import_checks.md

This example demonstrates a complex architectural rule. It specifies that modules named 'B' should not be imported by any other modules, with an exception for modules that are submodules of 'A'. This rule is expressed using PyTestArch's query language.

```python
RULE_SUBJECT: modules that are named 'B' 
IMPORT_TYPE: should not be imported by 
RULE_OBJECT: modules that are submodules of 'A'
```

--------------------------------

### Deploy Documentation using Mike

Source: https://github.com/zyskarch/pytestarch/blob/main/RELEASE.md

This command deploys a new version of the project's documentation and updates the aliases, typically pushing the changes to GitHub Pages. It requires the version number to be inserted. The `--push` flag ensures the changes are uploaded, and `--update-aliases` sets the new version as the `latest`.

```bash
mike deploy --push --update-aliases <insert new version> latest
```

--------------------------------

### Import Rule Explanations with 'except' Verb Marker

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/module_import_checks.md

This section provides pseudo-code explanations for various import rules when using the 'except' verb marker. These rules cover scenarios like 'should import except', 'should only import except', 'should not import except', and their 'be_imported_by' counterparts, clarifying the exact import dependencies and restrictions.

```pseudocode
| Rule                                 | Explanation                                                                                                     |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| M1 should import except M2           | M1 should import at least one module that isn't M2, but can also import M2                                     |
| M1 should only import except M2      | M1 should import at least one module that isn't M2 and should not import M2                                     |
| M1 should not import except M2       | M1 should not import any module other than M2, but does not have to import M2                                   |
| M1 should be imported except by M2   | at least one module that isn't M2 should import M1 (M2 can import M1 as well)                                   |
| M1 should only be imported except by M2 | at least one module that isn't M2 should import M1, and M2 cannot import M1                                     |
| M1 should not be imported except by M2| no module other than M2 should import M1, but M2 does not have to import M1                                     |
```

--------------------------------

### Create and Push Git Tag for Release

Source: https://github.com/zyskarch/pytestarch/blob/main/RELEASE.md

These commands are used to create a Git tag for the new release version and push it to the origin repository. This action is performed after the release branch has been approved and merged into the main branch.

```bash
git tag v<insert new version>
git push origin v<insert new version>
```

--------------------------------

### Define Layered Architecture in Pytest Arch

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Demonstrates the basic syntax for defining a layered architecture using `LayeredArchitecture`. This involves naming layers and specifying the modules they contain. This is a foundational step for applying architectural rules.

```python
LayeredArchitecture().layer("name").containing_modules([M1, M2]).layer(...)...
```

--------------------------------

### Pytest Arch Layer Rule Definition Syntax

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Illustrates the comprehensive syntax for defining layer rules using `LayerRule`. This includes specifying layers by name or group, defining allowed/disallowed access patterns (import, accessed by), and applying these rules to an architecture.

```python
LayerRule()
    .layers_that()
    .are_named("name"/["X", "Y"])
    .should/not/only()
    .access_layers_that()/be_accessed_by_layers_that()/access_any_layer_except_layers_that()/be_accessed_by_any_layer_except_layers_that()/access_anything()/be_accessed_by_anything()
    .are_named("X"/["X", "Y"])
    .assert_applies(evaluable, architecture)
```

--------------------------------

### PyTestArch Operation Markers

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Provides a mapping between PyTestArch keywords and the underlying operations they represent in terms of dependency graph analysis. This includes 'any edge', 'edge', 'neg edge', and 'neg any', simplifying the understanding of complex rules.

```plaintext
Operations:
    any edge
    edge
    neg edge
    neg any

Operation Markers:
    any         should import except, should only import except             | should be except, should only be except
    edge        should import, should only import                           | should be, should only be
    neg edge    should not import, should only import except                | should not be, should only be except
    neg any     should not import except, should only import                | should only be, should not be except

simplified:
    any         should except, should only except
    edge        should, should only
    neg edge    should not, should only except
    neg any     should not except, should only
```

--------------------------------

### PyTestArch: Module Name Matching Regex

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/module_import_checks.md

This Python snippet shows how to use the `have_name_matching` feature in PyTestArch to define rules based on module name regular expressions. It includes a warning about potential performance implications when using broad regex patterns and suggests alternatives for complex negation scenarios.

```python
Rule().modules_that().have_name_matching(r"^((?!test$).)*$").should_not().import_modules_that().have_name_matching(r".*test$")
```

```python
Rule().modules_that().have_name_matching(".*test$").should_not().be_imported_by_modules_that().have_name_matching(".*test$")
```

--------------------------------

### PyTestArch Alias Rules

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Describes special aliases in PyTestArch for common rules, such as 'should not import anything' and 'should not be imported by anything'. These aliases simplify common patterns and ensure clarity by implicitly including 'except itself'.

```plaintext
Aliases:
M1 should not import anything -> M1 should not import anything except itself
M1 should not be imported by anything -> M1 should not be imported by anything except itself
```

--------------------------------

### Visualize Architecture with Aliases (Python)

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/visualization.md

Plots the dependency graph of an architecture using `evaluable_architecture.visualize()`. Requires matplotlib. Allows specifying aliases for module names to shorten labels on the plot, improving readability, especially for modules with long names or many submodules. Aliases can be nested, with submodule aliases taking precedence.

```python
from pytestarch.example.architecture import EvaluableArchitecture

# Assuming evaluable_architecture is an instance of EvaluableArchitecture

# Example 1: Simple alias
evaluable_architecture.visualize(aliases={'long_root_name': 'r'})

# Example 2: Nested aliases
evaluable_architecture.visualize(aliases={'long_root_name': 'r', 'long_root_name.submodule': 'sub'})
```

--------------------------------

### PyTestArch 'Anything' Semantics

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Explains the semantic meaning of queries using 'anything' with 'not import' or 'not be_imported_by'. This clarifies how these broad rules are interpreted in terms of module dependencies, specifying the negation of any incoming or outgoing edges.

```plaintext
M1 should not import anything               -> neg(any edge from M1 to ?)
M1 should not be_imported by anything       -> neg(any edge from ? to M1)
```

--------------------------------

### PyTestArch 'anything' Keyword Limitations

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Details the valid and invalid combinations when using the 'anything' keyword for subjects or objects in PyTestArch queries. This helps users understand the constraints and capabilities of the query language, particularly when dealing with broad import rules.

```plaintext
not all combinations are possible with anything:
M1 should import anything                       x
M1 should import except anything                x
M1 should only import anything                  x
M1 should only import except anything           x
M1 should not import anything                   o
M1 should not import except anything            x
M1 should be_imported by anything               x
M1 should be_imported by except anything        x
M1 should only be_imported by anything          x
M1 should only be_imported except by anything   x
M1 should not be_imported by anything           o
M1 should not be_imported except by anything    x
```

--------------------------------

### PyTestArch Query Language Structure

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Defines the grammatical structure of queries in PyTestArch. It follows a pattern of SUBJECT VERB_MARKER_1 IMPORT_TYPE VERB_MARKER_2 OBJECT, with specific keywords for each component. This structure allows for expressive and precise definition of architectural dependencies.

```plaintext
SUBJECT VERB_MARKER_1 IMPORT_TYPE VERB_MARKER_2 OBJECT

VERB_MARKER_1:
    should
    should only
    should not

VERB_MARKER_2:
    except

IMPORT_TYPE:
    import_from
    be_imported_from

SUBJECT/OBJECT:
    sub_module_of
    name  # complete match
    partial_name  # partial match
    anything (only object)
```

--------------------------------

### PyTestArch Query Semantics: Import Rules

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Explains the semantic meaning of different PyTestArch import queries. It defines how each query translates into a directed edge in a dependency graph, covering operations like direct imports, negated imports, and imports excluding specific modules.

```plaintext
M1 should import M2                 -> edge from M1 to M2
M1 should only import M2            -> -"-, neg(any edge from M1 to non-M2)
M1 should not import M2             -> neg(edge from M1 to M2)
M1 should import except M2          -> any edge from M1 to non-M2
M1 should only import except M2     -> any edge from M1 to non-M2, neg(edge from M1 to M2)
M1 should not import except M2      -> neg(any edge from M1 to non-M2)
```

--------------------------------

### Pytest Arch: Rule Violation Message Format

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Describes the format of rule violation messages generated by Pytest Arch. It clarifies how modules and their associated layers are identified in these messages, aiding in debugging architectural issues.

```plaintext
All concrete modules are listed with "(LAYER X)" behind their name, such as "Violator1 (LAYER X) imports Violator2 (LAYER Y)".
```

--------------------------------

### Aliases for Import Restrictions

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/module_import_checks.md

This provides two convenient aliases for common import restriction rules. 'M1 should not import anything' is an alias for 'M1 should not import anything except itself', allowing internal imports within submodules but disallowing external ones. Similarly, 'M1 should not be imported by anything' is an alias for 'M1 should not be imported by anything except itself'.

```pseudocode
'M1 should not import anything' is equivalent to: 'M1 should not import anything except itself' (e.g. imports between its submodules are allowed, but no other imports)
'M1 should not be imported by anything' is equivalent to: 'M1 should not be imported by anything except itself' (dito)
```

--------------------------------

### PyTestArch Query Semantics: Be Imported From Rules

Source: https://github.com/zyskarch/pytestarch/blob/main/src/pytestarch/query_language/LANGUAGE_DEFINTION.md

Details the semantic interpretation of 'be_imported_from' rules in PyTestArch. This section clarifies how queries specifying that a module is imported by others are translated into dependency graph edges, including direct, negated, and exclusive import relationships.

```plaintext
M1 should be_imported_from M2               -> edge from M2 to M1
M1 should only be_imported_from M2          -> -"-, neg(any edge from non-M2 to M1)
M1 should not be_imported_from M2           -> neg(edge from M2 to M1)
M1 should be_imported_from except M2        -> any edge from non-M2 to M1
M1 should only be_imported_from except M2   -> any edge from non-M2 to M1, neg(edge from M2 to M1)
M1 should not be_imported_from except M2    -> neg(any edge from non-M2 to M1)
```

--------------------------------

### Bump Package Version

Source: https://github.com/zyskarch/pytestarch/blob/main/RELEASE.md

This command is used to update the package version according to semantic versioning principles. It requires specifying the version increment type (patch, minor, or major) based on the changes introduced in the release. This is a prerequisite for creating a new release.

```bash
poetry version patch
# or
poetry version minor
# or
poetry version major
```

--------------------------------

### Assert Architectural Rule Application

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/index.md

Evaluates the defined architectural rule against the evaluable representation of the code. If the rule is violated, an assertion error is raised. This is typically used within a testing framework like pytest.

```python
rule.assert_applies(evaluable)
```

--------------------------------

### Create Layer Rule in Python

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/layer_architecture_checks.md

Defines a rule based on a previously defined layered architecture. This rule specifies that a layer named 'import' should only access layers named 'model'. It uses 'access' instead of 'import' and requires the layered architecture object to be passed first.

```python
rule = (
    LayerRule()
    .based_on(arch).   # needs to be passed in first
    .layers_that()
    .are_named("import")
    .should_only()
    .access_layers_that()
    .are_named("model")
)
```

--------------------------------

### Define Architectural Rule - Should Not Be Imported By

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/index.md

Defines an architectural rule where a specified module should not be imported by any module that is a submodule of another specified module. This is useful for enforcing hierarchical dependencies.

```python
from pytestarch import Rule

rule = (
    Rule()
    .modules_that() 
    .are_named("project.src.moduleB") 
    .should_not() 
    .be_imported_by_modules_that() 
    .are_sub_modules_of("project.src.moduleA")
)
```

--------------------------------

### Define Layered Architecture in Python

Source: https://github.com/zyskarch/pytestarch/blob/main/docs/features/layer_architecture_checks.md

Defines a layered architecture by grouping modules into named layers. Modules can be specified directly or using regular expressions. PyTestArch assumes submodules belong to the same layer as their parent.

```python
arch = (
    LayeredArchitecture()
    .layer("import")
    .containing_modules(["M", "N"])
    .layer("model")
    .containing_modules("O")
)
```
Tokens:
Raw