Python Alfresco API Client

1.1.5 · active · verified Thu Apr 16

Python Client for all Alfresco Content Services REST APIs, built with Pydantic v2 models for robust data validation and serialization, and offering event support. It provides comprehensive coverage of Alfresco's API endpoints through dedicated subclients. The current version is 1.1.5, with frequent updates incorporating new API features and improvements.

Common errors

```
ModuleNotFoundError: No module named 'alfresco_api.client'
```
cause The `AlfrescoClient` class is not directly in the top-level `alfresco_api` package. It resides in the `client` submodule.

fix Change your import statement to `from alfresco_api.client import AlfrescoClient`.
```
ValidationError: Input should be a valid dictionary
```
cause You are passing data that does not match the Pydantic v2 model's expected schema (e.g., missing required fields, wrong data types, or providing a non-dictionary object when a dictionary is expected for model instantiation).

fix Examine the specific Pydantic model being used (e.g., `NodeBodyCreate`). Ensure all required fields are present with correct data types, and that you are passing a dictionary or keyword arguments that map directly to the model's fields.
```
alfresco_api.exceptions.AlfrescoAPIException: Authentication failed for user 'your_username'
```
cause The credentials (username/password) provided to the `AlfrescoClient` are incorrect or the Alfresco user lacks necessary permissions.

fix Verify the username and password are correct for your Alfresco instance. Check the user's permissions within Alfresco. Ensure `ALFRESCO_USERNAME` and `ALFRESCO_PASSWORD` (or direct arguments) are set correctly.

Warnings

breaking The client is built on Pydantic v2. If you are migrating from a project using Pydantic v1 or an older version of this client, you may encounter `ValidationError` due to changes in model definitions and validation logic.
Fix: Review the Pydantic model definitions (e.g., `NodeBodyCreate`) and update your data structures to conform to Pydantic v2 standards. Consult Pydantic v2 migration guides if necessary.
gotcha Incorrect Alfresco host, username, or password will lead to authentication failures or connection errors. This is a common setup mistake.
Fix: Double-check the `ALFRESCO_HOST`, `ALFRESCO_USERNAME`, and `ALFRESCO_PASSWORD` environment variables or the parameters passed directly to the `AlfrescoClient` constructor. Ensure the Alfresco instance is running and network accessible.
gotcha The `get_node_by_path` method (using `relative_path`) for efficient node retrieval by path was significantly improved and stabilized in v1.1.5. Older versions might have limited or different behavior.
Fix: Upgrade to `python-alfresco-api` version 1.1.5 or newer to leverage the most robust path-based node retrieval. For older versions, you might need to rely on ID-based lookups or custom queries.

Install

pip install python-alfresco-api Install latest version

Imports

AlfrescoClient

wrong:

from alfresco_api import AlfrescoClient

correct:

from alfresco_api.client import AlfrescoClient

The main client class resides in the 'client' submodule.

NodeBodyCreate
wrong:
```
from alfresco_api.models import NodeBodyCreate
```
correct:
```
from alfresco_api.model.nodes import NodeBodyCreate
```
Pydantic models are organized under 'model' and then by specific API resource (e.g., 'nodes').

Quickstart

This quickstart initializes the Alfresco client using environment variables for credentials, then fetches the 'Company Home' node by path and creates a new folder within it. Ensure your Alfresco instance is running and accessible.

import os
from alfresco_api.client import AlfrescoClient
from alfresco_api.model.nodes import NodeBodyCreate

# Configure Alfresco connection via environment variables
ALFRESCO_HOST = os.environ.get('ALFRESCO_HOST', 'http://localhost:8080')
ALFRESCO_USERNAME = os.environ.get('ALFRESCO_USERNAME', 'admin')
ALFRESCO_PASSWORD = os.environ.get('ALFRESCO_PASSWORD', 'admin')

# Initialize the client
try:
    client = AlfrescoClient(
        host=ALFRESCO_HOST,
        username=ALFRESCO_USERNAME,
        password=ALFRESCO_PASSWORD
    )

    # Example: Get the 'Company Home' node by its path (v1.1.5+ feature)
    nodes_api = client.nodes
    company_home_node = nodes_api.get_node_by_path(relative_path='/Company Home')
    print(f"Successfully connected. Company Home Node ID: {company_home_node.entry.id}")

    # Example: Create a new folder
    new_folder_name = 'MyTestFolder'
    folder_create_body = NodeBodyCreate(
        name=new_folder_name,
        node_type='cm:folder',
        properties={'cm:title': 'My Test Folder via Python API'}
    )
    created_folder = nodes_api.create_node(
        node_id=company_home_node.entry.id,
        node_body_create=folder_create_body
    )
    print(f"Created folder '{new_folder_name}' with ID: {created_folder.entry.id}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →