Preferences

Preferences ¶

The Preferences object provides an easy way to manage internal AE preferences, such as you find in After Effects' Preferences menu. It is accessed through the app.preferences attribute.

Preferences are identified by section and key within the file, and each key name is associated with a value.

Differences from ExtendScript:

The preference .txt files are read-only: set_pref_as_* writes to an in-memory override layer that takes precedence over the files, and there is no save_to_disk(). Overrides last for the lifetime of this object and never modify the files.
getPrefAsLong / getPrefAsFloat are merged into a single [get_pref_as_number][] (Python does not need the distinction).
Getters accept an optional default returned when the key is absent instead of raising KeyError.

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

Example

import py_aep
from py_aep.enums import PREFType

app = py_aep.parse("project.aep", ae_preferences_dir="...")
fps = app.preferences.get_pref_as_number(
    "Import Options Preference Section",
    "Import Options Default Sequence FPS",
    PREFType.PREF_Type_MACHINE_INDEPENDENT,
)

Functions¶

composition_presets ¶

composition_presets() -> list[CompPreset]

The New Composition presets (py_aep extension, not in ExtendScript).

Parsed from the "Composition Presets Section v11" of the composition preference file; menu separators are skipped and set_pref_as_* overrides are not consulted. Empty when no preferences directory was provided.

delete_pref ¶

delete_pref(
    section_name: str,
    key_name: str,
    pref_type: PREFType = PREF_Type_MACHINE_SPECIFIC,
) -> None

Delete the given preference from this object's view.

The file value (if any) is masked, not removed from disk: [have_pref][] returns False and getters fall back to their default afterwards.

Parameters:

section_name (str) –

The name of a preferences section.
key_name (str) –

The key name of the preference.
pref_type (PREFType, default: PREF_Type_MACHINE_SPECIFIC ) –

The preference file the preference belongs to.

get_pref_as_bool ¶

get_pref_as_bool(
    section_name: str,
    key_name: str,
    pref_type: PREFType = PREF_Type_MACHINE_SPECIFIC,
    *,
    default: bool | None = None,
) -> bool

The value of the given preference as a boolean.

Parameters:

section_name (str) –

The name of a preferences section.
key_name (str) –

The key name of the preference.
pref_type (PREFType, default: PREF_Type_MACHINE_SPECIFIC ) –

The preference file the preference is read from.
default (bool | None, default: None ) –

Returned when the key is absent (otherwise a missing key raises KeyError).

get_pref_as_number ¶

get_pref_as_number(
    section_name: str,
    key_name: str,
    pref_type: PREFType = PREF_Type_MACHINE_SPECIFIC,
    *,
    default: int | float | None = None,
) -> int | float

The value of the given preference as a number.

Merges ExtendScript's getPrefAsLong and getPrefAsFloat: integral values return int, others float.

Parameters:

section_name (str) –

The name of a preferences section.
key_name (str) –

The key name of the preference.
pref_type (PREFType, default: PREF_Type_MACHINE_SPECIFIC ) –

The preference file the preference is read from.
default (int | float | None, default: None ) –

Returned when the key is absent (otherwise a missing key raises KeyError).

get_pref_as_string ¶

get_pref_as_string(
    section_name: str,
    key_name: str,
    pref_type: PREFType = PREF_Type_MACHINE_SPECIFIC,
    *,
    default: str | None = None,
) -> str

The value of the given preference as a string.

Parameters:

section_name (str) –

The name of a preferences section.
key_name (str) –

The key name of the preference.
pref_type (PREFType, default: PREF_Type_MACHINE_SPECIFIC ) –

The preference file the preference is read from.
default (str | None, default: None ) –

Returned when the key is absent (otherwise a missing key raises KeyError).

have_pref ¶

have_pref(
    section_name: str,
    key_name: str,
    pref_type: PREFType = PREF_Type_MACHINE_SPECIFIC,
) -> bool

Whether the given preference exists (override or file value).

Parameters:

section_name (str) –

The name of a preferences section.
key_name (str) –

The key name of the preference.
pref_type (PREFType, default: PREF_Type_MACHINE_SPECIFIC ) –

The preference file the preference is read from.

output_name_template_presets ¶

output_name_template_presets() -> dict[str, str]

The "File Name and Location" template presets as a {name: template} mapping (py_aep extension, not in ExtendScript).

Parsed from the "Output File Name Template Presets Section v6" of the machine-specific preference file (e.g. Comp Name -> [compName].[fileExtension]); set_pref_as_* overrides are not consulted. Empty when no preferences directory was provided.

reload ¶

reload() -> None

Reload preferences from disk, discarding in-memory overrides.

set_pref_as_bool ¶

set_pref_as_bool(
    section_name: str,
    key_name: str,
    value: bool,
    pref_type: PREFType = PREF_Type_MACHINE_SPECIFIC,
) -> None

Override the given preference with a boolean value.

The override is in-memory only; the preference file on disk is never modified.

Parameters:

section_name (str) –

The name of a preferences section.
key_name (str) –

The key name of the preference.
value (bool) –

The new boolean value.
pref_type (PREFType, default: PREF_Type_MACHINE_SPECIFIC ) –

The preference file the preference belongs to.

set_pref_as_number ¶

set_pref_as_number(
    section_name: str,
    key_name: str,
    value: int | float,
    pref_type: PREFType = PREF_Type_MACHINE_SPECIFIC,
) -> None

Override the given preference with a number value.

The override is in-memory only; the preference file on disk is never modified. Merges ExtendScript's savePrefAsLong and savePrefAsFloat.

Parameters:

section_name (str) –

The name of a preferences section.
key_name (str) –

The key name of the preference.
value (int | float) –

The new numeric value.
pref_type (PREFType, default: PREF_Type_MACHINE_SPECIFIC ) –

The preference file the preference belongs to.

set_pref_as_string ¶

set_pref_as_string(
    section_name: str,
    key_name: str,
    value: str,
    pref_type: PREFType = PREF_Type_MACHINE_SPECIFIC,
) -> None

Override the given preference with a string value.

The override is in-memory only; the preference file on disk is never modified.

Parameters:

section_name (str) –

The name of a preferences section.
key_name (str) –

The key name of the preference.
value (str) –

The new string value.
pref_type (PREFType, default: PREF_Type_MACHINE_SPECIFIC ) –

The preference file the preference belongs to.

CompPreset ¶

A New Composition preset from the AE preferences.

Attributes¶

frame_rate ¶

frame_rate: float

height ¶

height: int

name ¶

name: str

pixel_aspect ¶

pixel_aspect: float

width ¶

width: int