Python-Alfresco-API v1.1

🚀 Features

📚 Documentation & Examples

🤖 MCP Server / LLM Integration

See python-alfresco-mcp-server

📦 Installation

Quick Install from PyPI

pip install python-alfresco-api

Virtual Environment Setup (Recommended)

Windows

# Clone the repository
git clone https://github.com/stevereiner/python-alfresco-api.git
cd python-alfresco-api
# Create virtual environment
python -m venv venv
# Activate virtual environment
venv\Scripts\activate
# Verify activation (should show venv path)
where python
# Install dependencies
pip install -r requirements.txt
# Deactivate when done
deactivate

Linux / MacOS

# Clone the repository
git clone https://github.com/stevereiner/python-alfresco-api.git
cd python-alfresco-api
# Create virtual environment
python3 -m venv venv
# Activate virtual environment
source venv/bin/activate
# Verify activation (should show venv path)
which python
# Install dependencies
pip install -r requirements.txt
# Deactivate when done
deactivate

Package Installation

pip install python-alfresco-api

Development with source

# After setting up virtual environment above
git clone https://github.com/your-org/python-alfresco-api.git
cd python-alfresco-api
# Activate your virtual environment first
# Windows: venv\Scripts\activate
# Linux/macOS: source venv/bin/activate
# Install in development mode
pip install -e .

Alfresco Installation

git clone https://github.com/Alfresco/acs-deployment.git

cd acs-deployment/docker-compose

 ports:
 - "8161:8161" # Web Console
 #- "5672:5672" # AMQP
 #- "61616:61616" # OpenWire
 #- "61613:61613" # STOMP
 docker-compose -f community-compose.yaml up

🎯 Environment Setup

Environment Configuration (Recommended)

# Windows
copy sample-dot-env.txt .env
# Mac and Linux
cp sample-dot-env.txt .env
# Edit .env and your Alfresco settings

Factory Pattern

from python_alfresco_api import ClientFactory
# Automatic configuration (loads from .env file or environment variables)
factory = ClientFactory() # Uses ALFRESCO_URL, ALFRESCO_USERNAME, etc.
# Or explicit configuration
factory = ClientFactory(
 base_url="http://localhost:8080",
 username="admin",
 password="admin"
)
Note 1: the priority order of ClientFactory parameters: 1. in auth_util passed in, 2. in other parameters passed into ClientFactory, 3. in enviroment .env, etc.
Note 2. For timeout, if not in 1-3, no default will be used. The settings for tickets or your system will be used.
# Create individual clients (all share same authentication session)
auth_client = factory.create_auth_client()
core_client = factory.create_core_client()
search_client = factory.create_search_client()
workflow_client = factory.create_workflow_client()
discovery_client = factory.create_discovery_client()
model_client = factory.create_model_client()
search_sql_client = factory.create_search_sql_client() # SOLR admin only
# Can also use a master client like setup with all clients initialized
master_client = factory.create_master_client()

Authentication

from python_alfresco_api import AuthUtil, ClientFactory
# Primary authentication pattern - Basic Auth with Alfresco
auth_util = AuthUtil(
 base_url="http://localhost:8080",
 username="admin",
 password="admin"
)
Note 1: the priority order of ClientFactory parameters: 1. in auth_util passed in, 2. in other parameters passed into ClientFactory, 3. in enviroment .env, etc.
Note 2. For timeout, if not in 1-3, no default will be used. The settings for tickets or your system will be used.
# Use with factory for shared authentication
factory = ClientFactory(auth_util=auth_util)
clients = factory.create_all_clients()

Sync and Async Usage

import asyncio
from python_alfresco_api import ClientFactory
async def main():
 factory = ClientFactory(
 base_url="http://localhost:8080",
 username="admin",
 password="admin"
 )
 
 # Create core client for node operations
 core_client = factory.create_core_client()
 
 # Sync node operation
 sync_node = core_client.get_node("-my-")
 print(f"Sync: User folder '{sync_node.entry.name}'")
 
 # Async node operation
 async_node = await core_client.get_node_async("-my-")
 print(f"Async: User folder '{async_node.entry.name}'")
# Run the async example
asyncio.run(main())

🎯 Key Operations & Examples

Essential Operation Samples

Basic Setup

from python_alfresco_api import ClientFactory
from python_alfresco_api.utils import content_utils_highlevel
factory = ClientFactory(base_url="http://localhost:8080", username="admin", password="admin")
core_client = factory.create_core_client()

