Merge pull request #63 from ansys/feat/10-document-legislation-id-change

Rename with_legislations to with_legislation_ids

.gitignore

@@ -59,3 +59,5 @@ doc/build
 
 # Pypi things
 deps
+
+venv/

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(['Candidate_AnnexXV'])
+    ...     .with_legislation_ids(['Candidate_AnnexXV'])
     ... )
 
     # Print out the result from the query.

doc/source/api/impacted_substances/bom.rst

@@ -11,7 +11,7 @@ Query definition
 .. autoclass:: ansys.grantami.bomanalytics.queries.BomImpactedSubstancesQuery
    :members:
 
-   .. automethod:: with_legislations
+   .. automethod:: with_legislation_ids
    .. automethod:: with_bom
 
 .. _ref_grantami_bomanalytics_api_impactedsubstances_bom_queryresult:

doc/source/api/impacted_substances/materials.rst

@@ -14,7 +14,7 @@ Query definition
    .. automethod:: with_record_history_ids
    .. automethod:: with_material_ids
    .. automethod:: with_batch_size
-   .. automethod:: with_legislations
+   .. automethod:: with_legislation_ids
 
 Query result
 ~~~~~~~~~~~~

doc/source/api/impacted_substances/parts.rst

@@ -9,7 +9,7 @@ Query definition
 .. autoclass:: ansys.grantami.bomanalytics.queries.PartImpactedSubstancesQuery
    :members:
 
-   .. automethod:: with_legislations
+   .. automethod:: with_legislation_ids
    .. automethod:: with_part_numbers
    .. automethod:: with_record_guids
    .. automethod:: with_record_history_guids

doc/source/api/impacted_substances/specifications.rst

@@ -9,7 +9,7 @@ Query definition
 .. autoclass:: ansys.grantami.bomanalytics.queries.SpecificationImpactedSubstancesQuery
    :members:
 
-   .. automethod:: with_legislations
+   .. automethod:: with_legislation_ids
    .. automethod:: with_specification_ids
    .. automethod:: with_record_guids
    .. automethod:: with_record_history_guids

doc/source/index/quick_code.rst

@@ -13,7 +13,7 @@ high concern) in an ABS/PVC blend:
     >>> query = (
     ...     queries.MaterialImpactedSubstancesQuery()
     ...     .with_material_ids(['plastic-abs-pvc-flame'])
-    ...     .with_legislations(['EU REACH - The Candidate List'])
+    ...     .with_legislation_ids(['Candidate_AnnexXV'])
     ... )
     >>> result = cxn.run(query)
     >>> pprint(result.impacted_substances)

examples/0_Getting_started.py

@@ -86,15 +86,15 @@
 # ``Candidate_AnnexXV`` is the ID of the ``EU REACH - The Candidate List`` legislation.
 
 # + tags=[]
-query = query.with_legislations(["Candidate_AnnexXV"])
+query = query.with_legislation_ids(["Candidate_AnnexXV"])
 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(["Candidate_AnnexXV"])  # noqa: E501
+query = queries.MaterialImpactedSubstancesQuery().with_material_ids(["plastic-abs-high-impact"]).with_legislation_ids(["Candidate_AnnexXV"])  # noqa: E501
 query
 # -
 
@@ -106,7 +106,7 @@
 query = (
     queries.MaterialImpactedSubstancesQuery()
     .with_material_ids(["plastic-abs-high-impact"])
-    .with_legislations(["Candidate_AnnexXV"])
+    .with_legislation_ids(["Candidate_AnnexXV"])
 )
 query
 # -

examples/1_Impacted_Substances_Queries/1-1_Materials_impacted_substances.py

@@ -54,7 +54,7 @@
 mat_query = (
     queries.MaterialImpactedSubstancesQuery()
     .with_material_ids([PPS_ID, PC_ID])
-    .with_legislations([REACH, SIN_LIST])
+    .with_legislation_ids([REACH, SIN_LIST])
 )
 # -
 

examples/1_Impacted_Substances_Queries/1-2_Parts_impacted_substances.py

@@ -65,7 +65,7 @@
 part_query = (
     queries.PartImpactedSubstancesQuery()
     .with_part_numbers([DRILL, WING])
-    .with_legislations([SIN_LIST, REACH])
+    .with_legislation_ids([SIN_LIST, REACH])
 )
 # -
 

