---
title: "2026-08-27 Python private import lint finalization"
description: "Finalized PLC2701 enforcement across the monorepo while preserving the two-commit linting branch."
image: "https://docs.virdx.dev/img/virdx-social-card.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.virdx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-08-27 Python private import lint finalization

## Work Done

- Added a shared isolated Ruff preview pass for `PLC2701` and wired it into every Python Nx lint target.
- Excluded tests, where private helper imports are intentional, from this production-boundary check.
- Kept `vxdata.sdk.namespaces._SPECIAL_NAMESPACES` private and added one narrow `# noqa: PLC2701` to the namespace generator.
- Preserved legacy Pixi lockfiles by wiring three projects through Nx and Lefthook instead of changing task-bearing manifests that would force lock upgrades.
- Verified all ten Python lint targets, Import Linter contracts, lock guards, module boundaries, and a negative test that catches the suppressed import when the suppression is removed.
- Folded the initial work into `chore: enforce Python import boundaries` and later appended focused orchestration commits.
- Added advisory ast-grep to the authoritative Python lint flow, pinned the CLI for CI, and opened draft linting PR [virdx/mono#353](https://github.com/virdx/mono/pull/353).
- Moved complete Python lint behavior into Pixi manifests; Nx targets now only call each project’s frozen Pixi `lint` task and provide cache metadata.
- Upgraded three legacy Pixi v6 locks to v7 in an isolated generated-only commit because manifest edits make the lock guard require the current schema.
- Delegated the 43 mechanical ast-grep fixes to a separate worktree and opened [virdx/mono#354](https://github.com/virdx/mono/pull/354); it leaves only advisory warnings and hints.

## Lessons Learned: Pitfalls

- Ruff preview mode changes behavior for already-selected stable rules. Enabling it in the normal project configuration surfaced unrelated legacy findings even with explicit preview rules. A separate `--isolated --preview --select PLC2701` pass avoids changing the existing baseline.
- Running affected typecheck, test, and build targets concurrently is unsafe because several Nx targets share and delete package `output/` and `dist/` directories. This caused false build failures, pytest import mismatches, and a temporary missing workspace module. Sequential reruns passed.
- The IPython environment set `MPLBACKEND=module://matplotlib_inline.backend_inline`, which breaks matplotlib tests outside notebooks. External project validation should remove that inherited variable.
- Task-only changes in three older Pixi manifests made their legacy lockfiles appear stale and would have forced noisy lock upgrades.

## Lessons Learned: Improvements

- Document that preview-only Ruff rules should run in an isolated second pass unless the repository has already adopted Ruff preview behavior globally.
- Document that build-dependent Nx validation must run sequentially when targets share generated output directories.
- Add `MPLBACKEND` sanitization to native project-command execution guidance for matplotlib projects.
- Keep Pixi manifests as the source of truth for Python project tasks. Nx should call those tasks and only add orchestration/cache metadata.
- Isolate unavoidable generated lock schema upgrades in their own commit so reviewers can separate them from behavioral changes.

Source: https://docs.virdx.dev/knowledge/inbox/2026-08-27-infrastructure-python-private-import-lint-finalization/index.mdx