Create Folder & Upload Document

# Create folder (High-Level Utility)
folder_result = content_utils_highlevel.create_folder_highlevel(
 core_client=core_client,
 name="My Project Folder", 
 parent_id="-my-"
)
# Upload document with auto-versioning
document_result = content_utils_highlevel.create_and_upload_file_highlevel(
 core_client=core_client,
 file_path="/path/to/document.pdf",
 parent_id=folder_result['id']
)

Search Content

from python_alfresco_api.utils import search_utils
search_client = factory.create_search_client()
# Simple text search (already optimized!)
results = search_utils.simple_search(
 search_client=search_client,
 query_str="finance AND reports",
 max_items=25
)

Download Document

# Download document content
content_response = core_client.nodes.get_content(node_id=document_id)
# Save to file
with open("downloaded_document.pdf", "wb") as file:
 file.write(content_response.content)

Get & Set Properties

from python_alfresco_api.utils import content_utils_highlevel
# Get node properties and details
node_info = content_utils_highlevel.get_node_info_highlevel(
 core_client=core_client,
 node_id=document_id
)
print(f"Title: {node_info.get('properties', {}).get('cm:title', 'No title')}")
# Update node properties
update_request = {
 "properties": {
 "cm:title": "Updated Document Title",
 "cm:description": "Updated via Python API"
 }
}
updated_node = core_client.nodes.update(node_id=document_id, request=update_request)

Document Versioning - Checkout & Checkin

from python_alfresco_api.utils import version_utils_highlevel
# Checkout document (lock for editing)
checkout_result = version_utils_highlevel.checkout_document_highlevel(
 core_client=core_client,
 node_id=document_id
)
# Later: Checkin with updated content (create new version)
checkin_result = version_utils_highlevel.checkin_document_highlevel(
 core_client=core_client,
 node_id=document_id,
 content="Updated document content",
 comment="Fixed formatting and added new section"
)

📚 Complete Documentation & Examples

🎯 Production-Ready Examples (examples/operations/)

🔄 Model Architecture & Conversion (V1.1)

# ✅ V1.1: Two model systems with conversion utilities
from python_alfresco_api.models.alfresco_core_models import NodeBodyCreate # Pydantic
from python_alfresco_api.raw_clients.alfresco_core_client.models import NodeBodyCreate as AttrsNodeBodyCreate # attrs
from python_alfresco_api.clients.conversion_utils import pydantic_to_attrs_dict
# 1. Use Pydantic for validation and AI integration
pydantic_model = NodeBodyCreate(name="document.pdf", nodeType="cm:content")
# 2. Convert for raw client usage 
factory = ClientFactory()
core_client = factory.create_core_client()
# Option A: Manual conversion via model_dump()
result = core_client.create_node(pydantic_model.model_dump())
# Option B: Conversion utilities (V1.1)
attrs_dict = pydantic_to_attrs_dict(pydantic_model, target_class_name="NodeBodyCreate") 
result = core_client.create_node(attrs_dict)
# 3. Raw clients return attrs-based domain models
repository_info = discovery_client.get_repository_information() # Returns attrs RepositoryInfo
# Convert to dict for further processing
repo_dict = repository_info.to_dict()

V1.2 Roadmap: Unified Pydantic Architecture

# 🎯 V1.2 Target: Single Pydantic model system
from python_alfresco_api.raw_clients.alfresco_core_client.models import NodeBodyCreate # Will be Pydantic!
# No conversion needed - everything is Pydantic BaseModel
pydantic_model = NodeBodyCreate(name="document.pdf", nodeType="cm:content")
result = core_client.create_node(pydantic_model) # Direct usage!

🔌 Event System

ActiveMQ Integration (Community Edition)

from python_alfresco_api.activemq_events import AlfrescoActiveMQEventClient
# Create event client
event_client = AlfrescoActiveMQEventClient(
 activemq_host="localhost",
 activemq_port=61616,
 username="admin",
 password="admin"
)
# Register event handler
async def node_created_handler(notification):
 print(f"Node created: {notification.nodeId}")
event_client.register_event_handler("alfresco.node.created", node_created_handler)
# Start listening
await event_client.connect()
await event_client.start_listening()

Event Gateway (Enterprise Edition)

