Document Management¶
Camelot provides some features for the management of documents. Notice that documents managed by Camelot are stored in a specific location (either an application directory on the local disk, a network share or a remote server).
This in contrast with some application that just store the link to a file in the database, and don’t store the file itself.
Three concepts are important for understanding how Camelot handles documents :
- The Storage : this is the place where Camelot stores its documents, by default this is a directory on the local system. When a file is checked in into a storage, a StoredFile is returned. Files are checked out from the storage by their StoredFile representation.
- The StoredFile : a stored file is a representation of a file stored in a storage. It does not contain the file itself but its name and meta information.
- The File Field type : is a custom field type to write and read the StoredFile into the database. The actual name of the StoredFile is the only thing stored in the database.
The File field type¶
Usually the first step when working with documents is to use the File field type somewhere in the model definition. Alternatively the Image field type can be used if one only wants to store images in that field.
- class camelot.types.File(max_length=100, upload_to=u'', storage=<class 'camelot.core.files.storage.Storage'>, **kwargs)[source]¶
Sqlalchemy column type to store files. Only the location of the file is stored
This column type accepts and returns a StoredFile. The name of the file is stored as a string in the database. A subdirectory upload_to can be specified:
class Movie( Entity ): script = Column( camelot.types.File( upload_to = 'script' ) )
Retrieving the actual storage from a File field can be a little cumbersome. The easy way is taking it from the field attributes, in which it will be put by default. If no field attributes are available at the location where the storage is needed, eg in some function doing document processing, one needs to go through SQLAlchemy to retrieve it.
For an ‘task’ object with a File field named ‘document’, the storage can be retrieved:
from sqlalchemy import orm task_mapper = orm.object_mapper( task ) document_property = task_mapper.get_property('document') storage = document_property.columns[0].type.storage
Parameters: max_length – the maximum length of the name of the file that will be saved in the database.
Parameters: upload_to – a subdirectory in the Storage, in which the the file should be stored.
Parameters: storage – an alternative storage to use for this field.
- class camelot.types.Image(max_length=100, upload_to=u'', storage=<class 'camelot.core.files.storage.Storage'>, **kwargs)[source]¶
Sqlalchemy column type to store images
This column type accepts and returns a StoredImage, and stores them in the directory specified by settings.CAMELOT_MEDIA_ROOT. The name of the file is stored as a string in the database.
The Image field type provides the same functionallity as the File field type, but the files stored should be images.
The StoredFile¶
When the File field type is used in the code, it returns and accepts objects of type StoredFile.
- class camelot.core.files.storage.StoredFile(storage, name)[source]¶
Helper class for the File field type. Stored file objects can be used within the GUI thread, as none of its methods should block.
The Image field type will return objects of type StoredImage.
- class camelot.core.files.storage.StoredImage(storage, name)[source]¶
Helper class for the Image field type Class linking an image and the location and filename where the image is stored
The Storage¶
This is where the actual file is stored. The default storage implementation simply represents a directory on the file system.
- class camelot.core.files.storage.Storage(upload_to='', stored_file_implementation=<class 'camelot.core.files.storage.StoredFile'>, root=None)[source]¶
Helper class that opens and saves StoredFile objects The default implementation stores files in the settings.CAMELOT_MEDIA_ROOT directory. The storage object should only be used within the model thread, as all of it’s methods might block.
The methods of this class don’t verify if they are called on the model thread, because these classes can be used server side or in a non-gui script as well.
- available()[source]¶
Verify if the storage is available
Returns: True if the storage is available, False otherwise
- checkin(local_path, filename=None)[source]¶
Check the file pointed to by local_path into the storage, and return a StoredFile
Parameters: - local_path – the path to the local file that needs to be checked in
- filename – a hint for the filename to be given to the checked in file, if None
is given, the filename from the local path will be taken.
The stored file is not guaranteed to have the filename asked, since the storage might not support this filename, or another file might be named like that. In each case the storage will choose the filename.
- checkin_stream(prefix, suffix, stream)[source]¶
Check the datastream in as a file into the storage
Parameters: - prefix – the prefix to use for generating a file name
- suffix – the suffix to use for generating a filen name, eg ‘.png’
Returns: a StoredFile
This method can also be used in combination with the StringIO module:
import StringIO stream = StringIO.StringIO() # write everything to the stream stream.write( 'bla bla bla' ) # prepare the stream for reading stream.seek( 0 ) stored_file = storage.checkin_stream( 'document', '.txt', stream )
- checkout(stored_file)[source]¶
Check the file pointed to by the local_path out of the storage and return a local filesystem path where the file can be opened
- checkout_stream(stored_file)[source]¶
Check the file stored_file out of the storage as a datastream
Returns: a file object
- list(prefix='*', suffix='*')[source]¶
Lists all files with a given prefix and or suffix available in this storage
Returns: a iterator of StoredFile objects