Project

class photonforge.pda.Project(document)

Live view of a PDA project or library document.

Methods

add(new_obj, *[, tag, bump_version, ...])	Add an object and any missing dependencies to the project.
add_library([name, version, library_id])	Attach a versioned library and its dependencies to the project.
add_tag(tag, *[, target])	Attach a tag to the project or a specific contained object.
add_version([version, bump_version, target])	Create a version for the selected target document reference.
attach(path, *[, target, filename, tags])	Upload a file and attach it to the project or one of its components.
attachments(*[, target, tags, all])	List attachments bound to the project or one of its components.
check_access()	Check if the current user can access this project.
components(*[, name, search, origin, ...])	Query components by exact name, regex, and origin scope.
detach(attachment, *[, target, delete])	Remove an attachment from the project or one of its components.
download_attachment(attachment)	Download the binary content of an attachment.
get_info([target])	Return metadata for the project or one contained object.
get_library_info([name])	Return metadata for one library or all imported libraries.
grant_permission(*, visibility[, ...])	Grant access permissions for the project document.
import_module(namespace, *[, reload])	Import the project and library Python modules.
list_permissions()	List sharing permissions for the project document.
list_tags([target])	Return available tags for the project or one contained object.
list_versions([target])	Return available versions for the project or one contained object.
load(target, *[, tag, version])	Load a tagged/versioned snapshot of a project object.
load_latest(*[, module_path, set_config, ...])	Reload latest project data from PDA in place.
remove_tag(tag, *[, target])	Remove one or more tags from the selected target.
retire(targets)	Retire technologies/components by object instance or name.
retire_unused()	Retire project-owned internal components unused by external ones.
revoke_permission(permission_id)	Revoke one permission by its identifier.
save_module()	Pack the loaded module directory and store it in PDA.
set(*[, name, description, labels])	Update editable project fields in-place.
set_external(component[, external])	Set/unset a component as external in the module mapping.
technologies(*[, name, search, origin])	Query technologies by exact name, regex, and origin scope.
transfer_ownership(grantee_id)	Transfer project ownership to another user identifier.
update(upd_obj, *[, tag, bump_version, ...])	Update an existing project object and optional dependencies.
update_permission(permission_id, *, role)	Change the role associated with an existing permission.

Attributes

description	Project description.
id	Project ID.
is_read_only	Project read-only state.
labels	Project labels.
module_name	Sanitized Python module name for this project.
module_path	Filesystem path where the project Python module is loaded.
name	Project name.

Parameters:

document (Document)

add(new_obj, *, tag=None, bump_version=None, update_existing_dependencies=True, update_config=True, project_tag='{datetime:%Y%m%d-%H%M%S}-{name}-{version_and_tag}', set_external=True)

Add an object and any missing dependencies to the project.

Parameters:

• new_obj (Component | Technology) – Component or technology to add.

• tag (str | None) – Optional tag applied to changed objects.

• bump_version (Literal['major', 'minor', 'patch'] | None) – Optional semantic bump for changed objects.

• update_existing_dependencies (bool) – Whether existing dependencies may be updated.

• update_config (bool) – Whether to update project config from current settings.

• project_tag (str | None) – If either tag or bump_version is not None, tag to the project using this template.

• set_external (bool) – Whether to mark this component to be external in the module pda_components mapping. Dependencies are never marked.

Returns:

Mapping with added and updated object lists.

Return type:

dict[Literal[‘added’, ‘updated’], list[~photonforge.Technology | ~photonforge.Component]]

add_library(name=None, *, version=None, library_id=None)

Attach a versioned library and its dependencies to the project.

Parameters:

• name (str | None) – Library project name when selecting by name/version.

• version (str | None) – Library version when selecting by name/version.

• library_id (str | None) – Specific library version record ID.

Returns:

None.

Return type:

object

add_tag(tag, *, target=None)

Attach a tag to the project or a specific contained object.

Parameters:

• tag (str) – Tag label to create.

• target (Component | Technology | str | None) – Optional target object or name. Defaults to project.

Returns:

Target object that received the tag.

Return type:

Component | Technology | Project

add_version(version=None, bump_version=None, *, target=None)

Create a version for the selected target document reference.

Parameters:

• version (str | None) – Explicit semantic version string.

• bump_version (Literal['major', 'minor', 'patch'] | None) – Semantic bump strategy when version is omitted.

• target (Component | Technology | str | None) – Optional target object or name. Defaults to project.

Returns:

Target object that received the version.

Return type:

Component | Technology | Project

attach(path, *, target=None, filename=None, tags=())

Upload a file and attach it to the project or one of its components.

