Validate Feature-Sliced Design (FSD) architecture in a Python project using pytest. The rules are adapted from the Steiger FSD plugin, with Python-specific checks where appropriate. This is an independent Python package, not an official Steiger port.
The applicable upstream changes are tracked through Steiger 0.7.0 / FSD plugin 0.8.0. See the changelog for Python adaptations.
pip install pytest-fsd
# or
uv add --dev pytest-fsdPython 3.8–3.14 is supported.
Add the layers used by your project, from highest to lowest, to pyproject.toml:
[tool.pytest_fsd]
base_path = "src"
layers = ["app", "pages", "widgets", "features", "entities", "shared"]
# ignore_paths = ["my_non_fsd_package"]Create an architecture test:
# tests/test_architecture.py
from pytest_fsd import validate_fsd_architecture
def test_architecture():
validate_fsd_architecture()Run pytest tests/test_architecture.py. Violations appear as assertion failures with a rule name and path. If your source root is different, set base_path accordingly. The validator reads [tool.pytest_fsd] from the project root; validate_fsd_architecture(project_root="...") can target another project.
Standalone checks also raise AssertionError on violations and return a nonzero exit status:
python -c "from pytest_fsd import validate_fsd_architecture; validate_fsd_architecture()"Unknown configuration keys/rules and invalid settings raise ValueError. A missing source root, uninspectable Python file, or symlink inside configured layers fails validation. ignore_paths excludes non-FSD top-level directories from the layer-name check; it does not suppress imports in configured layers.
The default checks cover layer import direction (forbidden-imports), slice independence (no-cross-imports), public APIs (public-api, no-public-api-sidestep, no-layer-public-api), structure (no-segmentless-slices, no-segments-on-sliced-layers, typo-in-layer-name, ambiguous-slice-names), naming (segments-by-purpose, repetitive-naming), and no-ui-in-app.
segments-by-purpose includes the generic names added in Steiger's FSD plugin 0.7.0, such as schemas, handlers, fixtures, middlewares, validators, resolvers, mutations, and assets. These names are checked when used as FSD segments. Python fixtures.py in a slice is also flagged because this package checks file segments as well as directories.
no-ui-in-app rejects an app/ui directory, as in Steiger. It also retains the Python-specific check for direct imports of common desktop GUI frameworks from the app layer.
Enable additional checks only when they suit your project:
[tool.pytest_fsd]
base_path = "src"
layers = ["app", "pages", "widgets", "features", "entities", "shared"]
extra_rules = [
"excessive-slicing", # More than 20 slices per layer
"shared-lib-grouping", # More than 15 loose Python files in shared/lib
"no-file-segments", # Segments must be directories
"no-reserved-folder-names", # No nested segment names such as model/model
"no-wildcard-exports", # No `from module import *` in __init__.py
]no-wildcard-exports was added in Steiger FSD plugin 0.8.0 and is disabled by default in both packages. It checks __init__.py files on every configured layer, including nested packages. Explicit module imports such as from . import model as model remain valid in Python. AST import diagnostics include line and character column numbers.
no-file-segments is a Python package option; it is not registered as a rule in Steiger FSD plugin 0.8.0. no-cross-imports is enabled here for compatibility, whereas the upstream plugin does not enable it by default. These choices are intentionally different from Steiger.
See the rule documentation for examples and details. The complete rule audit maps all 17 implemented rules and both input guards to positive/negative, activation, threshold and installed-package checks.
- Import rules statically inspect Python syntax, including relative imports, package initializers, function-local imports and
if TYPE_CHECKING:branches. They do not execute project code. Programmatic imports throughimportlib.import_module,importlib.__import__, and built-in__import__are analyzed too. Loader aliases, literal names, constant bindings, concatenation, f-strings, joins, relative packages and fromlists are supported. Literalexec/evalstrings and literalcompileinputs are inspected recursively, with bounded expansion. Unresolved recognized loader calls or executed code fail with[dynamic-imports]; they do not silently pass. Arbitrary user-defined import hooks and runtime code are not executed. - Shared APIs are enforced too: other segments use their root
__init__.py;shared/uiandshared/libexpose individual component/library package APIs or standalone Python modules. Imports within the same boundary remain valid. - Dot-hidden metadata directories and
__pycache__are excluded from scans. Underscore-prefixed packages such as_privateare ordinary code and are checked. no-public-api-sidestepsupports static__all__lists/tuples, concatenation, annotations,+=,appendandextend. Unresolved dynamic exports are reported as unknown.- Steiger's
inconsistent-namingandimport-localityhave no direct equivalent here. Consider Ruff'sNandTIDrules for Python naming and relative imports; their behavior is not identical to Steiger's rules. - Steiger's
insignificant-sliceneeds an import graph and is not implemented. The deprecatedprocesseslayer is not created by this package; omit it fromlayers. - This package checks Python files and filesystem structure. It does not implement every Steiger rule or every JavaScript-specific convention.
For example, this computed sibling import is rejected:
import importlib
layer = "features"
importlib.import_module(f"src.{layer}.other_slice")If the target comes from runtime input (importlib.import_module(requested_module)), validation fails with [dynamic-imports] because the target cannot be proven valid. Replace it with an explicit dispatch between statically known imports. The checker is an architecture linter; it does not emulate arbitrary Python execution or serve as an execution sandbox.
See the upstream FSD plugin changelog for Steiger's release history.
MIT. See LICENSE.