#291 Fix EU REACH, and some other miscellaneous documentation improve…

…ments (#343)

* Fix REACH legislation title. Specify what the legislation name should be set to.

* Catch a few more

* Replace localhost

* Revert change

README.rst

@@ -49,7 +49,7 @@ Here's a brief example of how to use PyGranta BoM Analytics:
     >>> query = (
     ...     queries.MaterialImpactedSubstancesQuery()
     ...     .with_material_ids(['plastic-abs-pvc-flame'])
-    ...     .with_legislations(['REACH - The Candidate List'])
+    ...     .with_legislations(['EU REACH - The Candidate List'])
     ... )
 
     # Print out the result from the query.

doc/source/index/quick_code.rst

@@ -8,12 +8,12 @@ high concern) in an ABS/PVC blend:
 
     >>> from pprint import pprint
     >>> from ansys.grantami.bomanalytics import Connection, queries
-    >>> cxn = Connection(servicelayer_url="http://localhost/mi_servicelayer") \
+    >>> cxn = Connection(servicelayer_url="http://my_mi_server/mi_servicelayer") \
     ...     .with_autologon().connect()
     >>> query = (
     ...     queries.MaterialImpactedSubstancesQuery()
     ...     .with_material_ids(['plastic-abs-pvc-flame'])
-    ...     .with_legislations(['REACH - The Candidate List'])
+    ...     .with_legislations(['EU REACH - The Candidate List'])
     ... )
     >>> result = cxn.run(query)
     >>> pprint(result.impacted_substances)

examples/0_Getting_started.py

@@ -82,18 +82,18 @@
 # Note that because the ``MaterialImpactedSubstancesQuery`` object has a fluent interface, you receive the same object
 # back that you started with, but with the material IDs added.
 #
-# Finally, add the legislation to the query.
+# Finally, add the legislation to the query. Legislations are identified by their ``Short title`` attribute.
 
 # + tags=[]
-query = query.with_legislations(["REACH - The Candidate List"])
+query = query.with_legislations(["EU REACH - The Candidate List"])
 query
 # -
 
 # Fluent interfaces are designed to allow a complex object to be constructed in a single line of code. As such, you can
 # consolidate the cells above into a single step:
 
 # + tags=[]
-query = queries.MaterialImpactedSubstancesQuery().with_material_ids(["plastic-abs-high-impact"]).with_legislations(["REACH - The Candidate List"])  # noqa: E501
+query = queries.MaterialImpactedSubstancesQuery().with_material_ids(["plastic-abs-high-impact"]).with_legislations(["EU REACH - The Candidate List"])  # noqa: E501
 query
 # -
 
@@ -105,7 +105,7 @@
 query = (
     queries.MaterialImpactedSubstancesQuery()
     .with_material_ids(["plastic-abs-high-impact"])
-    .with_legislations(["REACH - The Candidate List"])
+    .with_legislations(["EU REACH - The Candidate List"])
 )
 query
 # -

examples/1_Impacted_Substances_Queries/1-1_Materials_impacted_substances.py

@@ -43,7 +43,7 @@
 PPS_ID = "plastic-pps-generalpurpose"
 PC_ID = "plastic-pc-20carbonfiber"
 SIN_LIST = "The SIN List 2.1 (Substitute It Now!)"
-REACH = "REACH - The Candidate List"
+REACH = "EU REACH - The Candidate List"
 # -
 
 # Next import the ``queries`` module and build the query with the references in the previous cell.

examples/1_Impacted_Substances_Queries/1-2_Parts_impacted_substances.py

@@ -54,7 +54,7 @@
 DRILL = "DRILL"
 WING = "asm_flap_mating"
 SIN_LIST = "The SIN List 2.1 (Substitute It Now!)"
-REACH = "REACH - The Candidate List"
+REACH = "EU REACH - The Candidate List"
 # -
 
 # Next, import the ``queries`` module and build the query with the references in the previous cell.

examples/2_Compliance_Queries/2-1_Substance_compliance.py

@@ -16,7 +16,7 @@
 # # Performing a Substance Compliance Query
 
 # A Substance Compliance Query determines whether one or more substances are compliant with the specified indicators.
-# This example checks several materials for substances included on two watch lists ("REACH - The Candidate List", and
+# This example checks several materials for substances included on two watch lists ("EU REACH - The Candidate List", and
 # "The SIN List 2.1"), specifying substance amounts and thresholds for compliance.
 
 # ## Connecting to Granta MI
