Merge pull request #53 from pyansys/doc/49-server-response-logs

Server response log examples

.ipython/profile_default/startup/10-monkeypatch-connection.py

@@ -0,0 +1,41 @@
+import os
+from ansys.grantami.bomanalytics import Connection
+from ansys.grantami.bomanalytics._connection import BomAnalyticsClient
+
+# Monkey patch the Connection() class to use the environment variable-specified server URL.
+original_ctor = Connection.__init__
+
+
+def new_init(self: Connection, _):
+    original_ctor(self, os.getenv("TEST_SL_URL"))
+
+
+Connection.__init__ = new_init
+
+# Monkey patch the Connection builder methods to use the environment variable-specified credentials.
+Connection.with_creds_original = Connection.with_credentials
+
+
+def with_credentials(self: Connection, _, __) -> Connection:
+    user_name = os.getenv("TEST_USER")
+    password = os.getenv("TEST_PASS")
+    return self.with_creds_original(user_name, password)
+
+
+def with_autologon(self: Connection) -> Connection:
+    return self.with_credentials("foo", "bar")
+
+
+Connection.with_credentials = with_credentials
+Connection.with_autologon = with_autologon
+
+
+# Monkey patch the Client object to report the url specified in the code, or the one below if not overridden
+server_url = "http://my_grantami_server/mi_servicelayer"
+
+
+def __repr__(self: BomAnalyticsClient) -> str:
+    return f'<BomServicesClient: url="{server_url}", dbkey="{self._db_key}">'
+
+
+BomAnalyticsClient.__repr__ = __repr__

examples/0_Getting_started.py

@@ -0,0 +1,153 @@
+# ---
+# jupyter:
+#   jupytext:
+#     formats: ipynb,py:light
+#     text_representation:
+#       extension: .py
+#       format_name: light
+#       format_version: '1.5'
+#       jupytext_version: 1.13.1
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+# # [TECHDOCS]Getting Started
+
+# ## Introduction
+
+# This example describes how to connect to Granta MI and perform a basic Impacted Substances query. It also describes
+# how to view logging messages returned by the Granta MI server. It does not go into detail about the results of the
+# queries, please see the other examples for further detail in this area.
+
+# ## Connect to Granta MI
+
+# The first step is to connect to the Granta MI server. Use the `ansys.grantami.bomanalytics.Connection` class to create
+# a connection. The `Connection` class uses a fluent interface to build the connection which is always invoked in the
+# following sequence:
+#
+# 1. Specify the Granta MI Service Layer URL as a parameter to the `Connection` class
+# 2. Specify the authentication method using one of the `Connection.with_...()` methods
+# 3. Use the `Connection.connect()` method to finalize the connection. This returns a connection object which is called
+#    `cxn` in these examples.
+
+# + tags=[]
+from ansys.grantami.bomanalytics import Connection
+
+server_url = "http://my_grantami_server/mi_servicelayer"
+# -
+
+# If the Python script is running on Windows, in most cases you will be able to use the `.with_autologon()`.
+
+# + tags=[]
+cxn = Connection(server_url).with_autologon().connect()
+cxn
+# -
+
+# If the Python script is running on Linux without Kerberos enabled, or you wish to use an account other than your
+# logged-in account, you can specify credentials explicitly.
+
+# + tags=[]
+cxn = Connection(server_url).with_credentials("my_username", "my_password").connect()
+cxn
+# -
+
+# OIDC and anonymous authentication methods are also available, but these are beyond the scope of this example. See
+# the documentation for the `ansys-openapi-common` package for more details.
+
+# ## Construct a Query
+
+# Queries are also constructed using a fluent interface. However, the `Query` constructor takes no arguments; all the
+# details of the query are specified on `Query` methods.  To demonstrate this, we will aim to build a query that
+# determines the substances present in an ABS material that are impacted by the REACH Candidate List legislation.
+
+# First import the `queries` module and create a `MaterialImpactedSubstancesQuery` object.
+
+# + tags=[]
+from ansys.grantami.bomanalytics import queries
+
+query = queries.MaterialImpactedSubstancesQuery()
+query
+# -
+
+# Now add the material that we wish to query by specifying its material ID. Note: other methods of specifying records
+# are available; these are discussed in other examples.
+
+# + tags=[]
+query = query.with_material_ids(["plastic-abs-high-impact"])
+query
+# -
+
+# Note that because the `MaterialImpactedSubstancesQuery` object has a fluent interface, we receive the same object back
+# that we started with, just with the Material IDs added. Finally, add the legislation to the query.
+
+# + tags=[]
+query = query.with_legislations(["REACH - The Candidate List"])
+query
+# -
+
+# However, fluent interfaces are intended to allow a complex object to be constructed in a single line of code. We can
+# consolidate the above cells to create the object in a single step:
+
+# + tags=[]
+query = queries.MaterialImpactedSubstancesQuery().with_material_ids(["plastic-abs-high-impact"]).with_legislations(["REACH - The Candidate List"])  # noqa: E501
+query
+# -
+
+# Since the fluent interface can produce very long lines of code, it is required to break the query creation into
+# multiple lines. The following multi-line format is used throughout the examples, and is functionally equivalent to
+# the cell above.
+
+# + tags=[]
+query = (
+    queries.MaterialImpactedSubstancesQuery()
+    .with_material_ids(["plastic-abs-high-impact"])
+    .with_legislations(["REACH - The Candidate List"])
+)
+query
+# -
+
+# The cell above is the recommended way of creating queries using this API.
+
+# ## Run a Query
+
+# Now we have our `cxn` and `query` objects, we can use the `cxn.run()` method to run the query. This returns an object
+# that contains the results of the query.
+
+# + tags=[]
+result = cxn.run(query)
+result
+# -
+
+# ## Query Results
+
+# In the case of an `MaterialsImpactedSubstancesQuery`, the results object contains the list of substances present in
+# the material that are impacted by the specified legislations.
+
+# + tags=[]
+result.impacted_substances
+# -
+
+# ## Logging
+
+# All query results contain a list of messages that were returned by the server when running the query. These are
+# sorted in order of decreasing severity. The same messages are also available in the Service Layer log file.
+
+# + tags=[]
+result.messages
+# -
+
+# These messages are also available via the standard `logging` module using the 'ansys.grantami.bomanalytics' logger.
+# Alternatively, omit the logger name to get the root logger, which will include messages logged by all packages.
+# The code below creates a log handler that outputs all bomanalytics messages with severity INFO and above to either the
+# terminal or the notebook.
+
+# + tags=[]
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("ansys.grantami.bomanalytics")
+
+result = cxn.run(query)
+# -

