# psd_tools.api.smart_object

Smart object module.

## SmartObject

class psd_tools.api.smart_object.SmartObject(layer: LayerProtocol)

  Smart object that represents embedded or external file.

  Smart objects are attached to `SmartObjectLayer`.

  property data: bytes

    Embedded file content as bytes.

    For `kind == 'data'` this returns the bytes stored in the PSD without any filesystem access. For `kind == 'external'` this calls `open()` with no `external_dir` argument, which trusts `fullPath` from the PSD verbatim. Prefer `open()` with an explicit `external_dir` when processing untrusted files.

  property detected_filetype: str | None

    Best-effort file type, falling back when `filetype` is `None`.

    Resolution order:

    1. `filetype` — the value stored in the PSD.

    2. Extension taken from `filename` (lower-cased, dot stripped).

    3. Magic-byte sniffing of the first few embedded bytes (only for `kind == 'data'`; external objects are not read from disk to keep this property side-effect-free).

    Warning

    Steps 2 and 3 are heuristic. Do not use the result for security-sensitive decisions (e.g. deciding whether to execute content or trust a type boundary).

  property filename: str

    Original file name of the object.

  property filesize: int

    File size of the object.

  property filetype: str | None

    4-byte file-type code stored in the PSD, lowercased and stripped.

    Returns `None` when the field is absent or blank (e.g. some Adobe Illustrator smart objects store four spaces instead of a real type code). Use `detected_filetype` for a best-effort guess that falls back to the filename extension and magic bytes.

  is_psd() → bool

    Return True if the file is embedded PSD/PSB.

    Checks the stored `filetype` first; if that is `None` (blank field), falls back to inspecting the first four magic bytes of the embedded data. The filename extension is intentionally not used as a fallback to avoid misclassifying non-PSD files named `*.psd`.

  property kind: str

    Kind of the link, ‘data’, ‘alias’, or ‘external’.

  open(external_dir: str | PathLike | None = None) → Iterator[IO[bytes]]

    Open the smart object as binary IO.

    Parameters:

      external_dir – Directory to resolve external paths against. When provided, a `fullPath` that resolves outside this directory is silently ignored and `relPath` is tried instead. A `relPath` that resolves outside this directory raises `ValueError`. Strongly recommended when processing untrusted PSD files.

    Example:

        with layer.smart_object.open() as f:
            data = f.read()

  property resolution: float

    Resolution of the object.

  save(filename: str | PathLike | None = None, directory: str | PathLike | None = None, external_dir: str | PathLike | None = None) → None

    Save the smart object to a file.

    Parameters:

      - filename – Explicit destination path. When provided it is used as-is and `directory` is ignored.

      - directory – Output directory used when `filename` is `None`. Defaults to the current working directory. The embedded basename is written inside this directory; path-traversal sequences in the embedded name are stripped automatically.

      - external_dir – Passed to `open()` when the smart object kind is `'external'`. Constrains which paths on disk may be read. Strongly recommended when processing untrusted PSD files.

    Raises:

      ValueError – If the embedded name contains no safe basename, resolves outside `directory`, or (for external kind) the source path escapes `external_dir`.

  property transform_box: tuple[float, float, float, float, float, float, float, float] | None

    A tuple representing the coordinates of the smart objects’s transformed box. This box is the result of one or more transformations such as scaling, rotation, translation, or skewing to the original bounding box of the smart object.

    The format of the tuple is as follows: (x1, y1, x2, y2, x3, y3, x4, y4)

    Where 1 is top left corner, 2 is top right, 3 is bottom right and 4 is bottom left.

  property unique_id: str

    UUID of the object.

  property warp: object | None

    Warp parameters.