not sure if you're still having trouble with this, but I have indeed got a setup going of producing maps using the QGIS composer functionality via the Python API.
My general strategy is:-
1) Create a shared map canvas used by the composer, and all maps etc. Code to first create the QgsComposition looks like:
ms = canvas.mapSettings()
comp = QgsComposition(ms)
2) My composition does indeed have 2 separate maps. After reading in my composer template XML I refer to them similarly to you, e.g. using
3) Following instructions from John Sutton's blog post linked below:- before creating actual maps, I make sure the maps are linked properly to the canvas, by calling:-
4) Before creating the output PDF, call
In my case, I'd already set the layers I wanted to use for each map in the XML file, so I didn't need to modify these further in the Python script. Indeed I had them each locked in 'lock layer-set mode'. But I did also test modifying them in Python by changing the array of map layers, and it worked. E.g. here is an example of replacing the 2nd (hence index #1) layer of one of the maps:
layerSet = map_item.layerSet()
layerSet = ptua_iso_layer_id
Note:- in general I was having a lot of issues with blank maps being generated when loading layers from projects until I worked out the various 'best practices' for creating a QGIS script to run externally to QGIS, including making sure to set the QGIS path, call QgsApplication.initQgis(), etc. Creating a shared canvas and linking it to the loaded project via a QgsLayerTreeMapCanvasBridge seems a good approach, see this handy blog post and code sample from Richard Sutton:-
Hope this helps!