Merge branch 'developement'

.gitignore

@@ -135,6 +135,7 @@ quick_n_dirty.py
 *.CATDrawing
 *.CATPart
 *.CATProduct
+*.CATMaterial
 
 pycatia-exe.build
 pycatia-exe.dist

CHANGELOG.md

@@ -1,7 +1,16 @@
 # Changelog
 
 ## 0.7.1
+
 * fixed Documents.read() method which was broken by changes made in 0.6.9.
+* updated Documents.open() so that filename should now be a Path object.
+* updated Documents.new_from() so that filename should now be a Path object.
+* updated Documents.open() so that filename should now be a Path object.
+* updated the examples so they use explicit path objects.
+* updated the examples to show how to better initialise documents.
+* updated the user_scripts to show how to better initialise documents.
+* updated the introdutcion document to show how to get the PartDocument.
+
 
 ## 0.7.0
 * fixed the following Class methods so that the Reference.com_object is passed to 

docs/introduction.rst

@@ -19,6 +19,7 @@ You will almost always want to import the `catia`
 .. code-block:: python
 
     from pycatia import catia
+    from pycatia.mec_mod_interfaces.part_document import PartDocument
     # initialise the catia automation appliction. CATIA V5 should already be running.
     caa = catia()
     documents = caa.documents
@@ -28,27 +29,20 @@ class.
 
 .. code-block:: python
 
-    documents.add('Part')
+    part_document: PartDocument = documents.add('Part')
 
 the add method of the documents class expects the string 'Part', 'Product' or
 'Drawing'. ``documents.add('Part')`` adds a new CATPart to the documents
