`ImportExpr`/`ImportFromExpr` - Represents an import expression.

[xmnlab]

from gpt:

Understanding the Requirements

• ImportExpr: Represents the expression version of an import statement.
• ImportFromExpr: Represents the expression version of a from ... import ... statement.

In your AST framework:

• Expressions inherit from Expr or an expression-derived class.
• Statements inherit from StatementType or a class derived from it.
• Generally, classes do not inherit directly from AST.

---

Use Cases for ImportExpr and ImportFromExpr

In some programming languages, importing can be performed at runtime within expressions. Examples include:

• Python's importlib module: Allows dynamic imports.
• JavaScript's dynamic import(): Returns a promise that resolves to the module.
• Languages that treat modules as first-class objects.

In such cases, the import operation is an expression that can be used within other expressions or assigned to variables.

---

Designing ImportExpr and ImportFromExpr Classes

Inheritance Hierarchy

• Both ImportExpr and ImportFromExpr should inherit from Expr or a subclass of Expr.
• This allows them to be used wherever expressions are valid within your AST.

Class Definitions

1. ImportExpr

   • Inherits from Expr.
   • Represents an import operation as an expression.
   • Should encapsulate the module name and any aliasing.

2. ImportFromExpr

   • Inherits from Expr.
   • Represents a from ... import ... operation as an expression.
   • Should encapsulate the module name, the names being imported, and any aliasing.

---

Defining the Classes

1. Updating ASTKind Enum

First, we'll need to add new kinds to the ASTKind enum for these expressions.

# In src/astx/base.py, within the ASTKind enum, add:

ImportExprKind = -800
ImportFromExprKind = -801

2. Implementing ImportExpr Class

from astx.base import Expr, ASTKind, SourceLocation, NO_SOURCE_LOCATION, ASTNodes
from astx.types import ReprStruct
from typing import Optional
from public import public

@public
class ImportExpr(Expr):
    """Represents an import operation as an expression."""

    module: str
    alias: Optional[str]

    def __init__(
        self,
        module: str,
        alias: Optional[str] = None,
        loc: SourceLocation = NO_SOURCE_LOCATION,
        parent: Optional[ASTNodes] = None,
    ) -> None:
        super().__init__(loc=loc, parent=parent)
        self.module = module
        self.alias = alias
        self.kind = ASTKind.ImportExprKind
        # You can set the type_ attribute if needed
        # self.type_ = ModuleType or similar

    def __str__(self) -> str:
        """Return a string representation of the import expression."""
        if self.alias:
            return f"import {self.module} as {self.alias}"
        else:
            return f"import {self.module}"

    def get_struct(self, simplified: bool = False) -> ReprStruct:
        """Return the AST structure of the import expression."""
        key = "ImportExpr"
        value = {
            "module": self.module,
            "alias": self.alias,
        }
        return self._prepare_struct(key, value, simplified)

Explanation:

• Inheritance: Inherits from Expr, as it's an expression.
• Attributes:
  • module: The name of the module to import.
  • alias: An optional alias name.
• Methods:
  • __str__: Provides a readable string representation.
  • get_struct: Returns the AST structure.

3. Implementing ImportFromExpr Class

@public
class ImportFromExpr(Expr):
    """Represents a 'from ... import ...' operation as an expression."""

    module: Optional[str]
    names: list[str]
    aliases: dict[str, Optional[str]]  # Mapping from name to alias
    level: int  # Number of leading dots for relative imports

    def __init__(
        self,
        module: Optional[str],
        names: list[str],
        aliases: Optional[dict[str, Optional[str]]] = None,
        level: int = 0,
        loc: SourceLocation = NO_SOURCE_LOCATION,
        parent: Optional[ASTNodes] = None,
    ) -> None:
        super().__init__(loc=loc, parent=parent)
        self.module = module
        self.names = names
        self.aliases = aliases or {}
        self.level = level
        self.kind = ASTKind.ImportFromExprKind
        # You can set the type_ attribute if needed

    def __str__(self) -> str:
        """Return a string representation of the import-from expression."""
        level_dots = "." * self.level
        module_str = f"{level_dots}{self.module}" if self.module else level_dots
        imports = []
        for name in self.names:
            alias = self.aliases.get(name)
            if alias:
                imports.append(f"{name} as {alias}")
            else:
                imports.append(name)
        imports_str = ", ".join(imports)
        return f"from {module_str} import {imports_str}"

    def get_struct(self, simplified: bool = False) -> ReprStruct:
        """Return the AST structure of the import-from expression."""
        key = "ImportFromExpr"
        value = {
            "module": self.module,
            "level": self.level,
            "imports": [
                {"name": name, "alias": self.aliases.get(name)}
                for name in self.names
            ],
        }
        return self._prepare_struct(key, value, simplified)

Explanation:

• Inheritance: Inherits from Expr.
• Attributes:
  • module: The module to import from (can be None for relative imports).
  • names: A list of names to import.
  • aliases: A dictionary mapping names to their aliases.
  • level: The level of relative import.
