autocompleate in IDE for Python API

Programmers discuss here anything related to FreeOrion programming. Primarily for the developers to discuss.

Moderator: Committer

Message
Author
User avatar
Cjkjvfnby
AI Contributor
Posts: 539
Joined: Tue Jun 24, 2014 9:55 pm

autocompleate in IDE for Python API

#1 Post by Cjkjvfnby »

I make files to have autocompleate in IDE.

To turn it on you just need to put it to project path (my IDE add projcet path to python paths).

It is not final form. (it is larva for docs to replace current http://www.freeorion.org/index.php/AI_Python_API)

To have good documented API I need docstrings. (Now there is autogenerated by boost)

Things that looks strange for me (from python side):

1) Objects like IntSetSet can be represented by common immutable collections, no need to have special object.
2) Enums (class that has its instance as attribute, it looks wired)
3) class attribute of partType (it is keyword in python)

upd. new links
Universe generation: https://raw.githubusercontent.com/Cjkjv ... eeorion.py

AI : https://raw.githubusercontent.com/Cjkjv ... terface.py
Attachments
freeOrionAIInterface.txt
(114.64 KiB) Downloaded 147 times
Last edited by Cjkjvfnby on Mon Apr 06, 2015 10:55 pm, edited 1 time in total.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Geoff the Medio
Programming, Design, Admin
Posts: 13587
Joined: Wed Oct 08, 2003 1:33 am
Location: Munich

Re: autocompleate in IDE for Python API

#2 Post by Geoff the Medio »

Cjkjvfnby wrote:1) Objects like IntSetSet can be represented by common immutable collections, no need to have special object.
It's a C++ container, though... Exposing it to Python otherwise would require some special coding to process the std::set<std::set<int> > and fill a python container with sets of integers.

Why is this one specifically unusual, but all the other C++ containers exposed to Python as non-native container types not weird?
3) class attribute of partType (it is keyword in python)
Could be renamed without difficulty in the interface.

Code: Select all

Index: FreeOrion/python/PythonUniverseWrapper.cpp
===================================================================
--- FreeOrion/python/PythonUniverseWrapper.cpp	(revision 7379)
+++ FreeOrion/python/PythonUniverseWrapper.cpp	(working copy)
@@ -483,7 +483,7 @@
 
         class_<PartType, noncopyable>("partType", no_init)
             .add_property("name",               make_function(&PartType::Name,              return_value_policy<copy_const_reference>()))
-            .add_property("class",              &PartType::Class)
+            .add_property("partClass",          &PartType::Class)
             .def("productionCost",              &PartType::ProductionCost)
             .def("productionTime",              &PartType::ProductionTime)
             .def("canMountInSlotType",          &PartType::CanMountInSlotType)

User avatar
Cjkjvfnby
AI Contributor
Posts: 539
Joined: Tue Jun 24, 2014 9:55 pm

Re: autocompleate in IDE for Python API

#3 Post by Cjkjvfnby »

Code: Select all

Why is this one specifically unusual, but all the other C++ containers exposed to Python as non-native container types not weird?
Containers are not weired, it just bad practice in Python to use class instead of built-in collections.
Enums looks weired for me, to make python object that works in same way, I need to do extra work after declaration.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Geoff the Medio
Programming, Design, Admin
Posts: 13587
Joined: Wed Oct 08, 2003 1:33 am
Location: Munich

Re: autocompleate in IDE for Python API

#4 Post by Geoff the Medio »

Cjkjvfnby wrote:

Code: Select all

Why is this one specifically unusual, but all the other C++ containers exposed to Python as non-native container types not weird?
Containers are not weired, it just bad practice in Python to use class instead of built-in collections.
You didn't answer the question: why is that one specifically noted?

Also, as I said above, this is exposing a C++ container to Python (as a class), not creating a native Python container. It doesn't behave like a Python container, and is treated as a class, because it is a C++ class.
Enums looks weired for me, to make python object that works in same way, I need to do extra work after declaration.
If you want to write some C++ to run some Python code to set up a more palatable Python representation of the C++ enums, feel free...

User avatar
Cjkjvfnby
AI Contributor
Posts: 539
Joined: Tue Jun 24, 2014 9:55 pm

