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

`add_attachments(object_ids, files, filenames=None, content_types=None)` `async`

Attach one or more files to one or more features.

Accepts three calling modes:

Single — one int object_id and one file object: attach a single file to one feature.
Fan-out — one int object_id and an iterable of files: attach multiple files to the same feature concurrently.
Multi — iterables of object_ids and files: attach one file per feature, all concurrently. Object IDs may be repeated to attach multiple files to the same feature.

Parameters:

Name	Type	Description	Default
`object_ids`	`int \| Iterable[int]`	Feature OBJECTID(s) to attach files to.	required
`files`	`Path \| BinaryIO \| bytes \| Iterable[Path \| BinaryIO \| bytes]`	File(s) to attach. Each item may be a pathlib.Path, an open binary file object, or raw bytes.	required
`filenames`	`str \| None \| Iterable[str \| None]`	Filename override(s). In single mode, a plain `str` (or `None` to auto-detect). In fan-out / multi mode, an iterable of per-item overrides (or `None` to auto-detect all). Required per-item for any raw bytes entries.	`None`
`content_types`	`str \| None \| Iterable[str \| None]`	MIME type override(s). When omitted or `None` for an item, the type is guessed from the resolved filename and falls back to `application/octet-stream`.	`None`

Returns:

Type	Description
`AttachmentsResult`	AttachmentsResult with one result per input file, in input order.

Raises:

Type	Description
`LayerCapabilityError`	If the layer does not support attachments.
`InvalidParameterError`	If any iterables differ in length, or if a bytes file has no resolvable filename.

`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.

`delete_attachments(object_ids, attachment_ids)` `async`

Delete one or more attachments from one or more features.

Pairs are grouped by OBJECTID so that all attachments on the same feature are removed in a single request.

Accepts three calling modes:

Single — scalar object_id and attachment_id: delete one attachment from one feature.
Fan-out — scalar object_id and an iterable of attachment_ids: delete multiple attachments from the same feature in a single batched request.
Multi — iterables of object_ids and attachment_ids: delete one attachment per pair, concurrently. Object IDs may be repeated when deleting multiple attachments from the same feature.

Parameters:

Name	Type	Description	Default
`object_ids`	`int \| Iterable[int]`	Feature OBJECTID(s) whose attachments are being deleted.	required
`attachment_ids`	`int \| Iterable[int]`	Attachment ID(s) to delete, one per object_id entry.	required

Returns:

Type	Description
`AttachmentsResult`	AttachmentsResult with one result per input pair, in input order.

Raises:

Type	Description
`LayerCapabilityError`	If the layer does not support attachments.
`InvalidParameterError`	If object_ids and attachment_ids differ in length.

`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.

`supports_update()` `async`

Whether this layer supports updating existing features and attachments.

Returns:

Type	Description
`bool`	True if the layer's capabilities include the Update operation.

`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.

`update_attachments(object_ids, attachment_ids, files, filenames=None, content_types=None)` `async`

Replace the files of one or more existing attachments.

Accepts three calling modes:

Single — scalar object_id, attachment_id, and one file: replace a single attachment on one feature.
Fan-out — scalar object_id, an iterable of attachment_ids and an iterable of files: replace multiple attachments on the same feature concurrently.
Multi — iterables of object_ids, attachment_ids, and files: replace one attachment per entry, all concurrently. Object IDs may be repeated when updating multiple attachments on the same feature.

Parameters:

Name	Type	Description	Default
`object_ids`	`int \| Iterable[int]`	Feature OBJECTID(s) owning the attachments.	required
`attachment_ids`	`int \| Iterable[int]`	ID(s) of the existing attachments to replace.	required
`files`	`Path \| BinaryIO \| bytes \| Iterable[Path \| BinaryIO \| bytes]`	Replacement file(s). Each item may be a pathlib.Path, an open binary file object, or raw bytes.	required
`filenames`	`str \| None \| Iterable[str \| None]`	Filename override(s). In single mode, a plain `str` (or `None` to auto-detect). In fan-out / multi mode, an iterable of per-item overrides (or `None` to auto-detect all). Required per-item for any raw bytes entries.	`None`
`content_types`	`str \| None \| Iterable[str \| None]`	MIME type override(s). When omitted or `None` for an item, the type is guessed from the resolved filename and falls back to `application/octet-stream`.	`None`

Returns:

Type	Description
`AttachmentsResult`	AttachmentsResult with one result per input file, in input order.

Raises:

Type	Description
`LayerCapabilityError`	If the layer does not support attachments or does not support updating.
`InvalidParameterError`	If any iterables differ in length, or if a bytes file has no resolvable filename.

`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

