🔍 Code Extractor

function get_filecloud_document_path

Maturity: 58

Constructs and returns the FileCloud storage path for a controlled document, supporting both custom and standard folder structures with version-specific file paths.

File:
/tf/active/vicechatdev/CDocs/controllers/filecloud_controller.py
Lines:
92 - 159
Complexity:
moderate

Purpose

This function generates the complete FileCloud path for a controlled document file. It handles two path structures: custom paths (when doc.custom_path is set) and standard hierarchical paths (department/doc_type/doc_number). For published documents with custom paths, it returns the PDF path directly in the custom folder. For other cases, it creates a document-specific subfolder. The function supports retrieving specific versions or the current version of a document, and validates that the requested document and version exist before returning the path.

Source Code

def get_filecloud_document_path(document: Union[ControlledDocument, str], version: Optional[str] = None) -> str:
    """
    Get the path in FileCloud for a document.
    
    Args:
        document: Document instance or UID
        version: Optional specific version number
        
    Returns:
        FileCloud path for document
    """
    # Get document if UID was provided
    if isinstance(document, str):
        doc = ControlledDocument(uid=document)
        if not doc:
            raise ResourceNotFoundError(f"Document not found: {document}")
    else:
        doc = document
    
    
    # Check if document has a custom path
    if doc.custom_path:
        # Create path structure for custom path
        # For editable versions, create a folder with the document number
        document_folder = f"{doc.custom_path}/{doc.doc_number}"
        
        # If it's a published document and we need the PDF version, 
        # place it directly in the custom path
        if doc.is_published() and version is None:
            current_version = doc.current_version
            if current_version:
                return f"{doc.custom_path}/{doc.doc_number}_v{current_version.version_number}.pdf"
        
        # For specific version request or editable document
        if version:
            version_obj = doc.get_version_by_number(version)
            if not version_obj:
                raise ResourceNotFoundError(f"Version {version} not found for document {doc.uid}")
            
            return f"{document_folder}/{doc.doc_number}_v{version_obj.version_number}.{version_obj.file_type}"
        
        # Get current version
        current_version = doc.current_version
        if not current_version:
            raise ResourceNotFoundError(f"No current version found for document {doc.uid}")
        
        return f"{document_folder}/{doc.doc_number}_v{current_version.version_number}.{current_version.file_type}"
    
    # Original path logic for standard structure
    # (Keep existing code)
    department_folder = f"/{settings.FILECLOUD_ROOT_FOLDER}/{doc.department}"
    doc_type_folder = f"{department_folder}/{doc.doc_type}"
    document_folder = f"{doc_type_folder}/{doc.doc_number}"
    
    # Handle specific version request
    if version:
        version_obj = doc.get_version_by_number(version)
        if not version_obj:
            raise ResourceNotFoundError(f"Version {version} not found for document {doc.uid}")
        
        return f"{document_folder}/{doc.doc_number}_v{version_obj.version_number}.{version_obj.file_type}"
    
    # Get current version
    current_version = doc.current_version
    if not current_version:
        raise ResourceNotFoundError(f"No current version found for document {doc.uid}")
    
    return f"{document_folder}/{doc.doc_number}_v{current_version.version_number}.{current_version.file_type}"

Parameters

Name Type Default Kind
document Union[ControlledDocument, str] - positional_or_keyword
version Optional[str] None positional_or_keyword

Parameter Details

document: Either a ControlledDocument instance or a string UID of the document. If a string UID is provided, the function will attempt to load the ControlledDocument from the database. The document must exist or a ResourceNotFoundError will be raised.

version: Optional string specifying a particular version number to retrieve. If None (default), the function returns the path to the current version. If specified, must match an existing version number for the document or a ResourceNotFoundError will be raised.

Return Value

Type: str

Returns a string representing the full FileCloud path to the document file. The path format varies based on whether the document has a custom_path set. For custom paths with published documents (no version specified), returns '{custom_path}/{doc_number}_v{version}.pdf'. For custom paths with specific versions or editable documents, returns '{custom_path}/{doc_number}/{doc_number}_v{version}.{file_type}'. For standard paths, returns '/{FILECLOUD_ROOT_FOLDER}/{department}/{doc_type}/{doc_number}/{doc_number}_v{version}.{file_type}'.

Dependencies

  • CDocs.models.document
  • CDocs.config.settings
  • CDocs.controllers

Required Imports

from typing import Union, Optional
from CDocs.models.document import ControlledDocument
from CDocs.config import settings
from CDocs.controllers import ResourceNotFoundError
from CDocs.controllers import log_controller_action

Usage Example

# Example 1: Get path for current version using document instance
from CDocs.models.document import ControlledDocument
from your_module import get_filecloud_document_path

doc = ControlledDocument(uid='DOC-12345')
path = get_filecloud_document_path(doc)
print(path)  # Output: /ControlledDocs/Engineering/SOP/SOP-001/SOP-001_v2.docx

# Example 2: Get path using document UID string
path = get_filecloud_document_path('DOC-12345')

# Example 3: Get path for specific version
path = get_filecloud_document_path(doc, version='1')
print(path)  # Output: /ControlledDocs/Engineering/SOP/SOP-001/SOP-001_v1.docx

# Example 4: Document with custom path (published)
doc_custom = ControlledDocument(uid='DOC-67890')
doc_custom.custom_path = '/CustomFolder'
path = get_filecloud_document_path(doc_custom)
print(path)  # Output: /CustomFolder/SOP-002_v3.pdf

Best Practices

  • Always handle ResourceNotFoundError exceptions when calling this function, as it may be raised if the document or version doesn't exist
  • When passing a document UID string, ensure the document exists in the database before calling
  • The function is decorated with @log_controller_action, so all calls are logged for audit purposes
  • For published documents with custom paths, the function automatically returns PDF paths when no version is specified
  • The returned path is a logical FileCloud path, not a filesystem path - use FileCloudAPI for actual file operations
  • Version numbers should be passed as strings, not integers
  • The function does not create folders or files - it only generates the path where the file should be located
  • Custom paths take precedence over standard hierarchical paths when doc.custom_path is set

Tags

filecloud document-management path-generation version-control file-storage controlled-documents document-versioning file-path storage-path

Similar Components

AI-powered semantic similarity - components with related functionality:

  • function get_document_metadata_from_filecloud 72.2% similar

    Retrieves metadata for a specific document (and optionally a specific version) from FileCloud storage system.

    From: /tf/active/vicechatdev/CDocs/controllers/filecloud_controller.py

  • function get_document_download_url 70.2% similar

    Retrieves a download URL for a controlled document, automatically selecting between editable (Word) and PDF formats based on document status or explicit request.

    From: /tf/active/vicechatdev/document_controller_backup.py

  • function create_document_v2 70.1% similar

    Creates a new version of a controlled document by generating version metadata, storing the file in FileCloud, updating the document's revision number, and creating an audit trail entry.

    From: /tf/active/vicechatdev/CDocs/controllers/document_controller.py

  • function ensure_document_folders 69.8% similar

    Ensures all required folder hierarchies exist in FileCloud storage for a controlled document, creating them if they don't exist.

    From: /tf/active/vicechatdev/CDocs/controllers/filecloud_controller.py

  • function download_document_version 69.4% similar

    Downloads a specific version of a controlled document from FileCloud storage, with optional audit trail and watermark inclusion, and logs the download event.

    From: /tf/active/vicechatdev/document_controller_backup.py
← Back to Browse