pyegeria 1.5.1.1.49__py3-none-any.whl → 1.5.1.1.51__py3-none-any.whl

pyegeria/commands/doc/glossary/basic-glossary-tui.md

@@ -4,29 +4,37 @@
 # Working with glossaries
 
 ## Display glossary List
-### Entry
-![tui-show glossaries  2024-11-05 at 19.22.49@2x.png](tui-show%20glossaries%20%202024-11-05%20at%2019.22.49%402x.png)
+### Entry - `hey_egeria_cat tui`
+
+![tui-show-glossaries 2024-11-07 at 20.00.05.png](images/tui-show-glossaries%202024-11-07%20at%2020.00.05.png)
+
 ### Display
-![glossary-list](out-glossary-list%20example%202024-11-05%20at%2020.41.02%402x.png)
+![out-glossary-list example 2024-11-05 at 20.41.02@2x.png](images/out-glossary-list%20example%202024-11-05%20at%2020.41.02%402x.png)
+##### This shows three glossaries with their unique, Qualified Name and unique identifier (GUID). Language, Description and Usage are optional but highly recommended to help users find, use and manage glossaries.
+
 ## Create a new Glossary
 ### Entry
-![TUI-create glossary](/Users/dwolfson/localGit/egeria-v5/egeria-python/pyegeria/commands/doc/glossary/tui-create-glossary example 2024-11-05 at 20.34.24@2x.png)
+![tui-create-glossary example 2024-11-05 at 20.34.24@2x.png](images/tui-create-glossary%20example%202024-11-05%20at%2020.34.24%402x.png)
 
 ### Display
-![create glossary](/Users/dwolfson/localGit/egeria-v5/egeria-python/pyegeria/commands/doc/glossary/out-create-glossary example  2024-11-05 at 20.38.04@2x.png)
+##### The result of executing the create glossary command is displayed on the terminal. Note the GUID that is returned.
+![out-create-glossary example  2024-11-05 at 20.38.04@2x.png](images/out-create-glossary%20example%20%202024-11-05%20at%2020.38.04%402x.png)
+
 ## Delete a glossary
 
+##### To demonstrate deleting a glossary we first list all glossaries, then perform the delete, and finally list glossaries again to validate that the glossary has been deleted.
+
 ### 1. List available glossaries
-![delete-glossary-step1 2024-11-06 at 15.47.23@2x.png](delete-glossary-step1%202024-11-06%20at%2015.47.23%402x.png)
+![delete-glossary-step1 2024-11-06 at 15.47.23@2x.png](images/delete-glossary-step1%202024-11-06%20at%2015.47.23%402x.png)
 
 ### 2. Use TUI to delete a glossary, specifying a glossary GUID from the list glossaries command above
-![delete-glossary-step2 2024-11-06 at 15.51.29@2x.png](delete-glossary-step2%202024-11-06%20at%2015.51.29%402x.png)
+![delete-glossary-step2 2024-11-06 at 15.51.29@2x.png](images/delete-glossary-step2%202024-11-06%20at%2015.51.29%402x.png)
 
 ### 3. View the results of the delete glossary command
-![delete-glossary-step3 2024-11-06 at 15.53.19@2x.png](delete-glossary-step3%202024-11-06%20at%2015.53.19%402x.png)
+![delete-glossary-step3 2024-11-06 at 15.53.19@2x.png](images/delete-glossary-step3%202024-11-06%20at%2015.53.19%402x.png)
 
 ### 4. List glossaries again to see the remaining glossaries
-![delete-glossary-step4 2024-11-06 at 15.55.11@2x.png](delete-glossary-step4%202024-11-06%20at%2015.55.11%402x.png)
+![delete-glossary-step4 2024-11-06 at 15.55.11@2x.png](images/delete-glossary-step4%202024-11-06%20at%2015.55.11%402x.png)
 
 # Working with terms
 
@@ -34,57 +42,68 @@
 
 ### Display all terms across all visible glossaries
 
-![tui-show-glossary-terms 2024-11-05 at 19.37.53@2x.png](tui-show-glossary-terms%202024-11-05%20at%2019.37.53%402x.png)
+![tui-show-glossary-terms 2024-11-05 at 19.37.53@2x.png](images/tui-show-glossary-terms%202024-11-05%20at%2019.37.53%402x.png)
 
