psd_tools.api.smart_object

Smart object module.

SmartObject

class psd_tools.api.smart_object.SmartObject(layer: LayerProtocol)[source]

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 default confinement, so the read is restricted to the current working directory and an absolute fullPath pointing outside it is ignored. Use open() with an explicit external_dir to read linked files from a known location, or open(trust_full_path=True) to restore the historical unconfined behaviour for fully trusted 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[source]

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, *, trust_full_path: bool = False) → Iterator[IO[bytes]][source]

Open the smart object as binary IO.

For external smart objects the linked file is read from disk. By default the read is confined to a directory: external_dir when given, otherwise the current working directory. A fullPath stored in the PSD is honoured only when it resolves inside that directory; otherwise it is ignored and relPath (resolved inside the directory) is tried instead. A relPath that escapes the directory raises ValueError. This default prevents a crafted PSD from reading arbitrary files via an absolute fullPath. Note that the confinement directory itself is trusted: a relPath resolving to a file inside it is still read, so point external_dir at a location that holds only linked assets when processing untrusted files.

Parameters:

  • external_dir – Directory to resolve and confine external paths against. Defaults to the current working directory. Strongly recommended to set explicitly when processing untrusted PSD files.

  • trust_full_path – When True, disable confinement entirely and trust fullPath/relPath from the PSD verbatim (the historical behaviour). Only use this for fully trusted files. Cannot be combined with external_dir.

Raises:

ValueError – If trust_full_path is combined with external_dir, or a relPath escapes the confinement directory.

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, *, trust_full_path: bool = False) → None[source]

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.

  • trust_full_path – Passed to open() when the smart object kind is 'external'. When True, disable read confinement and trust the PSD paths verbatim. Cannot be combined with external_dir.

Raises:

ValueError – If the embedded name contains no safe basename, resolves outside directory, trust_full_path is combined with external_dir, 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.