Discussion: using FreeCAD or App namespaces, which is prefered

Here's the place for discussion related to coding in FreeCAD, C++ or Python. Design, interfaces and structures.
vocx
Posts: 1425
Joined: Thu Oct 18, 2018 9:18 pm

Discussion: using FreeCAD or App namespaces, which is prefered

Postby vocx » Thu Sep 05, 2019 4:40 pm

I was a bit confused at the beginning when looking at Python examples why sometimes commands are in the FreeCAD namespace, and other times in the App namespace. They are the same. And the same thing happens with Gui functions.

Is there a definite answer to when to use one or the other?

Code: Select all

FreeCAD.Version()
App.Version()

FreeCAD.Vector()
App.Vector()

FreeCADGui.Selection.getSelectionEx()
Gui.Selection.getSelectionEx()
I've read several times about Werner mentioning the Branding of FreeCAD. Given that it is open source, under the LGPL2 license, it is entirely possible to repackage FreeCAD as another software. He has mentioned to not hard-code "FreeCAD" because this breaks the branding of possible derivatives.

In this case, I think it makes total sense to prefer the use of App and Gui namespaces to call commands. In this way, we indicate that we are calling base functions of the application but we don't indicate a particular brand. However, I don't think this is enforced. I personally tend to write everything in the FreeCAD and FreeCADGui namespaces, just because the code I started modifying uses that style. Should we be using App and Gui instead?
triplus
Posts: 8677
Joined: Mon Dec 12, 2011 4:45 pm

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby triplus » Thu Sep 05, 2019 5:11 pm

In any way, you won't be able to avoid importing of the FreeCAD/FreeCADGui modules, somewhere. At minimum for creating the aliases (App/Gui). If i remember correctly, on why the mentioned aliases work by default, in the FreeCAD Python console. It's because somebody added two import statements, taking care of that. When writing a FreeCAD module or macro, there i guess best to use import FreeCAD as App and use the alias after.
vocx
Posts: 1425
Joined: Thu Oct 18, 2018 9:18 pm

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby vocx » Thu Sep 05, 2019 5:16 pm

triplus wrote:
Thu Sep 05, 2019 5:11 pm
In any way, you won't be able to avoid importing of the FreeCAD/FreeCADGui modules, somewhere.
...
App seems to exist always. When I run FreeCADCmd, it is there.
triplus
Posts: 8677
Joined: Mon Dec 12, 2011 4:45 pm

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby triplus » Thu Sep 05, 2019 5:47 pm

Wherever it works by default, somebody has likely already created the alias. Now personally i likely won't be relying on that anytime soon, and hence on top of the code, there will be the mentioned two imports. After i will use aliases, due to being shorter.

P.S. But this i guess has little to do with branding. Things like console outputs, there likely FreeCAD name is used often. Should we care all that much? IMHO no.
vocx
Posts: 1425
Joined: Thu Oct 18, 2018 9:18 pm

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby vocx » Thu Sep 05, 2019 6:20 pm

triplus wrote:
Thu Sep 05, 2019 5:47 pm
Wherever it works by default, somebody has likely already created the alias.
As I said the "FreeCADCmd" executable already includes it, nobody has added it. It is added in the sources at least.

Code: Select all

vocx@VOCX-TP:/opt/freecad-build$ bin/FreeCADCmd
FreeCAD 0.19, Libs: 0.19R18037 (Git)
(c) Juergen Riegel, Werner Mayer, Yorik van Havre 2001-2019
  #####                 ####  ###   ####  
  #                    #      # #   #   # 
  #     ##  #### ####  #     #   #  #   # 
  ####  # # #  # #  #  #     #####  #   # 
  #     #   #### ####  #    #     # #   # 
  #     #   #    #     #    #     # #   #  ##  ##  ##
  #     #   #### ####   ### #     # ####   ##  ##  ##

[FreeCAD Console mode <Use Ctrl-D (i.e. EOF) to exit.>]
>>> App.Vector()
Vector (0.0, 0.0, 0.0)
>>> 
P.S. But this i guess has little to do with branding.
...
The issue is with writing documentation. In the documentation, you can specifically refer to certain functions like "FreeCAD.Vector" or "App.Vector" and they will work the same.

The FreeCAD interface itself uses these aliases

Code: Select all