-![out-list-all-terms  2024-11-06 at 16.22.20@2x.png](out-list-all-terms%20%202024-11-06%20at%2016.22.20%402x.png)
-### Display all terms for a specific glossary
+![out-list-all-terms  2024-11-06 at 16.22.20@2x.png](images/out-list-all-terms%20%202024-11-06%20at%2016.22.20%402x.png)
 
-![tui-display-terms-for-example 2024-11-06 at 20.56.49.png](tui-display-terms-for-example%202024-11-06%20at%2020.56.49.png)
+### Display all terms for a specific glossary
 
-![out-create-term 2024-11-06 at 20.48.29.png](out-create-term%202024-11-06%20at%2020.48.29.png)
+![tui-display-terms-for-example 2024-11-06 at 20.56.49.png](images/tui-display-terms-for-example%202024-11-06%20at%2020.56.49.png)
 
-![out-list-terms-for-example 2024-11-06 at 16.40.12.png](out-list-terms-for-example%202024-11-06%20at%2016.40.12.png)
+![out-list-terms-for-example 2024-11-06 at 16.40.12.png](images/out-list-terms-for-example%202024-11-06%20at%2016.40.12.png)
 
 ### Display terms starting with a specified search string
-![tui-list-terms-second 2024-11-06 at 16.46.34.png](tui-list-terms-second%202024-11-06%20at%2016.46.34.png)
 
-![out-list-terms-second 2024-11-06 at 16.45.13.png](out-list-terms-second%202024-11-06%20at%2016.45.13.png)
-
-## Create a new term
+![tui-list-terms-second 2024-11-06 at 16.46.34.png](images/tui-list-terms-second%202024-11-06%20at%2016.46.34.png)
 
-![tui-create-term 2024-11-06 at 20.46.35.png](tui-create-term%202024-11-06%20at%2020.46.35.png)
-
-![out-display-terms-for-glossary-test 2024-11-06 at 20.51.28.png](out-display-terms-for-glossary-test%202024-11-06%20at%2020.51.28.png)
-## Delete a term
-
-## Export terms to a CSV File
-
-![tui-export-glossary 2024-11-06 at 21.02.16.png](tui-export-glossary%202024-11-06%20at%2021.02.16.png)
-
-![out-terms-export 2024-11-06 at 21.03.24.png](out-terms-export%202024-11-06%20at%2021.03.24.png)
-
-![out-exported-terms 2024-11-06 at 21.06.32.png](out-exported-terms%202024-11-06%20at%2021.06.32.png)
-
-## Import terms from a CSV File
+![out-list-terms-second 2024-11-06 at 16.45.13.png](images/out-list-terms-second%202024-11-06%20at%2016.45.13.png)
 
+## Create a new term
 
+![tui-create-term 2024-11-06 at 20.46.35.png](images/tui-create-term%202024-11-06%20at%2020.46.35.png)
 
+![out-create-term 2024-11-06 at 20.48.29.png](images/out-create-term%202024-11-06%20at%2020.48.29.png)
 
+![out-display-terms-for-glossary-test 2024-11-06 at 20.51.28.png](images/out-display-terms-for-glossary-test%202024-11-06%20at%2020.51.28.png)
 
+## Delete a term
+![tui-delete-term 2024-11-07 at 03.51.57.png](images/tui-delete-term%202024-11-07%20at%2003.51.57.png)
 
+![out-delete-term 2024-11-07 at 03.57.25.png](images/out-delete-term%202024-11-07%20at%2003.57.25.png)
 
+## Import & Export terms 
+#### We can import terms from a CSV formatted file and export terms to a CSV formatted file. 
 
+### Import terms into example glossary
 
+#### First we'll import terms from the file `Test1.om-terms`
+![tui-import-upsert-example 2024-11-07 at 10.08.37.png](images/tui-import-upsert-example%202024-11-07%20at%2010.08.37.png)
 
+#### Because the *verbose* option is enabled, we will get back a JSON structure reflecting the import status for each row in the file. Note that there must be a blank row at the end of the file because we detect a missing term name and skip that row.
+![out-import-terms 2024-11-07 at 08.15.18.png](images/out-import-terms%202024-11-07%20at%2008.15.18.png)
 