examples/1_Impacted_Substances_Queries/1-1_Materials_impacted_substances.py

@@ -22,32 +22,13 @@
 
 # ## Connecting to Granta MI
 
-# First define the username, password, and url we will use to connect to the Granta MI server.
-
-# + tags=[]
-user_name = "my_username"
-password = "my_password"
-server_url = "http://my_grantami_service/mi_servicelayer"
-# -
-
-# + nbsphinx="hidden"
-import os
-
-# This cell is included for package CI/CD purposes only, and is removed when generating the HTML documentation.
-# It will have no effect if the environment variables referenced below are unset.
-
-user_name = os.getenv("TEST_USER", user_name)
-password = os.getenv("TEST_PASS", password)
-server_url = os.getenv("TEST_SL_URL", server_url)
-# -
-
-# Now import the `ansys-grantami-bomanalytics` module and create the connection. See the example on creating connections
-# for more detail.
+# Import the `Connection` class and create the connection. See the Getting Started example for more detail.
 
 # + tags=[]
 from ansys.grantami.bomanalytics import Connection
 
-cxn = Connection(server_url).with_credentials(user_name, password).connect()
+server_url = "http://my_grantami_service/mi_servicelayer"
+cxn = Connection(server_url).with_credentials("user_name", "password").connect()
 # -
 
 # ## Building and Running the Query

examples/1_Impacted_Substances_Queries/1-2_Parts_impacted_substances.py

@@ -26,32 +26,13 @@
 
 # ## Connecting to Granta MI
 
-# First define the username, password, and url we will use to connect to the Granta MI server.
-
-# + tags=[]
-user_name = "my_username"
-password = "my_password"
-server_url = "http://my_grantami_service/mi_servicelayer"
-# -
-
-# + nbsphinx="hidden"
-import os
-
-# This cell is included for package CI/CD purposes only, and is removed when generating the HTML documentation.
-# It will have no effect if the environment variables referenced below are unset.
-
-user_name = os.getenv("TEST_USER", user_name)
-password = os.getenv("TEST_PASS", password)
-server_url = os.getenv("TEST_SL_URL", server_url)
-# -
-
-# Now import the `ansys-grantami-bomanalytics` module and create the connection. See the example on creating connections
-# for more detail.
+# Import the `Connection` class and create the connection. See the Getting Started example for more detail.
 
 # + tags=[]
 from ansys.grantami.bomanalytics import Connection
 
