pyegeria 5.4.0.28__py3-none-any.whl → 5.5.3.3__py3-none-any.whl

pyegeria/omvs/valid_metadata_lists.py

@@ -0,0 +1,37 @@
+"""
+PDX-License-Identifier: Apache-2.0
+Copyright Contributors to the ODPi Egeria project.
+
+This module contains the Valid Metadata Lists View Service client.
+"""
+
+from pyegeria.omvs.valid_metadata import ValidMetadataManager
+from typing import Any, Optional
+
+class ValidMetadataLists(ValidMetadataManager):
+    """
+    Client for the Valid Metadata Lists View Service.
+    This is a specialized version of the Valid Metadata Manager focusing on metadata lists.
+
+    Attributes
+    ----------
+    view_server : str
+        The name of the View Server to use.
+    platform_url : str
+        URL of the server platform to connect to.
+    user_id : str
+        The identity of the user calling the method.
+    user_pwd : str
+        The password associated with the user_id. Defaults to None.
+    """
+
+    def __init__(
+        self,
+        view_server: str,
+        platform_url: str,
+        user_id: str,
+        user_pwd: Optional[str] = None,
+        token: Optional[str] = None,
+    ):
+        super().__init__(view_server, platform_url, user_id, user_pwd, token)
+        self.url_marker = "valid-metadata"

pyegeria/omvs/valid_type_lists.py

@@ -0,0 +1,37 @@
+"""
+PDX-License-Identifier: Apache-2.0
+Copyright Contributors to the ODPi Egeria project.
+
+This module contains the Valid Type Lists View Service client.
+"""
+
+from pyegeria.omvs.valid_metadata import ValidMetadataManager
+from typing import Any, Optional
+
+class ValidTypeLists(ValidMetadataManager):
+    """
+    Client for the Valid Type Lists View Service.
+    This is a specialized version of the Valid Metadata Manager focusing on type lists.
+
+    Attributes
+    ----------
+    view_server : str
+        The name of the View Server to use.
+    platform_url : str
+        URL of the server platform to connect to.
+    user_id : str
+        The identity of the user calling the method.
+    user_pwd : str
+        The password associated with the user_id. Defaults to None.
+    """
+
+    def __init__(
+        self,
+        view_server: str,
+        platform_url: str,
+        user_id: str,
+        user_pwd: Optional[str] = None,
+        token: Optional[str] = None,
+    ):
+        super().__init__(view_server, platform_url, user_id, user_pwd, token)
+        self.url_marker = "valid-metadata"

pyegeria/view/__init__.py

@@ -0,0 +1,28 @@
+"""
+View module for pyegeria, containing output formatters and mermaid utilities.
+"""
+from pyegeria.view.mermaid_utilities import (
+    construct_mermaid_web,
+    construct_mermaid_jup,
+    load_mermaid,
+    render_mermaid,
+    save_mermaid_html,
+    save_mermaid_graph,
+)
+from pyegeria.view.output_formatter import (
+    generate_output,
+    resolve_output_formats,
+    populate_common_columns,
+)
+
+__all__ = [
+    "construct_mermaid_web",
+    "construct_mermaid_jup",
+    "load_mermaid",
+    "render_mermaid",
+    "save_mermaid_html",
+    "save_mermaid_graph",
+    "generate_output",
+    "resolve_output_formats",
+    "populate_common_columns",
+]

pyegeria/{_output_format_models.py → view/_output_format_models.py}

@@ -10,7 +10,7 @@ for different types of data, supporting composition and reuse of formats.
 The module defines the following models:
 - Column: Represents a column in an output format with name, key, and format attributes.
 - Format: Represents a format configuration with types and columns.
-- ActionParameter: Represents a parameter for an action with function, user_params, and spec_params.
+- ActionParameter: Represents a parameter for an action with function, required_params, optional_params, and spec_params.
 - FormatSet: Represents a complete format set with heading, description, aliases, annotations, formats, and actions.
 - FormatSetDict: A dictionary of format sets with methods for backward compatibility.
 
@@ -51,14 +51,35 @@ format_set_dict = format_set.dict()
 The models are designed to be backward compatible with the existing dictionary-based
 implementation. The `FormatSet` class has a `get` method that mimics the behavior of a
 dictionary, and the `FormatSetDict` class provides dictionary-like access to the format sets.
+
+Exceptions
+----------
+The following exceptions may be raised by functions and classes in this module:
+- FileNotFoundError: When attempting to load format sets from a non-existent JSON file.
+- json.JSONDecodeError: When a JSON file cannot be parsed.
+- pydantic.ValidationError: When provided data does not conform to the expected model schema
+  for `Column`/`Attribute`, `Format`, `ActionParameter`, `QuestionSpec`, or `FormatSet`.
+- KeyError: Accessing a missing format set label via `FormatSetDict.__getitem__` or
+  `FormatSet.get` when a default is not supplied.
+- ValueError: From internal validators if an attribute/format contains invalid values.
 """
 
 import json
 import os
 from pathlib import Path
 from typing import Dict, List, Optional, Union, Any
-from pydantic import BaseModel, Field, validator
+from pydantic import BaseModel, Field, validator, root_validator
 from loguru import logger
+__all__ = [
+    'Column',
+    'Attribute',
+    'Format',
+    'ActionParameter',
+    'FormatSet',
+    'FormatSetDict',
+    'save_format_sets_to_json',
+    'load_format_sets_from_json',
+]
 
 def save_format_sets_to_json(format_sets: Dict[str, 'FormatSet'], file_path: str) -> None:
     """
