Skip to main content

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_body must be seekable (so its length is known and the body can be replayed on retry) and is left open; handles opened by the SDK via file_path are 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__ in alfresco/__init__.py, so edit that value to the version you intend to release before triggering the workflow. The check job fails if the matching v<version> git tag already exists, so you cannot accidentally re-release an existing version.

  1. check — reads the version from alfresco/__init__.py (__version__) and fails if the v<version> git tag already exists.
  2. tests — runs the full suite (tests.yml). Add [skip test] to the commit message (or set skip_tests=true on a manual run) to bypass this step.
  3. build — builds the wheel + sdist (PEP 517).
  4. publish — uploads to PyPI from the pypi environment.
  5. tag — creates the v<version> git tag and a GitHub Release with the built artifacts attached.
  6. bump — after a successful release, advances __version__ on main to the next development version (auto-increments the patch, e.g. 0.1.0 → 0.1.1, or uses the next_version input on a manual run) and pushes a Bump 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)

Source distribution for alfresco-rest-client 1.0.1
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)

Table of built distributions (wheels) for alfresco-rest-client 1.0.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page