+#### Listing the glossary terms shows us the results of the import.
 
+![out-list-terms-for-example 2024-11-06 at 16.40.12.png](images/out-list-terms-for-example%202024-11-06%20at%2016.40.12.png)
 
+### Export terms to a CSV File
+#### Now we will create a copy of this glossary to a CSV file to use it for further demonstrations.
+![![tui-export-example 2024-11-07 at 09.52.59.png](images/tui-export-example%202024-11-07%20at%2009.52.59.png)tui-export-glossary 2024-11-06 at 21.02.16.png](tui-export-glossary%202024-11-06%20at%2021.02.16.png)
+![out-export-example 2024-11-07 at 09.54.57.png](images/out-export-example%202024-11-07%20at%2009.54.57.png)
 
+![out-exported-terms 2024-11-06 at 21.06.32.png](images/out-exported-terms%202024-11-06%20at%2021.06.32.png)
+### Demonstrating upsert capability
 
+#### We will copy the exported file to a new file called **upsert-example.om-terms** and modify the file by adding a fourth row and updating the description field of one of the terms.
 
+### Upsert
 
+#### Importing **upsert-example.om-terms**.
 
+![tui-upsert 2024-11-07 at 11.49.04.png](images/tui-upsert%202024-11-07%20at%2011.49.04.png)
 
+#### For rows in the file that contain a **Qualified Name**, any values provided on that row will over-write existing values. Rows that have a **Term Name** but do not have a **Qualified Name** will be appended to the glossary.
+![out-upsert-import 2024-11-07 at 19.37.00.png](images/out-upsert-import%202024-11-07%20at%2019.37.00.png)
 ----
 License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/),
 Copyright Contributors to the Egeria project.

pyegeria/commands/doc/hey_egeria: a pyegeria command line interface/hey_egeria: overview.md