@@ -110,31 +131,42 @@ def load_format_sets_from_json(file_path: str) -> Dict[str, 'FormatSet']:
 
 class Column(BaseModel):
     """
-    Represents a column in an output format.
+    Represents an attribute (formerly called a column) in an output format.
     
-    Attributes:
-        name: The display name of the column
-        key: The key used to access the column's value in the data
-        format: Whether the column's value should be formatted
+    Fields:
+        name: The display name of the attribute
+        key: The key used to access the attribute's value in the data
+        format: Whether the attribute's value should be formatted
     """
     name: str
     key: str
     format: bool = False
 
+# New preferred alias for Column
+Attribute = Column
+
 class Format(BaseModel):
     """
-    Represents a format configuration with types and columns.
+    Represents a format configuration with types and attributes.
     
-    Attributes:
+    Fields:
         types: The output types this format supports (e.g., "DICT", "TABLE", "ALL")
-        columns: The columns to include in the output
+        attributes: The attributes (formerly columns) to include in the output
     """
     types: List[str]
-    columns: List[Union[Column, Dict[str, Any]]]
+    attributes: List[Union[Column, Dict[str, Any]]]
     
-    @validator('columns', pre=True)
-    def validate_columns(cls, v):
-        """Convert dictionary columns to Column objects."""
+    @root_validator(pre=True)
+    def _migrate_columns_to_attributes(cls, values):
+        """Support legacy 'columns' by migrating to 'attributes' when loading."""
+        if isinstance(values, dict):
+            if 'attributes' not in values and 'columns' in values:
+                values['attributes'] = values.pop('columns')
+        return values
+
+    @validator('attributes', pre=True)
+    def validate_attributes(cls, v):
+        """Convert dictionary attributes to Attribute/Column objects."""
         result = []
         for item in v:
             if isinstance(item, dict):
@@ -144,48 +176,105 @@ class Format(BaseModel):
         return result
     
     def dict(self, *args, **kwargs):
-        """Override dict method to convert Column objects back to dictionaries."""
+        """Override dict method to convert Attribute objects back to dictionaries.
+        Emits both 'attributes' (preferred) and 'columns' (deprecated) for backward compatibility.
+        """
         result = super().dict(*args, **kwargs)
