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)
# 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!")
# 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()
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.1
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.1.tar.gz | 63.1 kB | With provenance | Details for alfresco_rest_client-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| alfresco_rest_client-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for alfresco_rest_client-1.0.1-py3-none-any.whl |
Total release size: 113.7 kB
Release files / alfresco_rest_client-1.0.1.tar.gz
| Download URL | alfresco_rest_client-1.0.1.tar.gz |
|---|---|
| Size | 63.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ee67ecc5c845ba335497512eb5ebd533354b5c0d2c0e8361bcb22450127bb06
|
|
BLAKE2b-256 checksum How to use checksums |
6f1e16ea3102f3b66b79a4a709efe0345537dc876971c5ad3c44568a161a888d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
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 Aug 5, 2026.
Transparency logRelease files / alfresco_rest_client-1.0.1-py3-none-any.whl
| Download URL | alfresco_rest_client-1.0.1-py3-none-any.whl |
|---|---|
| Size | 50.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
989ff2bde79750ffc74b074b9780f23a7634986645b03c9d3d0d63cef950f557
|
|
BLAKE2b-256 checksum How to use checksums |
e8e48125c4696bff88efda2febc31bc403af7ff0d2a1fc2acbf075c67b32cf41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
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 Aug 5, 2026.
Transparency logSecurity for alfresco-rest-client 1.0.1
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.1.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 Aug 5, 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.