idea A complete ArcGIS for Python API Reference in ArcGIS API for Python Ideas

A complete ArcGIS for Python API Reference

Thomas_Z1 — Thu, 13 May 2021 00:37:31 GMT

Please complete the API Reference with function's output descriptions.

Bad examples

FeatureLayer.edit_features:
https://developers.arcgis.com/python/api-reference/arcgis.features.toc.html#arcgis.features.FeatureLayer.edit_features

Output: dictionary

FeatureLayer.delete_features:
https://developers.arcgis.com/python/api-reference/arcgis.features.toc.html#arcgis.features.FeatureLayer.delete_features

Dict if future=False (default), else a concurrent.Future class.

This one-line documentation is not helpful.

I know this idea is not a feature but it would help extremely to have a more complete API reference.

By adding more information to the documentation, questions like this could be avoided: https://community.esri.com/t5/arcgis-api-for-python-questions/how-can-i-test-if-there-was-a-rollback/m-p/1057433

Re: A complete ArcGIS for Python API Reference

jcarlson — Thu, 13 May 2021 02:18:09 GMT

You should check out the GitHub repo. I've commented there before on documentation I thought was lacking, and it was addressed promptly.

Re: A complete ArcGIS for Python API Reference

Anonymous User — Mon, 20 Jun 2022 22:41:46 GMT

Hi @Thomas_Z1 - thanks for the feedback. Disappointed to hear that particular documentation is not helpful, sorry it is not up to par. As @jcarlson mentioned above - logging an issue in the arcgis-python-api repo will help us track your comments and link your comments to any changes we may make.

We've updated the documentation hosting system with the more recent release on June 3rd. The API Reference for the 2.0.1 release has a new look in addition to updated comment.

In general, our goal for return statement documentation is to state concisely what type the returned value is. When the value is an instance of a class within the API, we hyperlink to that class documentation so you can click it and directly see the properties and methods that will exist on that return value object (depending upon the input arguments). We know some links are missing, and we're working to make sure those hyperlinks are consistent across the API reference.

Code snippets are how we aim to augment the return statement with examples of what specific returns will look like. We try to provide a few examples of different parameter-argument combinations so we can show variations in output based upon those arguments.

For edit_features at 2.0.1, we added code snippets to demonstrate the formatting for updates, adds, and deletes arguments. We can add the output to those code snippets for the next release to hopefully provide further clarification. What would make this more complete? The return value may be a dictionary - would an example of what that dictionary looks like help? The return value may be an instance of the EditFeatureJob if run asynchronously, so we link to that class documentation within the return statement. Do these changes we made between 2.0.0 and 2.0.1 make the doc more complete?

The delete_features api reference contains a code snippet of what the dictionary looks like when the future argument is False. How could we best make the return statement doc more complete? An example where the future argument is True?

Thank you again for the feedback.

Re: A complete ArcGIS for Python API Reference

KimOllivier — Wed, 05 Oct 2022 05:14:09 GMT

I have been starting to use the Python API and I have found it very difficult to understand the functions.

The samples are just 'showoff' examples of why you would use GIS, not how to debug the tools. I find that the arcpy documentation is much more helpful because there are example snippets on every function right in the help, not somewhere in a sample. The edit tools have 16 samples for the whole module. Most of the functions and parameters are not covered with an example anywhere. I cannot find a working example of extract_changes(). I note in the community noticeboard that there was a bug in 2020 where 'optional' parameter for the URI were actually required. Has this changed? Let's see something working so I can backtrack to see why my environment is different.

I thought the python Open API on Github would have the source for arcgis! Some hope there, it only has a smattering of examples that give a once over lightly of each module. My initial thought was that since there was a missing function where I was porting an arcpy script I would add one myself - open source, published... (I can see a child table separately from the parent table in the GUI, so why not in the API?)

Re: A complete ArcGIS for Python API Reference

Clubdebambos — Tue, 18 Feb 2025 11:52:56 GMT

We are nearly 4 years later and I don't think much has improved with the ArcGIS API for Python reference. There are far too many methods where the functionality and use of each parameter is not clearly defined. Links to connected properties and managers missing, for example the MapContent. The content property for the Map class says "Returns a MapContent object that can be used to access the layers and tables in the map. This is useful for adding, updating, getting, and removing content from the Map." That's great, why not have a hyperlink for me to navigate directly to the MapContent object. There are plenty of "examples" which I use that term loosely that are incorrect. It seriously needs a revamp. As mentioned above by @KimOllivier the ArcPy documentation is far superior.

The lack of attention to detail for the ArcGIS API for Python is holding people back from being able to utilise it efficiently and hampering its adoption. I know this because people tell me this directly and constantly complain about the API reference.