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 filename: str

Original file name of the object.

property filesize: int

File size of the object.

property filetype: str

Preferred file extension, such as jpg.

is_psd() → bool

Return True if the file is embedded PSD/PSB.

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.