I hardly know where to begin, or end, but I'll try.
I want to create a python utility to do one very small, but repetitive, task: make a (known) subset of fields invisible in a map layer without having to fire up Arcmap.To my amazement, there is no way to do this.
I thought I was onto something when I find that one one can use arcpy.Describe() to get properties of a layer, one such property being a FieldInfo class. That class has a method called setVisible().
But no, there is apparently no way to get Describe() to access a layer in a map file unless one is already running arcmap using the interactive Python window. From a command line one can only access a standalone, .lyr, layer file.
And, to my amazement, the setVisibility() api does not work even then. Nothing changes.
My overwhelming impression of arcpy is that it is a poorly conceived, half baked, quite incomplete API with confusing terminology, and sketchy documentation. For instance: a layer file is treated quite differently to a layer. Apparently to get Describe() to get the properties of the layer (the kernel of the layer file tucked neatly inside) you have first to get the properties of a layer file. When you have done that the class instance returned has a property called -- trumpet roll -- "layer" which is: NO! not an instance of a layer class at all but another instance of Describe which then has layer properties one of which being an instance of FieldInfo. It is clear from the documentation that this cumbersome construct was some kind of afterthought. (The objects returned by describe do not even have a well defined class name: there is no "describe" class)
The documentation also blithely states that there are many properties of layers which the API does not support. Even the modification of quite simple layer properties are unsupported.. The suggested solution seems to be to construct out of band from the ground up an entire new layer and replace the offending layer with it.
Why, oh why, is this API so clunky? Sure, I can understand that certain operations are sufficiently complex that a simple Python API cannot really handle them. But to make certain fields in a layer hidden? Really? This API is now several years old, and it still seems really poor. Is there any chance that it is going to improve?
But no, there is apparently no way to get Describe() to access a layer in a map file unless one is already running arcmap using the interactive Python window.
I open MXDs and APRXs from outside of ArcGIS applications all the time (well, outside of the main app, not outside of Esri/ArcGIS libraries). See MapDocument—Help | ArcGIS Desktop and ArcGISProject—ArcPy | Documentation
Yes, but the the alternative to arcpy in the python api is shapely, which can't do it either.
Wrappers around arcobjects certainly haven't been developed for everything yet, I will give you that.
If it is the Describe object that you mostly have issues with, you might want to read How to Introspect a Describe "Object" . It is a few years old, but the discussion is still relevant for Describe, especially in ArcMap.
The Describe object is tricky because the way that ArcObjects was built doesn't cleanly line up with the overall object model put forward by ArcPy. Speaking of ArcObjects and ArcMap, object properties are implemented through a wide range of COM interfaces spanning dozens of ArcObject namespaces. Since checking every interface in the dozens of namespaces would lead to an up-front performance hit on creation objects, most of the Describe object properties and methods are evaluated lazily, which makes introspection difficult and sometimes working with IDEs too.
With ArcGIS Pro, Esri introduced a new version of Describe in the Data Access module (Describe—Data Access module | Documentation ) which is easier to work with since it dumps everything into Python dictionaries that Python coders are more comfortable with.
In ArcGIS Pro 2.4 and above, you have access to the entire CIM (Cartographic Information Model) through Python and ArcPy, that is the foundation for projects and layer objects and styling as saved in an ArcGIS Pro project file (*.aprx) or layer file (*.lyrx):
This is a really powerful new way to deal with layers and such. Do take heed of the warnings though, with power, responsibility comes as well, you can easily ruin your project if making modifications!
I agree the Describe object can be confusing. I personally see ArcPy also a lot in terms of geoprocessing automation, running and calling tools, not necessarily styling modifications, although it can be done. I think the link Joshua Bixby gave is the best description of some of the issues with Describe.