pyoncat 2.0__tar.gz → 2.3__tar.gz

{pyoncat-2.0 → pyoncat-2.3}/PKG-INFO

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: pyoncat
-Version: 2.0
+Version: 2.3
 Summary: A Python Client for ONCat (the ORNL Neutron Catalog).
-Home-page: https://oncat.ornl.gov
 Keywords: ornl,neutron,metadata,catalog
 Author: ONCat Support
 Author-email: oncat-support@ornl.gov
@@ -14,9 +13,10 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: oauthlib
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: requests
-Requires-Dist: requests-oauthlib
+Project-URL: Homepage, https://oncat.ornl.gov
 Description-Content-Type: text/markdown
 
 Welcome to PyONCat, a Python client designed to facilitate interaction with the ONCat API.

{pyoncat-2.0 → pyoncat-2.3}/pyoncat/__init__.py

@@ -9,29 +9,37 @@ hosted at https://oncat.ornl.gov.
 
 from __future__ import annotations
 
-import contextlib
 import functools
 import getpass
 import json
 import os
 import pathlib
-import sys
 import warnings
 import weakref
-from typing import Any, Callable, ClassVar
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal
+from urllib.parse import quote
 
 import oauthlib.oauth2
 import requests
 import requests_oauthlib
-from requests.packages.urllib3.exceptions import InsecureRequestWarning
+import urllib3
+from oauthlib.oauth2 import rfc6749
+from urllib3.exceptions import InsecureRequestWarning
 
-__version__ = "2.0"
+from pyoncat.reduction import ReductionFileBuilder
+
+__version__ = "2.3"
+
+# Constant for autoreduction user
+AUTOREDUCTION_USER = "auto"
 
 __all__ = [
+    "AUTOREDUCTION_USER",
     "FileSystemTokenStore",
     "ONCat",
     "ONCatObject",
     "PyONCatError",
+    "ReductionFileBuilder",
     "prompt_user_for_login",
 ]
 
