Summary
The 2.4 Release contains many new changes that improve the performance and experience of using the Python API. The Python API incorporates the Jupyter Lab 4.0 and Notebook 7.0 architecture to align with how these applications process Python code. The backend architecture changes necessitated a complete overhaul of fundamental structures within the Python API which required both the removal of some modules & classes and the transfer of functionality into new modules, classes, and accompanying properties/methods.
These modifications change how some familiar functionality is accessed, and provides some new ways to work with your Web GIS organization. Let's take a look at some of these new updates.
Primary Python Support is for version 3.11. Secondary support is provided for Python 3.10 and 3.12. We have dropped Support for Python 3.9.
Note: The ArcGIS API for Python 2.4.0 release is supported with:
- ArcGIS Pro 3.4 and later cloned environments
- ArcGIS Enterprise 11.4 and later
- Stand-alone conda and Python environments
Refactor: arcgis.mapping module
The previous arcgis.mapping module functionality was documented in the following subsections in the Python API reference. The mapping module has been refactored into two new modules, the map and layers modules. Let's do a quick rundown of how those classes have been refactored.
Working with 2D Maps: Classes for working with Web Map items and packaging offline map areas
- The WebMap class has been deprecated. The functionality for working with web maps has been refactored to the new Map class in the
arcgis.mapmodule. See WebMap class in this document for more details.- See Using the map widget and Working with web maps and web scenes Working with web maps for examples.
- The OfflineMapAreaManager and PackagingJob have been refactored into the arcgis.map module. The offline_areas property of the new Map class accesses the OfflineMapAreaManager similarly to the same property on the previous WebMap.
- See Managing offline map areas for example.
Working with 3D Maps: Classes for working the Web Scenes and the data types displayed through scene layers
- The WebScene class has been deprecated and its functionality refactored into the Scene class in the
arcgis.mapmodule.- See Using the map widget Displaying in 3d and Working with web maps and web scenes Working with web scenes for examples.
- All other classes in this section have been refactored into the
arcgis.layersmodule and documented under the Working with 3D Maps section in the new module.
Working with Map Service Layers: Classes for working with Map Services and the associated layers within them
The classes have been refactored into the arcgis.layers module documented under the Working with Map Service Layers subsection.
Working with OGC layers: Classes for working with services compliant with OGC standards
The arcgis.mapping.ogc submodule classes have all been refactored into the arcgis.layers module documented in the Working with OGC layers subsection.
Working with Map Forms: Components to control behavior for data collecting and editing in applications like Map Viewer or ArcGIS Field Maps
The functionality of the arcgis.mapping.forms submodule has been refactored into the arcgis.map module and accessed using the form() method of the MapContent class. Full reference documentation is provided in Forms reference documentation.
Utility Functions for Mapping: Class and functions for working with symbology and rendering in the map widget.
- The functionality of the Symbology class has been refactored into the
Symbolsmodule. - The functionality for generating renderers has been refactored into the SmartMappingManager and RendererManager classes.
- See Smart mapping, Advanced cartography 1 and Advanced cartography 2 for examples.
- The functionality for exporting and printing has been refactored into the print() and export_to_html() methods of the Map class.
The WebMap class
The WebMap class has been deprecated and its functionality has been refactored into the Map class in the new arcgis.map module. Initialize a new map object with an existing Web Map item by entering it as the item argument, similarly to initializing with the previous class.
# Initialize in 2.4.x and after
from arcgis.map import Map
wm_item = gis.content.get("<web_map_id>")
wm = Map(
item = wm_item
)# Initialize in 2.3.x and prior
from arcgis.mapping import WebMap
wm = WebMap(
webmapitem = item
)The table below shows a mapping between previous WebMap class properties and methods and corresponding functionality in the new 2.4 release:
Methods:
| WebMap operation | Map operation | Notes |
|---|---|---|
| wm.add_layer() | m.content.add() | new MapContent class method |
| wm.add_table() | m.content.add() | new MapContent class method |
| wm.basemap_title() | m.basemap.title | new BasemapManager class property |
| wm.configure_pop_ups() | m.content.popup(index_position) | new PopupManager class |
| wm.get_layer() | m.content.layers[index_position] | |
| wm.get_table() | m.content.tables[index_position] | |
| wm.move_from_basemap() | m.basemap.move_from_basemap(layer_index) | new BasemapManager class method |
| wm.move_to_basemap() | m.content.move_to_basemap(layer_index) | new MapContent class method |
| wm.print() | m.print() | |
| wm.remove_layer() | m.content.remove(index_position) | new MapContent class method |
| wm.remove_table() | m.content.remove(index_position, False) | new MapContent class method |
| wm.save() | m.save() | |
| wm.update() | m.update() | |
| wm.update_drawing_info() | m.content.update_layer(renderer) | new MapContent class method (update Renderer for layer) |
| wm.update_layer() | m.update_layer() | new MapContent class method |
Properties
| WebMap member | Map member | Notes |
|---|---|---|
| wm.basemap | m.basemap.basemap | new BasemapManager class |
| wm.basemap_switcher | NA | |
| wm.basemaps | wm.basemap.basemap_gallery | List |
| wm.basemaps | m.basemap.basemaps | property on new BasemapManager class |
| wm.bookmarks | m.bookmarks.list | list property on new Bookmarks class |
| wm.events | NA | |
| wm.forms | m.content.form() | new MapContent class method (returns FormInfo for managing forms) |
| wm.gallery_basemaps | m.basemap.basemap_gallery | new BasemapManager class property |
| wm.height | NA | |
| wm.layer_visibility | m.layer_visibility=True | new LayerVisibility widget |
| wm.layers | m.content.layers | new MapContent class property |
| wm.legend | m.legend.enabled=True | new Legend widget |
| wm.navigation | NA | |
| wm.offline_areas | m.offline_areas | OfflineMapAreaManager |
| wm.pop_ups | m.content.popups(layer_index).disable_popup | new PopupManager property |
| wm.scale_bar | NA | |
| wm.search | NA | |
| wm.tables | m.content.tables | new MapContent class property |
| wm.view_bookmarks | m.bookmarks.list | new Bookmarks class property |
| wm.width | NA | |
| wm.zoom | m.zoom |
The arcgis.widgets module
The previous arcgis.widgets module contained the MapView class which served as the map widget in Jupyter notebooks. The Python API 2.4 release refactors the MapView functionality into two new classes in the arcgis.map module: Map and Scene classes.
In previous releases, maps and scenes were intialized based on the mode argument entered in the GIS.map() method, or by setting the mode property of a MapView object. Either way, you were always working with an instance of the MapView class. You can still use the mode argument when intializing the gis.map() object, but rather than returning the same type of object, the default value of 2D will return a Map object, and 3D will return a Scene object. Refactoring the calls allowed Python development to align with the web map specification and the web scene specification directly. This will increase widget compatibility within notebooks to more closely reflect the browser experiences of the Map Viewer and Scene Viewer.
Some properties and methods on the MapView class have been entirely removed, including interactive functionality that could be programmed into specific events like on_click and on_draw, embedding the widget into the notebook, and properties and methods that controlled the Jupyter environment. Other properties and methods have been refactored into new classes, many using the exact same name. See the table below for a mapping between previous MapView method and property names and how to access that functionality within the 2.4 release.
Note: In the table below, mview represents a variable to a MapView object, m represents a variable to a Map object, and scene to a Scene object.
Methods:
| MapView class operation | Map class operation | Notes |
|---|---|---|
| mview.add_layer() | m.content.add() | new MapContent class method |
| mview.clear_graphics() | m.content.remove_all() | new MapContent class method |
| mview.display_message() | NA | |
| mview.draw() | m.content.draw() | |
| mview.embed() | NA | |
| mview.export_to_html() | m.export_to_html() | |
| mview.hide_mode_swich() | NA | |
| mview.on_click() | NA | |
| mview.on_draw_end() | NA | |
| mview.remove_layers() | m.content.remove(index_position) also m.content.remove_all() | new MapContent class |
| mview.save() | m.save() | |
| mview.set_js_cdn | NA | |
| mview.set_time_extent() | m.time_slider.time_extent() | new TimeSlider class method |
| mview.snap_to_zoom() | NA | |
| mview.sync_navigation() | m.sync_navigation() | |
| mview.take_screenshot() | NA | |
| mview.toggle_window_view() | NA | |
| mview.unsync_navigation() | m.unsync_navigation() | |
| mview.update() | m.update() | |
| mview.update_layer() | m.content.update_layer | new MapContent class method |
| mview.zoom_to_layer() | m.zoom_to_layer() |
Properties
| MapView class member | Map class member | Notes |
|---|---|---|
| mview.basemap | m.basemap.basemap | new BasemapManager class property |
| mview.basemaps | m.basemap.basemaps | new BasemapManager class property |
| mview.center | m.center | |
| mview.draw | m.content.draw() | |
| mview.end_time | m.time_slider.time_extent() | new TimeSlider class method |
| mview.extent | m.extent | |
| mview.gallery_basemaps | m.basemap.basemap_gallery | new BasemapManager class property |
| mview.jupyter_target | NA | |
| mview.heading | scene.heading | new Scene class property |
| mview.layers | m.content.layers | new MapContent class property |
| mview.legend | m.legend.enabled = True | new Legend widget |
| mview.local_raster_file_format | NA | |
| mview.mode | gis.map(mode="2D" or "3D") | * a parameter when initializing Map class |
| mview.print_service_url | NA | |
| mview.ready | NA | |
| mview.rotation | m.rotation | |
| mview.scale | m.scale | |
| mview.start_time | m.time_slider.time_extent() | new TimeSlider class method |
| mview.tab_mode | NA | |
| mview.tilt | scene.tilt | new Scene class property |
| mview.time_mode | m.time_slider.time_extent() | new TimeSlider class method |
| mview.time_slider | m.time_slider.enabled=True | new TimeSlider widget |
| mview.zoom | m.zoom |
New arcgis map Module
The Map class
The new map class was developed to align with the Jupyter Lab and Notebook 7 backend architecture and processing. The class includes properties which return auxiliary managment classes and interactive widget buttons for comprehensive management and visualization of a map and its content.
- bookmarks property - returns Bookmarks object to manage individual bookmarks
- content property - returns MapContent object to manage layers in a map
- popup property - returns PopupManager object to manage popup information for the layer entered as the index argument
- See Locating addresses for examples.
- renderer property - returns RendererManager object to manage symbology for layer entered as the index argument
- See Analyzing patterns in feature data for example.
- layer_visibility property - adds or removes a layer from the layer list widget
- popup property - returns PopupManager object to manage popup information for the layer entered as the index argument
- basemap property - returns BasemapManager object to manage the basemap for the map
- See Using the map widget Basemaps section for example.
New widgets to provide increased visibility of the content on a rendered map in a Jupyter notebook:
- legend - adds or removes a legend widget
- layer_list - adds or removes layer list widget
- time_slider - adds or removes a time slider widget
The Scene Class
The new scene class was developed to align with the Jupyter Lab and Notebook 7 backend architecture and processing. The class includes properties which return auxiliary managment classes and interactive widget buttons for comprehensive management and visualization of a scene and its content.
- content property - returns SceneContent object to manage the layers in a scene
- basemap property - returns BasemapManager to manage the basemap for the scene
New widgets to provide enhanced visualization on a rendered Scene in a Jupyter notebook:
- environment.daylight_enabled - adds or removes a daylight widget
- environment.weather_enabled - adds or removes a weather widget
- legend - adds or removes a legend widget
- layer_list - adds or removes layer list widget
- time_slider - adds or removes time slider widget
New arcgis.layers module
The Service class
The module also adds a new Service class designed to simplify getting specific types of services into the appropriate API object. No longer do you need to import a specific class into your scripts in order to initialize objects from url values to initialize the correct object. Now you can use the Service class to automatically determine the appropriate object type to return. Any service url entered as input will return an object of the corresponding class in the API. See below:
Most of the classes from the previous arcgis.mapping module have been refactored into this module. See the documentation above in the arcgis.mapping section for explanation.
# Previous releases:
from arcgis.features import FeatureLayerCollection
from arcgis.gis import GIS
gis = GIS(profile="your_online_profile")
fcoll = FeatureLayerCollection(
url = "https://services5.arcgis.com/jmdi6ffhe45GMz1s/arcgis/rest/services/Groundwater_Ordinance_Areas/FeatureServer",
gis=gis
)
type(fcoll)arcgis.features.layer.FeatureLayerCollection
# New at 2.4
from arcgis.layers import Service
fcoll = Service(
url_or_item="https://services5.arcgis.com/jmdi6ffhe45GMz1s/arcgis/rest/services/Groundwater_Ordinance_Areas/FeatureServer",
server=gis
)
print(type(fcoll))
service_obj = Service(
url_or_item="https://mapservices.weather.noaa.gov/vector/rest/services/outlooks/natl_fcst_wx_chart/MapServer",
server=gis
)
print(type(service_obj))
scene_obj = Service(
url_or_item="https://tiles.arcgis.com/tiles/oPre3pOfRfefL8y0/arcgis/rest/services/swissbuildings3D/SceneServer"
)
print(type(scene_obj))<class 'arcgis.features.layer.FeatureLayerCollection'> <class 'arcgis.layers._msl.map_layers.MapImageLayer'> <class 'arcgis.layers._scenelyrs._lyrs.Object3DLayer'>