alfresco-rest-client
Python client for Alfresco Content Services REST API, modelled after nuxeo-python-client.
Quick start
from alfresco import Alfresco, BasicAuth
client = Alfresco(url="http://localhost:8080", auth=BasicAuth("admin", "admin"))
# Nodes (files & folders)
root = client.nodes.get("-root-")
children = client.nodes.list_children("-root-")
folder = client.nodes.create_folder("-root-", "Reports")
uploaded = client.nodes.upload(folder.id, file_path="/tmp/q1.pdf") # streams; supports progress= callback
content = client.nodes.get_content(uploaded.id)
client.nodes.copy(uploaded.id, root.id, name="q1-copy.pdf")
client.nodes.delete(uploaded.id)
# Version + lock signals — populated by default on get()/list_children()/iter_children()
uploaded.version_label # e.g. "1.0" (empty if not versionable)
uploaded.is_versionable # True if node carries the cm:versionable aspect
uploaded.is_locked # True/False
uploaded.lock_owner # user id string, or None
uploaded.lock_type # "WRITE_LOCK" / "READ_ONLY_LOCK", or None
uploaded.lock_expires_at # datetime, or None (incl. indefinite PERSISTENT locks)
uploaded.lock_lifetime # "PERSISTENT" / "EPHEMERAL", or None
# Lock with an expiry (cm:expiryDate); omit time_to_expire for an indefinite lock
client.nodes.lock(uploaded.id, time_to_expire=3600) # seconds
client.nodes.unlock(uploaded.id)
# People (users)
me = client.people.get("-me-")
# Groups
groups = client.groups.list()
# Sites
sites = client.sites.list()
site = client.sites.create("eng", "Engineering", visibility="PRIVATE")
# Search (AFTS or CMIS)
results = client.search.search("cm:name:'budget*'")
results = client.search.search("SELECT * FROM cmis:document", language="cmis")
# Trashcan
deleted = client.trashcan.list()
# Comments
client.comments.create(uploaded.id, "LGTM!")
# Versions (node version history)
history = client.versions.list(uploaded.id)
version = client.versions.get(uploaded.id, "1.0")
client.versions.revert(uploaded.id, "1.0", major_version=True, comment="Restore")
client.versions.delete(uploaded.id, "1.0")
# Tags
client.tags.add_to_node(uploaded.id, ["reviewed"])
# Favorites
client.favorites.add("-me-", uploaded.id)
# Context-manager support
with Alfresco(url="http://localhost:8080", auth=BasicAuth("admin", "admin")) as c:
c.nodes.get("-root-")
client.close()
Device Sync
Alfresco Device Sync (the protocol behind the desktop-sync client) spans two hosts, and the SDK mirrors that split:
| Handler | Host | Purpose |
|---|---|---|
client.device_sync |
Repository (8080) | Unauthenticated bootstrap config — how a client should authenticate + where the Sync Service lives |
client.sync_amp |
Repository (8080) | Provisioning: subscribers, node subscriptions, syncer lookup, node stats (Device Sync AMP REST endpoints) |
client.sync_service |
Sync Service (9090) | The standalone change-delta engine: health, config, metrics and the change-polling flow |
Subscribers and subscriptions are provisioned on the repository (sync_amp),
but the actual change feed is pulled from the standalone Sync Service
(sync_service). Point the client at both hosts:
from alfresco import Alfresco, TicketAuth
client = Alfresco(
url="http://localhost:8080",
auth=TicketAuth("admin", "admin"),
sync_service_url="http://localhost:9090/alfresco", # required for client.sync_service
)
Auth note:
TicketAuthis host-aware. Repository requests get?alf_ticket=…; Sync Service requests getAuthorization: Basic base64("<ticket>:"). On OAuth/Identity-Service deployments the bearer token is accepted by both hosts.
Bootstrap config — client.device_sync
Wraps GET /alfresco/service/devicesync/config (unauthenticated).
cfg = client.device_sync.get_device_sync_config()
print(cfg.uri, cfg.repo_info.version_label, cfg.dsync_client_version_min)
idp = client.device_sync.get_identity_service_config() # OIDC settings
print(idp.auth_server_url, idp.realm, idp.client_id, idp.openid_configuration_url())
raw = client.device_sync.get_config() # raw JSON document
| Method | Endpoint |
|---|---|
get_config() → dict |
GET /alfresco/service/devicesync/config |
get_device_sync_config() → DeviceSyncConfig |
(parsed) |
get_identity_service_config() → IdentityServiceConfig |
(parsed identityServiceConfig) |
Provisioning (AMP) — client.sync_amp
Device Sync AMP REST endpoints under the repository's private v1 API
(/alfresco/api/-default-/private/alfresco/versions/1).
amp = client.sync_amp
# Subscribers
sub = amp.create_subscriber(device_os="linux", client_version="1.0.1")
amp.get_subscriber(sub.id)
amp.list_subscribers() # or iter_subscribers()
# Node subscriptions (map a repo folder into the device's sync set)
subn = amp.create_subscription(sub.id, target_node_id=folder.id) # subscription_type="CONTENT"
amp.get_subscription(sub.id, subn.id)
amp.list_subscriptions(sub.id) # or iter_subscriptions(sub.id)
# Syncer that handles the subscriber + per-node statistics
syncer = amp.get_syncer(sub.sync_service_id) # -> DeviceSyncConfig (uri, filters, repo info)
stats = amp.get_node_stats(folder.id) # -> NodeStats(size_in_bytes, number_of_documents)
# Teardown (delete subscriptions before their subscriber — see note below)
amp.delete_subscription(sub.id, subn.id)
amp.delete_subscriber(sub.id)
# Capability probe — is the Device Sync AMP installed on this repository?
amp.is_available() # -> bool
| Method | HTTP | Endpoint (under …/versions/1) |
|---|---|---|
is_available() → bool |
GET | /subscribers (probe) |
get_syncer(syncer_id) → DeviceSyncConfig |
GET | /syncers/{syncerId} |
create_subscriber(device_os, client_version) → Subscriber |
POST | /subscribers |
list_subscribers() / iter_subscribers() → Subscriber |
GET | /subscribers |
get_subscriber(subscriber_id) → Subscriber |
GET | /subscribers/{subscriberId} |
delete_subscriber(subscriber_id) |
DELETE | /subscribers/{subscriberId} |
create_subscription(subscriber_id, target_node_id) → Subscription |
POST | /subscribers/{subscriberId}/subscriptions |
list_subscriptions(subscriber_id) / iter_subscriptions(...) → Subscription |
GET | /subscribers/{subscriberId}/subscriptions |
get_subscription(subscriber_id, subscription_id) → Subscription |
GET | /subscribers/{subscriberId}/subscriptions/{nodeSubscriptionId} |
delete_subscription(subscriber_id, subscription_id) |
DELETE | /subscribers/{subscriberId}/subscriptions/{nodeSubscriptionId} |
get_node_stats(node_id) → NodeStats |
GET | /nodes-stats/{nodeId} |
Note: deleting a subscription (or its subscriber) whose target node has already been permanently deleted fails server-side with
HTTP 400 nodeRef is a mandatory parameter. Delete subscriptions while their target nodes still exist, and delete them before their subscriber.
Change-delta engine (App) — client.sync_service
The standalone Sync Service on port 9090 (requires sync_service_url).
svc = client.sync_service
svc.health() # unauthenticated Dropwizard probe
svc.is_available() # -> bool (reachable? never raises)
cfg = svc.get_config() # -> DeviceSyncConfig (filters, repo info, IdP)
svc.get_service_configuration() # alias endpoint, same shape
svc.metrics() # Dropwizard registry (gauges/counters/timers)
# Change-polling flow (needs a subscriber + subscription from sync_amp):
started = svc.start_sync(sub.id, subn.id, client_version="1.0.1") # changes=[...] optional
status = svc.get_sync(sub.id, subn.id, started.sync_id)
for change in status.changes: # plus status.resets / status.missing
print(change.change_type, change.path, change.name, change.seq_no)
svc.clear_sync(sub.id, subn.id, started.sync_id)
start_sync builds the required {"changes": [...], "clientVersion": ...}
body for you — pass client_version (and optional changes), or a complete
sync_request dict (validated to contain both keys).
The Sync Service URL can also be (re)configured after construction with
client.set_sync_service_url(url), which rebinds a host-aware TicketAuth so
the ticket is only ever sent to the newly-configured Sync Service host.
| Method | HTTP | Endpoint |
|---|---|---|
health() → dict |
GET | {sync_service_url}/healthcheck |
is_available() → bool |
GET | {sync_service_url}/healthcheck |
get_config() → DeviceSyncConfig |
GET | …/versions/1/config/syncService |
get_service_configuration() → DeviceSyncConfig |
GET | …/versions/1/config/syncServiceConfiguration |
metrics() → dict |
GET | …/versions/1/metrics |
start_sync(subscriber_id, subscriptions, client_version=…) → SyncStatus |
POST | …/subscribers/{id}/subscriptions/{query}/sync |
get_sync(subscriber_id, subscriptions, sync_id) → SyncStatus |
GET | …/subscriptions/{query}/sync/{syncId} |
clear_sync(subscriber_id, subscriptions, sync_id) |
DELETE | …/subscriptions/{query}/sync/{syncId} |
Understanding the change feed
The fields and semantics below were verified against a live Alfresco Content Services deployment.
SyncStatus.status (SyncState constants):
| Value | Meaning |
|---|---|
SyncState.OK ("ok") |
Returned by start_sync — the sync was accepted; poll it with get_sync. |
SyncState.NOT_READY ("notReady") |
The service is still preparing changes asynchronously — keep polling. |
SyncState.READY ("ready") |
Changes are available in status.changes. |
SyncState.ERROR ("error") |
Failure (see status.message), e.g. an unknown/cleared syncId or an unregistered subscription. |
Polling is asynchronous: start_sync returns ok, then get_sync may
return notReady several times before ready. Crash-recovery semantics:
re-polling an unknown or cleared syncId returns status == SyncState.ERROR
(message "invalid syncId …") — it does not raise or 404. clear_sync on an
unknown id is idempotent. Concurrent start_sync calls each allocate a distinct
syncId.
Change fields — one entry per affected node:
| Field | Notes |
|---|---|
change_type |
ChangeType value (see below). |
path / to_path |
Absolute repository path (/Company Home/…). Populated even for deletes (pre-delete path). For moves/renames, path=old, to_path=new. |
name / to_name |
Node name; to_name set on rename/move. |
parent_id / parent_ids |
Immediate parent id, then ancestors up to the root. to_parent_id/to_parent_ids for moves. |
is_folder |
Whether the node is a folder. |
node_type |
e.g. cm:content, cm:folder. |
size |
Byte size when known, else -1. |
aspects |
Applied aspect QNames. |
event_at / modified_at |
UTC datetimes parsed from the event / node millisecond timestamps (modified_at is None for deletes). |
seq_no |
Monotonic sequence number; changes are ordered so parents precede their children. |
checksum |
⚠️ Currently a server placeholder ("dummyChecksum") — not a usable content digest. |
ChangeType vocabulary (observed live):
| Constant | Value | Emitted when |
|---|---|---|
ChangeType.CREATE |
CREATE_REPOS |
A node is created. |
ChangeType.UPDATE |
UPDATE_REPOS |
Node content is updated. |
ChangeType.DELETE |
DELETE_REPOS |
A node is deleted. |
ChangeType.MOVE |
MOVE_REPOS |
A node is moved (single change carrying old+new parent/path). |
ChangeType.RENAME |
RENAME_REPOS |
A node is renamed (single change carrying name+to_name). |
ChangeType.CHECKED_IN |
NODECHECKEDIN |
Emitted alongside UPDATE_REPOS when a content update creates a new version. |
A move is a single MOVE_REPOS change (not a delete+create); a rename is a
single RENAME_REPOS. Property-only updates (e.g. changing cm:title) produce
no change. status.resets lists subscriptions the client must re-sync from
scratch and status.missing lists subscriptions the server no longer knows
about (both list[str]).
Delta paging & limits. A single sync is paged: poll get_sync with the same
sync_id while status.more_changes is True, applying status.changes each
round, then clear_sync. There is no client page-size parameter on
start_sync/get_sync, and the Sync Service does not expose a numeric
per-response cap in its configuration — bound your loop on more_changes rather
than a fixed batch size. There is no hasTooManyChanges flag: the
"re-sync from scratch" signal is the status.resets list (per subscription),
and an unrecoverable sync surfaces as status == SyncState.ERROR.
Auth matrix — against the standalone Sync Service (9090):
| Auth | Behaviour |
|---|---|
BasicAuth |
Accepted (200). |
TicketAuth |
Host-aware — sends the ticket as HTTP Basic (base64("<ticket>:")). |
OAuth2Auth / OAuth2 |
Host-aware — sends Authorization: Bearer <token>. On Identity-Service (OIDC) deployments the same IdP-issued token is validated by both the repository and the Sync Service, so one token covers both hosts. (Verified against a Basic-auth deployment where the Sync Service has no IdP configured; positive bearer acceptance requires an Identity-Service-enabled deployment.) |
| unauthenticated | 401 (except /healthcheck, which is open). |
All bundled auth handlers are host-aware: credentials (ticket or bearer) are
only ever sent to the configured repository and Sync Service origins, never to
any other host — including look-alike origins such as
https://sync.example.com.attacker.test. Used standalone (without an Alfresco
client to bind them), OAuth2Auth/OAuth2 fall back to attaching the token to
every request; the client binds them so this confinement takes effect.
Subscriber lifecycle, scoping & orphan recovery
create_subscriber returns a server-assigned id with no client-supplied
identifier — the service rejects unknown body fields (HTTP 400) and does
not correlate an X-Device-Id header, so registration is not idempotent. If
a client crashes between a successful create_subscriber and persisting the
returned id locally, it orphans a subscriber.
To recover, list your own subscribers and delete the stale ones.
list_subscribers() / iter_subscribers() are scoped to the authenticated
user: a regular user sees only the subscribers they created (verified live —
another user's subscribers are absent from the list and a direct get_subscriber
returns 404), so there is no cross-user enumeration. An administrator is
the exception and sees every subscriber on the repository. The endpoint requires
an authenticated session; no extra permission is needed to manage your own
subscribers.
Thread-safety
A single Alfresco instance (and its requests.Session) is safe to share
across threads — e.g. one sync-polling thread alongside a pool of upload/download
workers. The lazy handler cache is lock-guarded and the TicketAuth/OAuth2Auth
handlers synchronise their ticket/token exchange. Configure the client (including
set_sync_service_url) during setup, before sharing it across threads;
runtime reconfiguration is not synchronised against in-flight requests.
Streaming uploads & progress
client.nodes.upload() and client.nodes.update_content() stream the file
body in bounded blocks instead of buffering the whole file in memory, so memory
stays roughly constant regardless of file size. Both accept an optional
progress callback and a chunk_size (default 64 KiB):
def on_progress(bytes_read: int, total_bytes: int) -> None:
pct = (bytes_read * 100 / total_bytes) if total_bytes else 100
print(f"{bytes_read}/{total_bytes} bytes ({pct:.0f}%)")
# New file — from a local path or an open binary stream
node = client.nodes.upload(
folder.id,
file_path="/tmp/large.iso", # or: file_body=open(...), name="large.iso"
progress=on_progress,
chunk_size=1024 * 1024, # 1 MiB reads
)
# Replace an existing node's content, with progress
client.nodes.update_content(
node.id,
file_path="/tmp/large.iso",
mime_type="application/octet-stream",
progress=on_progress,
)
Callback contract:
progress(bytes_read, total_bytes)is invoked after each non-empty block; values are monotonic within an attempt and reach the exact file size. Only file-payload bytes are counted — multipart framing is excluded.- Empty files receive a single
(0, 0)completion notification. - Exceptions raised by the callback abort the upload (they are not swallowed).
- On an automatic 401 re-authentication retry the body is rebuilt and progress restarts from zero — treat a decrease as a retry reset.
- A caller-provided
file_bodymust be seekable (so its length is known and the body can be replayed on retry) and is left open; handles opened by the SDK viafile_pathare always closed.
Both parameters are keyword-only and optional, so existing calls keep working unchanged — the only difference is that request bodies are no longer fully buffered.
Authentication
| Method | Class | Notes |
|---|---|---|
| HTTP Basic | alfresco.BasicAuth(user, password) |
Simple, works everywhere |
| Ticket | alfresco.TicketAuth(user, password) |
Obtains a login ticket automatically |
| OAuth 2.0 | alfresco.OAuth2Auth(...) |
Bearer-token auth (Keycloak / Alfresco Identity Service) |
OAuth 2.0 example
Password (Resource Owner Password Credentials) grant:
from alfresco import Alfresco, OAuth2Auth
auth = OAuth2Auth(
token_url="http://localhost:8081/auth/realms/alfresco/protocol/openid-connect/token",
client_id="alfresco",
username="admin",
password="admin",
)
client = Alfresco("http://localhost:8080", auth=auth)
me = client.people.get("-me-")
Client-credentials grant (service account):
auth = OAuth2Auth(
token_url="https://idp/realms/r/protocol/openid-connect/token",
client_id="my-service",
client_secret="…",
grant_type="client_credentials",
)
Pre-fetched access token (e.g. from a browser-based auth code flow):
auth = OAuth2Auth.from_token(
access_token="eyJhbGciOi…",
refresh_token="…",
token_url="…",
client_id="…",
)
The handler caches the token, refreshes automatically before expiry (with a
30 s skew), and falls back to a full re-authentication if the refresh token
is rejected. Call auth.invalidate() to force a re-auth.
Local development
# Create & activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install build / dev tools
make install-dev
# Install the package in editable mode
pip install -e .
# Run smoke test
python3 tests/test_smoke.py
# Build wheel + sdist (PEP 517)
make build
# Remove build artifacts
make clean
Built packages are placed in dist/.
Releasing
Publishing is automated with GitHub Actions. Both publishing workflows use PyPI Trusted Publishing (OIDC) — there are no API tokens stored in the repo.
Release → PyPI (.github/workflows/release.yml)
Triggered by a push to main whose commit message contains [release], or
manually via Run workflow (workflow_dispatch).
Before releasing, set the correct release version. The version that gets tagged and published is read from
__version__inalfresco/__init__.py, so edit that value to the version you intend to release before triggering the workflow. Thecheckjob fails if the matchingv<version>git tag already exists, so you cannot accidentally re-release an existing version.
- check — reads the version from
alfresco/__init__.py(__version__) and fails if thev<version>git tag already exists. - tests — runs the full suite (
tests.yml). Add[skip test]to the commit message (or setskip_tests=trueon a manual run) to bypass this step. - build — builds the wheel + sdist (PEP 517).
- publish — uploads to PyPI from the
pypienvironment. - tag — creates the
v<version>git tag and a GitHub Release with the built artifacts attached. - bump — after a successful release, advances
__version__onmainto the next development version (auto-increments the patch, e.g.0.1.0 → 0.1.1, or uses thenext_versioninput on a manual run) and pushes aBump version to … [skip ci]commit.
To cut a release: set __version__ to the release version, then land a commit on
main, e.g. git commit -m "Release 0.1.0 [release]". The next development
version is set automatically by the bump step.
Snapshot → TestPyPI (.github/workflows/snapshot.yml)
Publishes dev builds versioned X.Y.Z.dev<run-number> to
TestPyPI from the testpypi environment. It runs when:
- any push lands on
main(automatic), or - a push on a working branch (
feature/**,fix/**,release/**) has a commit message containing[snapshot].
Release commits ([release]) are always skipped here to avoid double-publishing,
and the test suite must pass before a snapshot is published.
Install a snapshot with:
pip install -i https://test.pypi.org/simple/ --pre alfresco-rest-client
All third-party actions are pinned to commit SHAs, and each publishing job runs in a dedicated protected GitHub Environment (
pypi/testpypi).
Metadata
Release files for alfresco-rest-client 1.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| alfresco_rest_client-1.0.4.tar.gz | 88.4 kB | With provenance | Details for alfresco_rest_client-1.0.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| alfresco_rest_client-1.0.4-py3-none-any.whl | Python 3 | none | any | Details for alfresco_rest_client-1.0.4-py3-none-any.whl |
Total release size: 156.3 kB
Release files / alfresco_rest_client-1.0.4.tar.gz
| Download URL | alfresco_rest_client-1.0.4.tar.gz |
|---|---|
| Size | 88.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c54aa39137cb221224eb8ab35fbcdc465105536a40c4f2b6b5129d0c1f3bfd51
|
|
BLAKE2b-256 checksum How to use checksums |
33fa93a98f88ca356648889876de8a45cee5d7ca8b1c8138357fb7003702412e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logRelease files / alfresco_rest_client-1.0.4-py3-none-any.whl
| Download URL | alfresco_rest_client-1.0.4-py3-none-any.whl |
|---|---|
| Size | 67.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dc02d48b7a37cedeb82b4b129f1d5e07fd7305ea36f50ce4332d18cd43996b88
|
|
BLAKE2b-256 checksum How to use checksums |
fd53edc2cda8127ca7da2a3c87d2e835e43c0e5ac0c8bd63cb482bca71d0c9a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logSecurity for alfresco-rest-client 1.0.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for alfresco_rest_client-1.0.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.