@@ -41,8 +49,15 @@ __all__ = [
 ########################################################################
 
 
-CLIENT_CREDENTIALS_FLOW = "client"
-RESOURCE_OWNER_CREDENTIALS_FLOW = "resource_owner"
+FlowType = Literal[
+    "client_credentials",
+    "resource_owner",
+]
+CLIENT_CREDENTIALS_FLOW: FlowType = "client_credentials"
+RESOURCE_OWNER_CREDENTIALS_FLOW: FlowType = "resource_owner"
+
+
+assert isinstance(CLIENT_CREDENTIALS_FLOW, str)
 
 
 class ONCat:
@@ -102,11 +117,11 @@ class ONCat:
             The client secret for the OAuth client, which may be
             required alongside the client ID if you are using one.
 
-        token_getter: Callable[[], str | None] | None
+        token_getter: Callable[[], dict | None] | None
             An optional function that will be used to load the current
             OAuth token if one exists, else `None`.
 
-        token_setter: Callable[[str | None], None] | None
+        token_setter: Callable[[dict | None], None] | None
             An optional function that will be used to save the current
             OAuth token, to be retrieved later by the `token_getter`.
 
@@ -119,7 +134,7 @@ class ONCat:
             An optional API token that can be used by select clients to
             authenticate requests to the API as an alternative to OAuth.
 
-        flow: CLIENT_CREDENTIALS_FLOW | RESOURCE_OWNER_CREDENTIALS_FLOW | None
+        flow: FlowType | None
             The OAuth "flow" to use for authentication.  Required if you
             are using OAuth.
 
@@ -144,18 +159,40 @@ class ONCat:
 
     """
 
+    if TYPE_CHECKING:
+        Facility: Facility
+        Instrument: Instrument
+        Experiment: Experiment
+        Run: Run
+        Scan: Scan
+        Sample: Sample
+        Group: Group
+        Grouping: Grouping
+        Mapping: Mapping
+        Proposal: Proposal
+        Item: Item
+        Archive: Archive
+        Cycle: Cycle
+        Datafile: Datafile
+        Reduction: Reduction
+        Simulation: Simulation
+        User: User
+        Task: Task
+        Info: Info
+        CacheEntry: CacheEntry
+        UsageEntry: UsageEntry
+        Template: Template
+
     def __init__(
         self,
         url: str,
         client_id: str | None = None,
         client_secret: str | None = None,
-        token_getter: Callable[[], str | None] | None = None,
-        token_setter: Callable[[str | None], None] | None = None,
+        token_getter: Callable[[], dict | None] | None = None,
+        token_setter: Callable[[dict | None], None] | None = None,
         login_prompt: Callable[[], tuple[str, str]] | None = None,
         api_token: str | None = None,
-        flow: CLIENT_CREDENTIALS_FLOW
-        | RESOURCE_OWNER_CREDENTIALS_FLOW
-        | None = None,
+        flow: FlowType | None = None,
         scopes: list[str] | None = None,
         verify: bool = True,
         timeout: int | None = None,
@@ -202,7 +239,7 @@ class ONCat:
         self._client_secret = client_secret
         self._url = url
         self._flow = flow
-        self._scopes = scopes
+        self._scopes: list[Any] | None = scopes
         self._verify = verify
         self._timeout = timeout
 
@@ -228,7 +265,7 @@ class ONCat:
         self._call_method("delete", url, None, **kwargs)
 
     def _call_method(self, method, url, data, **kwargs):
-        url = requests.utils.quote(url)
+        url = quote(url)
         full_url = (
             self._url + url if url.startswith("/") else self._url + "/" + url
         )
@@ -275,7 +312,7 @@ class ONCat:
 
         try:
             return send_request()
-        except oauthlib.oauth2.rfc6749.errors.InvalidGrantError as error:
+        except rfc6749.errors.InvalidGrantError as error:
             if (
                 self._flow == RESOURCE_OWNER_CREDENTIALS_FLOW
                 and "(invalid_grant)" in str(error)
@@ -335,7 +372,7 @@ class ONCat:
         ):
             # Ignore invalid certs and lack of SSL for OAuth if
             # deploying locally.
-            requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
+            urllib3.disable_warnings(InsecureRequestWarning)
             os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
 
         return (
@@ -390,6 +427,7 @@ class ONCat:
     def _login_client_credentials(self):
         with warnings.catch_warnings():
             warnings.filterwarnings("ignore", category=DeprecationWarning)
+            assert self._client_id
             self._oauth_client = requests_oauthlib.OAuth2Session(
                 client=oauthlib.oauth2.BackendApplicationClient(
                     client_id=self._client_id,
@@ -409,7 +447,7 @@ class ONCat:
                 timeout=self._timeout,
             )
 
-        except oauthlib.oauth2.rfc6749.errors.InvalidClientError as error:
+        except rfc6749.errors.InvalidClientError as error:
             msg = (
                 "You seem to have provided some invalid client "
                 "credentials.  Are you sure they are correct?"
@@ -428,6 +466,7 @@ class ONCat:
                 )
                 raise LoginRequiredError(msg)
         else:
+            assert self._client_id
             initial_oauth_client = requests_oauthlib.OAuth2Session(
                 client=oauthlib.oauth2.LegacyApplicationClient(
                     client_id=self._client_id,
@@ -448,13 +487,13 @@ class ONCat:
                     timeout=self._timeout,
                 )
                 self._save_token(token)
-            except oauthlib.oauth2.rfc6749.errors.InvalidClientError as error:
+            except rfc6749.errors.InvalidClientError as error:
                 msg = (
                     "You seem to have provided some invalid client "
                     "credentials.  Are you sure they are correct?"
                 )
                 raise InvalidClientCredentialsError(msg) from error
-            except oauthlib.oauth2.rfc6749.errors.InvalidGrantError as error:
+            except rfc6749.errors.InvalidGrantError as error:
                 if "(invalid_grant)" in str(
                     error
                 ) and "username & password" in str(error):
@@ -518,8 +557,10 @@ class ONCatObject:
 
     """
 
-    def __init__(self, content: dict):
-        self._content = content
+    def __init__(self, content: dict | None = None):
+        # TODO: Consider a better way to represent a `None` ONCat object
+        # because not all responses will return a representation.
+        self._content = content or {}
 
     def __repr__(self):
         # https://stackoverflow.com/a/2626364/778572
@@ -529,20 +570,16 @@ class ONCatObject:
             "id={}".format(self._content.get("id")),
         ]
 
