Import options

ImportOptions ¶

Options for importing a file into an After Effects project.

This is a parameter container used by Project.import_file(). It validates the import settings before the actual import operation.

Unlike most py_aep classes, ImportOptions has no chunk backing - import settings are not stored in the .aep binary format.

Example

from pathlib import Path
from py_aep import ImportOptions, ImportAsType

opts = ImportOptions(Path("footage/shot_001.png"))
opts.sequence = True
opts.import_as = ImportAsType.FOOTAGE

See: https://ae-scripting.docsforadobe.dev/other/importoptions/

Attributes¶

file ¶

file: Path

The file to be imported. If a file is set in the constructor, you can access it through this attribute. Read / Write.

force_alphabetical ¶

force_alphabetical: bool

When True and sequence is also True, use alphabetical order for sequence frame numbering. Read / Write.

import_as ¶

import_as: ImportAsType

How to import the file. Read / Write.

layer_dimensions ¶

layer_dimensions: str | None

Footage dimensions for a layer_index import: "document" (the full canvas) or "layer" (the layer's content box), matching the "Footage Dimensions" option of AE's import dialog. None (the default) imports at document size. Read / Write.

py_aep extension: ExtendScript exposes no layer-selection API.

Note

"layer" is only supported for .psd/.psb. AE's own dialog defaults to Layer Size for .ai/.pdf, but computing an AI layer's artwork bounds requires rendering the PDF content, so py_aep raises NotImplementedError there.

layer_index ¶

layer_index: int | None

The single layer to import from a layered file (.psd/.psb/ .ai/.pdf), as its 0-based position in the list returned by list_layers (top layer first - the order of the "Choose Layer" dropdown of AE's import dialog). None (the default) imports the file like AE's "Merged Layers" / whole-document option. Only valid with ImportAsType.FOOTAGE. Read / Write.

py_aep extension: ExtendScript exposes no layer-selection API. An index (not a name) selects the layer because layered files may contain several layers with the same name; AE's own dialog disambiguates duplicates by dropdown position.

Raises:

ValueError –

On import, if the index is out of range for the file's selectable layers (see list_layers).

sequence ¶

sequence: bool

When True, import the file as part of a numbered image sequence. Read / Write.

Functions¶

can_import_as ¶

can_import_as(type: int | ImportAsType) -> bool

Check whether the file can be imported as the given type.

Gates on what py_aep can actually import: the per-extension capability table (get_import_as_types) reflects After Effects, while a file whose format py_aep does not implement (absent from data.file_formats, or marked unsupported) returns False for every type. ImportAsType.PROJECT is never importable (py_aep does not implement project import for any format), so it always returns False even though AE can import .mov/.m4a/.aep/.aet as a project.

Parameters:

type (int | ImportAsType) –

The import type to check.

Returns:

bool –

True if the file can be imported as type.

is_file_name_numbered ¶

is_file_name_numbered() -> tuple[bool, int]

Check whether the filename ends with a number.

Returns:

bool –

A tuple of (is_numbered, first_number) where
int –

is_numbered is True when the filename stem ends with
tuple[bool, int] –

digits and first_number is the parsed integer value (or
tuple[bool, int] –

0 when not numbered).