s3dgraphy 1.6.0.dev54__tar.gz → 1.6.0.dev55__tar.gz

{s3dgraphy-1.6.0.dev54/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev55}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev54
+Version: 1.6.0.dev55
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>

{s3dgraphy-1.6.0.dev54 → s3dgraphy-1.6.0.dev55}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev54"
+version = "1.6.0.dev55"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"

{s3dgraphy-1.6.0.dev54 → s3dgraphy-1.6.0.dev55}/src/s3dgraphy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.6.0.dev54"
+__version__ = "1.6.0.dev55"
 __datamodel_version__ = "1.5.5"  # s3Dgraphy connections datamodel version
 
 # s3Dgraphy/__init__.py

{s3dgraphy-1.6.0.dev54 → s3dgraphy-1.6.0.dev55}/src/s3dgraphy/api.py

@@ -3069,7 +3069,8 @@ def resolve_file(entry: Dict[str, Any], **kwargs) -> Dict[str, Any]:
 
 
 # ── a study into a room, from a folder (MICRO-ROOM-IMPORT, 15 Oct 2026) ──────
-def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = None,
+def room_import(em_json: Optional[str] = None, *, node: str, room: str,
+                title: Optional[str] = None,
                 base_dir: Optional[str] = None, visibility: str = "restricted",
                 token: Optional[str] = None, dry_run: bool = False,
                 pack_tilesets: Optional[str] = None, **kwargs) -> Dict[str, Any]:
@@ -3079,8 +3080,11 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
     hosted keeping their path, the graph is seated last as operations, then
     ``study-access``. ``dry_run``: the plan only, nothing written.
     ``pack_tilesets="3tz"``: a tileset folder goes up as one canonical