examples/3_Advanced_Topics/3-1_Working_with_XML_BoMs.py

@@ -94,7 +94,7 @@ def xml_validator(xml: str, schema_file: str) -> bool:
 impacted_substances_query = (
     queries.BomImpactedSubstancesQuery()
     .with_bom(valid_xml)
-    .with_legislations([SIN_LIST])
+    .with_legislation_ids([SIN_LIST])
 )
 # -
 
@@ -162,7 +162,7 @@ def xml_validator(xml: str, schema_file: str) -> bool:
 broken_query = (
     queries.BomImpactedSubstancesQuery()
     .with_bom(invalid_xml)
-    .with_legislations([SIN_LIST])
+    .with_legislation_ids([SIN_LIST])
 )
 
 RUN_QUERY = False

src/ansys/grantami/bomanalytics/indicators.py

@@ -431,6 +431,7 @@ class RoHSIndicator(_Indicator):
 
     def __init__(
         self,
+        *,
         name: str,
         legislation_ids: List[str],
         default_threshold_percentage: Optional[float] = None,
@@ -526,6 +527,7 @@ class WatchListIndicator(_Indicator):
 
     def __init__(
         self,
+        *,
         name: str,
         legislation_ids: List[str],
         default_threshold_percentage: Optional[float] = None,

src/ansys/grantami/bomanalytics/queries.py

@@ -744,14 +744,14 @@ def __repr__(self) -> str:
         return result
 
     @validate_argument_type([str], {str})
-    def with_legislations(self: _ImpactedSubstanceQuery, legislation_names: List[str]) -> _ImpactedSubstanceQuery:
+    def with_legislation_ids(self: _ImpactedSubstanceQuery, legislation_ids: List[str]) -> _ImpactedSubstanceQuery:
         """Add a list or set of legislations to retrieve the impacted substances for.
 
         Legislations are identified based on their ``Legislation ID`` attribute value.
 
         Parameters
         ----------
-        legislation_names : list[str] | set[str]
+        legislation_ids : list[str] | set[str]
             List or set of legislation ids.
 
         Returns
@@ -765,7 +765,7 @@ def with_legislations(self: _ImpactedSubstanceQuery, legislation_names: List[str
             Error to raise if the method is called with values that do not match the types described earlier.
         """
 
-        self._legislations.extend(legislation_names)
+        self._legislations.extend(legislation_ids)
         return self
 
     def _run_query(self, api_instance: api.ImpactedSubstancesApi, static_arguments: Dict) -> ResultBaseClass:
@@ -912,7 +912,7 @@ class MaterialImpactedSubstancesQuery(_ImpactedSubstanceMixin, _MaterialQueryBui
     >>> query = (
     ...     MaterialImpactedSubstancesQuery()
     ...     .with_material_ids(['elastomer-butadienerubber', 'NBR-100'])
-    ...     .with_legislations(["Candidate_AnnexXV"])
+    ...     .with_legislation_ids(["Candidate_AnnexXV"])
     ... )
     >>> cxn.run(query)
     <MaterialImpactedSubstancesQueryResult: 2 MaterialWithImpactedSubstances results>
@@ -1018,7 +1018,7 @@ class PartImpactedSubstancesQuery(_ImpactedSubstanceMixin, _PartQueryBuilder):
     >>> query = (
     ...     PartImpactedSubstancesQuery()
     ...     .with_part_numbers(['DRILL', 'FLRY34'])
-    ...     .with_legislations(["Candidate_AnnexXV"])
+    ...     .with_legislation_ids(["Candidate_AnnexXV"])
     ... )
     >>> cxn.run(query)
     <PartImpactedSubstancesQueryResult: 2 PartWithImpactedSubstances results>
@@ -1127,7 +1127,7 @@ class SpecificationImpactedSubstancesQuery(_ImpactedSubstanceMixin, _Specificati
     >>> query = (
     ...     SpecificationImpactedSubstancesQuery()
     ...     .with_specification_ids(['MIL-A-8625', 'PSP101'])
-    ...     .with_legislations(["Candidate_AnnexXV"])
+    ...     .with_legislation_ids(["Candidate_AnnexXV"])
     ... )
     >>> cxn.run(query)
     <SpecificationImpactedSubstancesQueryResult:
@@ -1742,7 +1742,7 @@ class BomImpactedSubstancesQuery(_ImpactedSubstanceMixin, _Bom1711QueryBuilder):
     >>> query = (
     ...     BomImpactedSubstancesQuery()
     ...     .with_bom("<PartsEco xmlns...")
-    ...     .with_legislations(["Candidate_AnnexXV"])
+    ...     .with_legislation_ids(["Candidate_AnnexXV"])
     ... )
     >>> cxn.run(query)
     <BomImpactedSubstancesQueryResult: 1 Bom1711WithImpactedSubstances results>

tests/test_integration_tests.py

@@ -14,7 +14,7 @@ class TestMaterialQueries:
     ids = ["plastic-abs-pvc-flame", "plastic-pmma-pc"]
 
     def test_impacted_substances(self, connection_with_db_variants):
-        query = queries.MaterialImpactedSubstancesQuery().with_material_ids(self.ids).with_legislations(LEGISLATIONS)
+        query = queries.MaterialImpactedSubstancesQuery().with_material_ids(self.ids).with_legislation_ids(LEGISLATIONS)
         response = connection_with_db_variants.run(query)
         assert response.impacted_substances
         assert response.impacted_substances_by_legislation
@@ -32,7 +32,7 @@ class TestPartQueries:
     ids = ["DRILL", "asm_flap_mating"]
 
     def test_impacted_substances(self, connection_with_db_variants):
-        query = queries.PartImpactedSubstancesQuery().with_part_numbers(self.ids).with_legislations(LEGISLATIONS)
+        query = queries.PartImpactedSubstancesQuery().with_part_numbers(self.ids).with_legislation_ids(LEGISLATIONS)
         response = connection_with_db_variants.run(query)
 
         assert response.impacted_substances
@@ -55,7 +55,7 @@ def test_impacted_substances(self, connection_with_db_variants):
         query = (
             queries.SpecificationImpactedSubstancesQuery()
             .with_specification_ids(self.ids)
-            .with_legislations(LEGISLATIONS)
+            .with_legislation_ids(LEGISLATIONS)
         )
         response = connection_with_db_variants.run(query)
 
@@ -95,7 +95,7 @@ def bom(self, connection_with_db_variants):
             return sample_bom_complex
 
     def test_impacted_substances(self, bom, connection_with_db_variants):
-        query = queries.BomImpactedSubstancesQuery().with_bom(bom).with_legislations(LEGISLATIONS)
+        query = queries.BomImpactedSubstancesQuery().with_bom(bom).with_legislation_ids(LEGISLATIONS)
         response = connection_with_db_variants.run(query)
 
         assert response.impacted_substances
@@ -116,14 +116,16 @@ def connection_missing_db(self, connection):
         return connection
 
     def test_missing_database_raises_grantami_exception(self, connection_missing_db):
-        query = queries.MaterialImpactedSubstancesQuery().with_material_ids(["mat_id"]).with_legislations(LEGISLATIONS)
+        query = (
+            queries.MaterialImpactedSubstancesQuery().with_material_ids(["mat_id"]).with_legislation_ids(LEGISLATIONS)
+        )
         with pytest.raises(GrantaMIException) as e:
             connection_missing_db.run(query)
         assert str(e.value) == "None of the record references resolved to material records in 'MI_Missing_Database'."
 
 
 def test_missing_table_raises_grantami_exception(connection):
-    query = queries.BomImpactedSubstancesQuery().with_bom(sample_bom_custom_db).with_legislations(LEGISLATIONS)
+    query = queries.BomImpactedSubstancesQuery().with_bom(sample_bom_custom_db).with_legislation_ids(LEGISLATIONS)
     with pytest.raises(GrantaMIException) as e:
         connection.run(query)
     assert "Table name" in str(e.value) and "not found in database" in str(e.value)
@@ -147,7 +149,7 @@ def _run_query(self, connection):
         mat_query = (
             queries.MaterialImpactedSubstancesQuery()
             .with_material_ids([MATERIAL_ID])
-            .with_legislations([LEGISLATION_ID])
+            .with_legislation_ids([LEGISLATION_ID])
         )
         results = connection.run(mat_query)
         return results
@@ -176,7 +178,7 @@ def test_legislation_is_affected_with_link_depth_one(self, connection_custom_db)
         query = (
             queries.SpecificationImpactedSubstancesQuery()
             .with_specification_ids(self.spec_ids)
-            .with_legislations(self.legislation_ids)
+            .with_legislation_ids(self.legislation_ids)
         )
         response = connection_custom_db.run(query)
         assert len(response.impacted_substances) == 1
@@ -194,7 +196,7 @@ def test_legislation_is_not_affected_with_no_links(self, connection_custom_db):
         query = (
             queries.SpecificationImpactedSubstancesQuery()
             .with_specification_ids(self.spec_ids)
-            .with_legislations(self.legislation_ids)
+            .with_legislation_ids(self.legislation_ids)
         )
         response = connection_custom_db.run(query)
         assert len(response.impacted_substances) == 0

tests/test_mocked_responses/test_materials.py

@@ -10,7 +10,9 @@
 
 class TestImpactedSubstances(BaseMockTester):
     query = (
-        queries.MaterialImpactedSubstancesQuery().with_legislations(["Fake legislation"]).with_material_ids(["Fake ID"])
+        queries.MaterialImpactedSubstancesQuery()
+        .with_legislation_ids(["Fake legislation"])
+        .with_material_ids(["Fake ID"])
     )
     mock_key = GetImpactedSubstancesForMaterialsResponse.__name__
 

tests/test_mocked_responses/test_messages.py

@@ -26,7 +26,7 @@ def test_critical_error_raises_exception(self, mock_connection, caplog):
     def test_non_critical_error_printed_to_stdout(self, mock_connection, severity, caplog):
         self.query = (
             queries.MaterialImpactedSubstancesQuery()
-            .with_legislations(["Fake legislation"])
+            .with_legislation_ids(["Fake legislation"])
             .with_material_ids(["Fake ID"])
         )
         mock_key = GetImpactedSubstancesForMaterialsResponse.__name__
@@ -45,7 +45,7 @@ def test_non_critical_error_printed_to_stdout(self, mock_connection, severity, c
     def test_info(self, mock_connection, caplog):
         self.query = (
             queries.MaterialImpactedSubstancesQuery()
-            .with_legislations(["Fake legislation"])
+            .with_legislation_ids(["Fake legislation"])
             .with_material_ids(["Fake ID"])
         )
         mock_key = GetImpactedSubstancesForMaterialsResponse.__name__

tests/test_mocked_responses/test_parts.py

@@ -17,7 +17,7 @@
 class TestImpactedSubstances(BaseMockTester):
     query = (
         queries.PartImpactedSubstancesQuery()
-        .with_legislations(["Fake legislation"])
+        .with_legislation_ids(["Fake legislation"])
         .with_part_numbers(["Fake part number"])
     )
     mock_key = GetImpactedSubstancesForPartsResponse.__name__

tests/test_mocked_responses/test_specifications.py

@@ -17,7 +17,7 @@
 class TestImpactedSubstances(BaseMockTester):
     query = (
         queries.SpecificationImpactedSubstancesQuery()
-        .with_legislations(["Fake legislation"])
+        .with_legislation_ids(["Fake legislation"])
         .with_specification_ids(["Fake ID"])
     )
     mock_key = GetImpactedSubstancesForSpecificationsResponse.__name__

tests/test_query_builders/test_common_queries.py

@@ -166,7 +166,7 @@ def test_add_indicators_wrong_types_type_error(self, query_type):
 
     def test_add_legislations_attribute_error(self, query_type):
         with pytest.raises(AttributeError):
-            query_type().with_legislations(LEGISLATIONS)
+            query_type().with_legislation_ids(LEGISLATIONS)
 
 
 @pytest.mark.parametrize(
@@ -180,15 +180,15 @@ def test_add_legislations_attribute_error(self, query_type):
 )
 class TestSubstanceQueries:
     def test_add_legislations_correct_types(self, query_type):
-        query = query_type().with_legislations(LEGISLATIONS)
+        query = query_type().with_legislation_ids(LEGISLATIONS)
         assert len(query._legislations) == len(LEGISLATIONS)
         for idx, legislation in enumerate(LEGISLATIONS):
             assert query._legislations[idx] == legislation
 
     def test_add_legislations_wrong_types_type_error(self, query_type):
         with pytest.raises(TypeError):
-            query_type().with_legislations(INDICATORS)
-            query_type().with_legislations(legislations=INDICATORS)
+            query_type().with_legislation_ids(INDICATORS)
+            query_type().with_legislation_ids(legislations=INDICATORS)
 
     def test_add_indicators_attribute_error(self, query_type):
         with pytest.raises(AttributeError):