@@ -0,0 +1,164 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- Copyright Contributors to the Egeria project. -->
+
+# Introduction
+# Hey_Egeria
+
+Hey_Egeria is a friendly, easy to use command line interface (CLI) to make using Egeria easier and more transparent. 
+It is implemented as a set of pyegeria commands that allows users to manage and inspect Egeria artifacts through a simple terminal interface.
+There are currently about 70 commands available, but the functions continue to grow and evolve with the needs of the Egeria community.
+
+Getting started is easy. The CLI runs in a standard terminal window operating in Mac, PC and Linux environments. 
+You will need to know some basic information about your Egeria environment, but if you are operating within a typical 
+Egeria development environment or Egeria Workspaces the pre-configured environment variables and defaults should just work without additional setup. 
+
+In this guide, we'll first review how to install hey_egeria, then go through how to use it from both the 
+TUI (Textual User Interface) as well as the command line. After walking through a number of basic examples, 
+we'll discuss how the CLI is organized, how to configure it and some advanced features. Let's get started!
+
+# Installation & Upgrade
+
+`hey_egeria` is written in python and is part of the the **__pyegeria package__** that can be found on [pypi](https://pypi.org). 
+To install and run the CLI  we use the **pipx** utility [Installation - pipx](https://pipx.pypa.io/latest/installation/). 
+This utility creates operating system level commands from suitably configured python packages. 
+It installs the package in a private environment so that the python packages are isolated from the rest of your environment. 
+So the first step is to install pipx from a terminal window by following the directions in the link above.
+
+
+Once **pipx** is installed, install **pyegeria** using pipx, this will create and configure all of the pyegeria commands. 
+Install pyegeria commands by entering into the terminal window:
+
+`pipx install pyegeria`
+
+This will result in a an output similar to:
+
+
+
+```➜  / pipx install pyegeria
+  installed package pyegeria 1.5.1.1.49, installed using Python 3.12.7
+  These apps are now globally available
+    - change_todo_status
+    - create_glossary
+    - create_term
+    - create_todo
+    - delete_glossary
+    - delete_todo
+    - export_terms_to_file
+    - get_asset_graph
+    - get_collection
+    - get_element_info
+    - get_guid_info
+    - get_project_dependencies
+    - get_project_structure
+    - get_tech_details
+    - get_tech_type_elements
+    - get_tech_type_template
+    - hey_egeria
+    - hey_egeria_cat
+    - hey_egeria_my
+    - hey_egeria_ops
+    - hey_egeria_per
+    - hey_egeria_tech
+    - list_archives
+    - list_asset_types
+    - list_assets
+    - list_catalog_targets
+    - list_cert_types
+    - list_deployed_catalogs
+    - list_deployed_databases
+    - list_deployed_schemas
+    - list_deployed_servers
+    - list_element_graph
+    - list_elements
+    - list_elements_for_classification
+    - list_engine_activity
+    - list_engine_activity_compressed
+    - list_glossaries
+    - list_glossary
+    - list_gov_action_processes
+    - list_gov_eng_status
+    - list_integ_daemon_status
+    - list_my_profile
+    - list_my_roles
+    - list_projects
+    - list_registered_services
+    - list_related_elements
+    - list_related_specification
+    - list_relationship_types
+    - list_relationships
+    - list_tech_templates
+    - list_tech_types
+    - list_terms
+    - list_todos
+    - list_user_ids
+    - list_valid_metadata_values
+    - load_archive
+    - load_archive_tui
+    - load_terms_from_file
+    - mark_todo_complete
+    - monitor_asset_events
+    - monitor_coco_status
+    - monitor_engine_activity
+    - monitor_engine_activity_compressed
+    - monitor_gov_eng_status
+    - monitor_integ_daemon_status
+    - monitor_my_todos
+    - monitor_open_todos
+    - monitor_platform_status
+    - monitor_server_list
+    - monitor_server_startup
+    - monitor_server_status
+    - reassign_todo
+    - refresh_gov_eng_config
+    - refresh_integration_daemon
+    - restart_integration_daemon
+    - start_daemon
+    - stop_daemon
+done! ✨ 🌟 ✨
+```
+
+There are a couple of interesting things to note in the output. The first is the version of pyegeria which can be helpful in determining if and when to upgrade. The second is the long list of pyegeria commands that are installed. Executing these commands directly can be a useful shortcut - especially within shell scripts - but for getting started and everyday use many people find that using the **hey_egeria** CLI is simpler. Hence, this document will focus more on using the CLI. 
+
+Uninstalling and upgrading pyegeria can also easily be done with pipx commands. Issuing:
+
+`pipx -h`
+
+Will provide a good overview.
+
+## First Use
+
+A good first use is to validate that we are able to communicate with an Egeria platform and check the status of the running servers. We can do this by typing:
+
+`hey_egeria ops show servers`
+
+Which should produce an output similar to:
+
+The structure of the command is:
+
+`hey_egeria` [area] [show/tell] [object] [required parameters] [--optional parameters]
+
+* hey_egeria` - this is the shell level command
+* [area] - there are currently four areas of commands that roughly correspond to user roles. They are:
+	* cat - for catalog users - this is for general usage of Egeria as a governance catalog.
+	* my - for individual information - these commands are relevant to an individual such as my_todos.
+	* ops - for Egeria operations - these commands are for working with the Egeria environment itself.
+	* tech - for technical users - these commands provide technical details and management.
+* [show/tell] - **show** commands display something and **tell** commands instruct Egeria to do something. 
+For example, above we requested to be shown the status of Egeria servers on a platform. We could use a tell command to, create or delete a glossary term.
+* [required parameters] - parameters are sometimes required by a command. 
+* [optional parameters] - most parameters are optional and have sensible defaults so that you don't have to type them in.
+
+There is a lot of detail here that can seem a bit daunting to learn - so to make things easier, we have a TUI 
+(Textual User Interface) that allows us to browse through the commands with documentation and guidance about how to fill out each command - and then to execute the command. Here is what it looks like:
+
+![tui-hey-egeria 2024-11-10 at 18.31.01@2x.png](images/tui-hey-egeria%202024-11-10%20at%2018.31.01%402x.png)
+Lets review the numbered annotations in the screenshot above:
+
+1) The left hand side is a scrollable list of commands organized by area, show/tell and then 
+## Working with the TUI
+
+
+
+----
+License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/),
+Copyright Contributors to the Egeria project.