• Methods:
  • __str__: Provides a readable string representation.
  • get_struct: Returns the AST structure.

---

Considerations

1. Type Annotations

• You might want to set the type_ attribute to represent the resulting type of the expression.
• For example, importing a module might result in a ModuleType, whereas importing a specific name might have a different type.

2. Dynamic Imports

• If your language supports dynamic imports (e.g., import('module') in JavaScript), you may need to handle asynchronous behavior or promises.
• You can extend the classes to accommodate such features if necessary.

3. Integration with Existing Classes

• If you have an AliasExpr class, you might reuse it within these expressions.
• For ImportFromExpr, you could have a list of AliasExpr instances instead of simple strings.

Using AliasExpr in ImportFromExpr:

from typing import List

@public
class ImportFromExpr(Expr):
    """Represents a 'from ... import ...' operation as an expression."""

    module: Optional[str]
    aliases: List[AliasExpr]
    level: int  # Number of leading dots for relative imports

    def __init__(
        self,
        module: Optional[str],
        aliases: List[AliasExpr],
        level: int = 0,
        loc: SourceLocation = NO_SOURCE_LOCATION,
        parent: Optional[ASTNodes] = None,
    ) -> None:
        super().__init__(loc=loc, parent=parent)
        self.module = module
        self.aliases = aliases
        self.level = level
        self.kind = ASTKind.ImportFromExprKind

    def __str__(self) -> str:
        """Return a string representation of the import-from expression."""
        level_dots = "." * self.level
        module_str = f"{level_dots}{self.module}" if self.module else level_dots
        imports_str = ", ".join(str(alias) for alias in self.aliases)
        return f"from {module_str} import {imports_str}"

    def get_struct(self, simplified: bool = False) -> ReprStruct:
        """Return the AST structure of the import-from expression."""
        key = "ImportFromExpr"
        value = {
            "module": self.module,
            "level": self.level,
            "imports": [alias.get_struct(simplified) for alias in self.aliases],
        }
        return self._prepare_struct(key, value, simplified)

---

Example Usage

1. Importing a Module as an Expression

# Create an import expression
import_expr = ImportExpr(module="math", alias=None)

# Use the import expression in an assignment
variable = Variable(name="math_module")
assignment = VariableAssignment(variable=variable, value=import_expr)

# Now 'math_module' holds the imported 'math' module

2. Importing Specific Names from a Module

# Create alias expressions
alias1 = AliasExpr(name="sqrt", asname="square_root")
alias2 = AliasExpr(name="pi")

# Create an import-from expression
import_from_expr = ImportFromExpr(module="math", aliases=[alias1, alias2])

# Use the import-from expression in code
# For example, as part of a function call or another expression

---

Conclusion

By designing ImportExpr and ImportFromExpr as subclasses of Expr, you can represent import operations as expressions within your AST framework. This allows for dynamic importing and integration with other expressions in the language.

---

Next Steps

• Integration: Ensure these classes integrate smoothly with the rest of your AST framework.
• Type Handling: Define the type_ attribute for these expressions to represent the types they yield.
• Testing: Create unit tests to verify their behavior in various scenarios.
• Documentation: Update your documentation to include these new classes and explain their usage.

---

Additional Considerations

1. Error Handling

• Implement error checking in constructors to handle invalid inputs, such as missing module names or invalid aliases.

2. Contextual Semantics

• Depending on your language's semantics, importing as an expression might have specific rules or limitations. Ensure these are reflected in your design.

3. Runtime Behavior

• If your AST is used for code generation or interpretation, define how these import expressions are executed at runtime.

[apkrelling]

@xmnlab , would it be possible for you to put here quick examples of what the output of the visit method of the transpiler for these classes should be? Thank you!

[xmnlab]

@apkrelling python doesn't have this import or import-from features as expressions, but we can workaround that.

just for the record some other programming languages would offer that (from gpt):

• JavaScript (ES2020 and Later): Supports dynamic imports using import() as an expression.
• PHP: The require and include statements can be used as expressions since they return values.
• Ruby: The require method can be used within expressions.
• Perl: require is a function and can be used as an expression.

but with python we could do it with __import__:

# Using __import__() as an expression
module = __import__('module_name')

for the import-from, maybe you could do something like this:

name = getattr(__import__('module_name', fromlist=['name']), 'name')

in the case of multiple imports

name1, name2 = (
    getattr(__import__('module_name', fromlist=['name1']), 'name1'), 
    getattr(__import__('module_name', fromlist=['name2']), 'name2'), 
)

[apkrelling]

Hello @xmnlab , about the AST ascii viz showing the wrong node names: The node names that will show on the AST ascii viz are the keys of the get_struct dictionary. The way we are currently designing the AliasExpr, ImportStmt, ImportFromStmt, ImportExpr, and ImportFomExpr classes, the names that we want as node names are the values. So the get_struct method would need to be modified to make them keys, not values. See the example below:

[apkrelling]

The ascii viz problem is solved on PR #122 .