`attachment_fields()` `async`

Attachment table field definitions from layer metadata.

Returns:

Type	Description
`FieldsResult`	FieldsResult built from the layer metadata's attachmentFields key,
`FieldsResult`	describing the columns available on each attachment.

`attachment_properties()` `async`

Attachment property crosswalk from layer metadata.

Returns:

Type	Description
`list[dict]`	The layer metadata's attachmentProperties list. Each entry maps a
`list[dict]`	camelCase queryAttachments response property (`name`) to its ESRI
`list[dict]`	attachment-table field (`fieldName`) and carries an `isEnabled`
`list[dict]`	flag. Empty list when the layer omits the key.

`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, `to_frame()` and `to_geodataframe()` methods in the QueryResult will replace coded domain values with their human-readable names automatically.	`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.

`query_attachments(*, object_ids=None, global_ids=None, definition_expression=None, attachments_definition_expression=None, attachment_types=None, size=None, keywords=None, return_url=None, return_metadata=None, order_by_fields=None, result_offset=None, result_record_count=None, return_count_only=False, **kwargs)` `async`

Query attachments on this layer.

Works on both feature service and map service layers. Each ESRI queryAttachments parameter is exposed as a named argument. return_count_only is only supported on feature service layers.

At least one feature selector — object_ids, global_ids, or definition_expression — must be supplied. object_ids and global_ids are mutually exclusive: ESRI silently ignores object_ids when global_ids is given, so supplying both raises rather than dropping one.

Parameters:

Name	Type	Description	Default
`object_ids`	`list[int] \| str \| None`	Parent feature OBJECTIDs to query. Mutually exclusive with global_ids; ignored by the server when global_ids is also supplied.	`None`
`global_ids`	`list[str] \| str \| None`	Parent feature GlobalIDs to query. Mutually exclusive with object_ids.	`None`
`definition_expression`	`str \| None`	SQL expression filtering parent features.	`None`
`attachments_definition_expression`	`str \| None`	SQL expression filtering attachments.	`None`
`attachment_types`	`list[str] \| str \| None`	Attachment file types to return (e.g. ["jpeg", "pdf"]).	`None`
`size`	`tuple[int, ...] \| list[int] \| str \| None`	Attachment file size filter in bytes. A single minimum (`(1000,)` or `"1000"`) returns attachments at least that large; a `(min, max)` pair or `"min,max"` string returns a range. A max-only range (`",1000"`) is rejected since the server ignores it.	`None`
`keywords`	`list[str] \| str \| None`	Filter attachments by keyword. A single string or a list of strings (comma-joined).	`None`
`return_url`	`bool \| None`	Include attachment download URLs.	`None`
`return_metadata`	`bool \| None`	Include EXIF metadata when available.	`None`
`order_by_fields`	`str \| None`	Fields to sort attachments by.	`None`
`result_offset`	`int \| None`	Number of attachments to skip (pagination).	`None`
`result_record_count`	`int \| None`	Maximum number of attachments to return.	`None`
`return_count_only`	`bool`	Return only per-feature attachment counts.	`False`
`**kwargs`		Additional raw API parameters passed through unchanged.	`{}`

Returns:

Type	Description
`AttachmentsQueryResult`	AttachmentsQueryResult with attachment groups and field metadata.

Raises:

Type	Description
`LayerCapabilityError`	If the layer does not support queryAttachments, or if return_count_only is requested but unsupported (e.g. map layers).
`InvalidParameterError`	If no feature selector is supplied, if both object_ids and global_ids are supplied, if size is malformed, if keywords or return_metadata is requested while the layer disables the corresponding property, or if order_by_fields is supplied while the layer does not support it.

`supports_attachments()` `async`

