lockss-pybasic 0.3.0.dev2__py3-none-any.whl → 0.3.0.dev4__py3-none-any.whl

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/nodeutil.py

@@ -33,89 +33,184 @@ LOCKSS node utilities.
 """
 
 from enum import Enum
-from re import Pattern
+from re import Match, Pattern
 import re
-from typing import Any, Optional
+from typing import Annotated, Any, ClassVar, Literal, Optional, Union
 
-from pydantic import BaseModel, Field, model_validator
+from annotated_types import Ge, Le
+from pydantic import BaseModel, BeforeValidator, Field, TypeAdapter, model_validator
 
-from .errorutil import InternalError
 
+#: An annotated type for port numbers (0-65535)
+PortNumber = Annotated[int, Ge(0), Le(65535)]
 
-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):
+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 LockssNodeProtocolEnum(Enum):
+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'
 
 
-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
+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.dist-info → lockss_pybasic-0.3.0.dev4.dist-info}/METADATA

@@ -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.dev4.dist-info/RECORD

@@ -0,0 +1,10 @@
+lockss/pybasic/__init__.py,sha256=NWFBmNQ6XEuQOYE0WVIYhe0Ci5wIxmzBewZ_oY8u-G8,1678
+lockss/pybasic/auidutil.py,sha256=Q4vjjGfymiXVwPu35RyyLZBnViv8mDJKCjOyJb-sbS8,13921
+lockss/pybasic/cliutil.py,sha256=F970MhLcQCYS3INLQT1Ij8nKt_ICmttiS3nSnuWuN7s,8106
+lockss/pybasic/errorutil.py,sha256=4EaO0a1yIG1DbWltASeT15bg1bGg5kOYspsW0iJdVLc,1951
+lockss/pybasic/fileutil.py,sha256=IIS2AFDgYtmBLPVHqQi1AkIFj6da04b6NQtjX9bIVqQ,2958
+lockss/pybasic/nodeutil.py,sha256=snBT7OPttThBJXVxgLC6Onmuoa8Z-jOOM1LWdhIb-js,7928
+lockss_pybasic-0.3.0.dev4.dist-info/METADATA,sha256=eZ1B2T-R5rn4u2ZXTkcWZFEGChVqOxbbV5FT-pusIpw,2338
+lockss_pybasic-0.3.0.dev4.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+lockss_pybasic-0.3.0.dev4.dist-info/licenses/LICENSE,sha256=EOxPunNz3XP6AjgbPFolu-d9BS_AF9TtKn1WXgeYPsE,1506
+lockss_pybasic-0.3.0.dev4.dist-info/RECORD,,

{lockss_pybasic-0.3.0.dev2.dist-info → lockss_pybasic-0.3.0.dev4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.4.0
+Generator: poetry-core 2.4.1
 Root-Is-Purelib: true
 Tag: py3-none-any

lockss_pybasic-0.3.0.dev2.dist-info/RECORD

@@ -1,10 +0,0 @@
-lockss/pybasic/__init__.py,sha256=c5oAL1taDdPzGD1IxLXhG8k-0GEdxr9duOohhsF4JA4,1678
-lockss/pybasic/auidutil.py,sha256=Q4vjjGfymiXVwPu35RyyLZBnViv8mDJKCjOyJb-sbS8,13921
-lockss/pybasic/cliutil.py,sha256=F970MhLcQCYS3INLQT1Ij8nKt_ICmttiS3nSnuWuN7s,8106
-lockss/pybasic/errorutil.py,sha256=4EaO0a1yIG1DbWltASeT15bg1bGg5kOYspsW0iJdVLc,1951
-lockss/pybasic/fileutil.py,sha256=IIS2AFDgYtmBLPVHqQi1AkIFj6da04b6NQtjX9bIVqQ,2958
-lockss/pybasic/nodeutil.py,sha256=m9WCVbfSzOKklA9qstoOUUbF0v-l1TtePfx6rjEh_IU,5872
-lockss_pybasic-0.3.0.dev2.dist-info/METADATA,sha256=mtfXJBQQ36ruZpFsntyU_-sF9FOdAS_O5XtdxmydcMY,2290
-lockss_pybasic-0.3.0.dev2.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
-lockss_pybasic-0.3.0.dev2.dist-info/licenses/LICENSE,sha256=EOxPunNz3XP6AjgbPFolu-d9BS_AF9TtKn1WXgeYPsE,1506
-lockss_pybasic-0.3.0.dev2.dist-info/RECORD,,