lockss-pybasic 0.3.0.dev2__tar.gz → 0.3.0.dev4__tar.gz

{lockss_pybasic-0.3.0.dev2 → lockss_pybasic-0.3.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lockss-pybasic
-Version: 0.3.0.dev2
+Version: 0.3.0.dev4
 Summary: Basic Python utilities
 License: BSD-3-Clause
 License-File: LICENSE
@@ -16,7 +16,8 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries
-Requires-Dist: click-extra (>=7.16.0,<7.17.0)
+Requires-Dist: annotated-types (>=0.7.0,<0.8.0)
+Requires-Dist: click-extra (>=7.17.0,<7.18.0)
 Requires-Dist: pydantic (>=2.13.0,<2.14.0)
 Project-URL: Repository, https://github.com/lockss/lockss-pybasic
 Description-Content-Type: text/x-rst
@@ -25,7 +26,7 @@ Description-Content-Type: text/x-rst
 lockss-pybasic
 ==============
 
-.. |RELEASE| replace:: 0.3.0-dev2
+.. |RELEASE| replace:: 0.3.0-dev4
 .. |RELEASE_DATE| replace:: NOT YET RELEASED
 
 **Latest release:** |RELEASE| (|RELEASE_DATE|)

{lockss_pybasic-0.3.0.dev2 → lockss_pybasic-0.3.0.dev4}/README.rst

@@ -2,7 +2,7 @@
 lockss-pybasic
 ==============
 
-.. |RELEASE| replace:: 0.3.0-dev2
+.. |RELEASE| replace:: 0.3.0-dev4
 .. |RELEASE_DATE| replace:: NOT YET RELEASED
 
 **Latest release:** |RELEASE| (|RELEASE_DATE|)

{lockss_pybasic-0.3.0.dev2 → lockss_pybasic-0.3.0.dev4}/pyproject.toml

@@ -28,7 +28,7 @@
 
 [project]
 name = "lockss-pybasic"
-version = "0.3.0-dev2" # Always change in __init__.py, and at release time in README.rst and CHANGELOG.rst
+version = "0.3.0-dev4" # Always change in __init__.py, and at release time in README.rst and CHANGELOG.rst
 description = "Basic Python utilities"
 license = { text = "BSD-3-Clause" }
 readme = "README.rst"
@@ -40,7 +40,8 @@ maintainers = [
     { name = "Thib Guicherd-Callin", email = "thib@cs.stanford.edu" },
 ]
 dependencies = [
-    "click-extra (>=7.16.0,<7.17.0)",
+    "annotated-types (>=0.7.0,<0.8.0)", # from Pydantic
+    "click-extra (>=7.17.0,<7.18.0)",
     "pydantic (>=2.13.0,<2.14.0)",
 ]
 classifiers = [

{lockss_pybasic-0.3.0.dev2 → lockss_pybasic-0.3.0.dev4}/src/lockss/pybasic/__init__.py

@@ -36,4 +36,4 @@ ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.
 '''.strip()
 
-__version__ = '0.3.0-dev2'
+__version__ = '0.3.0-dev4'

lockss_pybasic-0.3.0.dev4/src/lockss/pybasic/nodeutil.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2026, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+LOCKSS node utilities.
+"""
+
+from enum import Enum
+from re import Match, Pattern
+import re
+from typing import Annotated, Any, ClassVar, Literal, Optional, Union
+
+from annotated_types import Ge, Le
+from pydantic import BaseModel, BeforeValidator, Field, TypeAdapter, model_validator
+
+
+#: An annotated type for port numbers (0-65535)
+PortNumber = Annotated[int, Ge(0), Le(65535)]
+
+
+class NodeTypeEnum(Enum):
+    """An enumerated type representing LOCKSS node types."""
+    #: An enumerated constant representing LOCKSS 1.x nodes.
+    V1 = 'v1'
+    #: An enumerated constant representing LOCKSS 2.x nodes.
+    V2 = 'v2'
+
+
+class NodeProtocolEnum(Enum):
+    """An enumerated type representing protocols for reaching LOCKSS nodes."""
+    #: An enumerated constant representing HTTP.
+    HTTP = 'http'
+    #: An enumerated constant representing HTTPS.
+    HTTPS = 'https'
+
+
+class BaseNodeSpec(BaseModel):
+
+    DEFAULT_PROTOCOL: ClassVar[NodeProtocolEnum] = NodeProtocolEnum.HTTP
+
+    TYPE_FIELD: ClassVar[dict[str, str]] = dict(title='Type',
+                                                description="The node's type")
+
+    protocol: NodeProtocolEnum = Field(default=DEFAULT_PROTOCOL,
+                                       title='Protocol',
+                                       description="The protocol for reaching the node")
+
+    host: str = Field(title='Host',
+                      description="The node's host")
+
+
+class NodeSpec1(BaseNodeSpec):
+
+    DEFAULT_UI_PORT_V1: ClassVar[int] = 8081
+
+    type: Literal['v1'] = Field(**BaseNodeSpec.TYPE_FIELD)
+
+    ui: PortNumber = Field(default=DEFAULT_UI_PORT_V1,
+                           title='UI Port',
+                           description="The LOCKSS 1.x node's Web user interface port")
+
+
+class NodeSpec2(BaseNodeSpec):
+
+    DEFAULT_REPO_PORT: ClassVar[int] = 24611
+
+    DEFAULT_CFG_PORT: ClassVar[int] = 24612
+
+    DEFAULT_POL_PORT: ClassVar[int] = 24613
+
+    DEFAULT_CRW_PORT: ClassVar[int] = 24614
+
+    DEFAULT_MD_PORT: ClassVar[int] = 24615
+
+    DEFAULT_SOAP_PORT: ClassVar[int] = 24616
+
+    type: Literal['v2'] = Field(**BaseNodeSpec.TYPE_FIELD)
+
+    repository: PortNumber = Field(default=DEFAULT_REPO_PORT,
+                                   title='Repository Port',
+                                   description="The node's Repository Service REST API Port")
+
+    configuration: PortNumber = Field(default=DEFAULT_CFG_PORT,
+                                      title='Configuration Port',
+                                      description="The node's Configuration Service REST API Port")
+
+    poller: PortNumber = Field(default=DEFAULT_POL_PORT,
+                               title='Poller Port',
+                               description="The node's Poller Service REST API Port")
+
+    crawler: PortNumber = Field(default=DEFAULT_CRW_PORT,
+                                title='Crawler Port',
+                                description="The node's Crawler Service REST API Port")
+
+    metadata: PortNumber = Field(default=DEFAULT_MD_PORT,
+                                 title='Metadata Port',
+                                 description="The node's Metadata Service REST API Port")
+
+    soap: PortNumber = Field(default=DEFAULT_SOAP_PORT,
+                             title='SOAP Port',
+                             description="The node's SOAP Compatibility Service REST API Port")
+
+
+_RE_NODE_REFERENCE: Pattern[str] = re.compile(r'((?P<protocol>https?)://)?(?P<host>[^:]+)(:(?P<repository>\d+|(?=:))(:(?P<configuration>\d+|(?=:))(:(?P<poller>\d+|(?=:))(:(?P<crawler>\d+|(?=:))(:(?P<metadata>\d+|(?=:))(:(?P<soap>\d+))?)?)?)?)?)?')
+
+
+#: A type for LOCKSS node specification strings.
+NodeSpecStr = str
+
+
+def _parse_node_spec_string(node_spec_string: NodeSpecStr) -> dict[str, str]:
+    mat: Optional[Match[str]] = _RE_NODE_REFERENCE.fullmatch(node_spec_string)
+    if mat is None:
+        raise ValueError(f'Invalid node specification string: {node_spec_string}')
+    d = dict(host=mat.group('host'))
+    if prot := mat.group('protocol'):
+        d['protocol'] = prot
+    five = ('configuration', 'poller', 'crawler', 'metadata', 'soap')
+    if repo_or_ui := mat.group('repository'):
+        if any(mat.group(x) for x in five) or len(repo_or_ui) >= 5:
+            # 10000 or larger: assume V2
+            d['type'] = NodeTypeEnum.V2.value
+            d['repository'] = repo_or_ui
+        elif len(repo_or_ui) == 4:
+            # 1000 through 9999: assume V1
+            d['type'] = NodeTypeEnum.V1.value
+            d['ui'] = repo_or_ui
+        else:
+            raise ValueError(f'Invalid repository/UI port in node specification string: {repo_or_ui}')
+    else:
+        # Assume V2
+        d['type'] = NodeTypeEnum.V2.value
+    for k in five:
+        if p := mat.group(k):
+            d[k] = p # string okay, will be coerced to int
+    return d
+
+
+def _maybe_deserialize_node_spec_string(value: Any) -> Any:
+    if isinstance(value, NodeSpecStr) and not value.startswith('{'):
+        return _parse_node_spec_string(value)
+    return value
+
+
+#: A type for LOCKSS node specifications, that also accepts a compact LOCKSS
+#: node specification string.
+NodeSpec = Annotated[
+    Annotated[Union[NodeSpec1, NodeSpec2], Field(discriminator='type')],
+    BeforeValidator(_maybe_deserialize_node_spec_string)
+]
+
+
+#: A type adapter for the NodeSpec type.
+_node_spec_adapter: TypeAdapter[NodeSpec] = TypeAdapter(NodeSpec)
+
+
+def get_node_spec_adapter() -> TypeAdapter[NodeSpec]:
+    """
+    Gets a type adapter for the NodeSpec type, which is a union type and cannot
+    be instantiated directly.
+
+    :return: A type adapter for the NodeSpec type.
+    """
+    return _node_spec_adapter
+
+
+NodeSetKind = Literal['NodeSet']
+
+
+NodeSetIdentifier = str
+
+
+NodeIdentifier = str
+
+
+class NodeSet(BaseModel):
+
+    kind: NodeSetKind = Field(title='Kind',
+                              description="This object's kind")
+
+    id: NodeSetIdentifier = Field(title='Node Set Identifier',
+                                  description='An identifier for the node set')
+
+    name: str = Field(title='Node Set Name',
+                      description='A name for the node set')
+
+    nodes: dict[NodeIdentifier, NodeSpec] = Field(min_length=1,
+                                                  title='Nodes',
+                                                  description='A non-empty list of nodes')

lockss_pybasic-0.3.0.dev2/src/lockss/pybasic/nodeutil.py

@@ -1,121 +0,0 @@
-#!/usr/bin/env python3
-
-# Copyright (c) 2000-2026, Board of Trustees of Leland Stanford Jr. University
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# 1. Redistributions of source code must retain the above copyright notice,
-# this list of conditions and the following disclaimer.
-#
-# 2. Redistributions in binary form must reproduce the above copyright notice,
-# this list of conditions and the following disclaimer in the documentation
-# and/or other materials provided with the distribution.
-#
-# 3. Neither the name of the copyright holder nor the names of its contributors
-# may be used to endorse or promote products derived from this software without
-# specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
-
-"""
-LOCKSS node utilities.
-"""
-
-from enum import Enum
-from re import Pattern
-import re
-from typing import Any, Optional
-
-from pydantic import BaseModel, Field, model_validator
-
-from .errorutil import InternalError
-
-
-RE_NODE_REFERENCE: Pattern = re.compile(r'((?P<protocol>https?)://)?(?P<host>[^:]+)(:(?P<repository>\d+|(?=:))(:(?P<configuration>\d+|(?=:))(:(?P<poller>\d+|(?=:))(:(?P<crawler>\d+|(?=:))(:(?P<metadata>\d+|(?=:))(:(?P<soap>\d+))?)?)?)?)?)?')
-
-
-class LockssNodeTypeEnum(Enum):
-    V1 = 'v1'
-    V2 = 'v2'
-
-
-class LockssNodeProtocolEnum(Enum):
-    HTTP = 'http'
-    HTTPS = 'https'
-
-
-DEFAULT_UI_PORT_V1: int = 8081
-
-DEFAULT_REPO_PORT: int = 24611
-
-DEFAULT_CFG_PORT: int = 24612
-
-DEFAULT_POL_PORT: int = 24613
-
-DEFAULT_CRW_PORT: int = 24614
-
-DEFAULT_MD_PORT: int = 24615
-
-DEFAULT_SOAP_PORT: int = 24616
-
-
-class LockssNodeModel(BaseModel):
-    host: str = Field(title='Host', description="The LOCKSS node's host")
-    type: LockssNodeTypeEnum = Field(default=LockssNodeTypeEnum.V2, title='Type', description='LOCKSS node type')
-    protocol: LockssNodeProtocolEnum = Field(default=LockssNodeProtocolEnum.HTTPS, title='Protocol', description="The protocol for reaching the node")
-    repository: int = Field(default=DEFAULT_REPO_PORT, title='Repository Port', description="The node's Repository Service REST API Port")
-    configuration: int = Field(default=DEFAULT_CFG_PORT, title='Configuration Port', description="The node's Configuration Service REST API Port")
-    poller: int = Field(default=DEFAULT_POL_PORT, title='Poller Port', description="The node's Poller Service REST API Port")
-    crawler: int = Field(default=DEFAULT_CRW_PORT, title='Crawler Port', description="The node's Crawler Service REST API Port")
-    metadata: int = Field(default=DEFAULT_MD_PORT, title='Metadata Port', description="The node's Metadata Service REST API Port")
-    soap: int = Field(default=DEFAULT_SOAP_PORT, title='SOAP Port', description="The node's SOAP Compatibility Service REST API Port")
-    ui: int = Field(default=DEFAULT_UI_PORT_V1, title='UI Port', description="The LOCKSS 1.x node's Web user interface port")
-
-    @model_validator(mode='before')
-    @classmethod
-    def _validate_model_type(cls, data: Any) -> Any:
-        _has, _get, _set = (dict.__contains__, dict.get, dict.__setitem__) if isinstance(data, dict) else (hasattr, getattr, setattr)
-        if (host_orig := _get(data, 'host', None)) is not None and isinstance(host_orig, str):
-            host_ref: str = host_orig
-            mat = RE_NODE_REFERENCE.fullmatch(host_ref)
-            if mat is None:
-                raise ValueError(f'Invalid node reference: {host_ref}')
-            # Avoid conflicting definitions
-            five = ('configuration', 'poller', 'crawler', 'metadata', 'soap')
-            for k in ('protocol', *five):
-                if h_val := mat.group(k):
-                    if _get(data, k, None) is not None:
-                        raise ValueError(f"Node reference conflicts with '{k}' definition: {h_val}")
-                    _set(data, k, h_val)
-            # 'repository' + 'ui' is more complicated
-            if h_repo_or_ui := mat.group('repository'):
-                for k in ('repository', 'ui'):
-                    if _get(data, k, None) is not None:
-                        raise ValueError(f"Node reference conflicts with '{k}' definition: {h_repo_or_ui}")
-                try:
-                    repo_or_ui_int: int = int(h_repo_or_ui)
-                except ValueError as ve:
-                    raise InternalError from ve # shouldn't happen, should be \d+
-                if any(mat.group(x) for x in five) or repo_or_ui_int >= 10000:
-                    _set(data, 'repository', h_repo_or_ui)  # Assume v2
-                elif 1000 <= repo_or_ui_int < 10000:
-                    _set(data, 'ui', h_repo_or_ui) # Assume v1
-                    if _get(data, 'type', None) is None:
-                        _set(data, 'type', LockssNodeTypeEnum.V1.value)
-                else:
-                    raise ValueError(f'Invalid repository/UI port in node reference: {repo_or_ui_int}')
-            # Finally, reset 'host'
-            if any(mat.group(x) for x in ('protocol', 'repository', *five)):
-                _set(data, 'host', mat.group('host'))
-        return data