from python_alfresco_api.event_client import AlfrescoEventClient
# Unified event client (auto-detects available systems)
event_client = AlfrescoEventClient()
# Works with both Community (ActiveMQ) and Enterprise (Event Gateway)
await event_client.create_subscription("node-events")
await event_client.start_listening()

🔧 For Developing the Python Alfresco API Package

🧪 Development and Testing

Development Setup

pip install -r requirements-dev.txt

git clone https://github.com/stevereiner/python-alfresco-api.git
cd python-alfresco-api
# Install in development mode
pip install -e .

Run Tests

cd python-alfresco-api
# Simple - just run all tests pytest
pytest
# Run all tests with coverage
pytest --cov=python_alfresco_api --cov-report=html
# Custom test runner with additional features
python run_tests.py
# Features:
# - Environment validation (venv, dependencies)
# - Colored output with progress tracking
# - Test selection for 44%+ coverage baseline
# - Performance metrics (client creation speed)
# - Live Alfresco server detection
# - HTML coverage reports (htmlcov/index.html)
# - Test summary with next steps

Live Integration Tests

# Run one test (test live with Alfresco)
pytest tests/test_mcp_v11_true_high_level_apis_fixed.py -v

🔄 Project Structure

python-alfresco-api/
├── python_alfresco_api/
│ ├── __init__.py # Main exports
│ ├── auth_util.py # Authentication utility
│ ├── client_factory.py # Client factory pattern
│ ├── clients/ # Individual API clients + utilities
│ │ ├── auth_client.py
│ │ ├── core_client.py
│ │ ├── discovery_client.py
│ │ ├── search_client.py
│ │ ├── workflow_client.py
│ │ ├── model_client.py
│ │ ├── search_sql_client.py
│ │ └── conversion_utils.py # Pydantic ↔ attrs conversion utilities
│ ├── models/ # Pydantic v2 models (available for separate use)
│ │ ├── alfresco_auth_models.py
│ │ ├── alfresco_core_models.py
│ │ ├── alfresco_discovery_models.py
│ │ ├── alfresco_search_models.py
│ │ ├── alfresco_workflow_models.py
│ │ ├── alfresco_model_models.py
│ │ └── alfresco_search_sql_models.py
│ ├── raw_clients/ # Generated HTTP clients
│ ├── utils/ # Utility functions
│ │ ├── content_utils.py
│ │ ├── node_utils.py
│ │ ├── search_utils.py
│ │ ├── version_utils.py
│ │ └── mcp_formatters.py
│ └── events/ # Event system (Community + Enterprise)
│ ├── __init__.py # Event exports
│ ├── event_client.py # Unified event client (AlfrescoEventClient)
│ └── models.py # Event models (EventSubscription, EventNotification)
├── config/ # Code generation configurations
│ ├── auth.yaml # Auth API config → auth_client
│ ├── core.yaml # Core API config → core_client
│ ├── discovery.yaml # Discovery API config → discovery_client
│ ├── search.yaml # Search API config → search_client
│ ├── workflow.yaml # Workflow API config → workflow_client
│ ├── model.yaml # Model API config → model_client
│ ├── search_sql.yaml # Search SQL API config → search_sql_client
│ ├── general.yaml # Unified config → alfresco_client
│ └── README.md # Configuration documentation
├── openapi/ # OpenAPI specifications (checked in)
│ ├── openapi2/ # Original OpenAPI 2.0 specs
│ ├── openapi2-processed/ # Cleaned OpenAPI 2.0 specs
│ └── openapi3/ # Converted OpenAPI 3.0 specs
├── tests/ # Comprehensive test suite
├── scripts/ # Generation scripts
├── docs/ # Comprehensive documentation
│ ├── PYDANTIC_MODELS_GUIDE.md # Complete Pydantic models guide
│ ├── CLIENT_TYPES_GUIDE.md # Client architecture guide 
│ ├── CONVERSION_UTILITIES_DESIGN.md # Model conversion utilities
│ ├── REQUEST_TYPES_GUIDE.md # Node & Search request documentation
│ └── API_DOCUMENTATION_INDEX.md # Complete API reference
├── examples/ # Working usage examples
├── requirements.txt # Runtime dependencies
├── requirements-dev.txt # Development dependencies
├── run_tests.py # Test runner with nice display
└── README.md # This file

📋 Requirements

Runtime Requirements

Optional Dependencies

🛠️ Contributing

🤝 Contributing

📄 License

🆘 Support

🔗 Related Projects

⭐ Star History