pyegeria 5.3.5.3__py3-none-any.whl → 5.3.6.2__py3-none-any.whl

pyegeria/commands/cat/freddie_utils.py

@@ -30,6 +30,7 @@ commands = ["Create Glossary", "Update Glossary",
 ERROR = "ERROR-> "
 INFO = "INFO- "
 WARNING = "WARNING-> "
+pre_command = "\n---\n==> Processing command:"
 
 def is_valid_iso_date(date_text) -> bool:
     """Checks if the given string is a valid ISO date."""
@@ -65,22 +66,30 @@ def extract_attribute (text: str, label: str) -> str | None:
         """
     pattern = r"## " + re.escape(label) + r"\n(.*?)(?:##|$)"  # Construct pattern
     match = re.search(pattern, text, re.DOTALL)
-    if match:
-        return match.group(1).strip()
+    if match and not match.group(1).isspace():
+        txt =match.group(1).strip()
+        return txt
     return None
 
 def update_a_command(txt: str, command: str, obj_type: str, q_name: str, u_guid: str)->str:
     u_guid = u_guid if u_guid else " "
-    txt = txt.replace(f"{command}", f'**Update {obj_type}**\n')  # update the command
+    verb = command.split(' ')[0].strip()
+    action = "Update" if (verb == "Create" and u_guid is not None) else "Create"
+    txt = txt.replace(f"{command}", f'**{action} {obj_type}**\n')  # update the command
     txt = txt.replace('<GUID>', f'**GUID**\n{u_guid}')  # update with GUID
     txt = txt.replace('<Qualified Name>', f"**Qualified Name**\n{q_name}")
+    if "Qualified Name" not in txt:
+        txt += f"\n## **Qualified Name**\n{q_name}\n"
+    if "GUID" not in txt:
+        txt += f"\n## **GUID**\n{u_guid}\n"
     # if command == "Update Term":
     #     txt = txt.replace('Update Description', f"**Update Description**\n")
     return txt
 
 
 
-def process_glossary_upsert_command(egeria_client: EgeriaTech, txt: str, directive: str = "display" ) -> str | None:
+def process_glossary_upsert_command(egeria_client: EgeriaTech, element_dictionary: dict, txt: str,
+                                    directive: str = "display" ) -> str | None:
     """
     Processes a glossary create or update command by extracting key attributes such as
     glossary name, language, description, and usage from the given cell.
@@ -95,15 +104,17 @@ def process_glossary_upsert_command(egeria_client: EgeriaTech, txt: str, directi
     object_action = command.split(' ')[0].strip()
 
     glossary_name = extract_attribute(txt, 'Glossary Name')
-    print(f"\n==> Processing command: {command} for glossary: {glossary_name} with directive: {directive} ")
+    print(Markdown(f"{pre_command} `{command}` for glossary: `{glossary_name}` with directive: `{directive}` "))
     language = extract_attribute(txt, 'Language')
     description = extract_attribute(txt, 'Description')
     usage = extract_attribute(txt, 'Usage')
     glossary_display = (f"\n* Command: {command}\n\t* Glossary: {glossary_name}\n\t"
-                        f"* Language: {language}\n\t* Description: {description}\n\t"
-                        f"* Usage: {usage}")
+                        f"* Language: {language}\n\t* Description:\n{description}\n"
+                        f"* Usage: {usage}\n"
+                        f"* Qualified Name: <Qualified Name>\n"
+                        f"* GUID: <GUID>\n\n")
 
-    def validate_glossary(obj_action: str) -> tuple[bool, bool, str]:
+    def validate_glossary(obj_action: str) -> tuple[bool, bool, str | None, str | None]:
         valid = True
         msg = ""
         known_glossary_guid = None
@@ -124,18 +135,25 @@ def process_glossary_upsert_command(egeria_client: EgeriaTech, txt: str, directi
         if description is None:
             msg += f"* {INFO}Description is missing\n"
 
+        if len(glossary_details) > 1 and glossary_exists:
+            msg += f"* {ERROR}More than one glossary with name {glossary_name} found\n"
+            valid = False
+        if len(glossary_details) == 1:
+            known_glossary_guid = glossary_details[0]['elementHeader'].get('guid', None)
+            known_q_name = glossary_details[0]['glossaryProperties'].get('qualifiedName', None)
+
         if obj_action == "Update":
             q_name = extract_attribute(txt, 'Qualified Name')
 
             if not glossary_exists:
                 msg += f"* {ERROR}Glossary {glossary_name} does not exist\n"
                 valid = False
-            if len(glossary_details) > 1 and glossary_exists:
-                msg += f"* {ERROR}More than one glossary with name {glossary_name} found\n"
-                valid = False
-            if len(glossary_details) == 1:
-                known_glossary_guid = glossary_details[0]['elementHeader'].get('guid', None)
-                known_q_name = glossary_details[0]['glossaryProperties'].get('qualifiedName',None)
+            # if len(glossary_details) > 1 and glossary_exists:
+            #     msg += f"* {ERROR}More than one glossary with name {glossary_name} found\n"
+            #     valid = False
+            # if len(glossary_details) == 1:
+            #     known_glossary_guid = glossary_details[0]['elementHeader'].get('guid', None)
+            #     known_q_name = glossary_details[0]['glossaryProperties'].get('qualifiedName',None)
             if q_name is None:
                 msg += f"* {INFO}Qualified Name is missing => can use known qualified name of {known_q_name}\n"
                 valid = True
@@ -147,16 +165,18 @@ def process_glossary_upsert_command(egeria_client: EgeriaTech, txt: str, directi
                 msg += f"* -->Glossary {glossary_name} exists and can be updated\n"
             else:
                 msg += f"* --> validation failed\n"
-            msg+='---'
+
             print(Markdown(msg))
             return valid, glossary_exists, known_glossary_guid, known_q_name
 
         elif obj_action == "Create":
             if glossary_exists:
-                msg += f"{ERROR}Glossary {glossary_name} already exists"
-                valid = False
-            else:
+                msg += f"{ERROR}Glossary {glossary_name} already exists\n"
+
+            elif valid:
                 msg += f"-->It is valid to create Glossary \'{glossary_name}\' with:\n"
+                msg += glossary_display
+
             print(Markdown(msg))
             return valid, glossary_exists, known_glossary_guid, known_q_name
 
@@ -175,8 +195,9 @@ def process_glossary_upsert_command(egeria_client: EgeriaTech, txt: str, directi
             return None
         if object_action == "Update":
             if not exists:
-                print(f"\n-->Glossary {glossary_name} does not exist")
-                return None
+                print(f"\n{ERROR}Glossary {glossary_name} does not exist! Updating result document with Create command\n")
+                return update_a_command(txt, command, object_type, known_q_name, known_guid)
+
             body = {
                 "class": "ReferenceableRequestBody",
                 "elementProperties":
@@ -190,26 +211,32 @@ def process_glossary_upsert_command(egeria_client: EgeriaTech, txt: str, directi
                 }
             egeria_client.update_glossary(known_guid, body)
             print(f"\n-->Updated Glossary {glossary_name} with GUID {known_guid}")
+            element_dictionary[f"glossary.{glossary_name}"] = {'guid' : known_guid,
+                                                               'q_name' : known_q_name
+                                                              }
             return update_a_command(txt, command, object_type, known_q_name, known_guid)
         elif object_action == "Create" :
             guid = None
-            q_name = f"Glossary:{glossary_name}:{get_current_datetime_string()}"
 
             if exists:
-                print(f"Glossary {glossary_name} already exists")
+                print(f"\nGlossary {glossary_name} already exists and result document updated\n")
                 return update_a_command(txt, command, object_type, known_q_name, known_guid)
             else:
                 guid = egeria_client.create_glossary(glossary_name, description,
                                                      language, usage)
                 glossary = egeria_client.get_glossary_by_guid(guid)
                 if glossary == NO_GLOSSARIES_FOUND:
-                    print(f"Just created with GUID {guid} but Glossary not found")
+                    print(f"{ERROR}Just created with GUID {guid} but Glossary not found\n")
                     return None
-                q_name = glossary['glossaryProperties']["qualifiedName"]
-                return update_a_command(txt, command, object_type, q_name, guid)
+                qualified_name = glossary['glossaryProperties']["qualifiedName"]
+                element_dictionary[f"glossary.{glossary_name}"] = {
+                    'guid': guid,
+                    'q_name': qualified_name
+                    }
+                return update_a_command(txt, command, object_type, qualified_name, guid)
 
 
-def process_term_upsert_command(egeria_client: EgeriaTech, txt: str, directive: str = "display" ) -> str | None:
+def process_term_upsert_command(egeria_client: EgeriaTech, element_dictionary: dict, txt: str, directive: str = "display" ) -> str | None:
     """
     Processes a term create or update command by extracting key attributes such as
     term name, summary, description, abbreviation, examples, usage, version, and status from the given cell.
@@ -234,9 +261,10 @@ def process_term_upsert_command(egeria_client: EgeriaTech, txt: str, directive:
     status = extract_attribute(txt, 'Status')
     glossary_name = extract_attribute(txt, 'Glossary Name')
 
-    print(f"\n==> Processing command: {command} for Term {term_name} with directive: {directive}")
+    print(Markdown(f"{pre_command} `{command}` for term: `{term_name}` with directive: `{directive}`"))
 
-    def validate_term(obj_action: str) -> tuple[bool, bool, str]:
+    def validate_term(obj_action: str) -> tuple[bool, bool, str | None, str | None]:
+        nonlocal version
         valid = True
         msg = ""
         known_term_guid = None
@@ -256,8 +284,25 @@ def process_term_upsert_command(egeria_client: EgeriaTech, txt: str, directive:
             valid = False
         if status is None:
             msg += f"* {INFO}Term status is missing - will default to DRAFT"
-        if obj_action == "Update":  # check to see if provided information exists and is consistent with existing info
 
+        if summary is None:
+            msg += f"* {INFO}Term summary is missing\n"
+
+        if description is None:
+            msg += f"* {INFO}Term description is missing\n"
+
+        if abbreviation is None:
+            msg += f"* {INFO}Term abbreviation is missing\n"
+        if examples is None:
+            msg += f"* {INFO}Term examples is missing\n"
+        if usage is None:
+            msg += f"* {INFO}Term usage is missing\n"
+        if version is None:
+            msg += f"* {INFO}Term version is missing - will default to 0.0.1\n"
+            version = "0.0.1"
+
+
+        if obj_action == "Update":  # check to see if provided information exists and is consistent with existing info
             if not term_exists:
                 msg += f"* {ERROR}Term {term_name} does not exist\n"
                 valid = False
@@ -274,19 +319,20 @@ def process_term_upsert_command(egeria_client: EgeriaTech, txt: str, directive:
             else:
                 msg += f"--> * Term {term_name} exists and can be updated\n"
                 msg += term_display
-                msg += '\n---\n'
+
             print(Markdown(msg))
-            return valid, term_exists, known_term_guid
+            return valid, term_exists, known_term_guid, known_q_name
 
         elif obj_action == 'Create':  # if the command is create, check that it doesn't already exist
             if term_exists:
-                msg += f"{WARNING}Term \'{term_name}\' already exists\n"
-
+                msg += f"\n{WARNING}Term \'{term_name}\' already exists, response document updated.\n"
+            elif not valid:
+                msg += f"\n-->Validation checks failed in creating Term \'{term_name}\' with: {term_display}\n"
             else:
-                msg += f"-->It is valid to create Term \'{term_name}\' with: {term_display}\n"
-            msg += '\n---\n'
+                msg += f"\n-->It is valid to create Term \'{term_name}\' with: {term_display}\n"
+
             print(Markdown(msg))
-            return valid, term_exists, known_term_guid
+            return valid, term_exists, known_term_guid, known_q_name
 
     if object_action == "Update":
         term_guid = extract_attribute(txt, 'GUID')
@@ -311,11 +357,11 @@ def process_term_upsert_command(egeria_client: EgeriaTech, txt: str, directive:
         print(Markdown(term_display))
         return None
     elif directive == "validate":
-        is_valid, exists, known_guid = validate_term(object_action)
+        is_valid, exists, known_guid, known_q_name = validate_term(object_action)
         valid = is_valid if is_valid else None
         return valid
     elif directive == "process":
-        is_valid, exists, known_guid = validate_term(object_action)
+        is_valid, exists, known_guid, known_q_name = validate_term(object_action)
         if not is_valid:  # First validate the term before we process it
             return None
 
@@ -328,7 +374,7 @@ def process_term_upsert_command(egeria_client: EgeriaTech, txt: str, directive:
                 "elementProperties":
                     {
                         "class": "GlossaryTermProperties",
-                        "qualifiedName": q_name,
+                        "qualifiedName": known_q_name,
                         "summary": summary,
                         "description": description,
                         "abbreviation": abbreviation,
@@ -341,20 +387,28 @@ def process_term_upsert_command(egeria_client: EgeriaTech, txt: str, directive:
                 }
             egeria_client.update_term(known_guid, body)
             print(f"\n-->Updated Term {term_name} with GUID {known_guid}")
-            return update_a_command(txt, command, object_type, q_name, known_guid)
+            return update_a_command(txt, command, object_type, known_q_name, known_guid)
 
         elif object_action == "Create" :
             guid = None
             q_name = f"GlossaryTerm:{term_name}:{get_current_datetime_string()}"
             if exists:
-                print(f"\n-->Term {term_name} exists and document updated")
-                return update_a_command(txt, command, object_type, q_name, guid)
+                print(f"\n{ERROR}Term {term_name} exists and result document updated")
+                return update_a_command(txt, command, object_type, q_name, known_guid)
             else:
-                ## get the guid for the glossary from the name
-                glossary_guid = egeria_client.__get_guid__(property_name="displayName", display_name=glossary_name)
-                if glossary_guid == NO_ELEMENTS_FOUND:
-                    print(f"Glossary {glossary_name} not found")
-                    return None
+                ## get the guid for the glossary from the name - first look locally
+                glossary = element_dictionary.get(f"glossary.{glossary_name}",None)
+
+                if glossary is not None:
+                    glossary_guid = glossary.get('guid', None)
+                    if glossary_guid is None:
+                        print(f"{ERROR}Glossary reference {glossary_name} not found")
+                        return None
+                else:
+                    glossary_guid = egeria_client.__get_guid__(property_name="displayName", display_name=glossary_name)
+                    if glossary_guid == NO_ELEMENTS_FOUND:
+                        print(f"{ERROR}Glossary {glossary_name} not found")
+                        return None
                 term_body = {
                     "class": "ReferenceableRequestBody",
                     "elementProperties":
@@ -377,10 +431,15 @@ def process_term_upsert_command(egeria_client: EgeriaTech, txt: str, directive:
                     "initialStatus": status
                     }
                 term_guid = egeria_client.create_controlled_glossary_term(glossary_guid, term_body)
+                if term_guid == NO_ELEMENTS_FOUND:
+                    print(f"{ERROR}Term {term_name} not created")
+                    return None
                 print(f"\n-->Created Term {term_name} with GUID {term_guid}")
+                element_dictionary[f"term.{term_name}"] = {'guid': term_guid, 'q_name': q_name}
                 return update_a_command(txt, command, object_type, q_name, term_guid)
 
-def process_per_proj_upsert_command(egeria_client: EgeriaTech, txt: str, directive: str = "display" ) -> str | None:
+
+def process_per_proj_upsert_command(egeria_client: EgeriaTech, element_dictionary: dict, txt: str, directive: str = "display" ) -> str | None:
     """
     Processes a personal project create or update command by extracting key attributes such as
     glossary name, language, description, and usage from the given cell.
@@ -403,7 +462,7 @@ def process_per_proj_upsert_command(egeria_client: EgeriaTech, txt: str, directi
     project_health = extract_attribute(txt, 'Project Health')
     start_date = extract_attribute(txt, 'Start Date')
     planned_end_date = extract_attribute(txt, 'Planned End Date')
-    print(f"\n==> Processing command: {command} for project: {project_name} with directive: {directive} ")
+    print(Markdown(f"{pre_command} `{command}` for project: `{project_name}` with directive: `{directive}` "))
 
     project_display = (f"\n* Command: {command}\n\t* Project: {project_name}\n\t"
                         f"* Status: {project_status}\n\t* Description: {description}\n\t"
@@ -459,7 +518,7 @@ def process_per_proj_upsert_command(egeria_client: EgeriaTech, txt: str, directi
                 msg += f"* {ERROR}Project {project_name} does not exist\n"
                 valid = False
             if len(project_details) > 1 and project_exists:
-                msg += f"* {ERROR}More than one projecty with name {project_name} found\n"
+                msg += f"* {ERROR}More than one project with name {project_name} found\n"
                 valid = False
             if len(project_details) == 1:
                 known_guid = project_details[0]['elementHeader'].get('guid', None)
@@ -512,9 +571,8 @@ def process_per_proj_upsert_command(egeria_client: EgeriaTech, txt: str, directi
             return update_a_command(txt, command, object_type, known_q_name, known_guid)
         elif object_action == "Create" :
             guid = None
-
             if exists:
-                print(f"Project {project_name} already exists and")
+                print(f"Project {project_name} already exists and update document created")
                 return update_a_command(txt, command, object_type, known_q_name, known_guid)
             else:
                 guid = egeria_client.create_project(None,None, None, False,
@@ -526,5 +584,7 @@ def process_per_proj_upsert_command(egeria_client: EgeriaTech, txt: str, directi
                 if project_g == NO_GLOSSARIES_FOUND:
                     print(f"Just created with GUID {guid} but Project not found")
                     return None
-                q_name = project_g['prjectProperties']["qualifiedName"]
+
+                q_name = project_g['projectProperties']["qualifiedName"]
+                element_dictionary[f"project.{project_name}"] = {'guid': guid, 'q_name': q_name}
                 return update_a_command(txt, command, object_type, q_name, guid)

pyegeria/commands/cat/freddies-inbox/freddie_intro.md

@@ -0,0 +1,221 @@
+# Introduction to Freddie - an Egeria Markdown Processor
+
+A constant challenge in managing information is gathering enough metadata about the information to
+allow us to manage it. A common approach is to build fancy graphical user interfaces hoping that they
+will be attractive enough and easy enough to use that people will do so.
+
+Unfortunately, however, this ignores the fundamental fact that to use one of these nice GUI
+applications, you have to step away from the tools and processes that you were in the midst of performing.
+You have to leave your world and join someone elses.
+
+Freddie, is an experiment in turning this around. Its not that fancy graphical user
+interfaces don't have a role - but rather, to look at what we can do to support the
+tools and approaches people already use. And maybe even make their day job a little
+easier.
+
+So this is what we are exploring with Freddie. An Egeria Markdown language that allows
+users to intermix requests to Egeria with other text through the use of standard Markdown.
+
+This file is an example. You will see that we intersperse normal narrative text (such as this)
+with Commands to Egeria. We introduce a specific vocabulary to make Egeria requests.
+
+In the example below we will create a new Egeria glossary to hold definitions related to Freddie:
+---
+
+# Create Glossary
+
+## Glossary Name
+
+Egeria-Markdown
+
+## Language
+
+English
+
+## Description
+
+Glossary to describe the vocabulary of Freddie - an Egeria Markdown language to support the exchange of metadata in a
+Markdown form.
+Freddie allows users to input metadata using any text entry system that supports the entry of standard Markdown
+characters and through post-processing
+commands, validates the Egeria content and allows the requests to be sent to Egeria. This is an update
+
+## Usage
+
+1. (optional) load an example or template for the type of object from Egeria.
+2. Create a new document (perhaps from the template) and edit it, adding in the content with the Freddie controlled
+   Markdown language.
+3. Process the document to validate and display it before you submit it, Validation may annotate your document with
+   recommendations and potential issues.
+4. Submit the document to Egeria using the Freddie_sings command.
+
+## <Qualified Name>
+
+## <GUID>
+
+---
+
+# First Walk-Through
+The block of markdown above is a request to create a new Egeria Glossary called `Egeria-Markdown`. Let's briefly walk
+through. The command starts when we see `# Create Glossary`. This is a known phrase in Freddie. When we see this 
+phrase we recognize that this is an egeria markdown request block. The request block ends if we encounter another `#` or
+`---`, or run out of text. Within this request block we note some **attributes** that begin with a `## `. The first that
+we encounter is `## Glossary Name`. Not all attributes need to be filled in. Later, we'll process this file and demonstrate 
+how to tell - but first, lets look at the attributes shown:
+
+* `## Glossary Name` - this is the display name of the glossary. In this case the name is `Egeria-Markdown` As you can 
+see, the value of the attribute is the plain text that follows it.
+* `## Language` - what language will the terms of the glossary be in (yes there are ways to have mixed language but
+Freddie strives to be as simple as possible).
+* `## Description` - a description of the glossary and its purpose.
+* `## Usage` - how the glossary is meant to be used and by whom.
+* `## <Qualified Name>` - every element in Egeria must have a unique qualified name that we use to distinguish 
+it from all other elements. The qualified name is meant to be understandable by humans, although it may follow 
+formatting conventions. This attributes is in angle brackets because at this point we can't fill it in - we are just
+in the midst of creating the glossary. A qualified name will be created for us as part of the glossary creation. We'll
+see a little later how we get that.
+* `## <GUID>` - same story as qualified name except that this is meant for automation and not people.
+
+And that's it. That's all we need to do to specify the creation of a new glossary (well - mostly - we'll reveal a few 
+more details a bit later).
+
+## Great! That was easy!
+
+We now have a nice, clean, new...and empty...glossary - guess we better start filling it. Lets create a couple of terms.
+
+---
+
+# Create Term
+
+## Glossary Name
+
+Egeria-Markdown
+
+## Term Name
+
+Command
+
+## Summary
+
+Commands are how a user of the Freddie markdown language requests an action.
+
+## Description
+
+Commands are how a user can request Egeria to take an action such as Create or Update an Egeria element. Freddie
+provides
+a limited (but growing) set of commands. Freddie commands align with the pyegeria 'hey-egeria' command line interface.
+
+## Abbreviation
+
+## Examples
+
+Create Glossary or
+Update Glossary or
+Create Term or
+Update Term
+
+## Usage
+
+Commands are used in the Freddie Egeria markdown language.
+
+## Version
+
+0.2
+
+## Status
+
+DRAFT
+
+## Qualified Name
+
+---
+
+# Create Term
+
+## Glossary Name
+
+Egeria-Markdown
+
+## Term Name
+
+Source
+
+## Summary
+
+Source of the markdown content.
+
+## Description
+
+Source of the markdown content - could be jupter or plain markdown file.
+
+## Abbreviation
+
+## Examples
+
+## Usage
+
+## Version
+
+0.1
+
+## Status
+
+DRAFT
+
+## Update Description
+
+---
+
+# Create Term
+
+## Glossary Name
+
+Egeria-Markdown
+
+## Term Name
+
+Directive
+
+## Summary
+
+A directive defines how the command is to be processed.
+
+## Description
+
+Directives are one of:
+
+* display - just display what we've found
+* validate - check the validity of the requested action
+* process - process the requested action
+
+## Abbreviation
+
+## Examples
+
+## Usage
+
+## Version
+
+0.1
+
+## Status
+
+DRAFT
+
+---
+
+# Some terms specified - Now what?
+
+Ok - we've now created a glossary and three terms to go into the glossary. Here is what we'll do next.
+
+>Note: This is changing - so will be somewhat abstrct
+
+We will run a small program called freddie_md.py to operate on this markdown file. When we run this program we 
+tell it not just the name of the file to process but also provide a directive on what to do. Currently we have the 
+choice of:
+
+1. Display - just parse the file, breaking it down into request blocks, and display what we find
+2. Validate - parse the file and validate if the commands can be processed - showing information about what we observe.
+3. Process - parse the request blocks and execute the commands - and produce a new output file to simplify further processing.
+
+# Great --> let's give it a try!