External Modules

Codegen provides a way to handle imports from external packages and modules through the ExternalModule class.

# Python examples
import datetime
from requests import get

# TypeScript/JavaScript examples
import React from 'react'
import { useState, useEffect } from 'react'
import type { ReactNode } from 'react'
import axios from 'axios'

What are External Modules?

When writing code, you often import from packages that aren’t part of your project - like datetime and requests in Python, or react and axios in TypeScript. In Codegen, these are represented as ExternalModule instances.

for imp in codebase.imports:
    if isinstance(imp.symbol, ExternalModule):
        print(f"Importing from external package: {imp.resolved_symbol.source}")

External modules are read-only - you can analyze them but can’t modify their implementation. This makes sense since they live in your project’s dependencies!

Working with External Modules

The most common use case is handling external modules differently from your project’s code:

Identifying Function Calls as External Modules

For FunctionCall instances, you can check if the function definition is an ExternalModule via the FunctionCall.function_definition property:

for fcall in file.function_calls:
    definition = fcall.function_definition
    if isinstance(definition, ExternalModule):
        # Skip external functions
        print(f'External function: {definition.name}')
    else:
        # Process local functions...
        print(f'Local function: {definition.name}')

Import Resolution

Similarly, when working with imports, you can determine if they resolve to external modules by checking the Import.resolved_symbol property:

for imp in file.imports:
    resolved = imp.resolved_symbol
    if isinstance(resolved, ExternalModule):
        print(f"Import from external package: from {imp.module} import {imp.name}")

Use isinstance(symbol, ExternalModule) to reliably identify external modules. This works better than checking names or paths since it handles all edge cases.

Properties and Methods

External modules provide several useful properties:

# Get the module name
module_name = external_module.name  # e.g. "datetime" or "useState"

# Check if it's from node_modules (TypeScript/JavaScript)
if external_module.filepath == "":
    print("This is an external package from node_modules")

Common Patterns

Here are some typical ways you might work with external modules:

Skip External Processing:

When modifying function calls or imports, skip external modules since they can’t be changed:

# Example from a codemod that adds type hints
def add_type_hints(function):
    if isinstance(function.definition, ExternalModule):
        return  # Can't add type hints to external modules like React.FC
    # Add type hints to local functions...

Analyze Dependencies

Track which external packages your code uses:

# Find all external package dependencies
external_deps = set()
for imp in codebase.imports:
    if isinstance(imp.resolved_symbol, ExternalModule):
        external_deps.add(imp.resolved_symbol.source)
        # Will find things like 'react', 'lodash', 'datetime', etc.

When working with imports, always handle external modules as a special case. This ensures your codemods work correctly with both local and external code.