-    ``.3tz``. → the report. The one engine of the three doors (the command,
-    EMStudio, EM Tools); see :mod:`s3dgraphy.room_import`."""
+    ``.3tz``. ``container=`` (a study held in memory) with ``base_dirs=``
+    instead of the path; the person's choices as ``per_group``/``per_batch``/
+    ``per_item``, ``move``, ``lots``; ``before_seed`` for what a client adds
+    before the graph is seated. → the report. The one engine of the three
+    doors (the command, EMStudio, EM Tools); see :mod:`s3dgraphy.room_import`."""
     from .room_import import room_import as _run
     return _run(em_json, node=node, room=room, title=title, base_dir=base_dir,
                 visibility=visibility, token=token, dry_run=dry_run,

{s3dgraphy-1.6.0.dev54 → s3dgraphy-1.6.0.dev55}/src/s3dgraphy/room_import/__init__.py

@@ -52,13 +52,23 @@ written by dtcstamp (s3Dgraphy stays a reader), a sibling representation
 (`dtc_derived_from` the folder, a DTC step `packing` with its stamp); the
 folder stays as a reference. See :mod:`.pack`.
 
+A CLIENT WITH A DIALOG (EM Tools' «Bring into a room») calls the two halves:
+:func:`prepare` (the room, then the plan, from the study it holds in memory:
+`container=`, `base_dirs=`), shows the rows, and :func:`execute` with the
+person's choices (:func:`apply_choices` per group / batch / item, `move` for
+«Move here», the confirmed `lots`) and its hook for what only the client can
+make (`before_seed`: EM Tools publishes the scene's models there, so they are
+in the one seeding).
+
 Defaults to confirm (E.D.): the name `room_import` / `room-import`, a new
 room's visibility `restricted`.
 """
 
-from .engine import (JOURNAL_NAME, Interrupted, Journal, make_plan, markdown,
-                     room_import, summarise_plan)
+from .engine import (JOURNAL_NAME, Interrupted, Journal, apply_choices,
+                     birth_sections, execute, make_plan, markdown, plan_report,
+                     prepare, room_import, summarise_plan)
 from .errors import RoomError
 
-__all__ = ["JOURNAL_NAME", "Interrupted", "Journal", "RoomError", "make_plan",
-           "markdown", "room_import", "summarise_plan"]
+__all__ = ["JOURNAL_NAME", "Interrupted", "Journal", "RoomError", "apply_choices",
+           "birth_sections", "execute", "make_plan", "markdown", "plan_report",
+           "prepare", "room_import", "summarise_plan"]

{s3dgraphy-1.6.0.dev54 → s3dgraphy-1.6.0.dev55}/src/s3dgraphy/room_import/engine.py

@@ -376,10 +376,16 @@ def _open_room(node: str, token: Optional[str], room: str, title: str,
 
 def _upload_all(units: List[Dict[str, Any]], *, node: str, room: str,
                 token: Optional[str], journal: Journal, workers: int,
-                by_reference: bool, stop_after: Optional[int] = None
+                by_reference: bool, stop_after: Optional[int] = None,
+                progress: Optional[Callable[[str, int, int], None]] = None,
+                hold: Optional[Callable[[], Any]] = None,
+                on_bytes: Optional[Callable[[int], None]] = None
                 ) -> Dict[str, Any]:
     """Every unit not on the node goes up, in a pool. One failure is one row of
-    the report; an unreachable node stops the run (the journal is kept)."""
+    the report; an unreachable node stops the run (the journal is kept).
+    `hold()` before each file and each piece (a client's «Pause»); `on_bytes(n)`
+    as the bytes are read out, from the WORKERS (a client that draws hands it
+    to its own thread)."""
     total = sum(int(u["size"] or 0) for u in units)
     done = {"files": 0, "bytes": 0, "referenced": 0, "already": 0}
     failed: List[Dict[str, str]] = []
@@ -388,6 +394,8 @@ def _upload_all(units: List[Dict[str, Any]], *, node: str, room: str,
     stop = threading.Event()
 
     def one(u):
+        if hold is not None:
+            hold()
         if stop.is_set():
             return
         if by_reference:
@@ -402,8 +410,18 @@ def _upload_all(units: List[Dict[str, Any]], *, node: str, room: str,
                 if exc.status != 409:
                     raise
                 # a node that keeps the bytes it is given: upload them there
+        read = [0]
+
+        def piece_read(sent, _size):
+            if on_bytes is not None and sent > read[0]:
+                on_bytes(sent - read[0])
+                read[0] = sent
+
         info = nodeio.upload_asset(node, room, u["path"], u["sha256"],
-                                   u["media_type"], token)
+                                   u["media_type"], token,
+                                   piece_read if on_bytes is not None else None, hold=hold)
+        if info.get("already") and read[0]:
+            on_bytes(-read[0])      # the node had them after all: nothing was read out
         journal.note_file(u["sha256"], "already" if info.get("already") else "uploaded",
                           u["size"])
         with lock:
@@ -426,6 +444,15 @@ def _upload_all(units: List[Dict[str, Any]], *, node: str, room: str,
             u = futures[fut]
             try:
                 fut.result()
+                if progress is not None:
+                    # here, in the caller's thread: Blender's progress bar
+                    # must not be touched from a worker
+                    with lock:
+                        sent = done["bytes"]
+                    try:
+                        progress(os.path.basename(u["path"] or ""), sent, total)
+                    except Exception:  # noqa: BLE001 — a client's bar is not the run
+                        pass
             except RoomError as exc:
                 if exc.status is None or exc.status == 401:
                     stop.set()
@@ -603,36 +630,73 @@ def _seed(container, *, node: str, room: str, token: Optional[str],
     return out
 
 
-def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = None,
-                base_dir: Optional[str] = None, visibility: str = "restricted",
-                token: Optional[str] = None, dry_run: bool = False,
-                pack_tilesets: Optional[str] = None, journal_path: Optional[str] = None,
-                work_dir: Optional[str] = None, report_dir: Optional[str] = None,
-                by_reference: bool = False, workers: int = 4, reseed: bool = False,
-                elsewhere: str = "host",
-                stop_after: Optional[int] = None) -> Dict[str, Any]:
-    """Bring the study of `em_json` and every file of its folder into `room` on
-    `node`. → the report (also written as json + md unless `dry_run`)."""
+def _study(em_json: Optional[str], container: Any) -> Tuple[Any, List[str]]:
+    """The study: from its file, or the one a client holds in memory (EM Tools:
+    the graphs of the scene, the file's shelf). Anything with `graphs` (id →
+    Graph), `shelf` and `active_graph_id` — a :class:`~s3dgraphy.container.Container`."""
+    if container is not None:
+        return container, []
+    if not em_json:
+        raise ValueError("room_import needs an em.json or a container")
+    return _load(em_json)
+
+
+def _title_of(container: Any, em_json: Optional[str]) -> str:
+    active = None
+    try:
+        active = container.active()
+    except Exception:  # noqa: BLE001 — a container-like without active()
+        gid = getattr(container, "active_graph_id", None)
+        active = (getattr(container, "graphs", {}) or {}).get(gid)
+    name = getattr(active, "name", "") or ""
+    if isinstance(name, dict):
+        # a graph's name in several languages (`{"default": …}`): measured on
+        # 15 Oct 2026, the title was the dict written out
+        name = name.get("default") or next(iter(name.values()), "")
+    name = str(name or "")
+    if name:
+        return name
+    return os.path.basename(em_json).split(".")[0] if em_json else ""
+
+
+def prepare(em_json: Optional[str] = None, *, container: Any = None,
+            node: str, room: str, title: Optional[str] = None,
+            base_dir: Optional[str] = None, base_dirs: Optional[Iterable[str]] = None,
+            token: Optional[str] = None, dry_run: bool = False,
+            pack_tilesets: Optional[str] = None, journal_path: Optional[str] = None,
+            work_dir: Optional[str] = None, workers: int = 4) -> Dict[str, Any]:
+    """The first half of the gesture: the room (created, or taken up again —
+    unless `dry_run`), then the PLAN, every file the study names in its group.
+    Nothing is uploaded. → the run, for :func:`plan_report` and :func:`execute`.
+
+    A client with a dialog (EM Tools) calls this, shows `run["plan"]["rows"]`,
+    collects the person's choices, and then calls :func:`execute` with them.
+    `container` is the study a client holds in memory (its graphs are
+    rewritten IN PLACE when the files are hosted); `base_dirs` are where its
+    relative paths are looked for (the DosCo, the em.json's folder, the
+    .blend's folder), the first one also where the journal goes when no
+    `em_json` says where."""
     from . import pack as packing
 
     started = time.time()
     t0 = time.monotonic()
     nodeio.seen_requests(reset=True)
     node = node.strip().rstrip("/")
-    em_json = os.path.abspath(em_json)
-    if visibility not in VISIBILITIES:
-        raise ValueError(f"visibility is restricted or public, not {visibility!r}")
-    if elsewhere not in ELSEWHERE:
-        raise ValueError(f"elsewhere is one of {ELSEWHERE}, not {elsewhere!r}")
+    em_json = os.path.abspath(em_json) if em_json else ""
     if pack_tilesets not in (None, "", "3tz"):
         raise ValueError(f"--pack-tilesets knows 3tz, not {pack_tilesets!r}")
-    base = os.path.abspath(base_dir or os.path.dirname(em_json))
-    journal_path = journal_path or os.path.join(os.path.dirname(em_json), JOURNAL_NAME)
+    bases = [os.path.abspath(b) for b in (base_dirs or ()) if b]
+    if base_dir or not bases:
+        if not (base_dir or em_json):
+            raise ValueError("room_import needs base_dirs when there is no em.json")
+        bases.insert(0, os.path.abspath(base_dir or os.path.dirname(em_json)))
+    bases = list(dict.fromkeys(bases))
+    journal_path = journal_path or os.path.join(
+        os.path.dirname(em_json) if em_json else bases[0], JOURNAL_NAME)
     journal = Journal(journal_path, node=node, room=room, write=not dry_run)
-    container, warnings = _load(em_json)
+    container, warnings = _study(em_json, container)
     members = _members(container)
-    title = title or str(getattr(container.active(), "name", "") or "") or \
-        os.path.basename(em_json).split(".")[0]
+    title = title or _title_of(container, em_json) or room
     timings: Dict[str, float] = {}
 
     # THE ROOM BEFORE ANY QUESTION ABOUT ITS FILES. Measured on 15 Oct 2026: a
@@ -648,8 +712,8 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
         probe = _room_exists(node, token, room)
     else:
         where = _open_room(node, token, room, title, birth_sections(members),
-                           container.active_graph_id, journal)
-    plan = make_plan(container, base_dirs=[base], node=node, room=room,
+                           getattr(container, "active_graph_id", None), journal)
+    plan = make_plan(container, base_dirs=bases, node=node, room=room,
                      token=token if probe else None, journal=journal, workers=workers,
                      trees=inventory.CHOICE_REFERENCE if pack_tilesets else inventory.CHOICE_UPLOAD,
                      probe=probe)
@@ -670,7 +734,7 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
                 # its file on this disk, also when the node already has it (a
                 # row the HEAD answered for carries no path)
                 sib_path = (sib_row or {}).get("path") or inventory.resolve_path(
-                    str(sib.data.get("url") or ""), [base])
+                    str(sib.data.get("url") or ""), bases)
                 check = packing.reusable(sib, sib_path, folder_digest)
                 if check["ok"]:
                     packs.append({"tree": r["id"], "reused": sib.node_id,
@@ -688,7 +752,7 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
             packs.append(made)
         if any("archive_id" in p for p in packs):
             # the new siblings are resources like any other: planned again
-            plan = make_plan(container, base_dirs=[base, work], node=node, room=room,
+            plan = make_plan(container, base_dirs=bases + [work], node=node, room=room,
                              token=token, journal=journal, workers=workers,
                              trees=inventory.CHOICE_REFERENCE, probe=probe)
             for p in packs:
@@ -697,23 +761,115 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
                         raise RoomError(f"the packed archive {p['path']} was not found again")
         timings["pack"] = round(time.monotonic() - t0 - timings["plan"], 1)
 
-    summary = summarise_plan(plan, elsewhere=elsewhere)
-    report: Dict[str, Any] = {
-        "em_json": em_json, "base_dir": base, "node": node, "room": room, "title": title,
-        "visibility": visibility, "dry_run": dry_run, "pack_tilesets": pack_tilesets or "",
-        "elsewhere": elsewhere, "asked_the_node": probe,
-        "started_at": datetime.datetime.fromtimestamp(started).isoformat(timespec="seconds"),
-        "plan": summary, "packs": packs, "warnings": warnings[:20],
+    return {"em_json": em_json, "container": container, "members": members,
+            "base_dirs": bases, "node": node, "room": room, "title": title,
+            "token": token, "dry_run": dry_run, "pack_tilesets": pack_tilesets or "",
+            "journal": journal, "journal_path": journal_path, "where": where,
+            "probe": probe, "plan": plan, "packs": packs, "warnings": warnings,
+            "timings": timings, "t0": t0, "started": started, "workers": workers}
+
+
+def plan_report(run: Dict[str, Any], *, elsewhere: str = "host",
+                visibility: str = "restricted") -> Dict[str, Any]:
+    """What :func:`prepare` found, as the report's first half (the dry run's
+    whole report)."""
+    plan = run["plan"]
+    return {
+        "em_json": run["em_json"], "base_dir": run["base_dirs"][0],
+        "base_dirs": run["base_dirs"], "node": run["node"], "room": run["room"],
+        "title": run["title"], "visibility": visibility, "dry_run": run["dry_run"],
+        "pack_tilesets": run["pack_tilesets"], "elsewhere": elsewhere,
+        "asked_the_node": run["probe"],
+        "started_at": datetime.datetime.fromtimestamp(run["started"]).isoformat(timespec="seconds"),
+        "plan": summarise_plan(plan, elsewhere=elsewhere), "packs": run["packs"],
+        "warnings": run["warnings"][:20],
         "missing": [{"id": r["id"], "name": r["name"], "locator": r["locator"],
                      "note": r.get("note", "")}
                     for r in plan["rows"] if r["group"] == inventory.GROUP_MISSING],
     }
-    if dry_run:
-        report["requests"] = nodeio.seen_requests()
-        report["seconds"] = round(time.monotonic() - t0, 1)
-        report["timings"] = timings
-        return report
 
+
+def apply_choices(run: Dict[str, Any], *, per_group: Optional[Dict[str, str]] = None,
+                  per_batch: Optional[Dict[str, str]] = None,
+                  per_item: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+    """The person's choices on the plan (`inventory.apply_choices`: item >
+    batch > group), and the work they mean recounted: a file left as a
+    reference or skipped is not a unit any more, a tree left as a reference
+    has no files to send. → the plan."""
+    plan = run["plan"]
+    inventory.apply_choices(plan["rows"], per_group=per_group, per_batch=per_batch,
+                            per_item=per_item)
+    trees = [r for r in plan["rows"] if r.get("tree") and r["choice"] == inventory.CHOICE_UPLOAD]
+    keep = {t["id"] for t in trees}
+    plan["trees"] = trees
+    plan["members"] = [m for m in plan["members"] if m["tree_of"] in keep]
+    token = run["token"] if run["probe"] else None
+    head = _head_fn(run["node"], run["room"], token) if run["probe"] \
+        else (lambda _hexd: (False, None))
+    plan["units"] = _units(plan["rows"], plan["members"], head, run["journal"])
+    return plan
+
+
+def _bucket_lots(run: Dict[str, Any], lots: Iterable[Dict[str, Any]]) -> List[str]:
+    """L1 · each CONFIRMED session of photos becomes ONE acquisition in its
+    graph (`api.bucket_acquisition`, the serial node). → the acquisition ids."""
+    from ..api import bucket_acquisition
+    graphs = dict(run["members"])
+    active = getattr(run["container"], "active_graph_id", None)
+    made = []
+    for lot in lots or ():
+        if lot.get("confirmed") is False or not lot.get("ids"):
+            continue
+        graph = graphs.get(lot.get("graph_id") or active) or next(iter(graphs.values()))
+        out = bucket_acquisition(
+            graph, list(lot["ids"]), name=f"Photos · {lot.get('name') or ''}".strip(),
+            metadata={"camera": lot.get("camera"), "taken_from": lot.get("from"),
+                      "taken_to": lot.get("to"),
+                      "source": lot.get("source") or "room-import"})
+        made.append(str(out.get("acquisition_id") or out.get("id") or ""))
+    return made
+
+
+def execute(run: Dict[str, Any], *, visibility: str = "restricted",
+            elsewhere: str = "host", move: Optional[Iterable[str]] = None,
+            lots: Optional[Iterable[Dict[str, Any]]] = None,
+            before_seed: Optional[Callable[[Dict[str, Any]], Optional[Dict[str, Any]]]] = None,
+            progress: Optional[Callable[[str, int, int], None]] = None,
+            report_dir: Optional[str] = None, by_reference: bool = False,
+            reseed: bool = False, stop_after: Optional[int] = None,
+            hold: Optional[Callable[[], Any]] = None,
+            on_bytes: Optional[Callable[[int], None]] = None) -> Dict[str, Any]:
+    """The second half: the files up, the resources hosted, the graph seated,
+    `study-access`, the report (json + md in `report_dir`).
+
+    The person's choices: on the plan (:func:`apply_choices`, before this);
+    `move` — the rows (ids) or digests at home in another room the person
+    said «Move here» for (`elsewhere="move"`: all of them); `lots` — the
+    confirmed sessions of photos, one acquisition each. `before_seed(info)` is
+    the client's hook for the resources only IT can make — EM Tools exports
+    the scene's models and publishes them (`promote_model`) — called after the
+    files are up and hosted, BEFORE the graph is seated, so they are in the one
+    seeding. `info` is `{node, room, token, container, plan}`; it answers
+    `{uploaded, bytes, already, failed: [sentence], filled: [resource id]}`
+    (any of them), counted in the report. `progress(name, sent, total)`:
+    bytes, after each file. `hold()` — a client's «Pause»: called before each
+    file and each piece, it returns when the run may go on (truthy if it
+    waited); `on_bytes(n)` — the bytes as they are read out, from the upload
+    workers."""
+    if run["dry_run"]:
+        raise ValueError("a dry run is not executed: prepare it again without dry_run")
+    if visibility not in VISIBILITIES:
+        raise ValueError(f"visibility is restricted or public, not {visibility!r}")
+    if elsewhere not in ELSEWHERE:
+        raise ValueError(f"elsewhere is one of {ELSEWHERE}, not {elsewhere!r}")
+    node, room, token = run["node"], run["room"], run["token"]
+    journal, journal_path = run["journal"], run["journal_path"]
+    plan, where, members = run["plan"], run["where"], run["members"]
+    t0, timings, workers = run["t0"], run["timings"], run["workers"]
+    container = run["container"]
+
+    summary = summarise_plan(plan, elsewhere=elsewhere)
+    report = plan_report(run, elsewhere=elsewhere, visibility=visibility)
     try:
         report["room_state"] = where
         t1 = time.monotonic()
@@ -722,7 +878,8 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
         _say(f"{len(todo)} file(s) to send, {inventory.human_size(sum(int(u['size'] or 0) for u in todo))}")
         uploads = _upload_all(todo, node=node, room=room, token=token, journal=journal,
                               workers=workers, by_reference=by_reference,
-                              stop_after=stop_after)
+                              stop_after=stop_after, progress=progress,
+                              hold=hold, on_bytes=on_bytes)
         for u in plan["units"].values():
             if u["present"]:
                 journal.note_file(u["sha256"], "already", u["size"])
@@ -754,22 +911,27 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
         for r in plan["rows"]:
             if r["group"] == inventory.GROUP_ELSEWHERE:
                 homes[r.get("home") or "?"] = homes.get(r.get("home") or "?", 0) + 1
-        if elsewhere == "move":
-            for hexd in sorted({r["sha256"] for r in plan["rows"]
-                                if r["group"] == inventory.GROUP_ELSEWHERE and r.get("sha256")}):
-                row = next(r for r in plan["rows"] if r.get("sha256") == hexd)
-                try:
-                    answer = nodeio.move_asset_home(node, room, hexd, row.get("home"), token)
-                    if answer.get("home") == room:
-                        moved.add(hexd)
-                except RoomError as exc:
+        said = {str(x) for x in (move or ())}
+        to_move = sorted({r["sha256"] for r in plan["rows"]
+                          if r["group"] == inventory.GROUP_ELSEWHERE and r.get("sha256")
+                          and (elsewhere == "move" or r["id"] in said or r["sha256"] in said)})
+        for hexd in to_move:
+            row = next(r for r in plan["rows"] if r.get("sha256") == hexd)
+            try:
+                answer = nodeio.move_asset_home(node, room, hexd, row.get("home"), token)
+                if answer.get("home") == room:
+                    moved.add(hexd)
+                else:
                     uploads["failed"].append({"file": row["name"], "sha256": hexd,
-                                              "why": f"not moved here: {exc}"})
+                                              "why": f"the node kept it in {answer.get('home')}"})
+            except RoomError as exc:
+                uploads["failed"].append({"file": row["name"], "sha256": hexd,
+                                          "why": f"not moved here: {exc}"})
         rewritten = _rewrite(container, plan, node=node, room=room, manifests=manifests,
                              failed_hex=failed_hex, elsewhere=elsewhere, moved=moved)
         rewritten["homes_elsewhere"] = homes
         rewritten["moved_here"] = len(moved)
-        for p in packs:
+        for p in run["packs"]:
             # the packed archive was born in a work folder: that path is not
             # an address of the study, the room's store is
             res = dict(members).get(_graph_of(plan, p.get("archive_id"))) if p.get("archive_id") else None
@@ -780,6 +942,11 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
                     res.data.pop("addresses", None)
                 else:
                     res.data["addresses"] = kept
+        acquisitions = _bucket_lots(run, lots or ())
+        scene: Dict[str, Any] = {}
+        if before_seed is not None:
+            scene = dict(before_seed({"node": node, "room": room, "token": token,
+                                      "container": container, "plan": plan}) or {})
         seeded = {"applied": 0, "refused": 0, "not_news": 0, "sent": 0, "requests": 0,
                   "graphs": []}
         if where["seedable"]:
@@ -796,15 +963,23 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
     finally:
         journal.flush(force=True)
 
+    filled = set(scene.get("filled") or ())
+    if filled:
+        report["missing"] = [m for m in report["missing"] if m["id"] not in filled]
+        report["plan"]["missing"] = len(report["missing"])
     report.update({
-        "uploaded": {"files": uploads["files"], "bytes": uploads["bytes"]},
-        "already": {"files": summary["already"]["files"] + uploads["already"],
+        "uploaded": {"files": uploads["files"] + int(scene.get("uploaded") or 0),
+                     "bytes": uploads["bytes"] + int(scene.get("bytes") or 0)},
+        "already": {"files": summary["already"]["files"] + uploads["already"]
+                    + int(scene.get("already") or 0),
                     "bytes": summary["already"]["bytes"]},
         "referenced_by_node": uploads["referenced"],
         "references": summary["references"],
-        "failed": [f"{f['file']}: {f['why']}" for f in uploads["failed"]],
+        "failed": [f"{f['file']}: {f['why']}" for f in uploads["failed"]]
+        + [str(x) for x in scene.get("failed") or ()],
         "trees": [{"id": k, **v} for k, v in manifests.items()],
-        "rewritten": rewritten, "seeded": seeded,
+        "rewritten": rewritten, "seeded": seeded, "lots": acquisitions,
+        "scene": scene,
         "access": access or {"visibility": journal.here.get("visibility")},
         "link": targets.get("web") or targets.get("scheme") or "",
         "requests": nodeio.seen_requests(),
@@ -820,6 +995,51 @@ def room_import(em_json: str, *, node: str, room: str, title: Optional[str] = No
     return report
 
 
+def room_import(em_json: Optional[str] = None, *, node: str, room: str,
+                container: Any = None, title: Optional[str] = None,
+                base_dir: Optional[str] = None, base_dirs: Optional[Iterable[str]] = None,
+                visibility: str = "restricted",
+                token: Optional[str] = None, dry_run: bool = False,
+                pack_tilesets: Optional[str] = None, journal_path: Optional[str] = None,
+                work_dir: Optional[str] = None, report_dir: Optional[str] = None,
+                by_reference: bool = False, workers: int = 4, reseed: bool = False,
+                elsewhere: str = "host",
+                per_group: Optional[Dict[str, str]] = None,
+                per_batch: Optional[Dict[str, str]] = None,
+                per_item: Optional[Dict[str, str]] = None,
+                move: Optional[Iterable[str]] = None,
+                lots: Optional[Iterable[Dict[str, Any]]] = None,
+                before_seed: Optional[Callable[[Dict[str, Any]], Optional[Dict[str, Any]]]] = None,
+                progress: Optional[Callable[[str, int, int], None]] = None,
+                stop_after: Optional[int] = None,
+                hold: Optional[Callable[[], Any]] = None,
+                on_bytes: Optional[Callable[[int], None]] = None) -> Dict[str, Any]:
+    """Bring the study of `em_json` (or the `container` a client holds) and
+    every file of its folder into `room` on `node`: :func:`prepare`, the
+    choices (:func:`apply_choices`), :func:`execute`. → the report (also
+    written as json + md unless `dry_run`)."""
+    if visibility not in VISIBILITIES:
+        raise ValueError(f"visibility is restricted or public, not {visibility!r}")
+    if elsewhere not in ELSEWHERE:
+        raise ValueError(f"elsewhere is one of {ELSEWHERE}, not {elsewhere!r}")
+    run = prepare(em_json, container=container, node=node, room=room, title=title,
+                  base_dir=base_dir, base_dirs=base_dirs, token=token, dry_run=dry_run,
+                  pack_tilesets=pack_tilesets, journal_path=journal_path,
+                  work_dir=work_dir, workers=workers)
+    if per_group or per_batch or per_item:
+        apply_choices(run, per_group=per_group, per_batch=per_batch, per_item=per_item)
+    if dry_run:
+        report = plan_report(run, elsewhere=elsewhere, visibility=visibility)
+        report["requests"] = nodeio.seen_requests()
+        report["seconds"] = round(time.monotonic() - run["t0"], 1)
+        report["timings"] = run["timings"]
+        return report
+    return execute(run, visibility=visibility, elsewhere=elsewhere, move=move, lots=lots,
+                   before_seed=before_seed, progress=progress, report_dir=report_dir,
+                   by_reference=by_reference, reseed=reseed, stop_after=stop_after,
+                   hold=hold, on_bytes=on_bytes)
+
+
 def sentence(report: Dict[str, Any]) -> str:
     up = report.get("uploaded") or {}
     return (f"uploaded {up.get('files', 0)} ({inventory.human_size(up.get('bytes', 0))}), "

{s3dgraphy-1.6.0.dev54 → s3dgraphy-1.6.0.dev55}/src/s3dgraphy/room_import/node.py

@@ -275,7 +275,7 @@ def _offset_now(url: str, token, timeout) -> int:
 
 
 def _resumable(node, room, path, hexd, size, media_type, token, progress_cb,
-               timeout, piece) -> Dict[str, Any]:
+               timeout, piece, hold=None) -> Dict[str, Any]:
     start = urllib.request.Request(
         _room_url(node, room, "uploads"), method="POST",
         data=json.dumps({"size": size, "sha256": hexd,
@@ -292,6 +292,10 @@ def _resumable(node, room, path, hexd, size, media_type, token, progress_cb,
     offset = int(session.get("offset") or 0)
     failures = 0
     while True:
+        if hold is not None and hold() and offset:
+            # a client's «Pause» waited here, BETWEEN two pieces: the node
+            # says where it is now, and the upload goes on from there
+            offset = _offset_now(url, token, timeout)
         length = min(piece, size - offset)
         read_so_far = [0]
 
@@ -343,14 +347,17 @@ def upload_asset(node: str, room: str, path: str, sha256: Optional[str],
                  progress_cb: ProgressCb = None, *,
                  timeout: float = 600.0,
                  single_shot_max: int = SINGLE_SHOT_MAX,
-                 piece: int = PIECE) -> Dict[str, Any]:
+                 piece: int = PIECE,
+                 hold: Optional[Callable[[], None]] = None) -> Dict[str, Any]:
     """Put the file at `path` into `room`'s store on `node`.
 
     → `{ref, sha256, size, media_type, created, author, url, already}`.
     `already: True` means the HEAD said the room has it and nothing was sent.
     `sha256` may be None (it is computed here); when given it is checked by
     the node, so a file changed since the inventory read it is refused (422)
-    rather than stored under the wrong name.
+    rather than stored under the wrong name. `hold()` is called before each
+    piece of a resumable upload and returns when the client wants it to go on
+    (its «Pause»), truthy if it waited.
     """
     if not os.path.isfile(path):
         raise RoomError(f"not a file: {path}")
@@ -379,7 +386,7 @@ def upload_asset(node: str, room: str, path: str, sha256: Optional[str],
                             progress_cb, timeout)
     else:
         info = _resumable(node, room, path, hexd, size, media_type, token,
-                          progress_cb, timeout, piece)
+                          progress_cb, timeout, piece, hold)
     got = _hex(info.get("ref") or info.get("sha256") or "")
     if got != hexd:
         raise RoomError(f"the room stored sha256:{got[:12]}…, not the "

{s3dgraphy-1.6.0.dev54 → s3dgraphy-1.6.0.dev55/src/s3dgraphy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev54
+Version: 1.6.0.dev55
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>