python-alfresco-api 1.1.5__py3-none-any.whl → 1.2.0__py3-none-any.whl

python_alfresco_api/__init__.py

@@ -36,7 +36,7 @@ from .clients.conversion_utils import (
 # Import raw_clients to ensure they get packaged
 from . import raw_clients
 
-__version__ = "1.1.1"
+__version__ = "1.2.0"
 __all__ = [
     # Factory & utilities
     "ClientFactory",

python_alfresco_api/auth_util.py

@@ -7,6 +7,7 @@ Handles ticket-based authentication with automatic renewal.
 
 import asyncio
 import base64
+import json
 import os
 from typing import Optional, Dict, Any, Union
 from datetime import datetime, timedelta
@@ -276,31 +277,77 @@ class TicketAuthUtil:
     Handles both Basic auth and ticket-based authentication.
     """
     
-    def __init__(self, username: str, password: str, base_url: str = ""):
+    def __init__(self, username: str, password: str, base_url: str = "",
+                 verify_ssl: Union[bool, str] = True, timeout: Optional[int] = None):
         """
         Initialize ticket auth utility.
-        
+
         Args:
             username: Alfresco username
-            password: Alfresco password  
-            base_url: Base URL for Alfresco (optional, for future ticket API calls)
+            password: Alfresco password
+            base_url: Base URL for Alfresco (required to self-fetch a ticket)
+            verify_ssl: SSL verification - True, False, or path to certificate bundle
+            timeout: Request timeout in seconds (None = use system defaults)
         """
         self.username = username
         self.password = password
         self.base_url = base_url.rstrip('/')
+        self.verify_ssl = verify_ssl
+        self.timeout = timeout
         self.ticket = None
+        self.ticket_expires = None
         self._authenticated = False
-    
+
+    def authenticate_sync(self) -> bool:
+        """Synchronously fetch an Alfresco login ticket from username/password."""
+        if not self.base_url:
+            return False
+        try:
+            auth_url = f"{self.base_url}/alfresco/api/-default-/public/authentication/versions/1/tickets"
+            client_kwargs = {"verify": self.verify_ssl}
+            if self.timeout is not None:
+                client_kwargs["timeout"] = self.timeout
+            with httpx.Client(**client_kwargs) as client:
+                response = client.post(auth_url, json={"userId": self.username, "password": self.password})
+                if response.status_code == 201:
+                    self.ticket = response.json()["entry"]["id"]
+                    self.ticket_expires = datetime.now() + timedelta(hours=1)
+                    self._authenticated = True
+                    return True
+                print(f"Alfresco ticket authentication failed: {response.status_code} {response.text}")
+        except Exception as e:
+            print(f"Alfresco ticket authentication failed: {e}")
+        self._authenticated = False
+        return False
+
+    def ensure_authenticated_sync(self) -> bool:
+        """Ensure a valid ticket, fetching one if needed."""
+        if self.is_authenticated():
+            return True
+        return self.authenticate_sync()
+
     def get_basic_auth_header(self):
         """Get basic auth header for initial authentication."""
         auth_string = f"{self.username}:{self.password}"
         auth_b64 = base64.b64encode(auth_string.encode()).decode()
         return f'Basic {auth_b64}'
-    
+
     def get_auth_token(self):
-        """Get just the base64 auth token (without 'Basic ' prefix) for AuthenticatedClient."""
-        auth_string = f"{self.username}:{self.password}"
-        return base64.b64encode(auth_string.encode()).decode()
+        """Get the base64 token (no 'Basic ' prefix) for AuthenticatedClient.
+
+        Alfresco accepts a login ticket as `Authorization: Basic base64(<ticket>)`. We lazily
+        fetch a ticket (when base_url is set) and return base64(ticket); if that fails we fall
+        back to base64(username:password) so the client still authenticates.
+        """
+        if not self.is_authenticated() and self.base_url:
+            try:
+                self.ensure_authenticated_sync()
+            except Exception as e:
+                print(f"Alfresco ticket acquisition failed: {e}")
+        if self.is_authenticated() and self.ticket:
+            return base64.b64encode(self.ticket.encode()).decode()
+        # Fallback: basic credentials
+        return base64.b64encode(f"{self.username}:{self.password}".encode()).decode()
     
     def get_ticket_header(self):
         """Get ticket auth header if we have a ticket."""
@@ -332,8 +379,13 @@ class TicketAuthUtil:
                 self._authenticated = True
     
     def is_authenticated(self):
-        """Check if we have a valid ticket."""
-        return self._authenticated and self.ticket is not None
+        """Check if we have a valid (unexpired) ticket."""
+        if not self._authenticated or not self.ticket:
+            return False
+        if self.ticket_expires and datetime.now() >= self.ticket_expires:
+            self._authenticated = False
+            return False
+        return True
 
 class OAuth2AuthUtil:
     """
@@ -416,7 +468,18 @@ class OAuth2AuthUtil:
         
         # For environment variable loading
         self._load_oauth_env_config(load_env, env_file)
-    
+
+        # If an access token was supplied (constructor or env), mark it usable so the
+        # synchronous client-build path can use it immediately. Previously a provided token
+        # was ignored because _authenticated stayed False.
+        if self.access_token:
+            self._authenticated = True
+            # Derive expiry from the token's own JWT `exp` claim when no expires_in was given,
+            # so a *provided* (pasted) token that has since expired is detected as stale and
+            # refreshed via refresh_token — instead of being used blindly and 401ing.
+            if self.token_expires is None:
+                self.token_expires = self._expiry_from_jwt(self.access_token)
+
     def _load_oauth_env_config(self, load_env: bool, env_file: Optional[str]):
         """Load OAuth2-specific configuration from environment."""
         if not load_env:
@@ -569,26 +632,143 @@ class OAuth2AuthUtil:
                 
                 self._authenticated = True
                 return True
-        
+
         return False
-    
+
+    @staticmethod
+    def _expiry_from_jwt(token: str) -> Optional[datetime]:
+        """Best-effort read of a JWT access token's `exp` claim as a local naive datetime.
+
+        Lets a provided access token (which carries no expires_in) still be expiry-checked so
+        it can be refreshed when stale. Returns None for opaque (non-JWT) tokens or on any error.
+        """
+        try:
+            parts = token.split(".")
+            if len(parts) != 3:
+                return None
+            payload_b64 = parts[1]
+            payload_b64 += "=" * (-len(payload_b64) % 4)  # restore base64 padding
+            payload = json.loads(base64.urlsafe_b64decode(payload_b64))
+            exp = payload.get("exp")
+            return datetime.fromtimestamp(exp) if exp else None
+        except Exception:
+            return None
+
+    def _apply_token_response(self, token_data: Dict[str, Any]) -> None:
+        """Apply an OAuth2 token-endpoint response to this util's token state."""
+        self.access_token = token_data.get("access_token")
+        expires_in = token_data.get("expires_in")
+        if expires_in:
+            self.token_expires = datetime.now() + timedelta(seconds=expires_in)
+        elif self.access_token:
+            self.token_expires = self._expiry_from_jwt(self.access_token)
+        if "refresh_token" in token_data:
+            self.refresh_token = token_data["refresh_token"]
+        self._authenticated = bool(self.access_token)
+
+    # --- Synchronous token acquisition ---------------------------------------
+    # The sub-clients call get_auth_token() synchronously at client-build time, so the async
+    # authenticate()/ensure_authenticated() above never fire on their own. These sync variants
+    # let get_auth_token() lazily acquire/refresh a token so OAuth2 works end-to-end without the
+    # caller having to pre-await authenticate().
+
+    def _client_credentials_flow_sync(self) -> bool:
+        """Synchronous OAuth2 client-credentials flow."""
+        if not self.client_id or not self.client_secret or not self.token_endpoint:
+            raise ValueError(
+                "Client credentials flow requires client_id, client_secret, and token_endpoint"
+            )
+        data = {
+            "grant_type": "client_credentials",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+        if self.scope:
+            data["scope"] = self.scope
+        client_kwargs = {"verify": self.verify_ssl}
+        if self.timeout is not None:
+            client_kwargs["timeout"] = self.timeout
+        with httpx.Client(**client_kwargs) as client:
+            response = client.post(
+                self.token_endpoint, data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+            if response.status_code == 200:
+                self._apply_token_response(response.json())
+                return True
+        return False
+
+    def _refresh_token_flow_sync(self) -> bool:
+        """Synchronous refresh-token flow."""
+        if not self.refresh_token or not self.token_endpoint:
+            return False
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": self.refresh_token,
+            "client_id": self.client_id,
+        }
+        if self.client_secret:
+            data["client_secret"] = self.client_secret
+        client_kwargs = {"verify": self.verify_ssl}
+        if self.timeout is not None:
+            client_kwargs["timeout"] = self.timeout
+        with httpx.Client(**client_kwargs) as client:
+            response = client.post(
+                self.token_endpoint, data=data,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+            if response.status_code == 200:
+                self._apply_token_response(response.json())
+                return True
+        return False
+
+    def authenticate_sync(self) -> bool:
+        """Synchronous authenticate() — dispatches by grant type."""
+        try:
+            if self.grant_type == "client_credentials":
+                return self._client_credentials_flow_sync()
+            elif self.grant_type == "refresh_token" and self.refresh_token:
+                return self._refresh_token_flow_sync()
+            elif self.grant_type == "authorization_code":
+                # Requires prior user interaction; usable only if an access_token was supplied.
+                return self.is_authenticated()
+            else:
+                raise ValueError(f"Unsupported grant type: {self.grant_type}")
+        except Exception as e:
+            print(f"OAuth2 authentication failed: {e}")
+            self._authenticated = False
+            return False
+
+    def ensure_authenticated_sync(self) -> bool:
+        """Synchronous ensure_authenticated() — refresh if possible, else authenticate."""
+        if self.is_authenticated():
+            return True
+        if self.refresh_token:
+            if self._refresh_token_flow_sync():
+                return True
+        return self.authenticate_sync()
+
     def is_authenticated(self) -> bool:
         """Check if currently authenticated with valid access token."""
         if not self._authenticated or not self.access_token:
             return False
         
-        # Check token expiration
-        if self.token_expires and datetime.now() >= self.token_expires:
+        # Check token expiration (30s skew so we refresh just before it actually expires)
+        if self.token_expires and datetime.now() >= (self.token_expires - timedelta(seconds=30)):
             self._authenticated = False
             return False
-        
+
         return True
     
     def get_auth_headers(self) -> Dict[str, str]:
-        """Get authentication headers for API requests."""
+        """Get authentication headers for API requests (lazily acquiring a token if needed)."""
+        if not self.is_authenticated():
+            try:
+                self.ensure_authenticated_sync()
+            except Exception as e:
+                print(f"OAuth2 token acquisition failed: {e}")
         if not self.is_authenticated():
             return {}
-        
         return {
             "Authorization": f"Bearer {self.access_token}"
         }
@@ -600,10 +780,18 @@ class OAuth2AuthUtil:
         return ""
     
     def get_auth_token(self):
-        """Get just the access token (without 'Bearer ' prefix) for AuthenticatedClient."""
-        if self.is_authenticated():
-            return self.access_token
-        return ""
+        """Get the access token (no 'Bearer ' prefix) for AuthenticatedClient.
+
+        Lazily acquires/refreshes the token synchronously when needed, so the sub-clients'
+        synchronous build path produces a real Bearer header. Previously this returned "" unless
+        the caller had manually pre-awaited authenticate(), which nothing in the build path did.
+        """
+        if not self.is_authenticated():
+            try:
+                self.ensure_authenticated_sync()
+            except Exception as e:
+                print(f"OAuth2 token acquisition failed: {e}")
+        return self.access_token if self.is_authenticated() else ""
     
     def get_auth_prefix(self):
         """Get authentication prefix for headers. OAuth2AuthUtil uses Bearer tokens."""

python_alfresco_api/clients/core/actions/actions_client.py

@@ -303,5 +303,5 @@ class ActionsClient:
     
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"AlfrescoActionsClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/activities/activities_client.py

@@ -124,5 +124,5 @@ class ActivitiesClient:
     
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"AlfrescoActivitiesClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/comments/comments_client.py

@@ -303,5 +303,5 @@ class CommentsClient:
     
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"AlfrescoCommentsClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/content/content_client.py

@@ -458,5 +458,5 @@ class ContentClient:
     
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"AlfrescoContentClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/downloads/downloads_client.py

@@ -173,5 +173,5 @@ class DownloadsClient:
 
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"DownloadsClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/probes/probes_client.py

@@ -85,5 +85,5 @@ class ProbesClient:
 
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"ProbesClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/queries/queries_client.py

@@ -260,5 +260,5 @@ class QueriesClient:
 
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"QueriesClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/ratings/ratings_client.py

@@ -238,5 +238,5 @@ class RatingsClient:
 
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"RatingsClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/renditions/renditions_client.py

@@ -153,5 +153,5 @@ class RenditionsClient:
 
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"RenditionsClient(base_url='{base_url}')" 

python_alfresco_api/clients/core/versions/versions_client.py

@@ -31,8 +31,8 @@ class VersionsClient:
         return self.parent_client.raw_client
     
     def _get_core_client(self):
-        """Get the core client from the factory."""
-        return self._client_factory.create_core_client()
+        """Get the parent core client."""
+        return self.parent_client
     
     # ==================== SYNC METHODS ====================
     
@@ -110,9 +110,8 @@ class VersionsClient:
             CheckoutResponse: Response with checkout details
         """
         from ....utils import version_utils
-        
-        # Get core client from the same factory
-        core_client = self._client_factory.create_core_client()
+
+        core_client = self._get_core_client()
         
         # Use utility function for implementation
         result = version_utils.checkout_document(core_client, node_id)
@@ -140,9 +139,8 @@ class VersionsClient:
             CheckoutResponse: Response with unlock details
         """
         from ....utils import version_utils
-        
-        # Get core client from the same factory
-        core_client = self._client_factory.create_core_client()
+
+        core_client = self._get_core_client()
         
         # Use utility function for implementation
         result = version_utils.cancel_checkout(core_client, node_id)
@@ -178,9 +176,8 @@ class VersionsClient:
             CheckinResponse: Response with new version details
         """
         from ....utils import version_utils
-        
-        # Get core client from the same factory
-        core_client = self._client_factory.create_core_client()
+
+        core_client = self._get_core_client()
         
         # Use utility function for implementation
         result = version_utils.checkin_document(
@@ -256,46 +253,23 @@ class VersionsClient:
         except Exception as e:
             raise ValueError(f"Failed to enable versioning on node {node_id}: {str(e)}")
     
-    async def checkout_async(self, node_id: str) -> CheckoutResponse:
+    async def checkout_async(self, node_id: str, **kwargs) -> CheckoutResponse:
         """Async version of checkout."""
-        # For now, return a mock response structure
-        return CheckoutResponse(
-            node_id=node_id,
-            locked=True,
-            working_copy_id=f"{node_id}-working-copy",
-            locked_by="current_user",
-            locked_at=datetime.now()
-        )
+        return self.checkout(node_id, **kwargs)
     
-    async def cancel_checkout_async(self, node_id: str) -> CheckoutResponse:
+    async def cancel_checkout_async(self, node_id: str, **kwargs) -> CheckoutResponse:
         """Async version of cancel_checkout."""
-        # For now, return a mock response structure
-        return CheckoutResponse(
-            node_id=node_id,
-            locked=False,
-            working_copy_id=None,
-            locked_by=None,
-            locked_at=None
-        )
+        return self.cancel_checkout(node_id, **kwargs)
     
     async def checkin_async(
         self, 
         node_id: str, 
         comment: Optional[str] = None,
-        major_version: bool = False
+        major_version: bool = False,
+        **kwargs
     ) -> CheckinResponse:
         """Async version of checkin."""
-        # For now, return a mock response structure
-        version_number = "2.0" if major_version else "1.1"
-        
-        return CheckinResponse(
-            node_id=node_id,
-            version_number=version_number,
-            comment=comment or "No comment",
-            major_version=major_version,
-            created_at=datetime.now(),
-            created_by="current_user"
-        )
+        return self.checkin(node_id, comment=comment, major_version=major_version, **kwargs)
     
     # ==================== DETAILED METHODS - Moved from AlfrescoCoreClient ====================
     
@@ -399,5 +373,5 @@ class VersionsClient:
 
     def __repr__(self) -> str:
         """String representation for debugging."""
-        base_url = getattr(self._client_factory, 'base_url', 'unknown')
+        base_url = getattr(self.parent_client._client_factory, 'base_url', 'unknown')
         return f"AlfrescoVersionsClient(base_url='{base_url}')" 

python_alfresco_api/events/__init__.py

@@ -1,8 +1,9 @@
 """
 Alfresco Event System
 
-Unified event client supporting both Community Edition (ActiveMQ) and Enterprise Edition (Event Gateway).
-Provides automatic detection and graceful fallback capabilities.
+Event client for Alfresco's ActiveMQ messaging (repo events on the STOMP topic
+/topic/alfresco.repo.event2). Detects ActiveMQ availability and registers handlers; consumers
+subscribe to the STOMP topic directly (see AlfrescoEventClient for details).
 """
 
 from .event_client import AlfrescoEventClient