-        unicode_repr = "<{} at {}> JSON: {}".format(
+        return "<{} at {}> JSON: {}".format(
             " ".join(ident_parts),
             hex(id(self)),
             str(self),
         )
 
-        if sys.version_info[0] < 3:
-            return unicode_repr.encode("utf-8")
-        return unicode_repr
-
     def __str__(self):
         return json.dumps(self._content, sort_keys=True, indent=4)
 
-    def __getattr__(self, k):
+    def __getattr__(self, k) -> Any:
         if k[0] == "_":
             raise AttributeError(k)
 
@@ -551,7 +588,7 @@ class ONCatObject:
         except KeyError as e:
             raise AttributeError(*e.args) from e
 
-    def __getitem__(self, key):
+    def __getitem__(self, key) -> Any:
         elements = key.split(".")
         current = elements[0]
         remainder = elements[1:] if len(elements) > 1 else None
@@ -653,14 +690,24 @@ class _ONCatMixinMeta(type):
 
 
 class _ONCatResource(metaclass=_ONCatMixinMeta):
-    def __init__(self, parent_oncat):
+    _NAMESPACE: str
+    _RESOURCE_ENDPOINT: str
+
+    def __init__(self, parent_oncat: ONCat):
         self._parent_oncat_weakref = weakref.ref(parent_oncat)
 
+    @property
+    def _parent(self) -> ONCat:
+        parent = self._parent_oncat_weakref()
+        if parent is None:
+            msg = "ONCat client was garbage-collected"
+            raise ReferenceError(msg)
+        return parent
+
     def retrieve(self, identifier, **kwargs):
-        oncat = self._parent_oncat_weakref()
+        oncat = self._parent
 
-        if identifier.startswith("/"):
-            identifier = identifier[1:]
+        identifier = identifier.removeprefix("/")
 
         path = f"{self._NAMESPACE}/{self._RESOURCE_ENDPOINT}/{identifier}"
 
@@ -669,7 +716,7 @@ class _ONCatResource(metaclass=_ONCatMixinMeta):
 
 class _ListableONCatMixin(_ONCatResource):
     def list(self, **kwargs):
-        oncat = self._parent_oncat_weakref()
+        oncat = self._parent
 
         path = f"{self._NAMESPACE}/{self._RESOURCE_ENDPOINT}"
 
@@ -680,11 +727,10 @@ class _ListableONCatMixin(_ONCatResource):
 
 
 class _UpdatableONCatMixin(_ONCatResource):
-    def place(self, identifier, data, **kwargs):
-        oncat = self._parent_oncat_weakref()
+    def place(self, identifier: str, data: Any, **kwargs):
+        oncat = self._parent
 
-        if identifier.startswith("/"):
-            identifier = identifier[1:]
+        identifier = identifier.removeprefix("/")
 
         path = f"{self._NAMESPACE}/{self._RESOURCE_ENDPOINT}/{identifier}"
 
@@ -693,7 +739,7 @@ class _UpdatableONCatMixin(_ONCatResource):
 
 class _CreatableONCatMixin(_ONCatResource):
     def create(self, data, **kwargs):
-        oncat = self._parent_oncat_weakref()
+        oncat = self._parent
 
         path = f"{self._NAMESPACE}/{self._RESOURCE_ENDPOINT}"
 
@@ -701,11 +747,10 @@ class _CreatableONCatMixin(_ONCatResource):
 
 
 class _RemovableONCatMixin(_ONCatResource):
-    def remove(self, identifier, **kwargs):
-        oncat = self._parent_oncat_weakref()
+    def remove(self, identifier: str, **kwargs):
+        oncat = self._parent
 
-        if identifier.startswith("/"):
-            identifier = identifier[1:]
+        identifier = identifier.removeprefix("/")
 
         path = f"{self._NAMESPACE}/{self._RESOURCE_ENDPOINT}/{identifier}"
 
@@ -729,7 +774,7 @@ class _ControllerONCatMixin(_ONCatResource):
             else:
                 identifier = None
                 data = args[0]
-        else:
+        elif len(args) == 2:
             if not isinstance(args[0], str):
                 raise TypeError
             identifier = args[0]
@@ -738,7 +783,7 @@ class _ControllerONCatMixin(_ONCatResource):
         if identifier is not None and identifier.startswith("/"):
             identifier = identifier[1:]
 
-        oncat = self._parent_oncat_weakref()
+        oncat = self._parent
 
         if identifier is not None:
             path = (
@@ -773,7 +818,17 @@ class Experiment(_ListableONCatMixin):
 
 class Run(_ListableONCatMixin):
     _RESOURCE_ENDPOINT = "runs"
-    _NAMESPACE = "experimental"
+    _NAMESPACE = "api"
+
+
+class Scan(_ListableONCatMixin):
+    _RESOURCE_ENDPOINT = "scans"
+    _NAMESPACE = "api"
+
+
+class Sample(_ListableONCatMixin):
+    _RESOURCE_ENDPOINT = "samples"
+    _NAMESPACE = "api"
 
 
 class Group(_ListableONCatMixin):
@@ -783,22 +838,22 @@ class Group(_ListableONCatMixin):
 
 class Grouping(_ListableONCatMixin):
     _RESOURCE_ENDPOINT = "groupings"
-    _NAMESPACE = "experimental"
+    _NAMESPACE = "api"
 
 
 class Mapping(_ListableONCatMixin):
     _RESOURCE_ENDPOINT = "mappings"
-    _NAMESPACE = "experimental"
+    _NAMESPACE = "settings"
 
 
 class Proposal(_ListableONCatMixin):
     _RESOURCE_ENDPOINT = "proposals"
-    _NAMESPACE = "experimental"
+    _NAMESPACE = "api"
 
 
 class Item(_ListableONCatMixin):
     _RESOURCE_ENDPOINT = "items"
-    _NAMESPACE = "experimental"
+    _NAMESPACE = "api"
 
 
 class Archive(
@@ -808,6 +863,11 @@ class Archive(
     _NAMESPACE = "api"
 
 
+class Cycle(_ListableONCatMixin, _ControllerONCatMixin):
+    _RESOURCE_ENDPOINT = "cycles"
+    _NAMESPACE = "api"
+
+
 class Datafile(
     _ControllerONCatMixin,
     _CreatableONCatMixin,
@@ -874,6 +934,51 @@ class Template(
     _NAMESPACE = "settings"
 
 
+########################################################################
+# Summary Resources
+########################################################################
+
+
+class ExperimentSummary(_ONCatResource):
+    _RESOURCE_ENDPOINT = "experiment"
+    _NAMESPACE = "summary"
+
+
+class GroupingSummary(_ONCatResource):
+    _RESOURCE_ENDPOINT = "grouping"
+    _NAMESPACE = "summary"
+
+
+class InstrumentSummary(_ONCatResource):
+    _RESOURCE_ENDPOINT = "instrument"
+    _NAMESPACE = "summary"
+
+
+class ReductionSummary(_ONCatResource):
+    _RESOURCE_ENDPOINT = "reduction"
+    _NAMESPACE = "summary"
+
+
+class RunSummary(_ONCatResource):
+    _RESOURCE_ENDPOINT = "run"
+    _NAMESPACE = "summary"
+
+
+class SampleSummary(_ONCatResource):
+    _RESOURCE_ENDPOINT = "sample"
+    _NAMESPACE = "summary"
+
+
+class ScanSummary(_ONCatResource):
+    _RESOURCE_ENDPOINT = "scan"
+    _NAMESPACE = "summary"
+
+
+class SessionSummary(_ONCatResource):
+    _RESOURCE_ENDPOINT = "session"
+    _NAMESPACE = "summary"
+
+
 ########################################################################
 # Misc Tools
 ########################################################################
@@ -892,10 +997,10 @@ class _InMemoryTokenStore:
     def __init__(self):
         self._token = None
 
-    def set_token(self, token: str | None):
+    def set_token(self, token: dict | None):
         self._token = token
 
-    def get_token(self) -> str | None:
+    def get_token(self) -> dict | None:
         return self._token
 
 
@@ -922,7 +1027,7 @@ class FileSystemTokenStore:
     def __init__(self, path: str):
         self.path = path
 
-    def read_token(self) -> str | None:
+    def read_token(self) -> dict | None:
         """Read the token from the file on disk, if it exists.
 
         Return:
@@ -936,7 +1041,7 @@ class FileSystemTokenStore:
         with open(self.path) as storage:
             return json.load(storage)
 
-    def write_token(self, token: str | None):
+    def write_token(self, token: dict | None):
         """Write the token to the file on disk.
 
         Arguments:
@@ -1016,14 +1121,6 @@ def _yield_nodes(d, path, include_branches):
 class PyONCatError(Exception):
     """A base exception for all errors that may be raised by PyONCat."""
 
-    def __init__(self, message=None, original_error=None):
-        if not message:
-            message = ""
-        with contextlib.suppress(Exception):
-            message += " [" + original_error.response.json()["message"] + "]"
-        super().__init__(message)
-        self.original_error = original_error
-
 
 class UnauthorizedError(PyONCatError):
     """An error that is raised when the client is not authorized to

pyoncat-2.3/pyoncat/reduction.py

@@ -0,0 +1,724 @@
+"""Reduction file builder for creating JSON reduction files."""
+
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import re
+import sys
+import traceback
+from typing import Any
+
+
+class ReductionFileBuilder:
+    """Builder for creating JSON Reduction Files for ONCat cataloging.
+
+    Reduction files document the relationship between raw data and reduced
+    data, including all input files (raw data, calibration files, etc.)
+    and all output files (processed data, plots, etc.).
+
+    This class does NOT communicate with the ONCat API.  It only creates
+    JSON files on disk that can later be cataloged via the API.
+
+    The typical workflow is:
+
+        1. Create builder with user identifier
+        2. Add input files (raw data, calibrations, etc.)
+        3. Add output files (reduced data, plots, etc.)
+        4. Set metadata about the reduction
+        5. Write the JSON file to disk
+
+    All mutator methods return `self` for convenient method chaining.
+    Use `write_safe()` in autoreduction scripts to ensure cataloging
+    failures do not break the reduction.
+
+    Example usage:
+
+        from pyoncat import ReductionFileBuilder, AUTOREDUCTION_USER
+
+        builder = ReductionFileBuilder(user=AUTOREDUCTION_USER)
+        builder.add_input(
+            "/SNS/ARCS/IPTS-12345/nexus/ARCS_123456.nxs.h5",
+            type="raw",
+            purpose="sample-data"
+        )
+        builder.add_output(
+            "/SNS/ARCS/IPTS-12345/shared/autoreduce/ARCS_123456.nxs",
+            type="processed",
+            purpose="reduced-data"
+        )
+        builder.set_metadata({"ei": 100.0, "t0": 50.0})
+        path = builder.write_safe()  # Auto-derives path from inputs
+
+    """
+
+    def __init__(self, user: str, metadata: dict[str, Any] | None = None):
+        """Create a new reduction file builder.
+
+        Arguments:
+        ---------
+            user: str
+                XCAMS/UCAMS username or "auto" for autoreduction.  Must be
+                lowercase alphanumeric only.  A value must always be
+                provided by the caller; there is no default.
+
+            metadata: dict[str, Any] | None
+                Optional initial metadata dictionary.  Default: {}
+
+        Example:
+            from pyoncat import ReductionFileBuilder, AUTOREDUCTION_USER
+
+            builder = ReductionFileBuilder(user=AUTOREDUCTION_USER)
+            builder = ReductionFileBuilder(user="pp4", metadata={"ei": 100.0})
+
+        """
+        self._user = user
+        self._metadata = metadata if metadata is not None else {}
+        self._input_files: list[dict[str, Any]] = []
+        self._output_files: list[dict[str, Any]] = []
+        self._validation_errors: list[str] = []
+
+    def add_input(
+        self,
+        location: str,
+        type: str,
+        purpose: str,
+        fields: dict[str, str] | None = None,
+        relative_to: str | None = None,
+    ) -> ReductionFileBuilder:
+        """Add an input file to the reduction.
+
+        Arguments:
+        ---------
+            location: str
+                Path to the input file.  Must be absolute, or relative if
+                relative_to is provided.
+
+            type: str
+                File type.  Must be one of: "raw", "processed",
+                "user-provided", "history".
+
+            purpose: str
+                File purpose in kebab-case (e.g., "sample-data",
+                "vanadium", "detector-calibration", "mask", "ub-matrix").
+                Server validates format but accepts any kebab-case string.
+
+            fields: dict[str, str] | None
+                Optional metadata field mappings for this file.  Dict of
+                "source.path": "dest_path" for extracting metadata.
+                Primarily used for processed files.
+
+            relative_to: str | None
+                Base directory for relative paths.  If provided and
+                location is relative, will be resolved to absolute path.
+
+        Returns:
+        -------
+            Self for method chaining.  Never raises; validation errors are
+            stored internally and surfaced by validate().
+
+        Example:
+            # Absolute path
+            builder.add_input(
+                "/SNS/ARCS/IPTS-12345/nexus/ARCS_123456.nxs.h5",
+                type="raw",
+                purpose="sample-data"
+            )
+
+            # Relative path with relative_to
+            builder.add_input(
+                "./van.nxs",
+                type="processed",
+                purpose="detector-calibration",
+                relative_to="/SNS/ARCS/IPTS-12345/shared/autoreduce"
+            )
+
+            # Method chaining (use keyword args for clarity)
+            builder.add_input(
+                file1, type="raw", purpose="sample-data"
+            ).add_input(
+                file2, type="raw", purpose="vanadium"
+            )
+
+        """
+        resolved_location = self._resolve_path(location, relative_to)
+
+        file_dict: dict[str, Any] = {
+            "location": resolved_location,
+            "type": type,
+            "purpose": purpose,
+        }
+
+        # Only include fields if provided and non-empty
+        if fields:
+            file_dict["fields"] = fields
+
+        self._input_files.append(file_dict)
+        return self
+
+    def add_output(
+        self,
+        location: str,
+        type: str,
+        purpose: str,
+        fields: dict[str, str] | None = None,
+        relative_to: str | None = None,
+    ) -> ReductionFileBuilder:
+        """Add an output file to the reduction.
+
+        The 'fields' parameter is primarily used for output files to extract
+        specific metadata from processed NeXus files, for example:
+
+            fields={
+                "mantid_workspace_1.sample.geom_thickness": "thickness",
+                "mantid_workspace_1.title": "title"
+            }
+
+        Arguments:
+        ---------
+            location: str
+                Path to the output file.  Must be absolute, or relative if
+                relative_to is provided.
+
+            type: str
+                File type.  Must be one of: "raw", "processed",
+                "user-provided", "history".
+
+            purpose: str
+                File purpose in kebab-case (e.g., "reduced-data",
+                "plot", "log").  Server validates format but accepts any
+                kebab-case string.
+
+            fields: dict[str, str] | None
+                Optional metadata field mappings for this file.  Dict of
+                "source.path": "dest_path" for extracting metadata.
+                Commonly used for processed output files.
+
+            relative_to: str | None
+                Base directory for relative paths.  If provided and
+                location is relative, will be resolved to absolute path.
+
+        Returns:
+        -------
+            Self for method chaining.  Never raises; validation errors are
+            stored internally and surfaced by validate().
+
+        Example:
+            builder.add_output(
+                "/SNS/ARCS/IPTS-12345/shared/autoreduce/ARCS_123456.nxs",
+                type="processed",
+                purpose="reduced-data",
+                fields={"MDHistoWorkspace.experiment0.logs.ei.value": "ei"}
+            )
+
+            # With relative path
+            builder.add_output(
+                "ARCS_123456.nxs",
+                type="processed",
+                purpose="reduced-data",
+                relative_to=outdir
+            )
+
+        """
+        resolved_location = self._resolve_path(location, relative_to)
+
+        file_dict: dict[str, Any] = {
+            "location": resolved_location,
+            "type": type,
+            "purpose": purpose,
+        }
+
+        # Only include fields if provided and non-empty
+        if fields:
+            file_dict["fields"] = fields
+
+        self._output_files.append(file_dict)
+        return self
+
+    def set_metadata(self, metadata: dict[str, Any]) -> ReductionFileBuilder:
+        """Set the reduction metadata, replacing any existing metadata.
+
+        No validation is performed on structure or content.  This is a
+        "wild west" field where any valid JSON is accepted.  While no
+        validation is enforced, consistency across instruments is
+        encouraged.  See documentation for recommended metadata fields.
+
+        Arguments:
+        ---------
+            metadata: dict[str, Any]
+                Dictionary of metadata fields.  Can be empty.
+
+        Returns:
+        -------
+            Self for method chaining.
+
+        Example:
+            builder.set_metadata({
+                "ei": 100.0,
+                "t0": 50.0,
+                "duration": 3600.0,
+                "sample": {
+                    "name": "MySample",
+                    "temperature": 300.0
+                }
+            })
+
+        """
+        self._metadata = metadata
+        return self
+
+    def update_metadata(
+        self, metadata: dict[str, Any]
+    ) -> ReductionFileBuilder:
+        """Update the reduction metadata by merging with existing metadata.
+
+        Performs a shallow merge: top-level keys from metadata are merged
+        into existing metadata, but nested dictionaries are replaced, not
+        merged.
+
+        Arguments:
+        ---------
+            metadata: dict[str, Any]
+                Dictionary of metadata fields to merge.
+
+        Returns:
+        -------
+            Self for method chaining.
+
+        Example:
+            builder.set_metadata({"ei": 100.0})
+            builder.update_metadata({"t0": 50.0})
+            builder.get_metadata()  # {"ei": 100.0, "t0": 50.0}
+
+            # Nested dicts are replaced, not merged
+            builder.set_metadata({"sample": {"name": "A"}})
+            builder.update_metadata({"sample": {"temp": 300}})
+            builder.get_metadata()  # {"sample": {"temp": 300}}
+
+        """
+        self._metadata.update(metadata)
+        return self
+
+    def get_metadata(self) -> dict[str, Any]:
+        """Get a copy of the current metadata dictionary.
+
+        Returns:
+        -------
+            Copy of current metadata.  Modifications to the returned dict
+            won't affect builder state.
+
+        Example:
+            metadata = builder.get_metadata()
+            metadata["new_field"] = "value"  # Doesn't affect builder
+            builder.set_metadata(metadata)   # Explicit update required
+
+        """
+        return self._metadata.copy()
+
+    def clear_outputs(self) -> ReductionFileBuilder:
+        """Remove all output files from the builder.
+
+        Useful when re-running a reduction: keep the same inputs but start
+        fresh with outputs.
+
+        Returns:
+        -------
+            Self for method chaining.
+
+        Example:
+            builder = ReductionFileBuilder(user="auto")
+            builder.add_input(input_file, "raw", "sample-data")
+            builder.add_output(output_file, "processed", "reduced-data")
+
+            # Reduction failed, try again
+            builder.clear_outputs()
+            builder.add_output(new_output_file, "processed", "reduced-data")
+            builder.write_safe()
+
+        """
+        self._output_files = []
+        return self
+
+    def validate(self) -> list[str]:
+        """Validate the builder state and return any errors.
+
+        Performs minimal validation:
+
+        - Returns any errors accumulated from mutators (e.g., relative
+          paths without relative_to)
+        - At least one input file present
+        - At least one output file present
+        - User is set and non-empty
+        - Metadata is a dict
+        - If auto-deriving path: at least one input is type="raw" and
+          purpose="sample-data"
+        - All paths must be absolute and canonical (`/SNS/...` or
+          `/HFIR/...` for IPTS directories, or `/SNS/...` or `/HFIR/...`
+          for shared directories like /SNS/ARCS/shared/...)
+
+        Does NOT validate:
+
+        - Type/purpose enum values (server validates)
+        - Detailed file path patterns beyond canonical roots
+        - Fields mapping format (server validates)
+        - Metadata structure (intentionally unrestricted)
+
+        Returns:
+        -------
+            List of error messages.  Empty list if valid.
+
+        Example:
+            errors = builder.validate()
+            if errors:
+                print("Validation failed:")
+                for error in errors:
+                    print(f"  - {error}")
+            else:
+                builder.write()
+
+        """
+        errors = list(self._validation_errors)  # Copy accumulated errors
+
+        # Check for inputs and outputs
+        if not self._input_files:
+            errors.append("At least one input file is required")
+
+        if not self._output_files:
+            errors.append("At least one output file is required")
+
+        # Check user
+        if not self._user:
+            errors.append("User must be set and non-empty")
+
+        # Check metadata is a dict
+        if not isinstance(self._metadata, dict):
+            errors.append("Metadata must be a dictionary")
+
+        # Check for raw sample-data input (needed for auto-derivation)
+        has_raw_sample = any(
+            f.get("type") == "raw" and f.get("purpose") == "sample-data"
+            for f in self._input_files
+        )
+        if not has_raw_sample:
+            errors.append(
+                "At least one input file with type='raw' and "
+                "purpose='sample-data' is required for path auto-derivation"
+            )
+
+        # Validate canonical paths
+        for file_list, file_type in [
+            (self._input_files, "input"),
+            (self._output_files, "output"),
+        ]:
+            for file_dict in file_list:
+                location = file_dict.get("location", "")
+                if not location.startswith(
+                    "/SNS/"
+                ) and not location.startswith("/HFIR/"):
+                    msg = (
+                        f"Path must be canonical (start with /SNS/ or "
+                        f"/HFIR/): {location} ({file_type} file)"
+                    )
+                    errors.append(msg)
+
+        return errors
+
+    def to_dict(self) -> dict[str, Any]:
+        """Preview the JSON structure that will be written (without timestamp).
+
+        Returns:
+        -------
+            Dictionary representing the reduction file structure.  Does not
+            include the 'created' timestamp which is generated on write().
+
+        Example:
+            import json
+            preview = builder.to_dict()
+            print(json.dumps(preview, indent=2))
+
+        """
+        return {
+            "version": "1.0",
+            "input_files": self._input_files,
+            "output_files": self._output_files,
+            "user": self._user,
+            "metadata": self._metadata,
+        }
+
+    def write(self, path: str | None = None, overwrite: bool = True) -> str:
+        """Write the reduction file to disk.
+
+        Behavior:
+
+        1. Validates builder state via validate()
+        2. Generates RFC3339 timestamp with timezone
+        3. Derives path if not provided (from first raw sample-data input)
+        4. Creates parent directories if needed
+        5. Writes JSON file with 4-space indentation, sorted keys
+        6. Returns absolute path to written file
+
+        Auto-derived path format:
+
+            /{facility}/{inst}/{experiment}/shared/autoreduce/{inst}_{run}.json
+
+        Arguments:
+        ---------
+            path: str | None
+                Optional explicit path to write to.  If None, auto-derives
+                path from first input file with type="raw" and
+                purpose="sample-data".
+
+            overwrite: bool
+                Whether to overwrite existing file.  Default: True
+
+        Returns:
+        -------
+            Absolute path to the written file.
+
+        Raises:
+        ------
+            ValueError
+                If validation fails or path cannot be auto-derived.
+
+            FileExistsError
+                If file exists and overwrite=False.
+
+            IOError
+                If write fails.
+
+        Example:
+            # Auto-derive path
+            path = builder.write()
+            # /SNS/ARCS/IPTS-12345/shared/autoreduce/ARCS_123456.json
+
+            # Explicit path
+            path = builder.write("/custom/path/reduction.json")
+
+            # Don't overwrite
+            path = builder.write(overwrite=False)  # Raises if exists
+
+        """
+        # 1. Validate
+        errors = self.validate()
+        if errors:
+            error_list = "\n".join(f"  - {e}" for e in errors)
+            msg = f"Validation failed:\n{error_list}"
+            raise ValueError(msg)
+
+        # 2. Derive path if needed
+        if path is None:
+            path = self._derive_path()
+
+        # 3. Check overwrite
+        if not overwrite and os.path.exists(path):
+            msg = f"File already exists: {path}"
+            raise FileExistsError(msg)
+
+        # 4. Build JSON structure
+        content = {
+            "version": "1.0",
+            "input_files": self._input_files,
+            "output_files": self._output_files,
+            "created": self._generate_timestamp(),
+            "user": self._user,
+            "metadata": self._metadata,
+        }
+
+        # 5. Create directories
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+
+        # 6. Write file
+        with open(path, "w") as f:
+            json.dump(content, f, indent=4, sort_keys=True)
+
+        return path
+
+    def write_safe(
+        self, path: str | None = None, overwrite: bool = True
+    ) -> str | None:
+        """Write the reduction file to disk with error handling.  Never raises.
+
+        This is a convenience wrapper around write() that catches all
+        exceptions and prints them to stderr.  Use this in autoreduction
+        scripts where cataloging failures should not break the reduction.
+
+        Arguments:
+        ---------
+            path: str | None
+                Same as write().
+
+            overwrite: bool
+                Same as write().
+
+        Returns:
+        -------
+            Absolute path to written file on success, None on failure.
+
+        Example:
+            # In autoreduction script - safe, won't crash reduction
+            path = builder.write_safe()
+            if path:
+                print(f"Reduction cataloged: {path}")
+            else:
+                print("Warning: Cataloging failed (see stderr)")
+
+        """
+        try:
+            return self.write(path, overwrite)
+        except Exception as e:  # noqa: BLE001
+            # Intentionally catch all exceptions - design requirement for
+            # autoreduction scripts where cataloging failures should never
+            # break the reduction workflow
+            msg = f"Warning: Failed to catalog reduction: {e}"
+            print(msg, file=sys.stderr)
+            traceback.print_exc()
+            return None
+
+    @classmethod
+    def load(cls, path: str) -> ReductionFileBuilder:
+        """Load an existing reduction file for modification.
+
+        Arguments:
+        ---------
+            path: str
+                Path to existing JSON reduction file.
+
+        Returns:
+        -------
+            New ReductionFileBuilder instance populated with file contents.
+
+        Raises:
+        ------
+            FileNotFoundError
+                If file doesn't exist.
+
+            ValueError
+                If file is not valid JSON or missing required fields.
+
+        Example:
+            # Load and modify existing file
+            builder = ReductionFileBuilder.load(
+                "/SNS/ARCS/IPTS-12345/shared/autoreduce/ARCS_123456.json"
+            )
+            builder.add_output(
+                new_output_file, type="processed", purpose="reduced-data"
+            )
+            builder.write()  # Overwrites original file
+
+        """
+        if not os.path.exists(path):
+            msg = f"Reduction file not found: {path}"
+            raise FileNotFoundError(msg)
+
+        with open(path) as f:
+            content = json.load(f)
+
+        # Validate required fields
+        required = ["user", "metadata", "input_files", "output_files"]
+        missing = [f for f in required if f not in content]
+        if missing:
+            msg = f"Invalid reduction file, missing fields: {missing}"
+            raise ValueError(msg)
+
+        # Create builder
+        builder = cls(user=content["user"], metadata=content["metadata"])
+
+        # Add files (without fields if not present)
+        for f in content["input_files"]:
+            builder.add_input(
+                f["location"],
+                f["type"],
+                f["purpose"],
+                fields=f.get("fields"),  # May be None
+            )
+
+        for f in content["output_files"]:
+            builder.add_output(
+                f["location"],
+                f["type"],
+                f["purpose"],
+                fields=f.get("fields"),
+            )
+
+        return builder
+
+    # Private helper methods
+
+    def _resolve_path(self, location: str, relative_to: str | None) -> str:
+        """Resolve location to absolute path.
+
+        Stores validation errors internally; never raises.
+        """
+        # If already absolute, use as-is
+        # (validation will enforce canonical roots)
+        if os.path.isabs(location):
+            return location
+
+        # If relative and relative_to provided, resolve
+        if relative_to:
+            return os.path.abspath(os.path.join(relative_to, location))
+
+        # Relative without relative_to — store error and return as-is
+        msg = (
+            f"Path must be absolute or have relative_to specified: {location}"
+        )
+        self._validation_errors.append(msg)
+        return location
+
+    def _derive_path(self) -> str:
+        """Auto-derive JSON file path from first raw sample-data input.
+
+        Self-contained: duplicates a minimal regex for raw NeXus paths to
+        extract facility, instrument, IPTS, and run_number. No imports from
+        other parts of this repository.
+        """
+        # Find first raw sample-data input
+        raw_sample = None
+        for f in self._input_files:
+            if f.get("type") == "raw" and f.get("purpose") == "sample-data":
+                raw_sample = f["location"]
+                break
+
+        if not raw_sample:
+            msg = (
+                "Cannot auto-derive path: no input file with type='raw' "
+                "and purpose='sample-data'. Either add one or provide "
+                "explicit path."
+            )
+            raise ValueError(msg)
+
+        raw_nexus_regex = re.compile(
+            r"^/(?P<facility>SNS|HFIR)/"
+            r"(?P<instrument>[A-Z0-9_]+)/"
+            r"IPTS-(?P<ipts>\d+)/"
+            r"(?:[^/]+/)*"
+            r"[^/_]*_(?P<run_number>\d+)"
+            r"(?:_event|_histo)?"
+            r"\.(?:nxs(?:\.h5)?)$"
+        )
+
+        match = raw_nexus_regex.search(raw_sample)
+        if not match:
+            msg = (
+                f"Cannot parse facility/instrument/experiment from: "
+                f"{raw_sample}"
+            )
+            raise ValueError(msg)
+
+        facility = match.group("facility")
+        instrument = match.group("instrument")
+        ipts = match.group("ipts")
+        run_number = match.group("run_number")
+        experiment = f"IPTS-{ipts}"
+
+        return (
+            f"/{facility}/{instrument}/{experiment}/shared/autoreduce/"
+            f"{instrument}_{run_number}.json"
+        )
+
+    @staticmethod
+    def _generate_timestamp() -> str:
+        """Generate RFC3339 timestamp with timezone."""
+        now = datetime.datetime.now(datetime.timezone.utc).astimezone()
+        return now.isoformat()

{pyoncat-2.0 → pyoncat-2.3}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "poetry.masonry.api"
 # https://github.com/python-poetry/roadmap/issues/3
 [tool.poetry]
 name = "pyoncat"
-version = "2.0"
+version = "2.3"
 description = "A Python Client for ONCat (the ORNL Neutron Catalog)."
 authors = ["ONCat Support <oncat-support@ornl.gov>"]
 readme = ["pyoncat/README.md", "pyoncat/LICENSE"]