-        result['columns'] = [
-            column if isinstance(column, dict) else column.dict()
-            for column in self.columns
+        result['attributes'] = [
+            attr if isinstance(attr, dict) else attr.dict()
+            for attr in self.attributes
         ]
+        # Backward-compat alias
+        result['columns'] = list(result['attributes'])
         return result
 
+    # Backward-compat property to expose 'columns'
+    @property
+    def columns(self):
+        return self.attributes
+
+    @columns.setter
+    def columns(self, value):
+        # Allow setting via legacy field
+        self.attributes = self.validate_attributes(value)
+
 class ActionParameter(BaseModel):
     """
     Represents a parameter for an action.
     
     Attributes:
         function: The function to call
-        user_params: Parameters that can be provided by the user
+        required_params: Parameters that are required from the user
+        optional_params: Parameters that are optional from the user
         spec_params: Parameters that are fixed for this action
     """
     function: str
-    user_params: List[str] = Field(default_factory=list)
+    required_params: List[str] = Field(default_factory=list)
+    optional_params: Optional[List[str]] = Field(default_factory=list)
     spec_params: Dict[str, Any] = Field(default_factory=dict)
 
+    @root_validator(pre=True)
+    def _migrate_legacy_user_params(cls, values):
+        """Migrate legacy 'user_params' into 'required_params' when loading from older dict/json."""
+        if isinstance(values, dict):
+            if 'required_params' not in values and 'user_params' in values:
+                values['required_params'] = values.pop('user_params')
+        return values
+
+
+class QuestionSpec(BaseModel):
+    """
+    An example-question specification for a report spec.
+
+    Attributes:
+        perspectives: A list of perspective names for whom these questions are relevant
+        questions: Example natural-language questions this report spec can answer
+    """
+    @root_validator(pre=True)
+    def _migrate_legacy_roles(cls, values):
+        """Migrate legacy 'roles' field to 'perspectives' when loading from older dict/json."""
+        if isinstance(values, dict) and 'perspectives' not in values and 'roles' in values:
+            values = dict(values)
+            values['perspectives'] = values.pop('roles')
+        return values
+    perspectives: List[str] = Field(default_factory=list)
+    questions: List[str] = Field(default_factory=list)
+
 class FormatSet(BaseModel):
     """
-    Represents a complete format set with heading, description, aliases, annotations, formats, and actions.
+    Represents a complete format set with target_type, heading, description, aliases, annotations, formats, and actions.
     
     Attributes:
+        target_type: The related Open Metadata entity type this format set targets (e.g., Glossary, Term). Optional.
         heading: A title for the format set
         description: A description of what the format set is for
         aliases: Alternative names that can be used to reference this format set
         annotations: Additional metadata, like wiki links
+        family: Optional tag to group related format sets for organization/searching
         formats: A list of format configurations
         action: Optional action associated with the format set
         get_additional_props: Optional action used to retrieve additional properties for a format set
     """
+    target_type: Optional[str] = None
     heading: str
     description: str
     aliases: List[str] = Field(default_factory=list)
     annotations: Dict[str, List[str]] = Field(default_factory=dict)
+    family: Optional[str] = None
     formats: List[Union[Format, Dict[str, Any]]]
     action: Optional[Union[ActionParameter, Dict[str, Any]]] = None
     get_additional_props: Optional[Union[ActionParameter, Dict[str, Any]]] = None
+    # Optional: example questions and perspectives this report spec can address
+    question_spec: Optional[List[Union[QuestionSpec, Dict[str, Any]]]] = None
     
+    @root_validator(pre=True)
+    def _migrate_legacy_fields(cls, values):
+        """Migrate legacy fields from older saved JSON (entity_type -> target_type)."""
+        if isinstance(values, dict):
+            if 'entity_type' in values and 'target_type' not in values:
+                values['target_type'] = values.pop('entity_type')
+        return values
+
     @validator('formats', pre=True)
     def validate_formats(cls, v):
         """Convert dictionary formats to Format objects."""
@@ -196,6 +285,19 @@ class FormatSet(BaseModel):
             else:
                 result.append(item)
         return result
+
+    @validator('question_spec', pre=True)
+    def validate_question_spec(cls, v):
+        """Convert dictionary items to QuestionSpec objects when provided."""
+        if v is None:
+            return None
+        out: List[QuestionSpec] = []
+        for item in v:
+            if isinstance(item, dict):
+                out.append(QuestionSpec(**item))
+            else:
+                out.append(item)
+        return out
     
     @validator('action', 'get_additional_props', pre=True)
     def validate_action_like(cls, v):
@@ -225,6 +327,10 @@ class FormatSet(BaseModel):
             result['get_additional_props'] = (
                 self.get_additional_props if isinstance(self.get_additional_props, dict) else self.get_additional_props.dict()
             )
+        if self.question_spec is not None:
+            result['question_spec'] = [
+                item if isinstance(item, dict) else item.dict() for item in self.question_spec
+            ]
         return result
     
     def get(self, key, default=None):
@@ -265,7 +371,7 @@ class FormatSetDict(Dict[str, FormatSet]):
         Args:
             key: The name or alias to look up
             default: The default value to return if the key is not found
-            
+        
         Returns:
             FormatSet: The format set if found, otherwise the default value
         """
@@ -292,12 +398,42 @@ class FormatSetDict(Dict[str, FormatSet]):
         Args:
             key: The name or alias to look up
             default: The default value to return if the key is not found
-            
+        
         Returns:
             FormatSet: The format set if found, otherwise the default value
         """
         return self.find_by_name_or_alias(key, default)
     
+    def filter_by_family(self, family: str) -> Dict[str, FormatSet]:
+        """
+        Return a plain dict of format sets whose `family` matches the given value.
+        
+        Matching rules
+        - Case-insensitive comparison
+        - Leading/trailing whitespace in the input and stored family are ignored
+        - Pass an empty string ("") to match entries with no family assigned
+        
+        Args:
+            family: Family name to match (case-insensitive). Use "" to select entries with no family.
+        
+        Returns:
+            dict[str, FormatSet]: Mapping of spec name -> FormatSet for matching entries.
+        """
+        # Normalize the requested family
+        fam_norm = (family or "").strip().lower()
+        result: Dict[str, FormatSet] = {}
+        for name, fs in self.items():
+            fs_family_raw = getattr(fs, "family", None)
+            fs_family_norm = (fs_family_raw or "").strip().lower()
+            if fam_norm == "":
+                # Select items with no family set
+                if fs_family_norm == "":
+                    result[name] = fs
+            else:
+                if fs_family_norm == fam_norm:
+                    result[name] = fs
+        return result
+    
     def values(self):
         """Get all format sets."""
         return super().values()
@@ -344,7 +480,7 @@ class FormatSetDict(Dict[str, FormatSet]):
         
         Args:
             key: The name or alias to check
-            
+        
         Returns:
             bool: True if the format set exists, False otherwise
         """

pyegeria/view/_output_formats.py

@@ -0,0 +1,14 @@
+"""
+Deprecated module shim.
+This module has been renamed to pyegeria.base_report_formats.
+It re-exports all public APIs and raises DeprecationWarning on import.
+"""
+import warnings
+
+warnings.warn(
+    "pyegeria._output_formats is deprecated; use pyegeria.base_report_formats instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from pyegeria.view.base_report_formats import *  # noqa: F401,F403