Python Language Support

Python Language Support

This document describes the Python language parsing support in Arxo.

Overview

Arxo supports analyzing Python 3.8+ codebases, extracting import graphs, call graphs, and detecting side effects. Python support works alongside TypeScript and Rust support, enabling analysis of mixed-language projects. Parsing uses tree-sitter (tree-sitter-python).

Features

Import Graph Analysis

• import statements: Extracts import foo, import foo.bar, import foo as f
• from ... import: Extracts from foo import bar, from . import sibling, from ..package import module
• Relative imports: Handles . (current package) and .. (parent package)
• Module resolution: Resolves Python import paths to file paths:
  • foo.bar → foo/bar.py or foo/bar/__init__.py
  • .sibling → sibling module in the same package
  • ..parent.module → parent package’s module

Call Graph Analysis

• Function calls: Extracts direct calls (e.g., foo(), module.func())
• Method calls: Tracks method invocations (e.g., obj.method())
• Local definitions: Tracks top-level functions and classes for resolution

Effect Detection

Detects side effects in Python code:

• I/O: open, pathlib, os.path, shutil, read/write
• Network: requests, urllib, http.client, socket, get/post
• Storage: sqlite3, psycopg2, database clients, execute/commit
• Logging: print, logging, log/info/debug/warning/error
• Time: time, datetime, sleep, now
• Random: random, secrets, randint, choice
• Mutation: global, nonlocal statements

Configuration

Language Selection

You can specify the language in your config file:

data:
  language: python # Options: "typescript", "rust", "python", or "auto"
  import_graph:
    group_by: folder
    group_depth: 2
    exclude:
      - __pycache__
      - .venv
      - venv
      - .pytest_cache
      - node_modules

Auto-Detection

If language: auto is specified (the default), Arxo will:

1. Scan the project directory for file extensions
2. Detect which languages are present (.py/.pyi for Python, .rs for Rust, .ts/.tsx for TypeScript)
3. Parse all detected languages and merge their graphs

Mixed-Language Projects

Arxo supports analyzing projects with Python, TypeScript, and Rust:

data:
  language: auto
  import_graph:
    exclude:
      - __pycache__
      - .venv
      - venv
      - target
      - node_modules

Module Resolution

Python module resolution follows these rules:

1. Relative imports (., .., .foo): Resolved from the current file’s directory; one dot = current package, two dots = parent package.
2. Absolute imports (foo, foo.bar): Resolved from the project root; foo.bar maps to foo/bar.py or foo/bar/__init__.py.
3. Standard library and third-party packages: Not resolved; no edges are added for modules that are not under the project root.

Limitations

• Dynamic imports: importlib.import_module(), __import__(), and similar are not analyzed.
• exec/eval: Code executed via exec or eval is not analyzed.
• Type inference: No mypy-level type analysis; call resolution is best-effort.
• External packages: Installed packages (e.g. numpy, requests) are treated as external; only project .py/.pyi files are included in the graph.

Running Analysis

arxo analyze --path /path/to/python/project --config your-config.yaml

For JSON output (e.g. for scripting):

arxo analyze --path /path/to/python/project --config your-config.yaml --json