Re: autocompleate in IDE for Python API

#5 Post by Cjkjvfnby »

Geoff the Medio wrote:You didn't answer the question: why is that one specifically noted?
It is about "Objects like IntSetSet" ?
Also, as I said above, this is exposing a C++ container to Python (as a class), not creating a native Python container. It doesn't behave like a Python container, and is treated as a class, because it is a C++ class.

If it looks like a duck, swims like a duck, and quacks like a duck, then it probably is a duck. Some(or All) of this classes used in same way as builtin python collections. From C++ side it simplify code, form python side it is additional complexity.

My suggestion to avoid creating and using such classes in future. (Keep Python API simple as possible)

There is a lot of API aspects that I did not like, but first I want to finish with grooming and refactoring.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Geoff the Medio
Programming, Design, Admin
Posts: 13587
Joined: Wed Oct 08, 2003 1:33 am
Location: Munich

Re: autocompleate in IDE for Python API

#6 Post by Geoff the Medio »

Cjkjvfnby wrote:
Geoff the Medio wrote:You didn't answer the question: why is that one specifically noted?
It is about "Objects like IntSetSet" ?
Yes. What other objects are problematic, which aren't, why is IntSetSet notable?
From C++ side it simplify code, form python side it is additional complexity.
I suspect the Python complexity to reprocess the C++ class information into native Python containers is substantially less than it would be to generate such containers within (sort of) C++ code to return for Python API calls.
My suggestion to avoid creating and using such classes in future. (Keep Python API simple as possible)
Most of these classes already exist in the C++ data structures. They're just being exposed to Python to access. A few might be created to simplify the API that is presented, but not in most cases. There's no way to avoid creating C++ classes while writing sensible C++, especially for containers such as this.

If you don't like the API that the C++ code provides, I suggest writing a wrapper that preprocesses whatever the C++ gives, and turns it into whatever native Python data structures you'd prefer to work with. Instead of "import freeOrionAIInterface as fo" you'd do "import freeOrionAPIWrapper as fo" and then use whatever functions it provides.

User avatar
adrian_broher
Programmer
Posts: 1156
Joined: Fri Mar 01, 2013 9:52 am
Location: Germany

Re: autocompleate in IDE for Python API

#7 Post by adrian_broher »

Write something up with the boost python wrappers and fix the api as you would suggest.

http://www.boost.org/doc/libs/1_55_0/li ... ppers.html
Resident code gremlin
Attached patches are released under GPL 2.0 or later.
Git author: Marcel Metz

User avatar
Dilvish
AI Lead and Programmer Emeritus
Posts: 4768
Joined: Sat Sep 22, 2012 6:25 pm

Re: autocompleate in IDE for Python API

#8 Post by Dilvish »

The current state of the interface is an intermediate affair that balances complexity between the C++ side and the python side, where generally the simplest boost handling that makes things 'reasonably' available to the python side has been selected, very often relying on the boost indexing suites. In some cases (generally where the C++ side needs a newly created object from the python side) some extra C++ wrapping has been done so the python side can deal with pure python objects, such as with IssueCreateShipDesignOrderWrapper() of PythonAI.cpp and UpdateMetersWrapper() of PythonUniverseWrapper.py; in other cases the C++ side reprocesses things to make things easier on the python side, but doesn't go all the way to a native python object, such as in SystemNeighborsMapP of PythonUniverseWrapper.py

Since the whole point of using python was to make some coding content more readily user-customizable, I think it is appropriate that the long term goal be for the greatest reasonable amount of container complexity to be put on the C++ side of the interface; i.e., using more of these wrappers so that the python side doesn't just receive python-list-like objects and python-set-like objects, but actually receives python lists and python sets, or tuples and frozensets if not meant to be modifiable. UniverseObject classes such as ships, etc., probably need to continue to be exposed much as they are now.

That said, I think the current state is pretty reasonable for now -- I'm certainly not in the mood to put my current time into adding a bunch of wrappers to the C++ side of the interface. If someone else wants to do it, sure, fine.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Cjkjvfnby
AI Contributor
Posts: 539
Joined: Tue Jun 24, 2014 9:55 pm

Re: autocompleate in IDE for Python API