@@ -51,7 +51,7 @@
 
 svhc = indicators.WatchListIndicator(
     name="SVHC",
-    legislation_names=["REACH - The Candidate List"],
+    legislation_names=["EU REACH - The Candidate List"],
     default_threshold_percentage=0.1,
 )
 sin = indicators.WatchListIndicator(

examples/2_Compliance_Queries/2-2_Material_compliance.py

@@ -51,7 +51,7 @@
 
 svhc = indicators.WatchListIndicator(
     name="SVHC",
-    legislation_names=["REACH - The Candidate List"],
+    legislation_names=["EU REACH - The Candidate List"],
     default_threshold_percentage=0.1,
 )
 sin = indicators.WatchListIndicator(

examples/2_Compliance_Queries/2-3_Part_compliance.py

@@ -51,7 +51,7 @@
 
 svhc = indicators.WatchListIndicator(
     name="SVHC",
-    legislation_names=["REACH - The Candidate List"],
+    legislation_names=["EU REACH - The Candidate List"],
     default_threshold_percentage=0.1,
 )
 sin = indicators.WatchListIndicator(

examples/3_Advanced_Topics/3-1_Working_with_XML_BoMs.py

@@ -128,7 +128,7 @@ def xml_validator(xml: str, schema_file: str) -> bool:
 
 svhc = indicators.WatchListIndicator(
     name="SVHC",
-    legislation_names=["REACH - The Candidate List"],
+    legislation_names=["EU REACH - The Candidate List"],
     default_threshold_percentage=0.1,
 )
 compliance_query = (

examples/3_Advanced_Topics/3-2_Dealing_with_external_data_sources.py

@@ -78,7 +78,7 @@
 cxn = Connection(server_url).with_credentials("user_name", "password").connect()
 svhc = indicators.WatchListIndicator(
     name="SVHC",
-    legislation_names=["REACH - The Candidate List"],
+    legislation_names=["EU REACH - The Candidate List"],
     default_threshold_percentage=0.1,
 )
 mat_query = (

examples/3_Advanced_Topics/3-4_Writing_compliance_results_to_a_dataframe.py

@@ -33,7 +33,7 @@
 cxn = Connection(server_url).with_credentials("user_name", "password").connect()
 svhc = indicators.WatchListIndicator(
     name="SVHC",
-    legislation_names=["REACH - The Candidate List"],
+    legislation_names=["EU REACH - The Candidate List"],
     default_threshold_percentage=0.1,
 )
 part_query = (

src/ansys/grantami/bomanalytics/_connection.py

@@ -177,7 +177,7 @@ def _test_connection(client: "BomAnalyticsClient") -> None:
         except ApiException as e:
             if e.status_code == 404:
                 raise ConnectionError(
-                    "Cannot find the BoM Analytics service in Granta MI Service Layer. Ensure a compatible version of"
+                    "Cannot find the BoM Analytics service in Granta MI Service Layer. Ensure a compatible version of "
                     "the Restricted Substances Reports are available on the server and try again."
                 )
             else:
@@ -319,7 +319,7 @@ def set_database_details(
 
         Examples
         --------
-        >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+        >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
         >>> cxn.set_database_details(database_key = "MY_RS_DB",
         ...                          in_house_materials_table_name = "My Materials")
         """

src/ansys/grantami/bomanalytics/_query_results.py

@@ -176,7 +176,7 @@ def impacted_substances_by_legislation(self) -> Dict[str, List["ImpactedSubstanc
         --------
         >>> result: MaterialImpactedSubstancesQueryResult
         >>> result.impacted_substances_by_legislation
-        {'REACH - The Candidate List': [
+        {'EU REACH - The Candidate List': [
             <ImpactedSubstance: {"cas_number": 90481-04-2}>, ...]
         }
         """

src/ansys/grantami/bomanalytics/indicators.py

@@ -371,7 +371,8 @@ class RoHSIndicator(_Indicator):
     name : str
         Name of the indicator that is to identify the indicator in the query result.
     legislation_names : list[str]
-        Legislations against which compliance will be determined.
+        Legislations against which compliance will be determined. Legislations are identified based
+        on their ``Short title`` attribute value.
     default_threshold_percentage : float, optional
         Concentration of substance that is to be determined to be non-compliant. The default is ``None``.
         This parameter is only used if the legislation doesn't define a specific threshold for the substance.
@@ -456,7 +457,8 @@ class WatchListIndicator(_Indicator):
     name : str
         Name of the indicator that is used to identify the indicator in the query result.
     legislation_names : list[str]
-        Legislations against which compliance is to be determined.
+        Legislations against which compliance is to be determined. Legislations are identified based
+        on their ``Short title`` attribute value.
     default_threshold_percentage : float, optional
         Percentage of substance concentration that is to be determined to be non-compliant. The default is ``None``.
         This parameter is only used if the legislation doesn't define a specific threshold for the substance.

src/ansys/grantami/bomanalytics/queries.py

@@ -701,7 +701,7 @@ def __repr__(self) -> str:
     def with_legislations(self: Query_Builder, legislation_names: List[str]) -> Query_Builder:
         """Add a list or set of legislations to retrieve the impacted substances for.
 
-        The legislation records are referenced by legislation name.
+        Legislations are identified based on their ``Short title`` attribute value.
 
         Parameters
         ----------
@@ -722,7 +722,7 @@ def with_legislations(self: Query_Builder, legislation_names: List[str]) -> Quer
         --------
         >>> query = MaterialImpactedSubstancesQuery()
         >>> query = query.with_legislations(["California Proposition 65 List",
-        >>>                                  "REACH - The Candidate List"])
+        >>>                                  "EU REACH - The Candidate List"])
         <MaterialImpactedSubstances: 0 materials, batch size = 100, 2 legislations>
         """
 
@@ -835,7 +835,7 @@ class MaterialComplianceQuery(_ComplianceMixin, _MaterialQueryBuilder):
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> indicator = WatchListIndicator(
     ...     name="Prop 65",
     ...     legislation_names=["California Proposition 65 List"]
@@ -868,11 +868,11 @@ class MaterialImpactedSubstancesQuery(_ImpactedSubstanceMixin, _MaterialQueryBui
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> query = (
     ...     MaterialImpactedSubstancesQuery()
     ...     .with_material_ids(['elastomer-butadienerubber', 'NBR-100'])
-    ...     .with_legislations(["REACH - The Candidate List"])
+    ...     .with_legislations(["EU REACH - The Candidate List"])
     ... )
     >>> cxn.run(query)
     <MaterialImpactedSubstancesQueryResult: 2 MaterialWithImpactedSubstances results>
@@ -940,7 +940,7 @@ class PartComplianceQuery(_ComplianceMixin, _PartQueryBuilder):
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> indicator = WatchListIndicator(
     ...     name="Prop 65",
     ...     legislation_names=["California Proposition 65 List"]
@@ -974,11 +974,11 @@ class PartImpactedSubstancesQuery(_ImpactedSubstanceMixin, _PartQueryBuilder):
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> query = (
     ...     PartImpactedSubstancesQuery()
     ...     .with_part_numbers(['DRILL', 'FLRY34'])
-    ...     .with_legislations(["REACH - The Candidate List"])
+    ...     .with_legislations(["EU REACH - The Candidate List"])
     ... )
     >>> cxn.run(query)
     <PartImpactedSubstancesQueryResult: 2 PartWithImpactedSubstances results>
@@ -1050,7 +1050,7 @@ class SpecificationComplianceQuery(_ComplianceMixin, _SpecificationQueryBuilder)
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> indicator = WatchListIndicator(
     ...     name="Prop 65",
     ...     legislation_names=["California Proposition 65 List"]
@@ -1083,11 +1083,11 @@ class SpecificationImpactedSubstancesQuery(_ImpactedSubstanceMixin, _Specificati
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> query = (
     ...     SpecificationImpactedSubstancesQuery()
     ...     .with_specification_ids(['MIL-A-8625', 'PSP101'])
-    ...     .with_legislations(["REACH - The Candidate List"])
+    ...     .with_legislations(["EU REACH - The Candidate List"])
     ... )
     >>> cxn.run(query)
     <SpecificationImpactedSubstancesQueryResult:
@@ -1458,7 +1458,7 @@ class SubstanceComplianceQuery(_ComplianceMixin, _SubstanceQueryBuilder):
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> indicator = WatchListIndicator(
     ...     name="Prop 65",
     ...     legislation_names=["California Proposition 65 List"]
@@ -1602,7 +1602,7 @@ class BomComplianceQuery(_ComplianceMixin, _Bom1711QueryBuilder):
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> bom = "<PartsEco xmlns..."
     >>> indicator = WatchListIndicator(
     ...     name="Prop 65",
@@ -1636,12 +1636,12 @@ class BomImpactedSubstancesQuery(_ImpactedSubstanceMixin, _Bom1711QueryBuilder):
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> bom = "<PartsEco xmlns..."
     >>> query = (
     ...     BomImpactedSubstancesQuery()
     ...     .with_bom("<PartsEco xmlns...")
-    ...     .with_legislations(["REACH - The Candidate List"])
+    ...     .with_legislations(["EU REACH - The Candidate List"])
     ... )
     >>> cxn.run(query)
     <BomImpactedSubstancesQueryResult: 1 Bom1711WithImpactedSubstances results>
@@ -1663,7 +1663,7 @@ class Yaml:
 
     Examples
     --------
-    >>> cxn = Connection("http://localhost/mi_servicelayer").with_autologon().connect()
+    >>> cxn = Connection("http://my_mi_server/mi_servicelayer").with_autologon().connect()
     >>> cxn.run(Yaml)
     openapi: 3.0.1
     info: