Add built-in Python source analyzer (sgraph.analyzers)

[villelaitila]

Summary

Adds sgraph.analyzers, a built-in analysis layer that turns a Python project directory into an SGraph model directly — no external analyzer required.

from sgraph.analyzers import analyze_python

result = analyze_python("./src")
print(result.summary())
result.graph.to_xml("model.xml")

Implementation technique

• Standard-library ast only — no third-party Python parser. Each file is parsed with ast.parse and walked by an ast.NodeVisitor subclass.

• Structural pattern matching (match/case) drives name, decorator and type-annotation extraction over AST expression nodes.

• Two-phase pipeline:

  1. Discover + parse every file, build the element tree, and register each module in a registry.
  2. Resolve the collected import statements into dependency edges once the whole registry is known.

  Deferring import resolution to phase 2 means forward references and cross-module imports resolve regardless of file processing order. Duplicate edges are suppressed and self-references skipped.

Architecture

Module	Responsibility
analyzers/base.py	Framework-agnostic types: AnalyzerConfig (root path, include/exclude globs, external-import + stdlib toggles), AnalysisResult (graph + errors + stats + summary()), AnalysisError, SourceLocation, and the AnalysisLevel enum.
analyzers/code/base.py	Language-agnostic source plumbing: glob-based discovery with exclude filtering, file-path → module-path mapping, encoding-tolerant reading (utf-8 with latin-1 fallback).
analyzers/code/python/python_analyzer.py	Orchestrates the two phases; maps the filesystem into SElements (packages from __init__.py, modules from files, nested classes/functions/methods) and builds the import/from_import SElementAssociations.
analyzers/code/python/ast_visitor.py	Creates SElements per scope according to the configured level; records decorators, parameters and return-type annotations at FULL.
analyzers/code/python/import_resolver.py	Resolves absolute and relative imports (dot-level aware) against the module registry with parent-module fallback; external/stdlib targets skipped unless configured.
analyzers/database/, analyzers/infrastructure/	Reserved namespaces for future analyzers.

Analysis levels

AnalysisLevel lets callers trade detail for speed:

PACKAGES_ONLY  <  FILES  <  CLASSES  <  FUNCTIONS  <  FULL

• PACKAGES_ONLY / FILES — coarse structural graph
• CLASSES / FUNCTIONS — nested classes, functions and methods
• FULL — additionally captures parameters, return types and decorators

Tests

27 tests covering source discovery, module-path mapping, level gating, class/function extraction, and absolute/relative import resolution. All passing locally (pytest tests/analyzers/).

Notes for reviewers

• Pure standard library — no new runtime dependencies.
• database/ and infrastructure/ ship as empty reserved packages (placeholders for upcoming analyzers).
• In-code docstrings/comments are currently in Finnish; happy to translate them to English in this PR or a follow-up if preferred for the public API surface.

[softagram-bot]

Softagram Impact Report for pull/157 (head commit: f5e847e)

TL;DR Changed code files: 15 | Directly impacted code files: 0

⭐ Change Overview

(Open in Softagram Desktop for full details)

⭐ Details of Dependency Changes

(Open in Softagram Desktop for full details)

[]

📄 Full report

• Permalink: Full report for pull/157

Impact Report explained. Give feedback on this report to support@softagram.com