Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.14"]
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]

steps:
- uses: actions/checkout@v4
Expand Down
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Nikita Lebedev

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
151 changes: 36 additions & 115 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,162 +1,83 @@
[🇷🇺 Читать на русском](README.ru.md)
[Русская версия](README.ru.md)

# pytest-fsd

**FSD Architecture Validation for Python Projects.**
[![PyPI](https://img.shields.io/pypi/v/pytest-fsd)](https://pypi.org/project/pytest-fsd/)
[![Python](https://img.shields.io/pypi/pyversions/pytest-fsd)](https://pypi.org/project/pytest-fsd/)
[![CI](https://github.com/Horcag/pytest-fsd/actions/workflows/ci.yml/badge.svg)](https://github.com/Horcag/pytest-fsd/actions/workflows/ci.yml)

`pytest-fsd` automatically checks your Python project's architecture for compliance with the [Feature-Sliced Design](https://feature-sliced.design/) methodology.
Validate [Feature-Sliced Design (FSD)](https://feature-sliced.design/) architecture in a Python project using pytest. The rules are adapted from the [Steiger FSD plugin](https://github.com/feature-sliced/steiger), with Python-specific checks where appropriate. This is an independent Python package, not an official Steiger port.

It uses a hybrid approach: dynamic checks via [pytest-archon](https://pypi.org/project/pytest-archon/) + static AST analysis + file structure verification.

## Installation
## Install

```bash
pip install pytest-fsd
# or
uv add --dev pytest-fsd
```

## Usage
Python 3.8–3.14 is supported.

## Use

### 1. Configure `pyproject.toml`
Add the layers used by your project, from highest to lowest, to `pyproject.toml`:

```toml
[tool.pytest_fsd]
base_path = "src"
layers = ["app", "windows", "widgets", "features", "entities", "shared"]
layers = ["app", "pages", "widgets", "features", "entities", "shared"]
# ignore_paths = ["my_non_fsd_package"]
```

### 2. Create a test
Create an architecture test:

```python
# tests/test_architecture.py
from pytest_fsd import validate_fsd_architecture

def test_project_architecture():

def test_architecture():
validate_fsd_architecture()
```

### 3. Run

```bash
pytest tests/test_architecture.py -vv
```
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.

## Library Architecture
## Rules

Each rule is a folder inside `src/pytest_fsd/rules/<rule_name>/` containing:
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`.

- `__init__.py` — verification logic (the function `check(config, project_root) -> List[Violation]`)
- `README.md` — rule description, examples, and rationale
`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.

```
src/pytest_fsd/
__init__.py # Facade: validate_fsd_architecture()
config.py # Reads [tool.pytest_fsd] from pyproject.toml
_lib/ # Shared utilities
violations.py # Unified Violation dataclass
ast_utils.py # AST parsing for imports
fs_utils.py # File utilities, segment constants
rules/
forbidden_imports/ # pytest-archon: layers only import from layers below
no_cross_imports/ # pytest-archon: slices within the same layer are independent
no_public_api_sidestep/ # AST: importing from another slice is only allowed via its __init__.py
no_layer_public_api/ # FS: layer folders must not contain __init__.py
no_ui_in_app/ # AST: forbids importing UI frameworks directly into app
repetitive_naming/ # FS: files do not duplicate the slice name
no_segmentless_slices/ # FS: a slice must contain at least one standard segment
segments_by_purpose/ # FS: forbids utils/helpers/components/hooks
ambiguous_slice_names/ # FS: slice names must not match segment names in shared
no_segments_on_sliced_layers/ # FS: sliced layers must not contain segments directly
public_api/ # FS: every slice must have an __init__.py
```
`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.

---

## Steiger Rules Coverage Matrix

Full list of rules from the [Steiger FSD Plugin](https://github.com/feature-sliced/steiger) and their status in `pytest-fsd`:

| # | Steiger Rule | pytest-fsd Status | Description |
| --- | ----------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------- |
| 1 | `forbidden-imports` / `no-higher-level-imports` | ✅ **Complete** | Layers only import from layers below them |
| 2 | `no-cross-imports` | ✅ **Complete** | Slices within the same layer are independent of each other |
| 3 | `no-public-api-sidestep` | ✅ **Complete** | Importing from another slice is only allowed via `__init__.py` |
| 4 | `public-api` | ✅ **Complete** | Every slice and shared segment must have an `__init__.py` |
| 5 | `no-layer-public-api` | ✅ **Complete** | Layer folders (`features/`, `entities/`) must not contain `__init__.py` |
| 6 | `segments-by-purpose` | ✅ **Complete** | Forbids `utils`, `helpers`, `hooks`, `components`, `modals`, `types`, `constants`, etc. |
| 7 | `no-segmentless-slices` | ✅ **Complete** | A slice must contain at least one standard segment |
| 8 | `repetitive-naming` | ✅ **Complete** | Files do not duplicate the slice name (`user/user_model.py` → `user/model.py`) |
| 9 | `no-ui-in-app` | ✅ **Complete** | The `app` layer must not import UI frameworks |
| 10 | `ambiguous-slice-names` | ✅ **Complete** | Slice names must not match segment names in `shared/` |
| 11 | `no-segments-on-sliced-layers` | ✅ **Complete** | Sliced layers do not have direct segment folders |
| 12 | `inconsistent-naming` | 🔶 **Ruff** | Enforced by the `N` (pep8-naming) plugin in `Ruff` |
| 13 | `import-locality` | 🔶 **Ruff** | Enforced by the `TID` (flake8-tidy-imports) plugin in `Ruff` |
| 14 | `typo-in-layer-name` | ✅ **Complete** | Forbids unknown layer folders (e.g., `fietures` instead of `features`) in the root |
| 15 | `no-processes` | 🔶 **Configuration** | The `processes` layer is deprecated; simply do not include it in `layers` |
| 16 | `excessive-slicing` | ⚡ **Optional** | More than 20 slices in one layer (threshold: 20) |
| 17 | `insignificant-slice` | 🟡 **Manual check** | Requires import graph analysis to determine "insignificant" slices |
| 18 | `no-file-segments` | ⚡ **Optional** | A segment as a file (`model.py`) instead of a folder (`model/`) |
| 19 | `shared-lib-grouping` | ⚡ **Optional** | More than 15 ungrouped files in `shared/lib` |
| 20 | `no-reserved-folder-names` | ⚡ **Optional** | Subfolders in segments must not match segment names |

### Legend

| Status | Meaning |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| ✅ **Complete** | The rule is fully automated and runs every time `pytest` is executed |
| ⚡ **Optional** | The rule is automated but is enabled via `extra_rules` in `pyproject.toml` |
| 🔶 **Ruff / Configuration** | Covered by external tools (`Ruff`) or `pyproject.toml` configuration |
| 🟡 **Manual check** | Requires subjective evaluation or complex analysis better suited for manual code review |

---

## Enabling Optional Rules

Add to `pyproject.toml`:
Enable additional checks only when they suit your project:

```toml
[tool.pytest_fsd]
base_path = "src"
layers = ["app", "windows", "widgets", "features", "entities", "shared"]
layers = ["app", "pages", "widgets", "features", "entities", "shared"]
extra_rules = [
"excessive-slicing", # ≤ 20 slices per layer
"shared-lib-grouping", # ≤ 15 files in shared/lib
"no-file-segments", # Segments must be folders, not files
"no-reserved-folder-names" # Segment subfolders cannot be named ui/model/api/lib/config
"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
]
```

Each rule is described in detail in `src/pytest_fsd/rules/<rule_name>/README.md`.

---

## Configuring Ruff for Related Rules

For full coverage of FSD rules that Steiger checks at the linting level (which `pytest-fsd` does not duplicate), add to `pyproject.toml`:

```toml
[tool.ruff.lint]
select = ["N", "TID"]

[tool.ruff.lint.flake8-tidy-imports]
ban-relative-imports = "parents"
```
`no-file-segments` is a Python package option; it is not registered as a rule in Steiger FSD plugin 0.7.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.

| Ruff Plugin | Steiger Rule | What it checks |
| --------------------------- | --------------------- | ----------------------------------------------- |
| `N` (pep8-naming) | `inconsistent-naming` | `snake_case` for modules, variables, functions |
| `TID` (flake8-tidy-imports) | `import-locality` | Forbids relative imports from parent packages |
See the [rule documentation](src/pytest_fsd/rules/) for examples and details.

Detailed descriptions and configuration examples: `src/pytest_fsd/rules/inconsistent_naming/README.md` and `src/pytest_fsd/rules/import_locality/README.md`.
## Scope and limitations

## Known Limitations
- `forbidden-imports` and `no-cross-imports` use [pytest-archon](https://pypi.org/project/pytest-archon/). Imports guarded by `if TYPE_CHECKING:` are invisible to these runtime checks.
- `no-public-api-sidestep` analyzes Python syntax and explicit `__all__` lists. Dynamically assembled exports may be reported incorrectly.
- Steiger's `inconsistent-naming` and `import-locality` have no direct equivalent here. Consider Ruff's `N` and `TID` rules for Python naming and relative imports; their behavior is not identical to Steiger's rules.
- Steiger's `insignificant-slice` needs an import graph and is not implemented. The deprecated `processes` layer is not created by this package; omit it from `layers`.
- This package checks Python files and filesystem structure. It does not implement every Steiger rule or every JavaScript-specific convention.

- **`TYPE_CHECKING` imports**: Rules using `pytest-archon` (e.g., `forbidden-imports` and `no-cross-imports`) work based on dynamic import graph analysis at runtime. Imports inside `if TYPE_CHECKING:` blocks are not executed when the module loads and are therefore **not visible to these rules**.
- **Relative imports**: The `ast_utils.py` module supports relative paths for checking `no-public-api-sidestep`, however, `Ruff` (the `TID` plugin) is still better at controlling relative imports outside of slices.
- **Dynamic `__all__`**: The `no-public-api-sidestep` rule uses static AST analysis to extract `__all__` from the `__init__.py` file. If the export list is formed dynamically (e.g., `__all__ = a + b`), the static analyzer will not be able to read it, and the tool may yield false positive violations. Exports in `__all__` must be defined as an explicit list or tuple.
- **Minimum Python Version**: The library supports Python **3.8+**. For Python `<3.11`, backward compatibility is provided via the `tomli` package, and on Python `3.11+` the built-in `tomllib` is used.
See the [upstream FSD plugin changelog](https://github.com/feature-sliced/steiger/blob/master/packages/steiger-plugin-fsd/CHANGELOG.md) for Steiger's release history.

## License

MIT
MIT. See [LICENSE](LICENSE).
Loading
Loading