pyoncat 2.6__tar.gz → 2.8__tar.gz

{pyoncat-2.6 → pyoncat-2.8}/PKG-INFO

@@ -1,20 +1,19 @@
 Metadata-Version: 2.4
 Name: pyoncat
-Version: 2.6
+Version: 2.8
 Summary: A Python Client for ONCat (the ORNL Neutron Catalog).
 Keywords: ornl,neutron,metadata,catalog
 Author: ONCat Support
 Author-email: oncat-support@ornl.gov
-Requires-Python: >=3.7,<4
+Requires-Python: >=3.9,<4
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Requires-Dist: requests
 Project-URL: Homepage, https://oncat.ornl.gov
 Description-Content-Type: text/markdown
@@ -59,6 +58,10 @@ Alternatively, a Conda package is available up on [Anaconda](https://anaconda.or
 
 To use the authenticated version of the API, you need to obtain credentials from an ONCat administrator. Please contact ONCat Support at [oncat-support@ornl.gov](mailto:oncat-support@ornl.gov) to request credentials.
 
+### Request headers
+
+Every request PyONCat makes carries two headers: `User-Agent: pyoncat/<version> requests/<version> Python/<major.minor>`, naming PyONCat, the `requests` library, and the Python major.minor version, and `API-Client: v1 pyoncat/<version>`. They let server logs tell PyONCat traffic from other clients.
+
 ### Examples
 
 For usage examples, please refer to the API documentation at [oncat.ornl.gov](https://oncat.ornl.gov).

{pyoncat-2.6 → pyoncat-2.8}/pyoncat/README.md

@@ -38,6 +38,10 @@ Alternatively, a Conda package is available up on [Anaconda](https://anaconda.or
 
 To use the authenticated version of the API, you need to obtain credentials from an ONCat administrator. Please contact ONCat Support at [oncat-support@ornl.gov](mailto:oncat-support@ornl.gov) to request credentials.
 
+### Request headers
+
+Every request PyONCat makes carries two headers: `User-Agent: pyoncat/<version> requests/<version> Python/<major.minor>`, naming PyONCat, the `requests` library, and the Python major.minor version, and `API-Client: v1 pyoncat/<version>`. They let server logs tell PyONCat traffic from other clients.
+
 ### Examples
 
 For usage examples, please refer to the API documentation at [oncat.ornl.gov](https://oncat.ornl.gov).

{pyoncat-2.6 → pyoncat-2.8}/pyoncat/__init__.py

@@ -34,7 +34,18 @@ from pyoncat.reduction import ReductionFileBuilder
 if TYPE_CHECKING:
     import threading
 
-__version__ = "2.6"
+__version__ = "2.8"
+
+# Sent on every request PyONCat makes, API calls and token requests alike,
+# so server logs can tell PyONCat traffic from other clients.
+_USER_AGENT = (
+    f"pyoncat/{__version__} requests/{requests.__version__} "
+    f"Python/{sys.version_info.major}.{sys.version_info.minor}"
+)
+_CLIENT_HEADERS = {
+    "User-Agent": _USER_AGENT,
+    "API-Client": f"v1 pyoncat/{__version__}",
+}
 
 # Constant for autoreduction user
 AUTOREDUCTION_USER = "auto"
@@ -47,6 +58,7 @@ __all__ = [
     "REAUTH_NEVER",
     "REAUTH_PROMPT",
     "RESOURCE_OWNER_CREDENTIALS_FLOW",
+    "ConflictError",
     "DeviceAuthorizationCancelled",
     "DeviceAuthorizationChallenge",
     "DeviceAuthorizationDenied",
@@ -398,12 +410,12 @@ class ONCat:
         Cycle: Cycle
         Datafile: Datafile
         Reduction: Reduction
+        Dataset: Dataset
         Simulation: Simulation
         User: User
         Task: Task
         Info: Info
         Cache: Cache
-        Usage: Usage
         Template: Template
 
     def __init__(
@@ -525,14 +537,17 @@ class ONCat:
                     timeout=self._timeout,
                 )
             else:
+                auth_headers = (
+                    {"Authorization": "Bearer " + self._api_token}
+                    if self._api_token
+                    else {}
+                )
                 response = getattr(requests, method)(
                     full_url,
                     params=kwargs,
                     json=data,
                     verify=self._should_verify(),
-                    headers={"Authorization": "Bearer " + self._api_token}
-                    if self._api_token
-                    else None,
+                    headers={**_CLIENT_HEADERS, **auth_headers},
                     timeout=self._timeout,
                 )
             try:
@@ -547,6 +562,9 @@ class ONCat:
                 if error.response.status_code == 404:
                     msg = f'Could not find resource at "{full_url}"'
                     raise NotFoundError(msg) from error
+                if error.response.status_code == 409:
+                    msg = _conflict_message(error.response)
+                    raise ConflictError(msg) from error
                 msg = f'Error: "{error!s}"'
                 raise PyONCatError(msg) from error
 
@@ -750,7 +768,7 @@ class ONCat:
 
         Revocation uses the configured public `client_id` and no secret
         (the device-authorization client is a public client, RFC 8628
-        / ADR-0058).
+        / ADR-000058).
 
         Per RFC 7009 §2.2 the revocation endpoint returns HTTP 200 even for
         a token that is already invalid, so a 200 confirms the request was
@@ -799,6 +817,7 @@ class ONCat:
                     verify=self._should_verify(),
                     timeout=post_timeout,
                     headers={
+                        **_CLIENT_HEADERS,
                         "Content-Type": "application/x-www-form-urlencoded",
                         "Accept": "application/json",
                     },
@@ -975,6 +994,7 @@ class ONCat:
                 ),
                 scope=self._scopes,
             )
+            self._oauth_client.headers.update(_CLIENT_HEADERS)
         try:
             token = self._oauth_client.fetch_token(
                 self._url + "/oauth/token",
@@ -1012,6 +1032,7 @@ class ONCat:
                     client_secret=self._client_secret,
                 )
             )
+            initial_oauth_client.headers.update(_CLIENT_HEADERS)
 
             try:
                 token = initial_oauth_client.fetch_token(
@@ -1060,6 +1081,7 @@ class ONCat:
             auto_refresh_kwargs=auto_refresh_kwargs,
             token_updater=self._save_token,
         )
+        self._oauth_client.headers.update(_CLIENT_HEADERS)
 
     def _login_device_authorization(
         self,
@@ -1121,7 +1143,7 @@ class ONCat:
             device_auth_body["scope"] = scope_str
 
         # The caller's `device_authorization_timeout` bounds the WHOLE sign-in
-        # (ADR-0097), so the deadline clock starts BEFORE the initial
+        # (ADR-000097), so the deadline clock starts BEFORE the initial
         # device-authorization POST. A slow initial POST therefore counts
         # against the overall budget. `http_timeout` still caps each
         # individual POST; the caller deadline is the cumulative bound.
@@ -1142,6 +1164,7 @@ class ONCat:
                 verify=self._should_verify(),
                 timeout=post_timeout,
                 headers={
+                    **_CLIENT_HEADERS,
                     "Content-Type": "application/x-www-form-urlencoded",
                     "Accept": "application/json",
                 },
@@ -1230,6 +1253,7 @@ class ONCat:
                     verify=self._should_verify(),
                     timeout=post_timeout,
                     headers={
+                        **_CLIENT_HEADERS,
                         "Content-Type": "application/x-www-form-urlencoded",
                         "Accept": "application/json",
                     },
@@ -1397,6 +1421,7 @@ class ONCat:
                 },
                 token_updater=self._save_token,
             )
