From d60358443ebf84fc289ca4daa8d61a115641d532 Mon Sep 17 00:00:00 2001
From: tritao <joao@tritao.eu>
Date: Wed, 5 Feb 2025 00:17:59 +0000
Subject: [PATCH] App: Improve `Document.copyObject` Python API.

This updates the `Document.copyObject` Python API by allowing for
keyword arguments and aligning the documentation with the C++ API.

This can make the Python code more readable, by using the keywords form:

```python
document.copyObject(obj, recursive=True, return_all=False)
```

Previous keyword-less version tested and still working for backwards
compatibility.
---
 src/App/DocumentPy.xml    |  8 ++++----
 src/App/DocumentPyImp.cpp | 17 ++++++++++++++---
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/src/App/DocumentPy.xml b/src/App/DocumentPy.xml
index 55fcc7ef13..798994b3c8 100644
--- a/src/App/DocumentPy.xml
+++ b/src/App/DocumentPy.xml
@@ -136,15 +136,15 @@ viewType (String): override the view provider type directly, only effective when
         <UserDocu>Remove an object from the document</UserDocu>
       </Documentation>
     </Methode>
-    <Methode Name="copyObject">
+    <Methode Name="copyObject" Keyword="true">
       <Documentation>
           <UserDocu>
-copyObject(object, with_dependencies=False, return_all=False)
+copyObject(object, recursive=False, return_all=False)
 Copy an object or objects from another document to this document.
 
 object: can either a single object or sequence of objects
-with_dependencies: if True, all internal dependent objects are copied too.
-return_all: if True, return all copied objects, or else return only the copied
+recursive: if True, also recursively copies internal objects.
+return_all: if True, returns all copied objects, or else return only the copied
             object corresponding to the input objects.
           </UserDocu>
       </Documentation>
diff --git a/src/App/DocumentPyImp.cpp b/src/App/DocumentPyImp.cpp
index 22918cd8a5..1c7d8a03fe 100644
--- a/src/App/DocumentPyImp.cpp
+++ b/src/App/DocumentPyImp.cpp
@@ -426,10 +426,21 @@ PyObject* DocumentPy::removeObject(PyObject* args)
     }
 }
 
-PyObject* DocumentPy::copyObject(PyObject* args)
+PyObject* DocumentPy::copyObject(PyObject* args, PyObject* kwd)
 {
-    PyObject *obj, *rec = Py_False, *retAll = Py_False;
-    if (!PyArg_ParseTuple(args, "O|O!O!", &obj, &PyBool_Type, &rec, &PyBool_Type, &retAll)) {
+    PyObject* obj;
+    PyObject* rec = Py_False;
+    PyObject* retAll = Py_False;
+    static constexpr std::array<const char*, 4> kwlist {"object", "recursive", "return_all", nullptr};
+    if (!Base::Wrapped_ParseTupleAndKeywords(args,
+                                             kwd,
+                                             "O|O!O!",
+                                             kwlist,
+                                             &obj,
+                                             &PyBool_Type,
+                                             &rec,
+                                             &PyBool_Type,
+                                             &retAll)) {
         return nullptr;
     }