Whether this layer supports file attachments.

Returns:

Type	Description
`bool`	True if the layer metadata advertises hasAttachments=True.

`supports_query()` `async`

Whether this layer supports query operations.

Returns:

Type	Description
`bool`	True if the layer's capabilities include querying, False otherwise.

`supports_query_attachments()` `async`

Whether this layer supports the queryAttachments operation.

Returns:

Type	Description
`bool`	True if the layer advertises supportsQueryAttachments in its
`bool`	advancedQueryCapabilities.

`supports_query_attachments_count_only()` `async`

Whether this layer supports queryAttachments with returnCountOnly.

Map service layers do not support returnCountOnly and omit this key.

Returns:

Type	Description
`bool`	True if the layer advertises supportsQueryAttachmentsCountOnly in its
`bool`	advancedQueryCapabilities.

`supports_query_attachments_order_by_fields()` `async`

Whether this layer supports queryAttachments with orderByFields.

Returns:

Type	Description
`bool`	True if the layer advertises supportsQueryAttachmentsOrderByFields in
`bool`	its advancedQueryCapabilities.

Services

`archibald.services.FeatureService`

Bases: BaseService

ESRI FeatureServer service resource.

`archibald.services.MapService`

Bases: BaseService

ESRI MapServer service resource.

`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.

Services & Layers

Layers

archibald.services.FeatureLayer

__init__(client, service_path, layer_id)

add_attachments(object_ids, files, filenames=None, content_types=None) async

append(df, *, apply_coded_values=False) async

apply_edits(adds=None, updates=None, deletes=None, *, rollback_on_failure=False, apply_coded_values=False) async

delete_attachments(object_ids, attachment_ids) async

supports_apply_edits() async

supports_async_apply_edits() async

supports_rollback_on_failure() async

supports_update() async

sync(df, key_fields, *, apply_coded_values=False) async

update_attachments(object_ids, attachment_ids, files, filenames=None, content_types=None) async

upsert(df, key_fields, *, apply_coded_values=False) async

archibald.services.MapLayer

archibald.services.BaseLayer

__init__(client, service_path, layer_id)

attachment_fields() async

attachment_properties() async

fields() async

globalid_field() async

objectid_field() async

query(where='1=1', out_fields=None, return_geometry=True, out_sr=None, apply_coded_values=False, **kwargs) async

supports_attachments() async

supports_query() async

supports_query_attachments() async

supports_query_attachments_count_only() async

supports_query_attachments_order_by_fields() async

Services

archibald.services.FeatureService

archibald.services.MapService

archibald.services.BaseService

crs() async

description() async

max_record_count() async

`archibald.services.FeatureLayer`

`init(client, service_path, layer_id)`

`add_attachments(object_ids, files, filenames=None, content_types=None)` `async`

`append(df, *, apply_coded_values=False)` `async`

`apply_edits(adds=None, updates=None, deletes=None, *, rollback_on_failure=False, apply_coded_values=False)` `async`

`delete_attachments(object_ids, attachment_ids)` `async`

`supports_apply_edits()` `async`

`supports_async_apply_edits()` `async`

`supports_rollback_on_failure()` `async`

`supports_update()` `async`

`sync(df, key_fields, *, apply_coded_values=False)` `async`

`update_attachments(object_ids, attachment_ids, files, filenames=None, content_types=None)` `async`

`upsert(df, key_fields, *, apply_coded_values=False)` `async`

`archibald.services.MapLayer`

`archibald.services.BaseLayer`

`init(client, service_path, layer_id)`

`attachment_fields()` `async`

`attachment_properties()` `async`

`fields()` `async`

`globalid_field()` `async`

`objectid_field()` `async`

`query(where='1=1', out_fields=None, return_geometry=True, out_sr=None, apply_coded_values=False, **kwargs)` `async`

`supports_attachments()` `async`

`supports_query()` `async`

`supports_query_attachments()` `async`

`supports_query_attachments_count_only()` `async`

`supports_query_attachments_order_by_fields()` `async`

`archibald.services.FeatureService`

`archibald.services.MapService`

`archibald.services.BaseService`

`crs()` `async`

`description()` `async`

`max_record_count()` `async`