+            self._oauth_client.headers.update(_CLIENT_HEADERS)
 
 
 class ONCatObject:
@@ -1556,6 +1581,12 @@ ONCatRepresentation = ONCatObject
 ########################################################################
 
 
+# TODO: The REST documentation page derives the PyONCat class and method
+# in each code example from the resource's namespace and path, without
+# consulting this module. Where a resource has no class here, or the
+# class lacks the method, the example does not run. Decide how the
+# documentation should learn what this module provides or otherwise
+# resolve this mismatch.
 class _ONCatMixinMeta(type):
     REGISTERED_RESOURCES: ClassVar[list] = []
 
@@ -1719,7 +1750,7 @@ class Grouping(_ListableONCatMixin):
 
 class Mapping(_ListableONCatMixin):
     _RESOURCE_ENDPOINT = "mappings"
-    _NAMESPACE = "settings"
+    _NAMESPACE = "option"
 
 
 class Proposal(_ListableONCatMixin):
@@ -1772,6 +1803,57 @@ class Reduction(
     _NAMESPACE = "api"
 
 
+class Dataset(_ListableONCatMixin):
+    """The Datasets of an instrument: groups of reductions that belong
+    together, read-only.
+
+    Every cataloged reduction belongs to exactly one Dataset, and every
+    Dataset to exactly one experiment.  ONCat decides a reduction's
+    Dataset when the reduction file is ingested and stores its
+    identifier as the reduction's `indexed.dataset`.  The identifier
+    takes one of two forms: `<experiment>/<name>`, such as
+    `IPTS-20841/my-dataset`, for the reductions of an experiment whose
+    reduction files give the same `dataset.name` (see
+    `ReductionFileBuilder.set_dataset_name`); and the reduction file's
+    location, such as
+    `/SNS/REF_M/IPTS-20841/shared/autoreduce/REF_M_32025.json`, for any
+    other reduction, autoreduced or not, which is a Dataset of its own.
+    Datasets exist only on instruments where ONCat builds them; on any
+    other instrument `list` returns an empty list.
+
+    The ONCat website calls a named Dataset a Reduction Set and an
+    unnamed one a Reduction; both are this resource.
+
+    A Dataset record holds `id`, `name` (`None` when unnamed),
+    `facility`, `instrument`, `experiment`, `reductions` and `runs`
+    (each `{ranges, min, max, count}`: `ranges` lists `[first, last]`
+    pairs of reduction keys or run numbers), `earliest` and `latest`
+    (each `{created, ingested, modified}`), and `metadata`, a summary of
+    the reductions' metadata whose leaves hold `min`, `max`, `values`
+    (a list of strings, or the string `"TRUNCATED"` once a path has too
+    many distinct strings to list), and `booleans` (the distinct
+    booleans at the path, sorted: `[False]`, `[True]` or
+    `[False, True]`; present only when a reduction holds a boolean
+    there).
+
+    `retrieve` takes an identifier in either form, and `list`
+    takes the `experiment`, `name`, and `run` filters and paging
+    parameters; `run` keeps the Datasets whose `runs` ranges include
+    that run, whatever their experiment.
+    List a Dataset's reductions with `Reduction.list(..., dataset=...)`:
+
+        dataset = oncat.Dataset.retrieve(
+            "IPTS-20841/my-dataset", facility="SNS", instrument="REF_M"
+        )
+        reductions = oncat.Reduction.list(
+            facility="SNS", instrument="REF_M", dataset=dataset.id
+        )
+    """
+
+    _RESOURCE_ENDPOINT = "datasets"
+    _NAMESPACE = "api"
+
+
 class Simulation(_ControllerONCatMixin, _ListableONCatMixin):
     _RESOURCE_ENDPOINT = "simulations"
     _NAMESPACE = "api"
@@ -1803,11 +1885,6 @@ class Cache(_UpdatableONCatMixin):
     _NAMESPACE = "admin"
 
 
-class Usage(_ListableONCatMixin):
-    _RESOURCE_ENDPOINT = "usage"
-    _NAMESPACE = "admin"
-
-
 ########################################################################
 
 
@@ -1818,51 +1895,6 @@ class Template(
     _NAMESPACE = "settings"
 
 
-########################################################################
-# Summary Resources
-########################################################################
-
-
-class ExperimentSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "experiments"
-    _NAMESPACE = "summary"
-
-
-class GroupingSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "groupings"
-    _NAMESPACE = "summary"
-
-
-class InstrumentSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "instruments"
-    _NAMESPACE = "summary"
-
-
-class ReductionSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "reductions"
-    _NAMESPACE = "summary"
-
-
-class RunSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "runs"
-    _NAMESPACE = "summary"
-
-
-class SampleSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "samples"
-    _NAMESPACE = "summary"
-
-
-class ScanSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "scans"
-    _NAMESPACE = "summary"
-
-
-class SessionSummary(_ONCatResource):
-    _RESOURCE_ENDPOINT = "sessions"
-    _NAMESPACE = "summary"
-
-
 ########################################################################
 # Misc Tools
 ########################################################################
@@ -2028,6 +2060,18 @@ def _yield_nodes(d, path, include_branches):
             yield node_path
 
 
+def _conflict_message(response):
+    """Return the message a 409 response body carries, which names the
+    state that refused the request, or the response's status line when
+    the body holds none."""
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    message = body.get("message") if isinstance(body, dict) else None
+    return message or f'Error: "{response.status_code} {response.reason}"'
+
+
 ########################################################################
 # Exceptions
 ########################################################################
@@ -2078,6 +2122,16 @@ class BadRequestError(PyONCatError):
     """
 
 
+class ConflictError(PyONCatError):
+    """An error that is raised when a request conflicts with the current
+    state of the item it acts on, such as submitting a DOI that is no
+    longer drafting.
+
+    The message is the API's explanation. The same request can succeed
+    once the item's state allows it, so check the item before retrying.
+    """
+
+
 class DeviceAuthorizationError(PyONCatError):
     """An error that is raised when the OAuth 2.0 Device Authorization
     Grant (RFC 8628) flow cannot complete (for example, the user did not
@@ -2096,25 +2150,25 @@ class DeviceAuthorizationError(PyONCatError):
 # The four outcome subclasses below intentionally omit the `Error` suffix
 # (triggering N818): the names are the public 2.6 device-authorization
 # API contract
-# (ADR-0097), spelled to read as outcomes the caller catches by reason --
+# (ADR-000097), spelled to read as outcomes the caller catches by reason --
 # Denied / Expired / Cancelled / Timeout. They subclass
 # `DeviceAuthorizationError`, so the suffixed base type still catches them.
-class DeviceAuthorizationDenied(DeviceAuthorizationError):  # noqa: N818 - public API name (ADR-0097)
+class DeviceAuthorizationDenied(DeviceAuthorizationError):  # ruff: ignore[error-suffix-on-exception-name] - public API name (ADR-000097)
     """Raised when the user explicitly denied the sign-in request
     (the IdP returned `access_denied`, RFC 8628 §3.5)."""
 
 
-class DeviceAuthorizationExpired(DeviceAuthorizationError):  # noqa: N818 - public API name (ADR-0097)
+class DeviceAuthorizationExpired(DeviceAuthorizationError):  # ruff: ignore[error-suffix-on-exception-name] - public API name (ADR-000097)
     """Raised when the device code expired before the user approved the
     sign-in (the IdP returned `expired_token`, RFC 8628 §3.5)."""
 
 
-class DeviceAuthorizationCancelled(DeviceAuthorizationError):  # noqa: N818 - public API name (ADR-0097)
+class DeviceAuthorizationCancelled(DeviceAuthorizationError):  # ruff: ignore[error-suffix-on-exception-name] - public API name (ADR-000097)
     """Raised when the caller cancelled the sign-in in progress via the
     `cancel_event` passed to `login()`."""
 
 
-class DeviceAuthorizationTimeout(DeviceAuthorizationError):  # noqa: N818 - public API name (ADR-0097)
+class DeviceAuthorizationTimeout(DeviceAuthorizationError):  # ruff: ignore[error-suffix-on-exception-name] - public API name (ADR-000097)
     """Raised when the sign-in did not complete before the overall
     caller deadline (`device_authorization_timeout`) or the server's own
     `expires_in`, whichever came first."""

{pyoncat-2.6 → pyoncat-2.8}/pyoncat/reduction.py

@@ -10,6 +10,51 @@ import sys
 import traceback
 from typing import Any
 
+# PyONCat is installed without the rest of this repository, so the
+# constants below copy ONCat's rules instead of importing them.
+
+# ONCat takes a reduction file's facility and instrument from the first
+# two folders of the file's location.
+_LOCATION_REGEX = re.compile(
+    r"^/(?P<facility>HFIR|SNS)/(?P<instrument>[A-Z0-9_]+)/"
+)
+
+# ONCat's pattern for an instrument-level shared file: a file under
+# /<FAC>/<INST>/shared/ with no IPTS-<n> folder on the way.  ONCat
+# accepts such a file as an input only when <FAC> and <INST> are those
+# of the reduction file's own location.
+_SHARED_INPUT_REGEX = re.compile(
+    r"^/(?P<facility>HFIR|SNS)/(?P<instrument>[A-Z0-9_]*)/shared/"
+    r"(?:(?!IPTS-\d+/)[^/]+/)*[^/]+$"
+)
+
+# A raw input inside an experiment: /<FAC>/<INST>/IPTS-<n>/.../<name>.
+_RAW_INPUT_REGEX = re.compile(
+    r"^/(?P<facility>SNS|HFIR)/"
+    r"(?P<instrument>[A-Z0-9_]+)/"
+    r"(?P<experiment>IPTS-\d+)/"
+    r"(?:[^/]+/)*"
+    r"(?P<name>[^/]+)$"
+)
+
+_TRAILING_RUN_NUMBER_REGEX = re.compile(
+    r"_(\d+)(?:_event|_histo)?\.nxs(?:\.h5)?$"
+)
+
+# ONCat refuses a Dataset name with any of these segments, the text
+# between two "/": a web address rewrites them, so the Dataset could not
+# be opened by its address.
+_REFUSED_DATASET_NAME_SEGMENTS = ("", ".", "..")
+
+
+def _fspath(path: str | os.PathLike[str]) -> str:
+    """Return os.fspath(path) for a path object, and path itself otherwise.
+
+    The builder stores, validates, and writes locations as str, so a
+    pathlib.Path gives the same result as its str.  Any other value,
+    bytes included, passes through as the caller gave it."""
+    return os.fspath(path) if isinstance(path, os.PathLike) else path
+
 
 class ReductionFileBuilder:
     """Builder for creating JSON Reduction Files for ONCat cataloging.
@@ -30,8 +75,9 @@ class ReductionFileBuilder:
         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.
+    `write_safe()` never raises, so a failed write does not stop the rest
+    of the script; its stderr output marks an SNS autoreduction job as
+    failed.
 
     Example usage:
 
@@ -75,29 +121,46 @@ class ReductionFileBuilder:
         """
         self._user = user
         self._metadata = metadata if metadata is not None else {}
+        # Kept apart from metadata, so set_metadata() and
+        # update_metadata() never drop a name set_dataset_name() set.
+        self._dataset: dict[str, Any] | None = None
         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,
+        location: str | os.PathLike[str],
         type: str,
         purpose: str,
         fields: dict[str, str] | None = None,
-        relative_to: str | None = None,
+        relative_to: str | os.PathLike[str] | None = None,
     ) -> ReductionFileBuilder:
         """Add an input file to the reduction.
 
+        An entry identical to one already added (same resolved location,
+        type, purpose, and fields) is skipped, so a second reduction pass
+        in the same job can add the same files again.
+
         Arguments:
         ---------
-            location: str
+            location: str | os.PathLike[str]
                 Path to the input file.  Must be absolute, or relative if
-                relative_to is provided.
+                relative_to is provided.  An input may also be a shared
+                file of the reduction's own instrument, under
+                /<FAC>/<INST>/shared/ where <FAC> and <INST> are the first
+                two folders of the reduction file's location (for example
+                a grouping file); ONCat stores such a file by reference
+                only, listing it in the reduction without cataloging it as
+                a datafile.  validate() and write() refuse a shared file of
+                another facility or instrument whenever the reduction
+                file's location is known: the path passed to write(), or
+                the path write() derives from the first raw sample-data
+                input.
 
             type: str
                 File type.  Must be one of: "raw", "processed",
-                "user-provided", "history".
+                "user-provided", "history", "simulation".
 
             purpose: str
                 File purpose in kebab-case (e.g., "sample-data",
@@ -109,7 +172,7 @@ class ReductionFileBuilder:
                 "source.path": "dest_path" for extracting metadata.
                 Primarily used for processed files.
 
-            relative_to: str | None
+            relative_to: str | os.PathLike[str] | None
                 Base directory for relative paths.  If provided and
                 location is relative, will be resolved to absolute path.
 
@@ -142,7 +205,10 @@ class ReductionFileBuilder:
             )
 
         """
-        resolved_location = self._resolve_path(location, relative_to)
+        resolved_location = self._resolve_path(
+            _fspath(location),
+            None if relative_to is None else _fspath(relative_to),
+        )
 
         file_dict: dict[str, Any] = {
             "location": resolved_location,
@@ -154,19 +220,25 @@ class ReductionFileBuilder:
         if fields:
             file_dict["fields"] = fields
 
-        self._input_files.append(file_dict)
+        # The reduction file schema requires unique entries in each list
+        if file_dict not in self._input_files:
+            self._input_files.append(file_dict)
         return self
 
     def add_output(
         self,
-        location: str,
+        location: str | os.PathLike[str],
         type: str,
         purpose: str,
         fields: dict[str, str] | None = None,
-        relative_to: str | None = None,
+        relative_to: str | os.PathLike[str] | None = None,
     ) -> ReductionFileBuilder:
         """Add an output file to the reduction.
 
+        An entry identical to one already added (same resolved location,
+        type, purpose, and fields) is skipped, so a second reduction pass
+        in the same job can add the same files again.
+
         The 'fields' parameter is primarily used for output files to extract
         specific metadata from processed NeXus files, for example:
 
@@ -177,13 +249,13 @@ class ReductionFileBuilder:
 
         Arguments:
         ---------
-            location: str
+            location: str | os.PathLike[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".
+                "user-provided", "history", "simulation".
 
             purpose: str
                 File purpose in kebab-case (e.g., "reduced-data",
@@ -195,7 +267,7 @@ class ReductionFileBuilder:
                 "source.path": "dest_path" for extracting metadata.
                 Commonly used for processed output files.
 
-            relative_to: str | None
+            relative_to: str | os.PathLike[str] | None
                 Base directory for relative paths.  If provided and
                 location is relative, will be resolved to absolute path.
 
@@ -221,7 +293,10 @@ class ReductionFileBuilder:
             )
 
         """
-        resolved_location = self._resolve_path(location, relative_to)
+        resolved_location = self._resolve_path(
+            _fspath(location),
+            None if relative_to is None else _fspath(relative_to),
+        )
 
         file_dict: dict[str, Any] = {
             "location": resolved_location,
@@ -233,7 +308,9 @@ class ReductionFileBuilder:
         if fields:
             file_dict["fields"] = fields
 
-        self._output_files.append(file_dict)
+        # The reduction file schema requires unique entries in each list
+        if file_dict not in self._output_files:
+            self._output_files.append(file_dict)
         return self
 
     def set_metadata(self, metadata: dict[str, Any]) -> ReductionFileBuilder:
@@ -316,6 +393,59 @@ class ReductionFileBuilder:
         """
         return self._metadata.copy()
 
+    def set_dataset_name(self, name: str) -> ReductionFileBuilder:
+        """Set the dataset name, written as the reduction file's
+        top-level "dataset": {"name": name}.
+
+        Reductions in one experiment that carry the same dataset name
+        belong to one Dataset, which the ONCat website calls a Reduction
+        Set.  Names count exactly as written, so names that differ only
+        in case or spacing make two sets.  A reduction without a name is
+        a Dataset of its own, which the website calls a Reduction.
+
+        The name is kept apart from the metadata, so set_metadata() and
+        update_metadata() leave it in place, whichever order they are
+        called in.
+
+        Arguments:
+        ---------
+            name: str
+                Dataset name.  Must be a non-empty string in which no
+                part between slashes is empty, "." or "..", since a web
+                address rewrites such a part: "a/b", ".a" and "..." are
+                names, but "..", "a/../b", "a//b", "/a" and "a/" are not.
+
+        Returns:
+        -------
+            Self for method chaining.  An invalid name is not set (any
+            name set earlier is kept); the error is stored internally
+            and surfaced by validate().
+
+        Example:
+            builder.set_dataset_name("my-dataset")
+            builder.set_metadata({"ei": 100.0})
+            builder.to_dict()["dataset"]  # {"name": "my-dataset"}
+
+        """
+        if not isinstance(name, str) or not name:
+            msg = f"Dataset name must be a non-empty string: {name!r}"
+            self._validation_errors.append(msg)
+            return self
+
+        if any(
+            segment in _REFUSED_DATASET_NAME_SEGMENTS
+            for segment in name.split("/")
+        ):
+            msg = (
+                "Dataset name must have no empty, '.' or '..' part between "
+                f"slashes: {name!r}"
+            )
+            self._validation_errors.append(msg)
+            return self
+
+        self._dataset = {"name": name}
+        return self
+
     def clear_outputs(self) -> ReductionFileBuilder:
         """Remove all output files from the builder.
 
@@ -351,11 +481,19 @@ class ReductionFileBuilder:
         - 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/...)
+        - An input under an instrument's shared directory,
+          /<FAC>/<INST>/shared/, belongs to the facility and instrument
+          that are the first two folders of the reduction file's
+          location.  validate() knows that location only as the path
+          write() derives from the first raw sample-data input, and
+          leaves this check to ONCat when it cannot derive one.
+          write(path) checks against the path it is given.
+
+        A raw sample-data input is not required: write() needs one only
+        to derive a path when it is given none.
 
         Does NOT validate:
 
@@ -378,51 +516,7 @@ class ReductionFileBuilder:
                 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
+        return self._validate(self._derived_location())
 
     def to_dict(self) -> dict[str, Any]:
         """Preview the JSON structure that will be written (without timestamp).
@@ -431,6 +525,8 @@ class ReductionFileBuilder:
         -------
             Dictionary representing the reduction file structure.  Does not
             include the 'created' timestamp which is generated on write().
+            Includes "dataset" only after set_dataset_name() has set a
+            name, or after load() of a file whose name it accepts.
 
         Example:
             import json
@@ -438,22 +534,32 @@ class ReductionFileBuilder:
             print(json.dumps(preview, indent=2))
 
         """
-        return {
+        content = {
             "version": "1.0",
             "input_files": self._input_files,
             "output_files": self._output_files,
             "user": self._user,
             "metadata": self._metadata,
         }
+        if self._dataset is not None:
+            content["dataset"] = self._dataset
+
+        return content
 
-    def write(self, path: str | None = None, overwrite: bool = True) -> str:
+    def write(
+        self,
+        path: str | os.PathLike[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)
+        1. Validates builder state as validate() does, checking shared
+           inputs against path, or against the derived path when path
+           is None
+        2. Derives path if not provided (from first raw sample-data input)
+        3. Generates RFC3339 timestamp with timezone
         4. Creates parent directories if needed
         5. Writes JSON file with 4-space indentation, sorted keys
         6. Returns absolute path to written file
@@ -462,12 +568,19 @@ class ReductionFileBuilder:
 
             /{facility}/{inst}/{experiment}/shared/autoreduce/{inst}_{run}.json
 
+        {facility}, {inst}, and {experiment} are the first three folders
+        of the raw sample-data input's path.  {run} is the digits after a
+        leading "{inst}_" in its file name (REF_M_32025.nxs.h5 is run
+        32025), otherwise the digits before an optional _event or _histo
+        and the NeXus extension.
+
         Arguments:
         ---------
-            path: str | None
+            path: str | os.PathLike[str] | None
                 Optional explicit path to write to.  If None, auto-derives
                 path from first input file with type="raw" and
-                purpose="sample-data".
+                purpose="sample-data", and raises ValueError when there is
+                no such input.
 
             overwrite: bool
                 Whether to overwrite existing file.  Default: True
@@ -479,7 +592,9 @@ class ReductionFileBuilder:
         Raises:
         ------
             ValueError
-                If validation fails or path cannot be auto-derived.
+                If validation fails, or if path is None and cannot be
+                auto-derived: "no raw sample-data input to derive a path
+                from; pass a path" when there is no raw sample-data input.
 
             FileExistsError
                 If file exists and overwrite=False.
@@ -499,8 +614,13 @@ class ReductionFileBuilder:
             path = builder.write(overwrite=False)  # Raises if exists
 
         """
+        if path is not None:
+            path = _fspath(path)
+
         # 1. Validate
-        errors = self.validate()
+        errors = self._validate(
+            path if path is not None else self._derived_location()
+        )
         if errors:
             error_list = "\n".join(f"  - {e}" for e in errors)
             msg = f"Validation failed:\n{error_list}"
@@ -516,14 +636,7 @@ class ReductionFileBuilder:
             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,
-        }
+        content = {**self.to_dict(), "created": self._generate_timestamp()}
 
         # 5. Create directories
         os.makedirs(os.path.dirname(path), exist_ok=True)
@@ -535,17 +648,26 @@ class ReductionFileBuilder:
         return path
 
     def write_safe(
-        self, path: str | None = None, overwrite: bool = True
+        self,
+        path: str | os.PathLike[str] | None = None,
+        overwrite: bool = True,
     ) -> str | None:
-        """Write the reduction file to disk with error handling.  Never raises.
+        """Write the reduction file like write(), but never raise.
 
-        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.
+        write_safe() writes the same file to the same path as write(),
+        and catches every exception write() raises, so the rest of the
+        script keeps running.  On failure it prints the error and its
+        traceback to stderr and returns None.
+
+        write_safe() only writes the file; it does not catalog it.  At
+        SNS, the post-processing agent catalogs the reduction file after
+        the autoreduction job succeeds.  In an SNS autoreduction job, the
+        stderr output of a failed write marks the job as failed: the web
+        monitor shows it as failed, and the reduction is not cataloged.
 
         Arguments:
         ---------
-            path: str | None
+            path: str | os.PathLike[str] | None
                 Same as write().
 
             overwrite: bool
@@ -556,32 +678,34 @@ class ReductionFileBuilder:
             Absolute path to written file on success, None on failure.
 
         Example:
-            # In autoreduction script - safe, won't crash reduction
+            # In an autoreduction script: a failed write does not stop
+            # the script, and its stderr output marks the job as failed
             path = builder.write_safe()
             if path:
-                print(f"Reduction cataloged: {path}")
+                print(f"Reduction file written: {path}")
             else:
-                print("Warning: Cataloging failed (see stderr)")
+                print("Warning: reduction file not written (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
+        except Exception as e:  # ruff: ignore[blind-except]
+            # Intentionally catch every exception so a failed write never
+            # stops the rest of the autoreduction script.  The stderr
+            # output below is what marks an SNS autoreduction job as
+            # failed.
             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:
+    def load(cls, path: str | os.PathLike[str]) -> ReductionFileBuilder:
         """Load an existing reduction file for modification.
 
         Arguments:
         ---------
-            path: str
+            path: str | os.PathLike[str]
                 Path to existing JSON reduction file.
 
         Returns:
@@ -596,6 +720,10 @@ class ReductionFileBuilder:
             ValueError
                 If file is not valid JSON or missing required fields.
 
+        The file's dataset name goes through set_dataset_name()'s check.
+        A name it refuses is not loaded, validate() reports it, and
+        write() raises.
+
         Example:
             # Load and modify existing file
             builder = ReductionFileBuilder.load(
@@ -607,6 +735,7 @@ class ReductionFileBuilder:
             builder.write()  # Overwrites original file
 
         """
+        path = _fspath(path)
         if not os.path.exists(path):
             msg = f"Reduction file not found: {path}"
             raise FileNotFoundError(msg)
@@ -623,6 +752,11 @@ class ReductionFileBuilder:
 
         # Create builder
         builder = cls(user=content["user"], metadata=content["metadata"])
+        dataset = content.get("dataset")
+        if dataset is not None:
+            builder.set_dataset_name(
+                dataset.get("name") if isinstance(dataset, dict) else None
+            )
 
         # Add files (without fields if not present)
         for f in content["input_files"]:
@@ -666,12 +800,82 @@ class ReductionFileBuilder:
         self._validation_errors.append(msg)
         return location
 
+    def _validate(self, reduction_location: str | None) -> list[str]:
+        """Return validate()'s errors for a reduction file at
+        reduction_location; with None, shared inputs are not checked."""
+        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")
+
+        # 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)
+
+        # Check shared inputs belong to the reduction file's instrument
+        owner = (
+            _LOCATION_REGEX.match(os.fspath(reduction_location))
+            if reduction_location is not None
+            else None
+        )
+        if owner:
+            facility = owner.group("facility")
+            instrument = owner.group("instrument")
+            for file_dict in self._input_files:
+                shared = _SHARED_INPUT_REGEX.match(
+                    file_dict.get("location", "")
+                )
+                if shared and (
+                    shared.group("facility") != facility
+                    or shared.group("instrument") != instrument
+                ):
+                    msg = (
+                        f"Shared input must belong to the reduction "
+                        f"file's instrument, under "
+                        f"/{facility}/{instrument}/shared/: "
+                        f"{file_dict['location']} (input file)"
+                    )
+                    errors.append(msg)
+
+        return errors
+
+    def _derived_location(self) -> str | None:
+        """Return the path write() derives, or None when it cannot
+        derive one."""
+        try:
+            return self._derive_path()
+        except ValueError:
+            return None
+
     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.
+        Raises ValueError when there is no such input, or when its path
+        names no facility, instrument, experiment, and run.
         """
         # Find first raw sample-data input
         raw_sample = None
@@ -681,25 +885,16 @@ class ReductionFileBuilder:
                 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."
-            )
+            msg = "no raw sample-data input to derive a path from; pass a 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_INPUT_REGEX.match(raw_sample)
+        run_number = (
+            self._run_number(match.group("name"), match.group("instrument"))
+            if match
+            else None
         )
-
-        match = raw_nexus_regex.search(raw_sample)
-        if not match:
+        if match is None or run_number is None:
             msg = (
                 f"Cannot parse facility/instrument/experiment from: "
                 f"{raw_sample}"
@@ -708,15 +903,25 @@ class ReductionFileBuilder:
 
         facility = match.group("facility")
         instrument = match.group("instrument")
-        ipts = match.group("ipts")
-        run_number = match.group("run_number")
-        experiment = f"IPTS-{ipts}"
+        experiment = match.group("experiment")
 
         return (
             f"/{facility}/{instrument}/{experiment}/shared/autoreduce/"
             f"{instrument}_{run_number}.json"
         )
 
+    @staticmethod
+    def _run_number(name: str, instrument: str) -> str | None:
+        """Return the run in a raw file's name, read as ONCat reads a
+        reduction file's name: the digits after a leading
+        "<instrument>_" (REF_M_32025_event.nxs is run 32025), otherwise
+        the digits before an optional _event or _histo and the NeXus
+        extension; None when neither is there."""
+        run = re.match(
+            rf"{re.escape(instrument)}_(\d+)", name
+        ) or _TRAILING_RUN_NUMBER_REGEX.search(name)
+        return run.group(1) if run else None
+
     @staticmethod
     def _generate_timestamp() -> str:
         """Generate RFC3339 timestamp with timezone."""

{pyoncat-2.6 → pyoncat-2.8}/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.6"
+version = "2.8"
 description = "A Python Client for ONCat (the ORNL Neutron Catalog)."
 authors = ["ONCat Support <oncat-support@ornl.gov>"]
 readme = ["pyoncat/README.md", "pyoncat/LICENSE"]
@@ -21,7 +21,7 @@ packages = [
 ]
 
 [tool.poetry.dependencies]
-python = ">=3.7, <4"
+python = ">=3.9, <4"
 requests = "*"
 oauthlib = { version = "*", optional = true }
 requests-oauthlib = { version = "*", optional = true }