>>> Gui.runCommand('Std_ViewStatusBar',1)
>>> Gui.runCommand('Std_ViewStatusBar',0)
>>> Gui.runCommand('Std_Workbench',19)
>>> ### Begin command Std_New
>>> App.newDocument("Unnamed")
>>> App.setActiveDocument("Unnamed")
>>> App.ActiveDocument=App.getDocument("Unnamed")
>>> Gui.ActiveDocument=Gui.getDocument("Unnamed")
>>> Gui.activeDocument().activeView().viewDefaultOrientation()
>>> ### End command Std_New
>>> Gui.runCommand('Std_OrthographicCamera',1)
Somebody who is learning FreeCAD won't know about this, they will see the code reported by FreeCAD, and will just copy it to write their own scripts. So instead of using the FreeCAD namespace sometimes, and App other times, we should be consistent. The wiki has quite old programming documentation, maybe written by Jürgen himself, and a lot of that tends to use App, but without much explanation that it is interchangeable with FreeCAD. This is why I think it's a matter of branding. Basically, he wrote the documentation thinking that this could be used in any FreeCAD-based program, not necessarily the plain FreeCAD.
ezzieyguywuf
Posts: 542
Joined: Tue May 19, 2015 1:11 am

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby ezzieyguywuf » Thu Sep 05, 2019 6:29 pm

vocx wrote:
Thu Sep 05, 2019 6:20 pm
App seems to exist always. When I run FreeCADCmd, it is there.
It does. It is defined in FreeCADInit.py, and in fact it is simply:

Code: Select all

# some often used shortcuts (for lazy people like me  ;-)
App = FreeCAD
Log = FreeCAD.Console.PrintLog
Msg = FreeCAD.Console.PrintMessage
Err = FreeCAD.Console.PrintError
Wrn = FreeCAD.Console.PrintWarning
vocx
Posts: 1425
Joined: Thu Oct 18, 2018 9:18 pm

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby vocx » Thu Sep 05, 2019 6:51 pm

ezzieyguywuf wrote:
Thu Sep 05, 2019 6:29 pm

Code: Select all

# some often used shortcuts (for lazy people like me  ;-)
App = FreeCAD
Log = FreeCAD.Console.PrintLog
Msg = FreeCAD.Console.PrintMessage
Err = FreeCAD.Console.PrintError
Wrn = FreeCAD.Console.PrintWarning
So, should we all be lazy and use those shortcuts or not?

My issue is that the interface produces code with those shortcuts, so the program is telling you, "it's okay, use these short aliases".
ezzieyguywuf
Posts: 542
Joined: Tue May 19, 2015 1:11 am

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby ezzieyguywuf » Thu Sep 05, 2019 6:55 pm

vocx wrote:
Thu Sep 05, 2019 6:51 pm
So, should we all be lazy and use those shortcuts or not?
Great question.

I don't know that there's anything in the FreeCAD codebase that guarantees that these aliases will always be around.

That being said, as you point out the FreeCAD code itself generates python code which uses the aliases.

*shrug* As for me, I prefer to be as explicit as possible in my coding. Therefore, I prefer to use the FreeCAD namespace directly.

Then you consider projects such as numpy, or pandas, in which:

Code: Select all

import numpy as np
import pandas as pd
are practically universal standards.

Perhaps that is a good middle ground? If you wish to use the alias, then define it explicitly in your code:

Code: Select all

import FreeCAD as App
Yes, I think that seems like very sound coding practices. Of course, this is only my opinion...

Edit:

In fact, it seems to me that the FreeCAD code which generates the python code that you see in the python console should also explicitly define these aliases. This way, it makes it very clear what they are and where they come from.
vocx
Posts: 1425
Joined: Thu Oct 18, 2018 9:18 pm

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby vocx » Thu Sep 05, 2019 7:04 pm

ezzieyguywuf wrote:
Thu Sep 05, 2019 6:55 pm
...
Then you consider projects such as numpy, or pandas, in which:

Code: Select all

import numpy as np
import pandas as pd
are practically universal standards.
Correct. And in those cases the documentation outright tells you "this is the recommended way of importing numpy", and then you follow their advice.

As far as I can tell, there is nowhere in FreeCAD that tells you to use App. It just so happens to be defined here and there, and some documents (and programs) use it and some others do not.
Perhaps that is a good middle ground? If you wish to use the alias, then define it explicitly in your code:

Code: Select all

import FreeCAD as App
I agree.
In fact, it seems to me that the FreeCAD code which generates the python code that you see in the python console should also explicitly define these aliases. This way, it makes it very clear what they are and where they come from.
Also agree.
User avatar
bernd
Posts: 8332
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland

Re: Discussion: using FreeCAD or App namespaces, which is prefered

Postby bernd » Thu Sep 05, 2019 9:07 pm

good question. In FEM nearly 100 % of the code uses FreeCAD or FreeCADGui. Why? Just because I did not know about the App and FreeCAD when I started coding years ago. I just used FreeCAD. After a few month I knew the difference but did not want to have two standards in FEM, so I just continued for 5 years to use FreeCAD. This is how it is today ...

But never mind. In this question I would go in the future just for the one which is recommended.