Project¶

class photonforge.pda.Project(document)[source]¶

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_module_file`(path)	Copy a Python file into the project module, save it, and import it.
`add_tag`(tag, *[, target])	Attach a tag to the project or a specific contained object.
`add_version`([version, bump_version, target, ...])	Add a version to the project or one object in it, and tag its files.
`attach`(path, *[, target, filename, tags])	Upload a file and attach it to the project or one of its objects.
`attach_query`(*, target, table, source[, ...])	Attach a pointer to rows held somewhere else.
`attachment_status`(*[, version, tag_prefix, ...])	Report what the project holds and where its gaps are.
`attachments`(*[, target, tags, all, search])	List attachments bound to the project or one of its objects.
`changed_since`([mark, target, fields, ignore])	The saves made after `mark`: empty, and so falsy, when there were none.
`check_access`()	Check if the current user can access this project.
`component`(name, *[, version, save])	One component, by the name it has in the 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.
`edit_log`([target, since, limit, fields, ignore])	Every save to one document, oldest first, including unversioned ones.
`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.
`latest_head`([target])	Where a document stands now: the id of its newest save.
`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, save])	Load a tagged/versioned snapshot of a project object.
`load_latest`(*[, module_path, set_config, ...])	Bring this copy of the project up to date with everyone's saves.
`load_query`(attachment)	Read a pointer back off its attachment.
`remove_tag`(tag, *[, target])	Remove one or more tags from the selected target.
`restore`(names, *[, external])	Restore retired technologies/components by name.
`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.
`run_query`(attachment, *, connection[, ...])	Read the rows a pointer names, through a connection you opened.
`save_module`()	Pack the loaded module directory and store it in PDA.
`set`(*[, name, description, labels, module_name])	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.
`technology`(name, *[, version, save])	One technology, by name, as `component()` finds a component.
`trace`(attachment, *[, tag_prefix, rebuild])	Walk an attached file back to the design it describes.
`traceability_matrix`([target, tag_prefix])	Which file belongs to which version: a row per file, a column per version.
`transfer_ownership`(grantee_id)	Transfer project ownership to another user identifier.
`tree`([target])	What is in the project, as a tree.
`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.
`version_history`([target, kinds, limit, all, ...])	The numbered versions and tags of the project or one object in it.
`watch`([target, interval, fields, ignore])	Call `on_change` whenever a save to this document reaches you.

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='{name}-{version_and_tag}', set_external=True)[source]¶

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, with name, version, tag, version_and_tag and datetime fields. The name is trimmed to keep the tag within the server’s limit, and a label the project already carries is reported, not fatal.
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)[source]¶

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_module_file(path)[source]¶

Copy a Python file into the project module, save it, and import it.

A parametric component or technology is Python code, and a component built from code that lives only on your machine can be opened by a colleague but not changed. This puts the file in the project’s code folder, re-exports its parametric_component and parametric_technology functions from the project module, uploads the module, and imports it here. Adding the same file again replaces the code. A file with no such function is added too, for the helpers the others import.

>>> bend = project.add_module_file("bend.py")  
>>> project.add(bend.waveguide_bend(radius=3.0))  

A colleague gets the code with load_latest() and import_module(). It runs on import, for everyone.

Parameters:

path (str | Path) – A .py file with a plain name, like bend.py. A path inside the module folder is fine: the file is already in place.

Returns:

The imported submodule, project_module.<name>. A handle from before the next reload is stale; take a fresh one from import_module().

Raises:

RuntimeError – The project is read only, has no module loaded, or its code changed on the server since this copy was loaded; call load_latest() first, so nobody else’s file is overwritten.
ValueError – The name is reserved, or the file exports a function another file already exports.

Return type:

ModuleType

add_tag(tag, *, target=None)[source]¶

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, message=None, tag_prefix='version:')[source]¶

Add a version to the project or one object in it, and tag its files.

A version freezes the document. It does not freeze the list of attachments, because an attachment is a row bound to a document id and a row has no history for a version to pin. So this also writes <tag_prefix><version> onto every attachment on the target that does not already claim one; that tag is what trace() and attachment_status() read back. Nor does an object’s version pin the rest of the design, so the project’s own pinned ref is recorded with it; load() and trace() rebuild the whole design from that.

Parameters:

version (str | None) – Explicit version string.
bump_version (Literal['major', 'minor', 'patch'] | None) – Bump strategy when version is omitted.
target (Component | Technology | str | None) – Object or name to version. Defaults to the project.
message (str | None) – Message recorded with the version, at most 1000 characters. A server that does not record one ignores it; nothing is written elsewhere to compensate, because a tag and a message are different things.
tag_prefix (str | None) – Prefix of the tag written onto the attachments; None leaves them untouched.

Returns:

A Version mapping naming the version, and which attachments were stamped, skipped or failed.

Return type:

Version

Note

Stamping is not atomic, on purpose. A failed stamp leaves the version in place and is reported in Version.failed; calling again with that same explicit version stamps what is left and warns that the version already existed, rather than failing on it. With tag_prefix=None an existing version is an error.

attach(path, *, target=None, filename=None, tags=())[source]¶

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

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 | Technology | str | None) – Component or technology (object or name) to attach to; None (default) attaches to the project itself.
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]

attach_query(*, target, table, source, fixed=None, filterable=(), columns=(), units=None, schema=None, row_count=None, captured_version=None, filename=None, tags=())[source]¶

Attach a pointer to rows held somewhere else.

Measurement data is structured and large; attachments are opaque files. Rather than copy millions of rows into the project, this stores where they are: which table or view, which rows it is always about, and which column a reader may narrow on.

>>> pointer = project.attach_query(  
...     target="grating",                 # the design the rows describe
...     source="lab database",            # a label for where the rows live
...     table="spectra_with_run",         # the table or view to read
...     fixed={"serial": "GC-01"},        # always these rows
...     filterable=["run_id"],            # a reader may narrow by run
... )

No SQL is stored. The only statement run_query() composes is SELECT <columns> FROM <table> WHERE <column> = <value> AND ..., with identifiers quoted and values bound for the caller’s own driver. Put a join or an aggregate in a database view and point at the view.

Parameters:

target (Component | Technology | str) – The design the rows describe.
table (str) – Table or view to read. A plain identifier.
source (str) – A label for the system holding the rows, for a reader. Nothing checks the connection against it.
fixed (Mapping[str, object] | None) – Values this pointer is always about, as {column: value}, such as the device serial. A reader cannot change them.
filterable (Sequence[str]) – Columns a reader may narrow on with run_query(where=...). One the reader leaves unset narrows nothing.
columns (Sequence[str]) – Columns to return. Empty (default) returns every column.
units (Mapping[str, str] | None) – Optional column-to-unit map, for whoever plots the result.
schema (str | None) – Optional namespace for table.
row_count (int | None) – Row count when the pointer was written, as a sanity check.
captured_version (str | None) – Version the pointer was captured against.
filename (str | None) – Attachment name. Defaults to one built from table and fixed, so two pointers on one design do not collide.
tags (Sequence[str]) – Extra tags, alongside dataset_pointer.

Returns:

A BoundQuery.

Return type:

BoundQuery

Note

No credential is stored. run_query() takes a live connection that the caller opens.

attachment_status(*, version=None, tag_prefix='version:', include_empty=False)[source]¶

Report what the project holds and where its gaps are.

The status check a lead runs. Alongside the inventory it returns the two lists worth acting on: files carrying no version tag, so nothing says which version they belong to, and files naming a version older than their object’s newest one.

Parameters:

version (str | None) – Restrict the summary to one version.
tag_prefix (str) – Prefix of the tag that names a version.
include_empty (bool) – Also list objects carrying no version and no file. A tape-out project holds a cell per DoE variant, and ninety empty rows bury the two that matter.

Returns:

A AttachmentStatus mapping, which draws itself when printed or displayed in a notebook.

Return type:

AttachmentStatus

Note

Whether a measurement taken against an older version still describes the current component is a question for a person. This only says where to ask it.

attachments(*, target=None, tags=(), all=False, search=None)[source]¶

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

Parameters:

target (Component | Technology | str | None) – Component or technology (object or name) to list attachments for; None (default) lists the project’s own attachments.
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 and technology. Each returned record carries an extra owner field ({"kind": "project"} or {"kind": "component" | "technology", "name": ...}). Mutually exclusive with target.
search (str | None) – Case-insensitive substring of the filename, matched the same way the browser matches it. Sync-api filters server-side; the filter is applied again locally so an older server that ignores it still returns the right list.

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

changed_since(mark=None, *, target=None, fields=None, ignore=None)[source]¶

The saves made after mark: empty, and so falsy, when there were none.

>>> mark = project.latest_head("ring")  
>>> ...
>>> if project.changed_since(mark, fields=["parameters"]):  
...     raise RuntimeError("somebody else got there first")

Checking narrows the risk of overwriting a colleague; it does not remove it. A save that lands between this check and your own still wins.

Parameters:

mark (Head | Sequence[str] | Component | Technology | str | None) – The result of latest_head(). It remembers its object, so no name is needed. A marker kept as a plain list of strings (after a round trip through JSON) needs target.
target (Component | Technology | str | None) – The object, when mark is a plain list of strings.
fields (str | Sequence[str] | None) – Report only these parts of the document, as in edit_log(). Without it, any save at all counts.
ignore (Sequence[str] | None) – Top-level fields to leave out; None means the default for the document’s kind.

Returns:

An EditLog of the saves after mark that changed something reported.

Return type:

EditLog

check_access()[source]¶

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

component(name, *, version=None, save=None)[source]¶

One component, by the name it has in the project.

>>> bend = project.component("bend")  
>>> wide = project.component("bend", save=5)  

Parameters:

name (str) – The component’s name (not the parametric function’s).
version (str | None) – Leave out for your copy as it stands (call load_latest() first to include everyone’s saves); give one to rebuild the design at that version, as load() does.
save (int | Edit | None) – A save number from edit_log(), to rebuild the design as it was right after that save, versioned or not.

Returns:

The component. Looks in this project first, then its libraries; a library’s component can be read but not rebuilt at a version or save from here, since those belong to the library.

Return type:

Component

components(*, name=None, search=None, origin=None, external_only=True)[source]¶

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)[source]¶

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 | Technology | str | None) – Component or technology (object or name) the attachment is on; None (default) targets the project.
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)[source]¶

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

edit_log(target=None, *, since=None, limit=None, fields=None, ignore=None)[source]¶

Every save to one document, oldest first, including unversioned ones.

version_history() lists versions and tags, so a save nobody versioned is invisible to it. The change stream still holds every one; diffing the document after each save against the one before reports what moved as field: before -> after – parameters.radius on a component, layers.SiN.thickness on a technology, components[3] on the project. That is how you recover a value somebody overwrote.

>>> project.edit_log("bend", fields=["parameters"])  

Parameters:

target (Component | Technology | str | None) – The component or technology, or its name (the name it has in the project, not the parametric function’s); None (default) reads the project document itself.
since (Sequence[str] | None) – A marker from latest_head(); only the saves after it are returned. When target is not given, the marker’s own object is used.
limit (int | None) – Keep only the newest this many saves.
fields (str | Sequence[str] | None) – Report only these parts of the document: "parameters" for any knob, "parameters.radius" for one. One string or a list. A field the document does not have is refused. Without it you also see internal fields, such as pfNative, the fingerprint of the stored geometry, which changes on every save.
ignore (Sequence[str] | None) – Top-level fields to leave out of the report. None (default) drops what the system re-derives from the rest of the document – a component’s preview, the project’s schema registries – as listed in photonforge.pda._edits.IGNORED. Pass () to see everything.

Returns:

An EditLog, oldest first, which prints as a table. A row whose only changes were ignored is kept with nothing reported; EditLog.effective drops such rows.

Return type:

EditLog

Note

The chain carries neither a wall clock nor a user: changes are written with a zero timestamp and an actor that identifies a session, one run of Python. Rows report order and session, never date and person.

get_info(target=None)[source]¶

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)[source]¶

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')[source]¶

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)[source]¶

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.

latest_head(target=None)[source]¶

Where a document stands now: the id of its newest save.

Like Git’s HEAD, but per object: each component and technology has its own history, and the project has its own. It reads the server and changes nothing. Keep it, then ask changed_since() whether anyone saved after it:

>>> project.load_latest()  
>>> mark = project.latest_head("bend")  
>>> if project.changed_since(mark, fields=["parameters"]):  
...     print("someone changed it; look before you save")

Parameters:: target (Component | Technology | str | None) – The component or technology, or its name (the name it has in the project, not the parametric function’s); None (default) for the project document.
Returns:: opaque, safe to keep, and it remembers target.
Return type:: A Head

list_permissions()[source]¶

List sharing permissions for the project document.

Parameters:: None.
Returns:: Permission metadata list.
Return type:: list[dict[str, object]]

list_tags(target=None)[source]¶

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)[source]¶

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, save=None)[source]¶

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.
save (int | Edit | None) – Instead of a tag or version, a save number from edit_log() (or one of its rows): the object as it was right after that save, whether anyone versioned it or not.

Returns:

Object snapshot matching the search parameters.

Return type:

Component | Technology

Note

The object comes back as the whole design was at that moment. For a save, that is the project state the same save wrote. For a version or tag, it is the project state add_version() and update() record with every version and tag they make, which supplies the technology, subcomponents and configuration of that moment. A version or tag recorded without one, by an older server, raises rather than guessing, and the message names the save to load instead. Grid and tolerance stay the session’s.

load_latest(*, module_path=None, set_config=True, reload_module=True)[source]¶

Bring this copy of the project up to date with everyone’s saves.

This is the live state, not a numbered version (load() rebuilds one of those), and it uploads nothing of yours. An open copy does not update by itself, so call this before editing: a save from an out-of-date copy can undo someone else’s work, or write nothing.

With reload_module, the project’s code is unpacked again and, if it had been imported, imported again, so parametric components stay editable. Components you hold in variables are not changed; take fresh ones from components().

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

load_query(attachment)[source]¶

Read a pointer back off its attachment.

Parameters:: attachment (Mapping[str, object] | str) – The pointer attachment record or its id.
Returns:: A BoundQuery. Its names are re-checked on the way in, because the attachment may have been written by somebody else.
Return type:: BoundQuery

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)[source]¶

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

restore(names, *, external=False)[source]¶

Restore retired technologies/components by name.

The most recently retired object with each name is restored.

Parameters:

names (Sequence[str]) – Names of retired components/technologies.
external (bool) – Whether restored components are marked external.

Returns:

None.

Return type:

None

retire(targets)[source]¶

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()[source]¶

Retire project-owned internal components unused by external ones.

Return type:: None

revoke_permission(permission_id)[source]¶

Revoke one permission by its identifier.

Parameters:: permission_id (str) – Permission identifier.
Returns:: None.
Return type:: None

run_query(attachment, *, connection, where=None, limit=None)[source]¶

Read the rows a pointer names, through a connection you opened.

The statement is composed here from the pointer’s pieces, quoted and parameterised for whatever driver connection belongs to, so the same pointer reads from PostgreSQL, SQLite, MySQL, SQL Server, Oracle or DuckDB without being rewritten.

Parameters:

attachment (Mapping[str, object] | str | BoundQuery) – A BoundQuery, or the pointer attachment.
connection (object) – An open DB-API or SQLAlchemy connection. Never stored.
where (Mapping[str, object] | None) – Values for the columns the pointer offers as filters. A key it does not offer is refused rather than appended; one left out narrows nothing.
limit (int | None) – Stop after this many rows. Applied while fetching, since no row-limit syntax is common to every dialect.

Returns:

A pandas.DataFrame when pandas is available, else a list of rows.

Return type:

object

save_module()[source]¶

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, module_name=None)[source]¶

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.
module_name (str | None) – Optional replacement Python module name. Only allowed before the module is first saved; afterwards the name is pinned to the stored archive.

Return type:

None

set_external(component, external=True)[source]¶

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)[source]¶

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

technology(name, *, version=None, save=None)[source]¶

One technology, by name, as component() finds a component.

Parameters:

name (str)
version (str | None)
save (int | Edit | None)

Return type:

Technology

trace(attachment, *, tag_prefix='version:', rebuild=True)[source]¶

Walk an attached file back to the design it describes.

Four hops: the file’s version: tag names a version, that version is a row on the document the file is bound to, the row carries a reference pinning one exact moment, and resolving it rebuilds the object as the whole design was then; see load().

Parameters:

attachment (Mapping[str, object] | str) – An attachment record or its id.
tag_prefix (str) – Prefix of the tag that names a version.
rebuild (bool) – Resolve the reference and return the rebuilt object as Trace.component or Trace.technology.

Returns:

A Trace mapping, which draws the chain when printed or displayed and reports how solid the first hop was.

Return type:

Trace

Note

Only the first hop is a convention. Trace.confidence is "tag" when the file named a version, "unambiguous" when it did not but the document has exactly one, "missing" when the tag names a version that does not exist, and "none" otherwise. In the last two cases the candidates are returned rather than guessed between.

traceability_matrix(target=None, *, tag_prefix='version:')[source]¶

Which file belongs to which version: a row per file, a column per version.

✓ marks the version a file is labelled for; · a version its target has that the file is not labelled for. A file labelled with a version its target does not have, a typo such as version:1.0 for 1.0.0, is flagged.

Parameters:

target (Component | Technology | str | None) – Only the files on this component or technology; None for every file.
tag_prefix (str) – Prefix of the tag that names a version.

Returns:

A TraceabilityMatrix; .data_frame for pandas.

Return type:

TraceabilityMatrix

transfer_ownership(grantee_id)[source]¶

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]

tree(target=None)[source]¶

What is in the project, as a tree.

Its technologies with the files kept with them, its libraries, its source files and their unsaved changes, its top-level components with their newest version and how many cells and files each holds, the cells inside, and the files with the version each names. It is an overview, so it stays readable at any size: a component with many files or cells gets one summary line, which says tree(target=...) lists them. A notebook draws it; print gives it like the tree command; .mermaid() and .svg() are the drawings.

>>> project.tree()  
>>> project.tree("gc_doe_reticle")  # one component, with far more listed  

Parameters:: target (Component | Technology | str | None) – One component or technology to zoom into; None for the whole project.
Return type:: ProjectTree

update(upd_obj, *, tag=None, bump_version=None, update_existing_dependencies=True, update_config=True, project_tag='{name}-{version_and_tag}')[source]¶

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, with name, version, tag, version_and_tag and datetime fields. The name is trimmed to keep the tag within the server’s limit, and a label the project already carries is reported, not fatal.

Returns:

Mapping with added and updated object lists.

Return type:

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

update_permission(permission_id, *, role)[source]¶

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]

version_history(target=None, *, kinds=('version', 'tag'), limit=None, all=False, diff=False)[source]¶

The numbered versions and tags of the project or one object in it.

Each entry says who made it and when. For every save in between, versioned or not, see edit_log().

Parameters:

target (Component | Technology | str | None) – Object or name to query instead of the project document.
kinds (Sequence[str]) – Entry kinds to include, from "version" and "tag".
limit (int | None) – Keep only this many entries, after sorting newest first.
all (bool) – Merge the project and every component and technology it owns into one view, each on its own lane. Cannot be combined with target.
diff (bool) – Report what changed between consecutive versions.

Returns:

with the sequence of events.

Return type:

A History

watch(target=None, *, on_change, interval=0.5, fields=None, ignore=None)[source]¶

Call on_change whenever a save to this document reaches you.

It runs in the background, from now until cancel() or until this Python process ends: saves made while it is not running are not reported, so keep a latest_head() marker and call changed_since() when you come back. It fires on anyone’s saves, your own included, not when you use the object. It checks every interval seconds; a save from another machine usually arrives within a second or two.

The callback runs on the client’s event loop, so it cannot call this project’s methods and should be short: print, set a flag, queue something. It is handed the EditLog of what arrived, reduced to the saves that changed something reported. If it raises, the watch stops and Watcher.error holds the reason.

Parameters:

target (Component | Technology | str | None) – The component or technology, or its name; None (default) for the project document.
on_change (Callable[[EditLog], object]) – Called with one EditLog argument.
interval (float) – Seconds between checks.
fields (str | Sequence[str] | None) – Only fire for changes to these parts, as in edit_log().
ignore (Sequence[str] | None) – Top-level fields to leave out; None means the default for the document’s kind.

Returns:

A Watcher. Call cancel() when you are done.

Return type:

Watcher