Services & Layers
Layers
archibald.services.FeatureLayer
Bases: FeatureService, BaseLayer
Single layer within an ESRI FeatureServer service.
Inherits FeatureServer path validation from FeatureService and shared layer capability (metadata caching, field inspection, querying) from BaseLayer. Adds editing operations (applyEdits, upsert, sync).
__init__(client, service_path, layer_id)
Construct a FeatureLayer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
ArchieClient
|
The ArchieClient instance. |
required |
service_path
|
str
|
Service path ending in FeatureServer (e.g., "services/MyService/FeatureServer"). Validated by FeatureService. |
required |
layer_id
|
int
|
Layer index within the service (e.g., 0, 1, 2). |
required |
append(df, *, apply_coded_values=False)
async
Add all rows in df as new features.
Convenience wrapper around apply_edits(adds=df). Raises LayerCapabilityError if the layer does not support applyEdits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame | GeoDataFrame
|
Rows to add. OBJECTIDs are excluded from the payload. |
required |
apply_coded_values
|
bool
|
When True, translate human-readable domain names back to their raw codes before serialization. |
False
|
Returns:
| Type | Description |
|---|---|
ApplyEditsResult
|
ApplyEditsResult with add results for each row. |
apply_edits(adds=None, updates=None, deletes=None, *, rollback_on_failure=False, apply_coded_values=False)
async
Add, update, and/or delete features in a single batched operation.
Validates that the layer supports applyEdits, then delegates all serialization, batching, and posting to ApplyEditsOperation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adds
|
DataFrame | GeoDataFrame | None
|
Rows to add as new features. OBJECTIDs are excluded. |
None
|
updates
|
DataFrame | GeoDataFrame | None
|
Rows to update (must include the OBJECTID column). |
None
|
deletes
|
DataFrame | Series | list[int] | None
|
OBJECTIDs to delete — list[int], DataFrame with an OBJECTID column, or a Series of integer OBJECTIDs. |
None
|
rollback_on_failure
|
bool
|
Request server-side rollback on failure. Silently degraded to False with a warning if the layer does not support it. |
False
|
apply_coded_values
|
bool
|
When True, translate human-readable domain names in the DataFrame back to their raw codes before serialization. |
False
|
Returns:
| Type | Description |
|---|---|
ApplyEditsResult
|
ApplyEditsResult with all add, update, and delete results merged. |
Raises:
| Type | Description |
|---|---|
LayerCapabilityError
|
If the layer does not support edit operations. |
supports_apply_edits()
async
Whether this layer supports applyEdits operations.
Returns:
| Type | Description |
|---|---|
bool
|
True if the layer's capabilities include editing. |
supports_async_apply_edits()
async
Whether this layer supports server-side async applyEdits processing.
Returns:
| Type | Description |
|---|---|
bool
|
True if the layer advertises supportsAsyncApplyEdits in its |
bool
|
advancedEditingCapabilities. |
supports_rollback_on_failure()
async
Whether this layer supports the rollbackOnFailure parameter.
Returns:
| Type | Description |
|---|---|
bool
|
True if the layer advertises supportsRollbackOnFailureParameter in |
bool
|
its advancedEditingCapabilities. |
sync(df, key_fields, *, apply_coded_values=False)
async
Full sync: add new features, update existing features, delete removed features.
Same diff logic as upsert, plus features present in the layer but absent from df are collected as deletes. After sync, the layer's keyed contents exactly mirror df.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame | GeoDataFrame
|
Source DataFrame or GeoDataFrame representing the desired state. |
required |
key_fields
|
list[str]
|
Column names whose combined values uniquely identify a feature. Used to match rows in df against existing layer features. |
required |
apply_coded_values
|
bool
|
When True, translate human-readable domain names back to their raw codes before serialization. |
False
|
Returns:
| Type | Description |
|---|---|
ApplyEditsResult
|
ApplyEditsResult with add, update, and delete results. |
Raises:
| Type | Description |
|---|---|
LayerCapabilityError
|
If the layer does not support applyEdits or query operations. |
InvalidParameterError
|
If key_fields is invalid. |
upsert(df, key_fields, *, apply_coded_values=False)
async
Add new features and update existing features matched by key_fields.
Performs a slim query (key fields + OBJECTID, no geometry) to build an existing-key index, then partitions df into adds (keys absent from the layer) and updates (keys present, with OBJECTID injected). Never deletes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame | GeoDataFrame
|
Source DataFrame or GeoDataFrame. |
required |
key_fields
|
list[str]
|
Column names whose combined values uniquely identify a feature. Used to match rows in df against existing layer features. |
required |
apply_coded_values
|
bool
|
When True, translate human-readable domain names back to their raw codes before serialization. |
False
|
Returns:
| Type | Description |
|---|---|
ApplyEditsResult
|
ApplyEditsResult with add and update results. |
Raises:
| Type | Description |
|---|---|
LayerCapabilityError
|
If the layer does not support applyEdits or query operations. |
InvalidParameterError
|
If key_fields is invalid. |
archibald.services.MapLayer
Bases: MapService, BaseLayer
Single layer within an ESRI MapServer service.
Inherits MapServer path validation from MapService and shared layer capability (metadata caching, field inspection, querying) from BaseLayer. Supports querying only.
archibald.services.BaseLayer
Bases: BaseService
Abstract base for a single layer within an ESRI service.
Provides layer init, metadata caching, field inspection, and query execution. Subclasses must define expected_type and may add editing support.
__init__(client, service_path, layer_id)
Construct a BaseLayer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
ArchieClient
|
The ArchieClient instance. |
required |
service_path
|
str
|
Service path validated by BaseService against expected_type. |
required |
layer_id
|
int
|
Layer index within the service (e.g., 0, 1, 2). |
required |
fields()
async
Field definitions from layer metadata.
Returns:
| Type | Description |
|---|---|
FieldsResult
|
FieldsResult providing access to field names and definitions. |
globalid_field()
async
Name of the GlobalID field for this layer, if present.
Returns:
| Type | Description |
|---|---|
str | None
|
The name of the GlobalID field, a UUID string used for unique |
str | None
|
identification across systems. None if not defined. |
objectid_field()
async
Name of the OBJECTID field for this layer.
Returns:
| Type | Description |
|---|---|
str
|
The name of the OBJECTID field, used for pagination and often as a |
str
|
unique identifier for features. |
query(where='1=1', out_fields=None, return_geometry=True, out_sr=None, apply_coded_values=False, **kwargs)
async
Execute a query on this layer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
where
|
str
|
WHERE clause (default "1=1" returns all features). |
'1=1'
|
out_fields
|
list[str] | str | None
|
Field names to return. Can be None (→ all), a list, or a comma-separated string. |
None
|
return_geometry
|
bool
|
Include feature geometries in the response. |
True
|
out_sr
|
int | None
|
Output spatial reference (EPSG code) for geometries. |
None
|
apply_coded_values
|
bool
|
When True, |
False
|
**kwargs
|
Additional query parameters (e.g., orderByFields, resultType). |
{}
|
Returns:
| Type | Description |
|---|---|
QueryResult
|
QueryResult with aggregated features, field definitions, and geometry type. |
Raises:
| Type | Description |
|---|---|
InvalidParameterError
|
If out_fields contains unknown field names. |
LayerCapabilityError
|
If the layer does not support query operations. |
supports_query()
async
Whether this layer supports query operations.
Returns:
| Type | Description |
|---|---|
bool
|
True if the layer's capabilities include querying, False otherwise. |
Services
archibald.services.FeatureService
archibald.services.MapService
archibald.services.BaseService
Bases: ABC
Base class for all ESRI REST service resources.
Validates that the provided service path ends with the expected service type on construction. Provides a single async method for fetching and caching service-level metadata.
crs()
async
Well-known ID of the service's spatial reference system.
Defaults to 3857, Web Mercator.
description()
async
Human-readable service description.
max_record_count()
async
Maximum number of records the service returns per request.