The file is uploaded and bound to the target document on the server, which grants read access to anyone with access to that document. The binding is the association: nothing is stored in the document itself.

Parameters:

• path (str | Path) – Path to the file to upload.

• target (Component | str | None) – Component (object or name) to attach to; None (default) attaches to the project itself. Technologies are not supported.

• filename (str | None) – Optional file name override (defaults to the path name).

• tags (Sequence[str]) – Optional tags stored on the attachment. Use a tag convention (e.g. “design_manual”, “drc_ruleset”, “cross_section”, “gds”) to categorize attachments and filter them with attachments(tags=).

Returns:

Attachment metadata for the uploaded file.

Return type:

dict[str, object]

attachments(*, target=None, tags=(), all=False)

List attachments bound to the project or one of its components.

Parameters:

• target (Component | str | None) – Component (object or name) to list attachments for; None (default) lists the project’s own attachments. Technologies are not supported.

• tags (Sequence[str]) – Optional tag filter; only attachments carrying every given tag are returned.

• all (bool) – When True, list attachments across the project and every tracked component. Each returned record carries an extra owner field ({"kind": "project"} or {"kind": "component", "name": ...}). Mutually exclusive with target.

Returns:

Attachment metadata records (as returned by attach()), each with id, filename, mimeType, tags, and (when all=True) an extra owner field.

Return type:

list[dict[str, object]]

check_access()

Check if the current user can access this project.

Parameters:

None.

Returns:

Tuple (has_access, payload) from the access endpoint.

Return type:

tuple[bool, dict[str, object]]

components(*, name=None, search=None, origin=None, external_only=True)

Query components by exact name, regex, and origin scope.

Parameters:

• name (str | None) – Exact component name filter.

• search (str | Pattern | None) – Regex or pattern string filter for names.

• origin (str | DocumentId | None) – Source scope (“self”, “libraries”, or library name).

• external_only (bool) – Whether listings include only components marked external. Ignored when name or search is provided.

Returns:

Filtered component objects grouped by origin when needed.

Return type:

dict[str, dict[str, Component]] | dict[str, Component] | Component

property description: str | None

Project description.

detach(attachment, *, target=None, delete=True)

Remove an attachment from the project or one of its components.

Parameters:

• attachment (Mapping[str, object] | str) – Raw attachment ID, attachment reference from attachments(), or metadata returned by attach().

• target (Component | str | None) – Component (object or name) the attachment is on; None (default) targets the project. Technologies are not supported.

• delete (bool) – Soft-delete the attachment (default). When False the attachment is only unlinked from the target and kept.

Return type:

None

download_attachment(attachment)

Download the binary content of an attachment.

Parameters:

attachment (Mapping[str, object] | str) – Raw attachment ID, attachment reference from attachments(), or metadata returned by attach().

Returns:

Raw file bytes.

Return type:

bytes

get_info(target=None)

Return metadata for the project or one contained object.

Parameters:

target (Component | Technology | str | None) – Optional object or name to query instead of the project document.

Returns:

Metadata payload with document details, tags, and versions.

Return type:

dict[str, object]

get_library_info(name=None)

Return metadata for one library or all imported libraries.

Parameters:

name (str | None) – Optional library name. If omitted, returns all libraries.

Returns:

Metadata payload for one library, or a list of payloads for all imported libraries.

Return type:

dict[str, object] | list[dict[str, object]]

grant_permission(*, visibility, grantee_id=None, role='viewer')

Grant access permissions for the project document.

Parameters:

• visibility (Literal['private', 'organization']) – Permission visibility scope.

• grantee_id (str | None) – User or organization ID who will receive the permission.

• role (Literal['owner', 'editor', 'viewer']) – Access role to grant.

Returns:

Created permission payload.

Return type:

dict[str, object]

Notes

For organization visibility, grantee_id defaults to the current organization when available.

Important

Setting public visibility is not allowed, as it shares the contents and all dependencies with all users in the platform. Please contact support if you want to share a public library.

property id: DocumentId

Project ID.

import_module(namespace, *, reload=True)

Import the project and library Python modules.

Parameters:

• namespace (dict | None) – Optional mapping to populate with imported modules.

• reload (bool) – Whether to hard-reload project/library modules from disk.

Returns:

Mapping from module name to imported module object.

Return type:

dict[str, object]

Each imported module gets two read-only live mappings: pda_components and pda_technologies.

Example

Import parametric components from the project and its libraries in the current namespace (equivalent to using import project_module for each dependency of the project):

>>> project.import_module(globals())  

property is_read_only: bool

Project read-only state.

property labels: tuple[str]

Project labels.

list_permissions()

List sharing permissions for the project document.

