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.
check_access()	Check if the current user can access this project.
components(*[, name, search, origin])	Query components by exact name, regex, and origin scope.
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.
load(target, *[, tag, version])	Load a tagged/versioned snapshot of a project object.
reload(*[, 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.
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.
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, 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.

• 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

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)

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).

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.

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]

The returned payload includes matching tags and versions for the current document reference.

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.

Raises:

RuntimeError – If name is provided and no matching library is found.

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 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]]

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:

One object for a unique match, otherwise a list of matches.

Return type:

Component | Technology | list[Component | Technology]

Returns one object when selection resolves to a single reference, otherwise returns all matching snapshots.

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.

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

Reload latest project data from PDA in place.

Parameters:

• module_path (str | Path | None)

• set_config (bool)

• reload_module (bool)

Return type:

Project

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.

Parameters:

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

Returns:

None.

Return type:

None

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

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.

Raises:

RuntimeError – If the project is read-only.

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)

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.

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]