Source code for cerebro.cargador

# -*- coding: utf-8 -*-
"""
The cerebro.cargador module provides access to the Cargador file storage.

.. rubric:: Functions

* :py:func:`download_file() <cerebro.cargador.download_file>`
* :py:func:`download_thumbnail() <cerebro.cargador.download_thumbnail>`
* :py:func:`file_name_form_hash() <cerebro.cargador.file_name_form_hash>`
* :py:func:`is_connected() <cerebro.cargador.is_connected>`
* :py:func:`is_local() <cerebro.cargador.is_local>`
* :py:func:`storage_host() <cerebro.cargador.storage_host>`
* :py:func:`storage_path() <cerebro.cargador.storage_path>`
"""


import py_cerebro_carga

def file_name_form_hash(hash):
	"""
	:param string hash: file hash sum.
	:returns: absolute file path. If the file is absent in the file storage, None is returned.
	:rtype: string	
	
	::
		
		attach = cerebro.core.current_attachment() # resolving current attachment
		file_name = cerebro.cargador.file_name_form_hash(attach.file_hash()) # trying to resolve file name by the hash sum
		print('File name', file_name)
	"""
	return py_cerebro_carga.file_name_form_hash(hash)

def download_file(hash,  project_id):
	"""
	:param string hash: file hash sum.
	:param int project_id: project ID.	
	
	Enqueues the file to be downloaded from a remote file storage.
	
	::
	
		# Attachment download
		attach = cerebro.core.current_attachment() # getting current attachment
		task =  cerebro.core.current_task() # getting the current task to get the project ID
		
		if attach.is_link() != True: # checking if the attachment is a file, not a link
			file_name = cerebro.cargador.file_name_form_hash(attach.file_hash()) # trying to get filename by the hash sum
			if file_name == '' or file_name == None: # if the file is absent, trying to download it
				cerebro.cargador.download_file(attach.file_hash(), task.project_id())		
		
	.. note:: You can download a review on the file using the same method, but getting the review hash sum instead of the source file hash sum - :py:meth:`attach.review_hash() <cerebro.aclasses.Attachment.review_hash>`.
		Use the :py:func:`cerebro.cargador.download_thumbnail` function to download the file's thumbnails.
		
	.. seealso:: :py:func:`download_thumbnail() <cerebro.cargador.download_thumbnail>`
	"""
	py_cerebro_carga.download_file(hash,  project_id)
	
def download_thumbnail(hash,  project_id):
	"""
	:param string hash: thumbnail hash sum.
	:param int project_id: project ID.
	
	Enqueues the thumbnail to be downloaded from a remote file storage.
	
	.. note:: Thumbnails downloaded with the download_thumbnail function, are saved into a special folder for thumbnails,
		in order to keep clean folders with source files.
	
	::
	
		# Downloading a thumbnail of an attachment
		attach = cerebro.core.current_attachment() # resolving current attachment
		task =  cerebro.core.current_task() # resolving current attachment to get the project ID
		
		hashs = attach.thumbnail_hashs() # resolving the list of thumbnail hash sums
		
		for hash in hashs: # sorting out the thumbnails 
			if hash != '' and hash != None: # if a file has a thumbnail
				file_name = cerebro.cargador.file_name_form_hash(hash) # trying to get the thumbnail name by the hash sum			
				if file_name == '' or file_name == None: # if the thumbnail is absent, trying to download it				
					cerebro.cargador.download_thumbnail(hash, project_id)		
		
	.. seealso:: :py:func:`download_file() <cerebro.cargador.download_file>`
	"""
	py_cerebro_carga.download_thumbnail(hash,  project_id)
	
def is_local():
	"""
	:returns: True, if local Cargador service is connected. False, if network Cargador is connected.
	:rtype: bool
	"""
	
	return py_cerebro_carga.carga_is_local() != 0
	
def is_connected():
	"""
	:returns: True, if connection to the Cargador service is established.
	:rtype: bool
	"""
	
	return py_cerebro_carga.carga_is_connected() != 0
	
def storage_path():
	"""
	:returns: Path to the file storage.
	:rtype: string
	"""
	
	return py_cerebro_carga.carga_path()
	
def storage_host():
	"""
	:returns: Address of the host with the Cargador service connected.
	:rtype: string
	
	If a local Cargador service is connected, 'localhost' returns.
	"""
	
	return py_cerebro_carga.carga_host()