skills.rest
DataDog
DataDogOFFICIAL
Explore all skills by this author →
Website𝕏@datadoghqGitHub

circular-import-analysis

Detect circular imports in ddtrace and propose architectural fixes for dependency cycles.

650|546|Updated Jun 20, 2016
Search Tags:#dependency analysis#Python#Refactoring#ci#ARCHITECTURE#circular imports#ddtrace
One-click install
npx skills add https://github.com/DataDog/dd-trace-py --skill circular-import-analysis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: circular-import-analysis
Source: https://github.com/DataDog/dd-trace-py/tree/main/.claude/skills/circular-import-analysis
Command: npx skills add https://github.com/DataDog/dd-trace-py --skill circular-import-analysis

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires uv.

What problem does it solve?

Circular imports in the ddtrace codebase cause CI failures in the detect_circular_imports job and signal structural design problems. This Skill runs the cycle detector locally and guides you through sound architectural fixes instead of papering over cycles with deferred imports.

Core Features & Use Cases

  • Local Cycle Detection: Runs scripts/import-analysis/cycles.py via uv to write all detected cycles to cycles.json with nodes and concrete cycle paths.
  • Five Architectural Fix Patterns: Provides decision guidance for extracting shared types, dependency inversion, registry-based initialization, module splitting, and moving misplaced code.
  • Use Case: When the detect_circular_imports CI job fails on your PR after adding a module, run the analysis locally, grep both import directions to identify cross-boundary names, classify the dependency, apply the matching pattern, and re-run the detector to verify the cycle is gone.

Quick Start

Run the circular import analysis on ddtrace and propose an architectural fix for any cycles found in cycles.json.

Frequently Asked Questions about circular-import-analysis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I detect circular imports in a Python project?▼

Run the cycle detector with uv run --script scripts/import-analysis/cycles.py analyze cycles.json. It writes all detected cycles to cycles.json, where each entry lists the tangled modules in nodes and one concrete cycle path.

How to fix circular imports in Python without deferred imports?▼

Classify the dependency first: extract shared types into a third module, invert dependencies with a Protocol, push registration to the importing module, split the module along its dependency boundary, or move the code to the module that owns it.

Why are deferred imports inside functions a bad fix for circular imports?▼

Deferred imports hide the structural problem rather than solving it. They complicate testing and static analysis, and impose a runtime cost on every call, so architectural restructuring is preferred.

What do I need installed to run the circular import analysis?▼

You need uv on your PATH, installed via brew install uv or pip install uv. The analysis script runs through uv run --script and requires no other setup.

How do I verify a circular import fix worked?▼

Re-run uv run --script scripts/import-analysis/cycles.py analyze cycles.json after your change and confirm the cycle no longer appears in the output. Then remove the cycles.json file.

Related Skills

Explore More Software Engineering Skills→
langwatchlangwatch
3.5k

github

Clone repositories, commit changes, and open pull requests on GitHub via the gh CLI.

Official
Intermediate
lklimeklklimek
1

ci-loop

Monitor GitHub Actions runs, diagnose failures, apply fixes, and push changes until tests pass.

Community
Advanced
testdoubletestdouble
198

refactor

Refactor code iteratively with test-gated validation after each step.

Official
Advanced
pax-kpax-k
3

architecture-boundary-enforcer

Enforce and document architecture boundaries using dependency-cruiser, ESLint, import-linter, and custom scripts.

Community
Advanced