-collection.
-
-We want to work on this new document. Since this has just been added it's the
-active document.
-
-.. code-block:: python
-
-    document = caa.active_document
+collection and returns a `Document`` object. In this case it is a `PartDocument`.
 
 The document object :ref:`Document<Document>` has a
 number of properties that can be accessed.
 
 .. code-block:: python
 
-    document.name
+    part_document.name
     # returns the name of the new document.
-    document.path
+    part_document.path
     # returns the pathlib.Path object of the document.
 
 
@@ -61,7 +55,7 @@ create one here anyway.
 
 .. code-block:: python
 
-    part = document.part()
+    part = part_document.part
     hybrid_bodies = part.hybrid_bodies
     new_set = hybrid_bodies.add()
     new_set.name
@@ -71,7 +65,6 @@ create one here anyway.
 
 
 
-
 For more detailed examples on how to interact with pycatia see the
 :ref:`examples` page. There contain several scripts that can be run in the
 terminal.

examples/example__assembly_convertor__001.py

@@ -33,21 +33,14 @@
 
 from pycatia import catia
 from pycatia.product_structure_interfaces.assembly_convertor import AssemblyConvertor
-from pycatia.product_structure_interfaces.product import Product
 from pycatia.product_structure_interfaces.product_document import ProductDocument
 
 # file_type can be "TXT", "HTML" or "XLS".
 file_type = "XLS"
 
 caa = catia()
-document = ProductDocument(caa.active_document.com_object)
-product = Product(document.product.com_object)
-# Note: It's not necessary to explicitly use the ProductDocument or the Product class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   product = document.product
-# But declaring 'document' and 'product' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
+product_document = ProductDocument(caa.active_document.com_object)
+product = product_document.product
 
 bom = product.get_item("BillOfMaterial")
 assembly_convertor = AssemblyConvertor(bom.com_object)

examples/example__bom_custom_001.py

@@ -25,19 +25,12 @@
 from datetime import datetime
 
 from pycatia import catia
-from pycatia.product_structure_interfaces.product import Product
 from pycatia.product_structure_interfaces.product_document import ProductDocument
 
 caa = catia()
-document = ProductDocument(caa.active_document.com_object).product
-product = Product(document.com_object)
+product_document: ProductDocument = caa.active_document
+product = product_document.product
 products = product.products
-# Note: It's not necessary to explicitly use the ProductDocument or the Product class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   product = document.product
-# But declaring 'document' and 'product' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
 
 part_numbers = []
 prd_dict = {}

examples/example__constraints_001.py

@@ -24,18 +24,12 @@
 
 from pycatia import catia
 from pycatia.enumeration.enumeration_types import cat_constraint_type
-from pycatia.product_structure_interfaces.product import Product
 from pycatia.product_structure_interfaces.product_document import ProductDocument
 
 caa = catia()
-document = ProductDocument(caa.active_document.com_object).product
-product = Product(document.com_object)
-# Note: It's not necessary to explicitly use the ProductDocument or the Product class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   product = document.product
-# But declaring 'document' and 'product' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
+# if the active document is a CATProduct this will return a ProductDocument
+product_document: ProductDocument = caa.active_document
+product = product_document.product
 
 products = product.products
 constraints = product.constraints()

examples/example__document__001.py

@@ -21,12 +21,12 @@
 
 sys.path.insert(0, os.path.abspath("..\\pycatia"))
 ##########################################################
-
+from pathlib import Path
 import time
 
 from pycatia import CATIADocHandler
 
-catia_part = r"tests\cat_files\part_measurable.CATPart"
+catia_part = Path(os.getcwd(), r"tests\cat_files\part_measurable.CATPart")
 
 with CATIADocHandler(catia_part) as caa:
     document = caa.document

examples/example__document__003.py

@@ -26,27 +26,26 @@
 from pathlib import Path
 
 from pycatia import catia
-from pycatia.in_interfaces.document import Document
+from pycatia.mec_mod_interfaces.part_document import PartDocument
 
 # path to file to open.
-file_name = r"tests\cat_files\part_measurable.CATPart"
+file_name = Path(os.getcwd(), r"tests\cat_files\part_measurable.CATPart")
 
 caa = catia()
 # open document
 documents = caa.documents
-documents.open(file_name)
+part_document: PartDocument = documents.open(file_name)
 
-document = caa.active_document
-assert isinstance(document, Document)
+assert isinstance(part_document, PartDocument)
 
 # _Full_ path of new file. This uses current working directory.
 new_file_name = Path(os.getcwd(), "new_part.CATPart")
 # save document as new name.
-document.save_as(new_file_name, overwrite=True)
+part_document.save_as(new_file_name, overwrite=True)
 
 # to export to another support file_format (license permitting).
 new_export_file_name = Path("c:\\temp\\new_export_part.stp")
-document.export_data(new_export_file_name, "stp", overwrite=True)
+part_document.export_data(new_export_file_name, "stp", overwrite=True)
 
 # close document
-document.close()
+part_document.close()

examples/example__drafting__001.py

@@ -36,14 +36,9 @@
 a0_y = 841
 
 caa = catia()
-document = DrawingDocument(caa.active_document.com_object)
-drawing = DrawingRoot(document.drawing_root.com_object)
-# Note: It's not necessary to explicitly use the DrawingDocument or the DrawingRoot class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   drawing = document.drawing_root
-# But declaring 'document' and 'drawing_root' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
+# if the active document is a CATDrawing this will return a DrawingDocument
+drawing_document: DrawingDocument = caa.active_document
+drawing = DrawingRoot(drawing_document.drawing_root.com_object)
 
 sheets = drawing.sheets
 sheet = sheets.active_sheet

examples/example__human_modelling__001.py

@@ -22,20 +22,13 @@
 from pycatia import catia
 from pycatia.enumeration.enumeration_types import swk_anthro_sex
 from pycatia.enumeration.enumeration_types import swk_posture_spec
-from pycatia.product_structure_interfaces.product import Product
 from pycatia.product_structure_interfaces.product_document import ProductDocument
 from pycatia.dnb_human_modeling_interfaces.swk_hmi_workbench import SWKHmiWorkbench
 
 caa = catia()
-document = ProductDocument(caa.active_document.com_object)
-product = Product(document.product.com_object)
-# Note: It's not necessary to explicitly use the ProductDocument or the Product class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   product = document.product
-# But declaring 'document' and 'product' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
-
+# if the active document is a CATProduct this will return a ProductDocument
+product_document: ProductDocument = caa.active_document
+product = product_document.product
 
 human_work_bench = SWKHmiWorkbench(product.get_technological_object("HumanWorkbench"))
 gender = swk_anthro_sex.index("Female")

examples/example__hybrid_bodies__001.py

@@ -29,19 +29,13 @@
 
 from pycatia import catia
 from pycatia.mec_mod_interfaces.body import Body
-from pycatia.mec_mod_interfaces.part import Part
 from pycatia.mec_mod_interfaces.part_document import PartDocument
 
 caa = catia()
-document = PartDocument(caa.active_document.com_object)
-part = Part(document.part.com_object)
+# if the active document is a CATPart this will return a PartDocument
+part_document: PartDocument = caa.active_document
+part = part_document.part
 bodies = part.bodies
-# Note: It's not necessary to explicitly use the PartDocument or the Part class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   part = document.part
-# But declaring 'document' and 'part' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
 
 # Warning: if you have several bodies with the same name the first will always be chosen.
 body_cube_1_item = bodies.get_item_by_name("Body.Cube.1")

examples/example__hybrid_shape_factory__001.py

@@ -27,19 +27,13 @@
 
 from pycatia import catia
 from pycatia.in_interfaces.reference import Reference
-from pycatia.mec_mod_interfaces.part import Part
 from pycatia.mec_mod_interfaces.part_document import PartDocument
 
 caa = catia()
-document = PartDocument(caa.active_document.com_object)
-part = Part(document.part.com_object)
+# if the active document is a CATPart this will return a PartDocument
+part_document: PartDocument = caa.active_document
+part = part_document.part
 bodies = part.bodies
-# Note: It's not necessary to explicitly use the PartDocument or the Part class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   part = document.part
-# But declaring 'document' and 'part' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
 
 # initialise the hybrid shape factory. this is used to determine the shape type later.
 hsf = part.hybrid_shape_factory

examples/example__hybrid_shape_factory__002.py

@@ -24,7 +24,6 @@
 ##########################################################
 
 from pycatia import catia
-from pycatia.mec_mod_interfaces.part import Part
 from pycatia.mec_mod_interfaces.part_document import PartDocument
 from pycatia.scripts.csv_tools import create_points
 
@@ -36,16 +35,8 @@
 
 documents = caa.documents
 # create a new part.
-documents.add("Part")
-
-document = PartDocument(caa.active_document.com_object)
-part = Part(document.part.com_object)
-# Note: It's not necessary to explicitly use the PartDocument or the Part class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   part = document.part
-# But declaring 'document' and 'part' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
+part_document: PartDocument = documents.add("Part")
+part = part_document.part
 
 # full path name to csv file.
 file = r"tests\Sample_Point_CSV_File1_small.csv"

examples/example__hybrid_shape_factory__003.py

@@ -23,20 +23,12 @@
 
 from pycatia import catia
 from pycatia.in_interfaces.reference import Reference
-from pycatia.mec_mod_interfaces.part import Part
 from pycatia.mec_mod_interfaces.part_document import PartDocument
 
 caa = catia()
 documents = caa.documents
-documents.add("Part")
-document = PartDocument(caa.active_document.com_object)
-part = Part(document.part.com_object)
-# Note: It's not necessary to explicitly use the PartDocument or the Part class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   part = document.part
-# But declaring 'document' and 'part' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
+part_document: PartDocument = documents.add("Part")
+part = part_document.part
 
 hybrid_bodies = part.hybrid_bodies
 hsf = part.hybrid_shape_factory

examples/example__hybrid_shape_factory__004.py

@@ -32,18 +32,12 @@
 from pycatia.hybrid_shape_interfaces.hybrid_shape_point_coord import (
     HybridShapePointCoord,
 )
-from pycatia.mec_mod_interfaces.part import Part
 from pycatia.mec_mod_interfaces.part_document import PartDocument
 
 caa = catia()
-document = PartDocument(caa.active_document.com_object)
-part = Part(document.part.com_object)
-# Note: It's not necessary to explicitly use the PartDocument or the Part class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   part = document.part
-# But declaring 'document' and 'part' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
+# if the active document is a CATPart this will return a PartDocument
+part_document: PartDocument = caa.active_document
+part = part_document.part
 
 hbs = part.hybrid_bodies
 hb_construction_lines = hbs.item("construction_geometry")
@@ -53,11 +47,11 @@
     hs = hss.item(shape_index)
 
     # clear the selection on each loop.
-    document.selection.clear()
+    part_document.selection.clear()
     # add the shape to the selection.
-    document.selection.add(hs)
+    part_document.selection.add(hs)
     # create the selected element by getting the first item in the document selection.
-    selected_elem = document.selection.item(1)
+    selected_elem = part_document.selection.item(1)
 
     # test part only has HybridShapeLinePtPt
     if selected_elem.type == "HybridShapeLinePtPt":

examples/example__hybrid_shape_factory__005.py

@@ -23,19 +23,13 @@
 ##########################################################
 
 from pycatia import catia
-from pycatia.mec_mod_interfaces.part import Part
 from pycatia.mec_mod_interfaces.part_document import PartDocument
 
 caa = catia()
-document = PartDocument(caa.active_document.com_object)
-part = Part(document.part.com_object)
+# if the active document is a CATPart this will return a PartDocument
+part_document: PartDocument = caa.active_document
+part = part_document.part
 bodies = part.bodies
-# Note: It's not necessary to explicitly use the PartDocument or the Part class
-# with the com_object. It's perfectly fine to write it like this:
-#   document = caa.active_document
-#   part = document.part
-# But declaring 'document' and 'part' this way, your linter can't resolve the
-# product reference, see https://github.com/evereux/pycatia/issues/107#issuecomment-1336195688
 
 hsf = part.hybrid_shape_factory
 hbs = part.hybrid_bodies