Repository navigation
Handler Python API
tactic_handler_api provides object access, editing, file transfers, check-in
and optional UI commands from local Python and connected DCC applications.
In the Handler Script Editor and a connected DCC, import the running API the same way. It uses the existing UI and Commit Queue; do not close it. Local Python runs on the GUI thread, so submit data work and inspect its result in a subsequent command. UI commands dispatch themselves.
from tactic_handler_api import get_api
th = get_api()
operation = th.submit(lambda: [project.get_code() for project in th.projects()])
# In a later command, when operation.done is True:
print(operation.result())Importing the standalone API does not load Qt. Localized date presentation loads
Qt only when called. Server procedure source is checked by content, including
bundled .source files; changing source without changing its size or timestamp
cannot reuse an older executable body. Parsing is cached for four source bodies.
For a standalone script, use the existing configured Handler session. This does not open windows, connect a DCC, or switch the application's current project:
from tactic_handler_api import local
with local() as th:
project = th.project("demo")
stype = project.stype("types/object")
result = stype.query(limit=50, order_by=["name asc"])
for sobject in result.items:
print(sobject.get_code(), sobject.get_value("name"))demo, types/object, codes, fields, pipelines, processes and contexts below are
examples. Use actual values from your server. The Search Type namespace is not
assumed to equal the project code. The standalone factory borrows Handler's
TACTIC authentication/configuration. Keep one runtime per script/service and
close it at shutdown.
Inside an already connected DCC:
from tactic_handler_api import get_api
th = get_api()
operation = th.submit(lambda: th.project("demo").stype("types/object").get(code="O1"))
# In a later command:
if operation.done:
print(operation.result().get_info())
# The Maya runtime owns and closes this borrowed API.This reuses the same thin-client connection. TACTIC queries, repository downloads
and uploads run in Handler, not Maya. To own a separate API lifetime, use
from tactic_handler_api import from_client then
th = from_client(maya.runtime().client) and close it at teardown.
Closing that API closes its executor and remote handles, not the borrowed DCC
connection. Handles are isolated per API session; release() frees a specific
remote handle. The service bounds sessions to 64 and handles to 4096 per session,
and expires inactive abandoned sessions after 30 minutes on the next request.
The following surface is available in local Python and the DCC API.
A repeated return type refers to the same subtree below;
dict, list, tuple and scalar values are data, not additional method owners.
Native* identifies existing Handler objects exposed through the remote
allowlist. Their common public methods are expanded here;
additional local-only thlib internals are not part of this contract.
th
├─ projects() -> list[Project]
├─ project(project_code) -> Project
│ ├─ get_code() -> str
│ ├─ get_info() -> mapping of project fields
│ ├─ stypes() -> list[SType]
│ ├─ stype(search_type) -> SType
│ │ ├─ get_code() -> str
│ │ ├─ get_info() -> mapping of Search Type fields
│ │ ├─ get_project() -> Project
│ │ ├─ get_columns_info() -> {column: metadata dict}
│ │ ├─ get(code=... | id=...) -> SObject
│ │ ├─ new(values, parent=..., relation=..., direction=...) -> unsaved SObject
│ │ ├─ query(filters, order_by=..., limit=50, offset=0,
│ │ │ include_snapshots=False) -> SearchResult
│ │ │ ├─ items -> tuple[SObject, ...] (objects loaded by this query)
│ │ │ ├─ offset, limit -> int
│ │ │ ├─ total -> int | None (total matching count, when available)
│ │ │ ├─ has_more -> bool
│ │ │ └─ next() -> SearchResult (explicitly load the next portion)
│ │ ├─ pipelines() -> list[NativePipeline]
│ │ │ └─ each NativePipeline
│ │ │ ├─ get_info() -> dict (code, search_type, pipeline XML, ...)
│ │ │ ├─ get_all_pipeline_names() -> list[str] (process names)
│ │ │ ├─ get_all_tasks_pipelines_names() -> list[str] (task pipeline codes)
│ │ │ ├─ get_all_pipeline_process() -> list[dict] (config/process records)
│ │ │ ├─ get_pipeline_process(process_code) -> process record dict | None
│ │ │ ├─ get_process_info(process) -> XML node attributes dict | None
│ │ │ ├─ get_processes_info_by_type(type) -> list[node attributes dict]
│ │ │ └─ get_process_label(process) -> str
│ │ ├─ schema() -> NativeSchema | None
│ │ │ ├─ get_info() -> dict (schema search_type node attributes)
│ │ │ ├─ get_parents(), get_children() -> list[connection dict]
│ │ │ ├─ get_child(child_stype, parent_stype) -> connection dict | None
│ │ │ ├─ get_parent(parent_stype, child_stype) -> connection dict | None
│ │ │ ├─ get_child_instance(instance_type, related_type) -> connection dict | None
│ │ │ └─ get_parent_instance(instance_type, related_type) -> connection dict | None
│ │ └─ definitions -> DefinitionCatalog (Search Type scope; expanded below)
│ ├─ workflow() -> NativeWorkflow
│ │ ├─ get_all_pipelines() -> {search_type: {pipeline_code: NativePipeline}}
│ │ ├─ get_by_stype_code(code) -> {pipeline_code: NativePipeline} | None
│ │ ├─ get_by_pipeline_code(stype_code, pipeline_code) -> NativePipeline | None
│ │ ├─ get_by_process_node_type(stype_code, node_type) -> NativePipeline | None
│ │ ├─ get_child_pipeline_by_process_code(parent_pipeline, process)
│ │ │ -> NativePipeline | None (task/child pipeline; same pipeline methods)
│ │ └─ get_pipeline_by_parent(parent_process) -> NativePipeline | None
│ ├─ download_scripts() -> list[dict] (script records; also stores files locally)
│ ├─ require_script_access(path) -> bool (fresh authenticated group check; raises PermissionError on denial)
│ └─ definitions -> DefinitionCatalog (project scope)
│ ├─ list(search_type=..., view=..., login=..., limit=100, offset=0)
│ │ -> list[Definition]
│ ├─ get(config_code) -> Definition
│ ├─ new(view, xml, search_type=..., login="") -> unsaved Definition
│ │ └─ Definition (same for list/get)
│ │ ├─ code, search_type, view, login, xml -> stored identity and XML
│ │ ├─ set_xml(xml), validate() -> None
│ │ ├─ element(name) -> DefinitionElement
│ │ │ ├─ name -> str
│ │ │ ├─ set_attribute(name, value) -> None
│ │ │ ├─ set_widget(section, class_name) -> None
│ │ │ └─ set_option(section, name, value) -> None
│ │ └─ commit() -> this Definition
│ └─ resolve(view, search_type=...) -> ResolvedDefinition (read-only)
│ └─ search_type, view, xml -> str
├─ sobject(search_key) -> SObject
│ ├─ get_code() -> str | None (new objects may not have a code)
│ ├─ get_search_key() -> str (requires a saved object)
│ ├─ get_project() -> Project
│ ├─ get_stype() -> SType
│ ├─ get_info() -> mapping (including staged changes)
│ ├─ get_value(column) -> field value
│ ├─ changes() -> dict of staged values
│ ├─ set_value(column, value), discard_changes() -> None
│ ├─ commit(), refresh() -> this SObject
│ ├─ related(search_type=..., direction="child", filters=...) -> list[SObject]
│ ├─ tasks(process=None) -> list[SObject] (sthpw/task; same edit/commit methods)
│ ├─ notes(process=None, context=None) -> list[SObject] (sthpw/note)
│ ├─ snapshots(process=None) -> list[Snapshot] (expanded below)
│ ├─ dependencies() -> {search_type: {search_key: NativeSObject}}
│ │ └─ each NativeSObject (read-only remote surface)
│ │ ├─ get_info() -> dict
│ │ ├─ get_code(), get_search_key() -> identity
│ │ └─ get_value(column) -> field value
│ └─ delete(dependencies=...) -> list[dict] of deleted records; immediate server write
├─ snapshot(search_key) -> Snapshot
│ ├─ get_info() -> mapping of snapshot fields
│ ├─ get_code(), get_search_key() -> str
│ ├─ get_version() -> version from TACTIC
│ ├─ is_latest() -> native latest flag
│ ├─ is_versionless() -> bool
│ ├─ get_previewable_files_objects() -> list[NativeFile]
│ └─ get_files_objects() -> list[NativeFile]
│ └─ each NativeFile (also returned by preview accessors)
│ ├─ get_info(), get_dict() -> file record dict
│ ├─ get_code(), get_search_key(), get_unique_id() -> native identity
│ ├─ get_value(column) -> field value
│ ├─ get_type(), get_base_type(), get_ext() -> str
│ ├─ get_filename_with_ext(), get_filename(), get_filename_no_type_prefix() -> str
│ ├─ get_repo_path(), get_abs_path(), get_full_abs_path() -> local path str
│ ├─ get_web_path(), get_full_web_path() -> URL str
│ ├─ get_file_size(check_real_size=False) -> size
│ ├─ get_md5() -> str
│ ├─ get_timestamp(obj=False, pretty=False, simple=False) -> native timestamp
│ ├─ get_metadata() -> decoded metadata or original stored value
│ ├─ is_exists(), is_local_current(timestamp_tolerance=2.0), is_previewable() -> bool
│ ├─ get_web_preview(), get_icon_preview() -> NativeFile | None (not URL)
│ └─ get_meta_file_object() -> NativeFileObject | None (expanded under files)
├─ logins() -> list[NativeLogin]
├─ login(login_name) -> NativeLogin
│ ├─ get_info() -> dict
│ ├─ get_login(), get_code(), get_project_code(), get_display_name() -> str
│ ├─ check_security(group, path, project=None) -> native access value | None
│ ├─ get_login_groups() -> list[NativeLoginGroup] (membership)
│ ├─ get_all_login_groups() -> list[NativeLoginGroup] (all loaded groups)
│ └─ get_login_group(login_group_code) -> NativeLoginGroup | None
│ ├─ get_info() -> dict
│ ├─ get_code(), get_login_group(), get_pretty_name() -> str
│ └─ get_description() -> stored description
├─ files -> FilesAPI
│ ├─ match(paths, templates=None) -> list[NativeFileObject]
│ │ └─ each NativeFileObject (matched file/sequence/UDIM group, not a DB File)
│ │ ├─ get_all_files_list(first=False, filenames=False, no_ext=False) -> list[str] | str
│ │ ├─ get_name_part(), get_file_ext(), get_pretty_file_name(), get_type() -> str
│ │ ├─ get_sizes_list(together=False, files_list=None) -> list[size] | total size | None
│ │ ├─ get_metadata() -> dict (template, frames/tiles, app_info when present, ...)
│ │ └─ is_previewable() -> bool
│ ├─ ensure_local(file, overwrite="cancel", verify_md5=False) -> Path
│ ├─ open(file) -> Path (download if needed, then native opener)
│ └─ reveal(file) -> Path (show folder)
├─ repositories -> RepositoriesAPI
│ ├─ list() -> list[repository dict]
│ ├─ get(repository_code) -> repository dict
│ └─ sync(snapshot_or_files, overwrite="cancel", verify_md5=False) -> list[Path]
├─ commit_queue(project_code=None) -> CommitQueue (no window required)
│ ├─ get(operation_id) -> QueueItem
│ ├─ items(search_key=None, state=None) -> list[QueueItem]
│ ├─ add(target, context=..., files=..., repository=..., description=..., ...)
│ │ -> QueueItem (prepared, not uploaded)
│ │ ├─ id -> str
│ │ ├─ state -> str
│ │ ├─ set_description(text) -> None
│ │ ├─ commit() -> Snapshot (confirmed check-in)
│ │ ├─ submit() -> Operation[Snapshot]
│ │ └─ remove() -> None
│ └─ remove_completed() -> int (removed count)
├─ ui -> UIAPI (optional; no QObjects exposed)
│ ├─ show() -> Operation[UIAPI]
│ ├─ checkin_files(search_key, context, description, paths) -> Operation[UIAPI]
│ ├─ project(project_code) -> ProjectUI
│ │ ├─ project_code -> str
│ │ ├─ show() -> Operation[ProjectUI]
│ │ └─ commit_queue() -> WindowUI
│ ├─ sobject(search_key_or_object) -> SObjectUI
│ │ ├─ identity -> SearchKey
│ │ ├─ show() -> Operation[SObjectUI]
│ │ ├─ snapshots(), notes(), tasks() -> DockUI (with target navigation)
│ │ └─ commit_queue() -> WindowUI (with target navigation)
│ ├─ window(window_id) -> WindowUI
│ │ ├─ id -> str
│ │ └─ show() -> Operation[WindowUI]
│ └─ dock(dock_id) -> DockUI
│ ├─ id -> str
│ └─ show() -> Operation[DockUI]
├─ submit(callable, *args, **kwargs) -> Operation[result type]
│ ├─ id, state -> str
│ ├─ done -> bool
│ ├─ result() -> result (does not wait)
│ ├─ wait(timeout=None) -> result (worker/CLI only while pending)
│ ├─ cancel() -> bool (pending work only)
│ └─ on_done(callback), on_error(callback), on_progress(callback)
│ -> Subscription (each accepts dispatch=...)
│ ├─ close() -> None (disconnect observer)
│ └─ error -> callback exception | None
└─ close(wait=True) -> None
SearchResult contains the found sObjects, their total count and loading parameters.
Query limits are 1–1000. Loading more is explicit; reading local items never
fetches additional records. A final next() returns an empty SearchResult
without another TACTIC query. The remote call still crosses the DCC transport.
Ordering includes an identity tie-breaker; offset-based loading is not a
transactional snapshot of changing data.
# CLI/worker, or inside th.submit(...):
result = th.project("demo").stype("types/object").query(limit=50)
for sobject in result.items:
print(sobject.get_code())
if result.has_more:
result = result.next()SObject field getters read a local copy, including in Maya. Local get_info()
returns a read-only mapping with copied values. Other remote handles (including
SearchResult properties) make explicit RPC calls and belong in submitted work.
Native objects returned by pipelines, schema, workflow,
logins and file accessors retain their native methods; their remote methods
can perform I/O and should stay inside submitted work. Their remote surface is
the explicit allowlist in tactic_handler_api/contract.py, not arbitrary Python
attribute access.
SearchKey.parse(text) is an additional import-level helper, not a service on
th. It returns SearchKey with search_type, project_code, column and
value; str(key) produces its normalized TACTIC search key.
-
Workflow and pipelines: lookup methods return native Pipeline objects;
process lookups return plain dictionaries.
get_all_pipeline_names()is a historical name for process names, not pipeline codes.get_pipeline_process(process_code)matches the process record'sprocessfield (its name), not the record's databasecode. Its result contains nativeconfig/processfields.get_process_info(process)instead reads XML node attributes such asname,type,label,color,task_pipelineand the connection attributes retained by the native parser. A task pipeline uses the same Pipeline API; its process names describe its configured statuses.get_by_process_node_typetreatsNone/manualastask. Pipeline lookup by code/node type requires a known Search Type; native methods can raise for an unknown type. These objects do not exposecommit()or a process/status editor. -
Schema:
get_info()is the schema'ssearch_typeXML node attributes, not an XML document or database column catalog. Relationship methods returnconnectattribute dictionaries (from,to, and server-defined attributes such asrelationship,from_col,to_col,instance_type,pathwhen present). These are descriptors, not linked sObjects. Obtain actual related records throughsobject.related(...). Schema absence returnsNone; this surface does not provide schema mutation methods. -
Dependencies:
dependencies()preserves the native result grouped by related Search Type and then search key. It discovers related children, not a recursively expanded dependency graph. Its values are NativeSObject, not the staged SObject wrapper. For editing, resolve the identity withth.sobject(dependency.get_search_key()), then useset_value/commit. Do not pass the returned object mapping directly todelete(dependencies=...); that argument is a collection of related Search Type strings explicitly selected for deletion, not individual dependency objects or search keys. -
Files: preview accessors return File objects, not image URLs or pixels;
continue through
get_full_web_path()orfiles.ensure_local(...). The matched FileObject is a separate native file-group description. Withfirst=True,get_all_files_listreturns one path string; withfilenames=Trueit returns a list regardless offirst.get_sizes_listcan returnNonewhen no sizes are found.
The following chain is available in a worker, including over the DCC connection:
project = th.project("demo")
workflow = project.workflow()
pipeline = workflow.get_by_pipeline_code("types/object", "main")
if pipeline is not None:
for process in pipeline.get_all_pipeline_names():
print(process, pipeline.get_process_info(process))
task_pipeline = workflow.get_child_pipeline_by_process_code(pipeline, process)
if task_pipeline is not None:
print("Task statuses:", task_pipeline.get_all_pipeline_names())The codes in this example are placeholders. A process does not necessarily have
a child/task pipeline; None is a valid result. No labels are translated by the
public API.
def rename(th, search_key, name):
sobject = th.sobject(search_key)
sobject.set_value("name", name) # Local staged value, no write.
print(sobject.changes())
sobject.commit() # Waits for server confirmation.
return sobject
operation = th.submit(rename, th, "types/object?project=demo&code=O1", "New name")Failed commits retain staged changes; they do not publish them into native UI
objects. Refreshing a dirty editor raises DirtyObject; commit or discard first.
Concurrent mutation of the same editor during commit/refresh raises
ConcurrentEdit. This protects the local editor, not simultaneous edits by other
users on the server. Server permissions, validation and triggers remain native.
def create_child(th, parent_key, pipeline_code):
stype = th.project("demo").stype("types/object")
child = stype.new(
{"name": "New object", "pipeline_code": pipeline_code},
parent=parent_key,
relation="types/object_in_object", # Actual schema instance type.
direction="child",
)
return child.commit()Creation forwards form values, parent and relationship to native
insert_sobjects; it does not guess or substitute a pipeline. New objects have
no usable search key until committed. Existing identities cannot be edited.
Deletion is explicit and immediate; inspect dependencies() before passing
the native dependency selection to delete().
Data methods are synchronous and return their documented value. submit() moves data work
to a worker. UI .show() commands always return an Operation and own their
dispatch; they are safe to call directly from Qt/Maya's GUI thread.
operation = th.submit(th.sobject, "types/object?project=demo&code=O1")
print(operation.id, operation.state, operation.done)
# Worker/CLI only:
sobject = operation.wait(timeout=30)States: queued, running, finished, failed, cancelled.
result() never waits: before completion it raises NotReady; afterward it
returns the value or raises the original exception. wait() is forbidden on a
known Qt/Maya UI thread while unfinished. A wait timeout does not cancel the
operation or roll back a server write. cancel() cancels only work that has not
started and reports whether cancellation succeeded.
Defaults: four workers and at most 64 outstanding operations; overflow raises
QueueFull. Chain synchronous calls inside one submitted function. Submitting
again from that executor's own worker is rejected to prevent nested-wait
deadlocks. A UI .show() inside an existing API worker uses that worker and
returns a completed Operation after its commands are accepted, without nested
submission. Closing cancels pending work; running operations are not forcibly
interrupted: they can finish their remaining synchronous steps before remote
handles are released. Use close(wait=False) on a GUI thread. Closing waits for
this runtime's submitted work, not independently managed external threads.
Custom scripts launched by the Maya runtime keep their legacy synchronous flow;
that exception is scoped to the script execution and does not relax other UI calls.
# Maya example: callbacks touching Maya/UI must be explicitly dispatched.
import maya.utils
subscription = operation.on_done(
lambda obj: print(obj.get_code()),
dispatch=maya.utils.executeDeferred,
)
# Also available: on_error(callback, dispatch=...), on_progress(...).
# Disconnect during owner/window teardown:
subscription.close()Without dispatch, callback thread affinity is unspecified (completion thread,
or registration thread for an already finished operation). Callbacks receive
one argument. Progress is best-effort data, not a delivery-guaranteed event log;
headless transfers/check-in emit progress, while desktop/remote progress remains
in their existing queue views. Observer errors are retained as
subscription.error and cannot turn a successful commit into a failed one.
Disconnect callbacks when their UI owner/selection becomes obsolete. No callback
implicitly switches to the Qt thread.
def download_snapshot(th, snapshot_key):
snapshot = th.snapshot(snapshot_key)
print(snapshot.get_code(), snapshot.get_version())
return th.repositories.sync(snapshot, overwrite="cancel", verify_md5=True)
operation = th.submit(download_snapshot, th, "sthpw/snapshot?code=SNAPSHOT001")Snapshot exposes get_info, get_code, get_search_key, get_version,
is_latest, is_versionless, get_files_objects, and
get_previewable_files_objects. File accessors return native File objects.
-
th.files.match(paths, templates=None)→ native matched FileObjects. -
th.files.ensure_local(file, overwrite="cancel", verify_md5=False)→Path. -
th.files.open(file)→ ensure local, then native file opener;Path. -
th.files.reveal(file)→ native folder opener;Path. -
th.repositories.list()→ active native repository records. -
th.repositories.get(repository_code)→ a configured repository record. -
th.repositories.sync(snapshot_or_files, ...)→list[Path].
Overwrite decisions are explicit: cancel, skip, overwrite. skip may
return a stale local file. Freshness uses native metadata; received bytes are
validated against HTTP response size, not a potentially stale discovery size.
The downloader is shared with Repository Sync. Each operation owns its staging
path, so one runtime never deletes another runtime's partial transfer. This API
syncs explicitly supplied files/snapshots; it does not yet expose the UI's
recursive scope/preset discovery as a new high-level API.
def prepare(th, search_key, source_path, repository_code):
queue = th.commit_queue("demo")
return queue.add(
search_key, context="publish/main", files=[source_path],
repository=repository_code, description="First version",
file_type="file", mode="upload", generate_previews=False,
)
# CLI/worker:
item = prepare(th, "types/object?project=demo&code=O1", source_path, repository_code)
item.set_description("Ready")
snapshot = item.commit()
# Alternatively, outside an already submitted function:
# operation = item.submit()add() prepares a queue entry but does not upload. QueueItem.commit() returns a
confirmed, file-hydrated Snapshot. QueueItem.submit() is shorthand for
th.submit(item.commit). Source paths must be readable by the standalone
Handler. The API does not reinterpret Maya paths or invoke DCC scene-save as part
of this file-based operation.
Additional add options: version, is_revision, update_versionless,
keep_file_name, generate_previews; modes upload, copy, preallocate.
Defaults do not change versionless snapshots. files is a collection of paths,
not one string. Regular files are matched independently; queue submission of
custom sequence/UDIM templates is not yet exposed.
Inspect queue.items(search_key=..., state=...), queue.get(operation_id) and
item.state; edit item.set_description(text), remove item.remove() or
queue.remove_completed(). Project-scoped queues reject foreign-project items.
Duplicate prepared check-ins are rejected. A completed item retains its server
result, so calling commit() again on that item does not upload twice.
Ownership differs deliberately:
| Runtime | Queue owner | Lifetime |
|---|---|---|
get_api() in Handler |
Existing desktop CommitQueueController | Existing queue persistence and UI |
get_api() in Maya / from_client(...)
|
Same desktop queue through domain RPC commands | Existing Handler application |
local() without a queue gateway |
One headless queue | In-memory, owned by that API runtime |
Editing one item by id ignores the UI's bulk-selection setting. A result remains available after desktop auto-clean (bounded terminal cache: 1000 items). Application shutdown disconnects the bridge and fails pending waiters.
Headless execution serializes check-ins and reuses native naming, file staging
and server transactions. It marks an execution error uncertain and refuses an
automatic retry: a lost reply may follow a successful server-side write. Verify
the server before making a new check-in. This is not server-side exactly-once
delivery or a persistent headless job service.
Headless data, XML, downloads and file check-in can run without Qt. Generating
image previews still uses the existing Qt image codecs (no windows/event loop);
set generate_previews=False when Qt is not installed. Native file/folder
openers naturally require a desktop environment.
def adjust_edit_definition(th, config_code):
catalog = th.project("demo").stype("types/object").definitions
definition = catalog.get(config_code)
element = definition.element("category_code")
element.set_widget("display", "SelectWdg")
element.set_option("display", "values_expr", "@GET(types/category.code)")
element.set_option("display", "labels_expr", "@GET(types/category.name)")
element.set_option("display", "empty", "-- Select --")
definition.validate()
return definition.commit()project.definitions.list(search_type=None, view=None, login=None, limit=100, offset=0) returns exact saved records across Search Types. An SType catalog adds
its type filter. get(config_code) addresses one record, including its login
scope, not all records sharing a view name. New records use
catalog.new(view, xml, search_type=..., login="") then commit().
Definitions expose code, search_type, view, login, xml, set_xml,
validate, element and commit. Elements support set_attribute,
set_widget("display" | "edit", class_name) and set_option(section, name, value).
Expressions remain server expressions; they are not evaluated or flattened.
Unknown elements/attributes and comments survive structural editing, although
XML whitespace/serialization may change. Duplicate element names within a view
are rejected. Ambiguous element names across views require explicit XML editing.
catalog.resolve(view) returns a read-only ResolvedDefinition from the native
project ViewsConfig lookup. It does not claim to reproduce the server's complete
merged widget-resolution engine. Never save a resolved result over an arbitrary
record. Saving targets the concrete config/widget_config and invalidates
reference metadata; definitions should have one editing owner at a time.
Retrieving a UI handle has no navigation side effect. .show() owns scheduling
and returns Operation[handle] in every execution context. Call it directly:
th.ui.show()
th.ui.project("demo").show()
th.ui.sobject("types/object?project=demo&code=O1").notes().show()
th.ui.window("commit_queue").show()These are independent examples, not an ordered navigation script. To select a target and show its queue in order, use one scoped command:
operation = th.ui.project("demo").commit_queue().show()
# In a later GUI command, after operation.done becomes True:
queue_window = operation.result()
print(queue_window.id) # commit_queueUI commands use the session's executor and desktop dispatcher. Remote commands
use the DCC connection.
Qt objects never leave the UI thread. Errors remain on the operation and are
available through result()/on_error(...). Cancellation and session shutdown
use the ordinary Operation contract. Callbacks retain their explicit dispatch
rules; a pending wait() still must not run on the GUI thread.
Object handles also have .snapshots(), .tasks() and .commit_queue();
project handles have .commit_queue(). ui.dock(dock_id) and
ui.window(window_id) use registered Handler identifiers. They are command
handles, not leaked QObjects or arbitrary widget lookups. One scoped operation
issues navigation before its window/dock command; a failed navigation stops the
remaining steps. Completion means native commands were accepted, not that all
asynchronous data loading/rendering has finished.
Object/project queue handles navigate before showing the shared queue; they do
not promise a separate or filtered queue instance. A headless runtime returns an
operation failed with UIUnavailable. Business operations never call .ui
implicitly.
Recursive repository presets, messaging/administration/settings and arbitrary
search-tab/editor controls are not exposed by this API. Use maya.cmds for
native Maya scripting and Handler for TACTIC operations.
See DCC startup and scripts.
Bundled project-specific custom scripts require adaptation before use. Import
get_api() explicitly; the launcher supplies only TACTIC_PROJECT_CODE and
TACTIC_SCRIPT_KWARGS and never changes the process-wide current project.
Implementation ownership:
-
tactic_handler_api: explicit domain façade, staged values, bounded execution. -
thlib.checkin_operation,thlib.repository_download: shared native execution. -
thlib.ui.api_bridge: Qt-thread marshalling to the existing queue owner. -
thlib.ui.tactic_rpc: onlyhandler.call,handler.release,handler.close; the call target/member must belong to the explicit domain contract. There is no module import, arbitrary public getter, or global environment gateway.
The composition root attaches the shared queue/runtime before accepting script work. Maya shutdown drains submitted API work off its UI thread before stopping the borrowed transport. The operator currently executes incoming domain commands serially; multiple submitted DCC calls are not parallel TACTIC transactions.
Run the focused regression suite with the repository Python environment:
python -m unittest tests.test_handler_api tests.test_handler_api_services tests.test_handler_api_headless tests.test_handler_api_desktop tests.test_tactic_dcc_sdk tests.test_script_editor tests.test_environment_import tests.test_checkin_operation tests.test_checkin_vertical tests.test_commit_queue tests.test_repository_syncTests cover actual native object wrappers, local HTTP transfer, real staged files, the Qt queue model/dispatcher, direct UI calls from the Qt thread, ordered scoped commands and cancellation, nested workflow/pipeline/schema/dependency results, SearchResult continuation, the real thin-client TCP transport, and a subprocess that rejects Qt/UI imports. TACTIC server mutations and Maya-native execution are isolated; this suite does not replace acceptance against a live TACTIC/Maya setup.
th.project(code).automation exposes fixed read(), preview(document),
save_draft(document, expected_revision, operation_id), draft(draft_id),
activate(draft_id, draft_revision, expected_revision, operation_id),
operation(operation_id) and save_hooks(rules, expected_revision, operation_id).
drafts() lists this author's reviewable drafts (TS 0.112.214). draft() also
returns host-reported trial evidence and freshness. To revise an inactive source,
preview the new document, then pass optional keyword arguments draft_id and its
original draft_revision to save_draft, using the new preview revision and a new
operation UUID. Old reports remain historical and no longer qualify. Activated
drafts cannot be revised this way; normal saved-script editing remains separate.
The same domain object is available through the existing remote API. Obtain it
inside the API worker/session; it captures the project's server stub. No Qt
objects or arbitrary RPC names are accepted. These operations require TS
0.112.207 with upgraded project schema and administrator access.
Preview compiles Python syntax without running it. Saving creates inactive private draft metadata. Activation separately checks native execution permission, source revision and configuration dependencies, then publishes a normal Local Python script with a Handler check-in hook or tab-specific shared shelf binding. Use an identical operation UUID/payload after lost replies. Receipts are historical; read current configuration separately. Drafts/receipts share the project DB with the native configuration mutation and must be backed up with it.
run_checkin_program(argv, TACTIC_SCRIPT_KWARGS, timeout=60, per_file=False) from
tactic_handler_api.automation invokes an absolute executable on the desktop
without a shell (Windows batch files are rejected). It captures output and raises
on nonzero exit or timeout. Named argument tokens include {file}, project,
search key, process/context, operation ID and completed snapshot key; see Script
Triggers Help. Native programs own their child-process/external-effect cleanup.
This is normal user-authorized execution, not a sandbox or exactly-once service.
Client hooks do not enforce headless/other-client check-ins.
Local shelf scripts receive captured TACTIC_SCRIPT_KWARGS with project, entry,
tab and selected search keys. They create UI on the existing GUI thread/engine;
submit slow work through the existing API workers. The small native Frame example
supports show(records, modal=True) and releases its window after close.
Saving, syntax validation and activation remain separate from execution.
An isolated trial runner is unavailable; never call a normal script run isolated.
thlib.ui.agent_desktop.AgentDesktopController owns authenticated desktop registration
and fixed start/stop relaying; thlib.local_agent.LocalAgents owns local child processes
and their private cached Python environment. Application shutdown/sign-out stops only
this instance's children. No arbitrary desktop command API is exposed. Chat/provider
controllers pass the selected execution target through AgentExecutorCmd.
Before automatic registration, the companion checks the native class_exists
API for tactic.ui.panel.agent_executor_cmd.AgentExecutorCmd. A missing command
disables polling for that authenticated session; reconnecting checks again.
Transport failures leave polling enabled and never stop or replay local work.
The Handler hook editor checks HandlerAutomationCmd before reading or saving.
Legacy TACTIC uses the original config/trigger query/update API instead, with
revision and identity checks and native start/finish/abort transactions. Existing
Before/After hooks remain editable and runnable; unrelated triggers are preserved.
Stream retains its native command validation and publication receipts. A command
failure never selects the legacy path; only class_exists == False does.
The client-only HTTP/MCP runtime and indexed TS reference documents are bundled under
thlib/agent_runtime, independently of a Stream checkout. Refresh exact copies with
python tools/sync_agent_runtime.py --stream-root <TS/tactic_stream> and verify with
--check; do not copy Stream server/database code. Local Codex uses the current OS
account's CLI authentication; TACTIC credentials stay outside model inputs.
For a local SType.query(include_snapshots=True), call
sobject.snapshots(prefetched=True) to use that query's native Process /
Contexts / Snapshot objects and their existing File methods without another
request. process= remains supported. This explicitly reads the prefetched
point-in-time data; call ordinary snapshots() for a fresh query. Requesting
prefetch without include_snapshots=True raises ValueError. The default query
behavior and remote API contracts are unchanged.
TACTIC-Handler · Releases · Issues · English · Русский
English
- Home
- Installation
- Feature tour
- User guide
- Assistant
- Dashboards
- Knowledge Base
- Maya / Shelf
- Plugins / Плагины
Русский
- Главная
- Установка
- Обзор возможностей
- Руководство пользователя
- Помощник
- Дашборды
- База знаний
- Maya / Shelf
- Plugins / Плагины
Development / Разработка