#9 Post by Cjkjvfnby »

Dilvish wrote: I think it is appropriate that the long term goal be for the greatest reasonable amount of container complexity to be put on the C++ side of the interface;
I agree.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Cjkjvfnby
AI Contributor
Posts: 539
Joined: Tue Jun 24, 2014 9:55 pm

Re: autocompleate in IDE for Python API

#10 Post by Cjkjvfnby »

Cjkjvfnby wrote:I make file freeOrionAIInterface.py to have autocompleate in IDE.
Does any one use it?
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Dilvish
AI Lead and Programmer Emeritus
Posts: 4768
Joined: Sat Sep 22, 2012 6:25 pm

Re: autocompleate in IDE for Python API

#11 Post by Dilvish »

It seems like a good idea, but I've been too busy to try fiddling with that just yet. I do plan to, perhaps this coming week. Recently my FO time has been mostly focused on taking care of things for 0.4.4. RC1 which Vezzra will be building in a matter of hours.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Cjkjvfnby
AI Contributor
Posts: 539
Joined: Tue Jun 24, 2014 9:55 pm

Re: autocompleate in IDE for Python API

#12 Post by Cjkjvfnby »

I update stub it is on same link:
- show inheritance
- add return stub for methods
- add return stub for properties for some classes
- exclude autogenerated classes (map_indexing_suite_*)


May be you know if it is possible to force boost to show argument names?

current doc is:

Code: Select all

>>>print u.getVisibilityTurnsMap.__doc__
getVisibilityTurnsMap( (universe)arg1, (int)arg2, (int)arg3) -> VisibilityIntMap :
C++ signature :
   class std::map<enum Visibility,int,struct std::less<enum Visibility>,class std::allocator<struct std::pair<enum Visibility const ,int> > > getVisibilityTurnsMap(class Universe {lvalue},int,int)
and I want names from c++ code :

Code: Select all

getVisibilityTurnsMap( (universe)universe, (int)object_id, (int)empire_id) -> VisibilityIntMap
Auto complete shows variables names, but this names is not helpful.
(I rename args to name related with type: (int)arg2 -> number1)
https://gist.github.com/Cjkjvfnby/0ec2f ... e-py-L2330
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Dilvish
AI Lead and Programmer Emeritus
Posts: 4768
Joined: Sat Sep 22, 2012 6:25 pm

Re: autocompleate in IDE for Python API

#13 Post by Dilvish »

Cjkjvfnby wrote:May be you know if it is possible to force boost to show argument names?
No, I have no idea about that.

Code: Select all

and I want names from c++ code
I can understand that getting this automatically would be the handiest, but I expect manual is all we'll have. It looks like you have a handle on figuring them out, but here's some tips that might possibly be helpful: The first point to check will be the interfaces specified in the /python folder and also in the /AI folder (the top level one, not default/AI). In many cases they will simply specify the function being exposed without showing the full signature directly, but if you get yourself an IDE suitable for C++ then it should make it very easy for you to see the signatures-- probably worthwhile even if you are not going to try programming in C++. I think you mentioned using Eclipse, it should be able to handle C++ ok.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Geoff the Medio
Programming, Design, Admin
Posts: 13587
Joined: Wed Oct 08, 2003 1:33 am
Location: Munich

Re: autocompleate in IDE for Python API

#14 Post by Geoff the Medio »

You can specify a docstring when exposing a C++ function to Python (which is done using the def(...) function). For example, this compiles for me in PythonUniverseWrapper.cpp:

Code: Select all

            .def("getVisibilityTurnsMap",       make_function(
                                                    &Universe::GetObjectVisibilityTurnMapByEmpire,
                                                    return_value_policy<return_by_value>()
                                                ),
                 "docstring for this function")
I don't know where / how the docstring would be shown / used in Python, but it might be useful?

User avatar
em3
Vacuum Dragon
Posts: 630
Joined: Sun Sep 25, 2011 2:51 pm

Re: autocompleate in IDE for Python API

#15 Post by em3 »

https://github.com/mmoderau
[...] for Man has earned his right to hold this planet against all comers, by virtue of occasionally producing someone totally batshit insane. - Randall Munroe, title text to xkcd #556

Post Reply