Parameters:

None.

Returns:

Permission metadata list.

Return type:

list[dict[str, object]]

list_tags(target=None)

Return available tags for the project or one contained object.

Parameters:

target (Component | Technology | str | None) – Optional object or name to query instead of the project document.

Returns:

List of tag strings for the target.

Return type:

list[str]

list_versions(target=None)

Return available versions for the project or one contained object.

Parameters:

target (Component | Technology | str | None) – Optional object or name to query instead of the project document.

Returns:

List of version strings for the target.

Return type:

list[str]

load(target, *, tag=None, version=None)

Load a tagged/versioned snapshot of a project object.

Parameters:

• target (Component | Technology | str) – Component/technology object or exact name.

• tag (str | None) – Optional tag filter.

• version (str | None) – Optional version filter.

Returns:

Object snapshot matching the search parameters.

Return type:

Component | Technology

load_latest(*, module_path=None, set_config=True, reload_module=True)

Reload latest project data from PDA in place.

Parameters:

• module_path (str | Path | None) – Root directory where modules are unpacked.

• set_config (bool) – Whether to apply project config to PhotonForge.

• reload_module (bool) – Whether to reload the project module.

Returns:

This project, reloaded in its latest, writable version.

Return type:

Project

property module_name: str

Sanitized Python module name for this project.

property module_path: Path

Filesystem path where the project Python module is loaded.

property name: str

Project name.

remove_tag(tag, *, target=None)

Remove one or more tags from the selected target.

Parameters:

• tag (str | Sequence[str]) – Tag label or labels to remove.

• target (Component | Technology | str | None) – Optional target object or name. Defaults to project.

Returns:

Target object from which tags were removed.

Return type:

Component | Technology | Project

retire(targets)

Retire technologies/components by object instance or name.

Objects still referenced by remaining project content are kept and reported through a runtime warning.

Parameters:

targets (Sequence[Component | Technology | str]) – Components/technologies (or names) to retire.

Returns:

None.

Return type:

None

retire_unused()

Retire project-owned internal components unused by external ones.

Return type:

None

revoke_permission(permission_id)

Revoke one permission by its identifier.

Parameters:

permission_id (str) – Permission identifier.

Returns:

None.

Return type:

None

save_module()

Pack the loaded module directory and store it in PDA.

The module includes all files in the directory project.module_path / project.module_name.

Return type:

None

set(*, name=None, description=None, labels=None)

Update editable project fields in-place.

Parameters:

• name (str | None) – Optional replacement project name.

• description (str | None) – Optional replacement project description.

• labels (Sequence[str] | None) – Optional replacement label collection.

Return type:

None

set_external(component, external=True)

Set/unset a component as external in the module mapping.

Parameters:

• component (Component | str) – Component object or component name to set.

• external (bool) – Set/unset flag.

Return type:

None

technologies(*, name=None, search=None, origin=None)

Query technologies by exact name, regex, and origin scope.

Parameters:

• name (str | None) – Exact technology name filter.

• search (str | Pattern | None) – Regex or pattern string filter for names.

• origin (str | DocumentId | None) – Source scope (“self”, “libraries”, or library name).

Returns:

Filtered technology objects grouped by origin when needed.

Return type:

dict[str, dict[str, Technology]] | dict[str, Technology] | Technology

transfer_ownership(grantee_id)

Transfer project ownership to another user identifier.

Parameters:

grantee_id (str) – Identifier of the new owner.

Returns:

Updated owner permission payload.

Return type:

dict[str, object]

update(upd_obj, *, tag=None, bump_version=None, update_existing_dependencies=True, update_config=True, project_tag='{datetime:%Y%m%d-%H%M%S}-{name}-{version_and_tag}')

Update an existing project object and optional dependencies.

Parameters:

• upd_obj (Component | Technology) – Component or technology to update.

• tag (str | None) – Optional tag applied to changed objects.

• bump_version (Literal['major', 'minor', 'patch'] | None) – Optional semantic bump for changed objects.

• update_existing_dependencies (bool) – Whether existing dependencies may be updated.

• update_config (bool) – Whether to update project config from current setting.

• project_tag (str | None) – If either tag or bump_version is not None, tag to the project using this template.

Returns:

Mapping with added and updated object lists.

Return type:

dict[Literal[‘added’, ‘updated’], list[~photonforge.Technology | ~photonforge.Component]]

update_permission(permission_id, *, role)

Change the role associated with an existing permission.

Parameters:

• permission_id (str) – Permission identifier.

• role (Literal['editor', 'viewer']) – New role value.

Returns:

Updated permission payload.

Return type:

dict[str, object]