-cxn = Connection(server_url).with_credentials(user_name, password).connect()
+server_url = "http://my_grantami_service/mi_servicelayer"
+cxn = Connection(server_url).with_credentials("user_name", "password").connect()
 # -
 
 # + [markdown] tags=[]

examples/2_Compliance_Queries/2-1_Substance_compliance.py

@@ -19,32 +19,13 @@
 
 # ## Connecting to Granta MI
 
-# First define the username, password, and url we will use to connect to the Granta MI server.
-
-# + tags=[]
-user_name = "my_username"
-password = "my_password"
-server_url = "http://my_grantami_service/mi_servicelayer"
-# -
-
-# + nbsphinx="hidden"
-import os
-
-# This cell is included for package CI/CD purposes only, and is removed when generating the HTML documentation.
-# It will have no effect if the environment variables referenced below are unset.
-
-user_name = os.getenv("TEST_USER", user_name)
-password = os.getenv("TEST_PASS", password)
-server_url = os.getenv("TEST_SL_URL", server_url)
-# -
-
-# Now import the `ansys-grantami-bomanalytics` module and create the connection. See the example on creating connections
-# for more detail.
+# Import the `Connection` class and create the connection. See the Getting Started example for more detail.
 
 # + tags=[]
 from ansys.grantami.bomanalytics import Connection
 
-cxn = Connection(server_url).with_credentials(user_name, password).connect()
+server_url = "http://my_grantami_service/mi_servicelayer"
+cxn = Connection(server_url).with_credentials("user_name", "password").connect()
 # -
 
 # ## Defining an Indicator

examples/2_Compliance_Queries/2-2_Material_compliance.py

@@ -21,32 +21,13 @@
 
 # ## Connecting to Granta MI
 
-# First define the username, password, and url we will use to connect to the Granta MI server.
-
-# + tags=[]
-user_name = "my_username"
-password = "my_password"
-server_url = "http://my_grantami_service/mi_servicelayer"
-# -
-
-# + nbsphinx="hidden"
-import os
-
-# This cell is included for package CI/CD purposes only, and is removed when generating the HTML documentation.
-# It will have no effect if the environment variables referenced below are unset.
-
-user_name = os.getenv("TEST_USER", user_name)
-password = os.getenv("TEST_PASS", password)
-server_url = os.getenv("TEST_SL_URL", server_url)
-# -
-
-# Now import the `ansys-grantami-bomanalytics` module and create the connection. See the example on creating connections
-# for more detail.
+# Import the `Connection` class and create the connection. See the Getting Started example for more detail.
 
 # + tags=[]
 from ansys.grantami.bomanalytics import Connection
 
-cxn = Connection(server_url).with_credentials(user_name, password).connect()
+server_url = "http://my_grantami_service/mi_servicelayer"
+cxn = Connection(server_url).with_credentials("user_name", "password").connect()
 # -
 
 # ## Defining an Indicator

examples/2_Compliance_Queries/2-3_Part_compliance.py

@@ -21,32 +21,13 @@
 
 # ## Connecting to Granta MI
 
-# First define the username, password, and url we will use to connect to the Granta MI server.
-
-# + tags=[]
-user_name = "my_username"
-password = "my_password"
-server_url = "http://my_grantami_service/mi_servicelayer"
-# -
-
-# + nbsphinx="hidden"
-import os
-
-# This cell is included for package CI/CD purposes only, and is removed when generating the HTML documentation.
-# It will have no effect if the environment variables referenced below are unset.
-
-user_name = os.getenv("TEST_USER", user_name)
-password = os.getenv("TEST_PASS", password)
-server_url = os.getenv("TEST_SL_URL", server_url)
-# -
-
-# Now import the `ansys-grantami-bomanalytics` module and create the connection. See the example on creating connections
-# for more detail.
+# Import the `Connection` class and create the connection. See the Getting Started example for more detail.
 
 # + tags=[]
 from ansys.grantami.bomanalytics import Connection
 
-cxn = Connection(server_url).with_credentials(user_name, password).connect()
+server_url = "http://my_grantami_service/mi_servicelayer"
+cxn = Connection(server_url).with_credentials("user_name", "password").connect()
 # -
 
 # ## Defining an Indicator