Merge pull request #101 from tracim/feature/614_file_content_endpoints

.travis.yml

@@ -5,6 +5,13 @@ python:
   - "3.5"
   - "3.6"
 
+addons:
+  apt:
+    packages:
+    - libreoffice
+    - imagemagick
+    - libmagickwand-dev
+    - ghostscript
 services:
   - docker
   - redis-server

README.md

@@ -20,6 +20,13 @@ on Debian Stretch (9) with sudo:
     sudo apt install git
     sudo apt install python3 python3-venv python3-dev python3-pip
     sudo apt install redis-server
+    sudo apt install zlib1g-dev libjpeg-dev
+    sudo apt install imagemagick libmagickwand-dev ghostscript
+
+for better preview support:
+
+    sudo apt install libreoffice # most office documents file and text format
+    sudo apt install inkscape # for .svg files.
 
 ### Get the source ###
 

development.ini.sample

@@ -175,6 +175,17 @@ wsgidav.config_path = %(here)s/wsgidav.conf
 ## Do not set http:// prefix.
 # wsgidav.client.base_url = 127.0.0.1:<WSGIDAV_PORT>
 
+### Preview
+## You can parametrized allowed jpg preview dimension list, if not set, default
+## is 256x256. First {width}x{length} items is default preview dimensions.
+## all items should be separated by ',' and you should be really careful to do
+## set anything else than '{int}x{int}' item and ', ' separator
+# preview.jpg.allowed_dims = 256x256,1000x1000
+## Preview dimensions can be set as restricted, if set as restricted, access
+## endpoint to  to get any other preview dimensions than allowed_dims will
+## return error
+# preview.jpg.restricted_dims = True
+
 ###
 # wsgi server configuration
 ###

setup.py

@@ -35,6 +35,7 @@ requires = [
     'filedepot',
     'babel',
     'python-slugify',
+    'preview-generator',
     # mail-notifier
     'mako',
     'lxml',
@@ -48,7 +49,8 @@ tests_require = [
     'pytest-cov',
     'pep8',
     'mypy',
-    'requests'
+    'requests',
+    'Pillow'
 ]
 
 mysql_require = [

tracim/__init__.py

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
+
+
 try:  # Python 3.5+
     from http import HTTPStatus
 except ImportError:
@@ -27,6 +29,7 @@ from tracim.views.core_api.system_controller import SystemController
 from tracim.views.core_api.user_controller import UserController
 from tracim.views.core_api.workspace_controller import WorkspaceController
 from tracim.views.contents_api.comment_controller import CommentController
+from tracim.views.contents_api.file_controller import FileController
 from tracim.views.errors import ErrorSchema
 from tracim.exceptions import NotAuthenticated
 from tracim.exceptions import InvalidId
@@ -109,6 +112,7 @@ def web(global_config, **local_settings):
     comment_controller = CommentController()
     html_document_controller = HTMLDocumentController()
     thread_controller = ThreadController()
+    file_controller = FileController()
     configurator.include(session_controller.bind, route_prefix=BASE_API_V2)
     configurator.include(system_controller.bind, route_prefix=BASE_API_V2)
     configurator.include(user_controller.bind, route_prefix=BASE_API_V2)
@@ -116,6 +120,7 @@ def web(global_config, **local_settings):
     configurator.include(comment_controller.bind, route_prefix=BASE_API_V2)
     configurator.include(html_document_controller.bind, route_prefix=BASE_API_V2)  # nopep8
     configurator.include(thread_controller.bind, route_prefix=BASE_API_V2)
+    configurator.include(file_controller.bind, route_prefix=BASE_API_V2)
 
     hapic.add_documentation_view(
         '/api/v2/doc',

tracim/config.py

@@ -411,6 +411,26 @@ class CFG(object):
         #     self.RADICALE_CLIENT_BASE_URL_HOST,
         #     self.RADICALE_CLIENT_BASE_URL_PREFIX,
         # )
+        self.PREVIEW_JPG_RESTRICTED_DIMS = asbool(settings.get(
+            'preview.jpg.restricted_dims', False
+        ))
+        preview_jpg_allowed_dims_str = settings.get('preview.jpg.allowed_dims', '')  # nopep8
+        allowed_dims = []
+        if preview_jpg_allowed_dims_str:
+            for sizes in preview_jpg_allowed_dims_str.split(','):
+                parts = sizes.split('x')
+                assert len(parts) == 2
+                width, height = parts
+                assert width.isdecimal()
+                assert height.isdecimal()
+                size = PreviewDim(int(width), int(height))
+                allowed_dims.append(size)
+
+        if not allowed_dims:
+            size = PreviewDim(256, 256)
+            allowed_dims.append(size)
+
+        self.PREVIEW_JPG_ALLOWED_DIMS = allowed_dims
 
     def configure_filedepot(self):
         depot_storage_name = self.DEPOT_STORAGE_NAME
@@ -427,3 +447,16 @@ class CFG(object):
 
         TREEVIEW_FOLDERS = 'folders'
         TREEVIEW_ALL = 'all'
+
+
+class PreviewDim(object):
+
+    def __init__(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+
+    def __repr__(self):
+        return "<PreviewDim width:{width} height:{height}>".format(
+            width=self.width,
+            height=self.height,
+        )

tracim/exceptions.py

@@ -178,3 +178,15 @@ class UserCreationFailed(TracimException):
 
 class ParentNotFound(NotFound):
     pass
+
+
+class RevisionDoesNotMatchThisContent(TracimException):
+    pass
+
+
+class PageOfPreviewNotFound(NotFound):
+    pass
+
+
+class PreviewDimNotAllowed(TracimException):
+    pass

tracim/lib/core/content.py

@@ -7,6 +7,7 @@ import typing
 from operator import itemgetter
 
 import transaction
+from preview_generator.manager import PreviewManager
 from sqlalchemy import func
 from sqlalchemy.orm import Query
 from depot.manager import DepotManager
@@ -25,6 +26,9 @@ from sqlalchemy.sql.elements import and_
 from tracim.lib.utils.utils import cmp_to_key
 from tracim.lib.core.notifications import NotifierFactory
 from tracim.exceptions import SameValueError
+from tracim.exceptions import PageOfPreviewNotFound
+from tracim.exceptions import PreviewDimNotAllowed
+from tracim.exceptions import RevisionDoesNotMatchThisContent
 from tracim.exceptions import EmptyCommentContentNotAllowed
 from tracim.exceptions import EmptyLabelNotAllowed
 from tracim.exceptions import ContentNotFound
@@ -43,11 +47,13 @@ from tracim.models.data import UserRoleInWorkspace
 from tracim.models.data import Workspace
 from tracim.lib.utils.translation import fake_translator as _
 from tracim.models.context_models import RevisionInContext
+from tracim.models.context_models import PreviewAllowedDim
 from tracim.models.context_models import ContentInContext
 
 __author__ = 'damien'
 
 
+# TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
 def compare_content_for_sorting_by_type_and_name(
         content1: Content,
         content2: Content
@@ -86,7 +92,7 @@ def compare_content_for_sorting_by_type_and_name(
         else:
             return 0
 
-
+# TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
 def compare_tree_items_for_sorting_by_type_and_name(
         item1: NodeTreeItem,
         item2: NodeTreeItem
@@ -133,6 +139,7 @@ class ContentApi(object):
         self._show_all_type_of_contents_in_treeview = all_content_in_treeview
         self._force_show_all_types = force_show_all_types
         self._disable_user_workspaces_filter = disable_user_workspaces_filter
+        self.preview_manager = PreviewManager(self._config.PREVIEW_CACHE_DIR, create_folder=True)  # nopep8
 
     @contextmanager
     def show(
@@ -190,6 +197,7 @@ class ContentApi(object):
         return self._session.query(Content)\
             .join(ContentRevisionRO, self._get_revision_join())
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
     @classmethod
     def sort_tree_items(
         cls,
@@ -205,6 +213,7 @@ class ContentApi(object):
 
         return content_list
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
     @classmethod
     def sort_content(
         cls,
@@ -500,16 +509,24 @@ class ContentApi(object):
             raise ContentNotFound('Content "{}" not found in database'.format(content_id)) from exc  # nopep8
         return content
 
-    def get_one_revision(self, revision_id: int = None) -> ContentRevisionRO:
+    def get_one_revision(self, revision_id: int = None, content: Content= None) -> ContentRevisionRO:  # nopep8
         """
         This method allow us to get directly any revision with its id
         :param revision_id: The content's revision's id that we want to return
+        :param content: The content related to the revision, if None do not
+        check if revision is related to this content.
         :return: An item Content linked with the correct revision
         """
         assert revision_id is not None# DYN_REMOVE
 
         revision = self._session.query(ContentRevisionRO).filter(ContentRevisionRO.revision_id == revision_id).one()
-
+        if content and revision.content_id != content.content_id:
+            raise RevisionDoesNotMatchThisContent(
+                'revision {revision_id} is not a revision of content {content_id}'.format(  # nopep8
+                    revision_id=revision.revision_id,
+                    content_id=content.content_id,
+                    )
+            )
         return revision
 
     # INFO - A.P - 2017-07-03 - python file object getter
@@ -632,6 +649,7 @@ class ContentApi(object):
             )\
             .one()
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
     def get_folder_with_workspace_path_labels(
             self,
             path_labels: [str],
@@ -725,6 +743,104 @@ class ContentApi(object):
             ),
         ))
 
+
+    def get_pdf_preview_path(
+            self,
+            content_id: int,
+            revision_id: int,
+            page: int
+    ) -> str:
+        """
+        Get pdf preview of revision of content
+        :param content_id: id of content
+        :param revision_id: id of content revision
+        :param page: page number of the preview, useful for multipage content
+        :return: preview_path as string
+        """
+        file_path = self.get_one_revision_filepath(revision_id)
+        if page >= self.preview_manager.get_page_nb(file_path):
+            raise PageOfPreviewNotFound(
+                'page {page} of content {content_id} does not exist'.format(
+                    page=page,
+                    content_id=content_id
+                ),
+            )
+        jpg_preview_path = self.preview_manager.get_pdf_preview(
+            file_path,
+            page=page
+        )
+        return jpg_preview_path
+
+    def get_full_pdf_preview_path(self, revision_id: int) -> str:
+        """
+        Get full(multiple page) pdf preview of revision of content
+        :param revision_id: id of revision
+        :return: path of the full pdf preview of this revision
+        """
+        file_path = self.get_one_revision_filepath(revision_id)
+        pdf_preview_path = self.preview_manager.get_pdf_preview(file_path)
+        return pdf_preview_path
+
+    def get_jpg_preview_allowed_dim(self) -> PreviewAllowedDim:
+        """
+        Get jpg preview allowed dimensions and strict bool param.
+        """
+        return PreviewAllowedDim(
+            self._config.PREVIEW_JPG_RESTRICTED_DIMS,
+            self._config.PREVIEW_JPG_ALLOWED_DIMS,
+        )
+
+    def get_jpg_preview_path(
+        self,
+        content_id: int,
+        revision_id: int,
+        page: int,
+        width: int = None,
+        height: int = None,
+    ) -> str:
+        """
+        Get jpg preview of revision of content
+        :param content_id: id of content
+        :param revision_id: id of content revision
+        :param page: page number of the preview, useful for multipage content
+        :param width: width in pixel
+        :param height: height in pixel
+        :return: preview_path as string
+        """
+        file_path = self.get_one_revision_filepath(revision_id)
+        if page >= self.preview_manager.get_page_nb(file_path):
+            raise Exception(
+                'page {page} of revision {revision_id} of content {content_id} does not exist'.format(  # nopep8
+                    page=page,
+                    revision_id=revision_id,
+                    content_id=content_id,
+                ),
+            )
+        if not width and not height:
+            width = self._config.PREVIEW_JPG_ALLOWED_DIMS[0].width
+            height = self._config.PREVIEW_JPG_ALLOWED_DIMS[0].height
+
+        allowed_dim = False
+        for preview_dim in self._config.PREVIEW_JPG_ALLOWED_DIMS:
+            if width == preview_dim.width and height == preview_dim.height:
+                allowed_dim = True
+                break
+
+        if not allowed_dim and self._config.PREVIEW_JPG_RESTRICTED_DIMS:
+            raise PreviewDimNotAllowed(
+                'Size {width}x{height} is not allowed for jpeg preview'.format(
+                    width=width,
+                    height=height,
+                )
+            )
+        jpg_preview_path = self.preview_manager.get_jpeg_preview(
+            file_path,
+            page=page,
+            width=width,
+            height=height,
+        )
+        return jpg_preview_path
+
     def _get_all_query(
         self,
         parent_id: int = None,
@@ -797,6 +913,67 @@ class ContentApi(object):
 
         return resultset.all()
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
+    def get_all_without_exception(self, content_type: str, workspace: Workspace=None) -> typing.List[Content]:
+        assert content_type is not None# DYN_REMOVE
+
+        resultset = self._base_query(workspace)
+
+        if content_type != ContentType.Any:
+            resultset = resultset.filter(Content.type==content_type)
+
+        return resultset.all()
+
+    def get_last_active(self, parent_id: int, content_type: str, workspace: Workspace=None, limit=10) -> typing.List[Content]:
+        assert parent_id is None or isinstance(parent_id, int) # DYN_REMOVE
+        assert content_type is not None# DYN_REMOVE
+        assert isinstance(content_type, str) # DYN_REMOVE
+
+        resultset = self._base_query(workspace) \
+            .filter(Content.workspace_id == Workspace.workspace_id) \
+            .filter(Workspace.is_deleted.is_(False)) \
+            .order_by(desc(Content.updated))
+
+        if content_type!=ContentType.Any:
+            resultset = resultset.filter(Content.type==content_type)
+
+        if parent_id:
+            resultset = resultset.filter(Content.parent_id==parent_id)
+
+        result = []
+        for item in resultset:
+            new_item = None
+            if ContentType.Comment == item.type:
+                new_item = item.parent
+            else:
+                new_item = item
+
+            # INFO - D.A. - 2015-05-20
+            # We do not want to show only one item if the last 10 items are
+            # comments about one thread for example
+            if new_item not in result:
+                result.append(new_item)
+
+            if len(result) >= limit:
+                break
+
+        return result
+
+    def get_last_unread(self, parent_id: int, content_type: str,
+                        workspace: Workspace=None, limit=10) -> typing.List[Content]:
+        assert parent_id is None or isinstance(parent_id, int) # DYN_REMOVE
+        assert content_type is not None# DYN_REMOVE
+        assert isinstance(content_type, str) # DYN_REMOVE
+
+        read_revision_ids = self._session.query(RevisionReadStatus.revision_id) \
+            .filter(RevisionReadStatus.user_id==self._user_id)
+
+        not_read_revisions = self._revisions_base_query(workspace) \
+            .filter(~ContentRevisionRO.revision_id.in_(read_revision_ids)) \
+            .filter(ContentRevisionRO.workspace_id == Workspace.workspace_id) \
+            .filter(Workspace.is_deleted.is_(False)) \
+            .subquery()
+
     # TODO - G.M - 2018-07-17 - [Cleanup] Drop this method if unneeded
     # def get_all_without_exception(self, content_type: str, workspace: Workspace=None) -> typing.List[Content]:
     #     assert content_type is not None# DYN_REMOVE
@@ -1281,6 +1458,7 @@ class ContentApi(object):
 
         return ContentType.sorted(content_types)
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
     def exclude_unavailable(
         self,
         contents: typing.List[Content],
@@ -1294,6 +1472,7 @@ class ContentApi(object):
                 contents.remove(content)
         return contents
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
     def content_under_deleted(self, content: Content) -> bool:
         if content.parent:
             if content.parent.is_deleted:
@@ -1302,6 +1481,7 @@ class ContentApi(object):
                 return self.content_under_deleted(content.parent)
         return False
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
     def content_under_archived(self, content: Content) -> bool:
         if content.parent:
             if content.parent.is_archived:
@@ -1310,6 +1490,7 @@ class ContentApi(object):
                 return self.content_under_archived(content.parent)
         return False
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
     def find_one_by_unique_property(
             self,
             property_name: str,
@@ -1338,6 +1519,7 @@ class ContentApi(object):
         )
         return query.one()
 
+    # TODO - G.M - 2018-07-24 - [Cleanup] Is this method already needed ?
     def generate_folder_label(
             self,
             workspace: Workspace,

tracim/models/context_models.py

@@ -6,6 +6,7 @@ from enum import Enum
 from slugify import slugify
 from sqlalchemy.orm import Session
 from tracim import CFG
+from tracim.config import PreviewDim
 from tracim.models import User
 from tracim.models.auth import Profile
 from tracim.models.data import Content
@@ -18,6 +19,17 @@ from tracim.models.workspace_menu_entries import WorkspaceMenuEntry
 from tracim.models.contents import ContentTypeLegacy as ContentType
 
 
+class PreviewAllowedDim(object):
+
+    def __init__(
+            self,
+            restricted:bool,
+            dimensions: typing.List[PreviewDim]
+    ) -> None:
+        self.restricted = restricted
+        self.dimensions = dimensions
+
+
 class MoveParams(object):
     """
     Json body params for move action model
@@ -46,6 +58,39 @@ class WorkspaceAndContentPath(object):
         self.workspace_id = workspace_id
 
 
+class WorkspaceAndContentRevisionPath(object):
+    """
+    Paths params with workspace id and content_id model
+    """
+    def __init__(self, workspace_id: int, content_id: int, revision_id) -> None:
+        self.content_id = content_id
+        self.revision_id = revision_id
+        self.workspace_id = workspace_id
+
+
+class ContentPreviewSizedPath(object):
+    """
+    Paths params with workspace id and content_id, width, heigth
+    """
+    def __init__(self, workspace_id: int, content_id: int, width: int, height: int) -> None:  # nopep8
+        self.content_id = content_id
+        self.workspace_id = workspace_id
+        self.width = width
+        self.height = height
+
+
+class RevisionPreviewSizedPath(object):
+    """
+    Paths params with workspace id and content_id, revision_id width, heigth
+    """
+    def __init__(self, workspace_id: int, content_id: int, revision_id: int, width: int, height: int) -> None:  # nopep8
+        self.content_id = content_id
+        self.revision_id = revision_id
+        self.workspace_id = workspace_id
+        self.width = width
+        self.height = height
+
+
 class WorkspaceAndUserPath(object):
     """
     Paths params with workspace id and user_id
@@ -80,6 +125,17 @@ class CommentPath(object):
         self.comment_id = comment_id
 
 
+class PageQuery(object):
+    """
+    Page query model
+    """
+    def __init__(
+            self,
+            page: int = 0
+    ):
+        self.page = page
+
+
 class ContentFilter(object):
     """
     Content filter model

tracim/tests/__init__.py

@@ -25,6 +25,8 @@ from tracim.config import CFG
 from tracim.extensions import hapic
 from tracim import web
 from webtest import TestApp
+from io import BytesIO
+from PIL import Image
 
 
 def eq_(a, b, msg=None):
@@ -54,6 +56,15 @@ def set_html_document_slug_to_legacy(session_factory) -> None:
     assert content_query.count() > 0
 
 
+def create_1000px_png_test_image():
+    file = BytesIO()
+    image = Image.new('RGBA', size=(1000, 1000), color=(0, 0, 0))
+    image.save(file, 'png')
+    file.name = 'test_image.png'
+    file.seek(0)
+    return file
+
+
 class FunctionalTest(unittest.TestCase):
 
     fixtures = [BaseFixture]
@@ -68,8 +79,8 @@ class FunctionalTest(unittest.TestCase):
             'depot_storage_dir': '/tmp/test/depot',
             'depot_storage_name': 'test',
             'preview_cache_dir': '/tmp/test/preview_cache',
+            'preview.jpg.restricted_dims': True,
             'email.notification.activated': 'false',
-
         }
         hapic.reset_context()
         self.engine = get_engine(self.settings)

tracim/views/contents_api/file_controller.py

@@ -0,0 +1,572 @@
+# coding=utf-8
+import typing
+
+import transaction
+from depot.manager import DepotManager
+from preview_generator.exception import UnavailablePreviewType
+from pyramid.config import Configurator
+from pyramid.response import FileResponse, FileIter
+
+try:  # Python 3.5+
+    from http import HTTPStatus
+except ImportError:
+    from http import client as HTTPStatus
+
+from tracim import TracimRequest
+from tracim.extensions import hapic
+from tracim.lib.core.content import ContentApi
+from tracim.views.controllers import Controller
+from tracim.views.core_api.schemas import FileContentSchema
+from tracim.views.core_api.schemas import AllowedJpgPreviewDimSchema
+from tracim.views.core_api.schemas import ContentPreviewSizedPathSchema
+from tracim.views.core_api.schemas import RevisionPreviewSizedPathSchema
+from tracim.views.core_api.schemas import PageQuerySchema
+from tracim.views.core_api.schemas import WorkspaceAndContentRevisionIdPathSchema  # nopep8
+from tracim.views.core_api.schemas import FileRevisionSchema
+from tracim.views.core_api.schemas import SetContentStatusSchema
+from tracim.views.core_api.schemas import FileContentModifySchema
+from tracim.views.core_api.schemas import WorkspaceAndContentIdPathSchema
+from tracim.views.core_api.schemas import NoContentSchema
+from tracim.lib.utils.authorization import require_content_types
+from tracim.lib.utils.authorization import require_workspace_role
+from tracim.models.data import UserRoleInWorkspace
+from tracim.models.context_models import ContentInContext
+from tracim.models.context_models import RevisionInContext
+from tracim.models.contents import ContentTypeLegacy as ContentType
+from tracim.models.contents import file_type
+from tracim.models.revision_protection import new_revision
+from tracim.exceptions import EmptyLabelNotAllowed
+from tracim.exceptions import PageOfPreviewNotFound
+from tracim.exceptions import PreviewDimNotAllowed
+
+FILE_ENDPOINTS_TAG = 'Files'
+
+
+class FileController(Controller):
+    """
+    Endpoints for File Content
+    """
+
+    # File data
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.CONTRIBUTOR)
+    @require_content_types([file_type])
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    # TODO - G.M - 2018-07-24 - Use hapic for input file
+    @hapic.output_body(NoContentSchema(), default_http_code=HTTPStatus.NO_CONTENT)  # nopep8
+    def upload_file(self, context, request: TracimRequest, hapic_data=None):
+        """
+        Upload a new version of raw file of content. This will create a new
+        revision.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        file = request.POST['files']
+        with new_revision(
+                session=request.dbsession,
+                tm=transaction.manager,
+                content=content
+        ):
+            api.update_file_data(
+                content,
+                new_filename=file.filename,
+                new_mimetype=file.type,
+                new_content=file.file,
+            )
+
+        return
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.output_file([])
+    def download_file(self, context, request: TracimRequest, hapic_data=None):
+        """
+        Download raw file of last revision of content.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        file = DepotManager.get().get(content.depot_file)
+        response = request.response
+        response.content_type = file.content_type
+        response.app_iter = FileIter(file)
+        return response
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.input_path(WorkspaceAndContentRevisionIdPathSchema())
+    @hapic.output_file([])
+    def download_revisions_file(self, context, request: TracimRequest, hapic_data=None):  # nopep8
+        """
+        Download raw file for specific revision of content.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        revision = api.get_one_revision(
+            revision_id=hapic_data.path.revision_id,
+            content=content
+        )
+        file = DepotManager.get().get(revision.depot_file)
+        response = request.response
+        response.content_type = file.content_type
+        response.app_iter = FileIter(file)
+        return response
+
+    # preview
+    # pdf
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.handle_exception(UnavailablePreviewType, HTTPStatus.BAD_REQUEST)
+    @hapic.handle_exception(PageOfPreviewNotFound, HTTPStatus.BAD_REQUEST)
+    @hapic.input_query(PageQuerySchema())
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.output_file([])
+    def preview_pdf(self, context, request: TracimRequest, hapic_data=None):
+        """
+        Obtain a specific page pdf preview of last revision of content.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        pdf_preview_path = api.get_pdf_preview_path(
+            content.content_id,
+            content.revision_id,
+            page=hapic_data.query.page
+        )
+        return FileResponse(pdf_preview_path)
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.handle_exception(UnavailablePreviewType, HTTPStatus.BAD_REQUEST)
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.output_file([])
+    def preview_pdf_full(self, context, request: TracimRequest, hapic_data=None):  # nopep8
+        """
+        Obtain a full pdf preview (all page) of last revision of content.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        pdf_preview_path = api.get_full_pdf_preview_path(content.revision_id)
+        return FileResponse(pdf_preview_path)
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.handle_exception(UnavailablePreviewType, HTTPStatus.BAD_REQUEST)
+    @hapic.input_path(WorkspaceAndContentRevisionIdPathSchema())
+    @hapic.input_query(PageQuerySchema())
+    @hapic.output_file([])
+    def preview_pdf_revision(self, context, request: TracimRequest, hapic_data=None):  # nopep8
+        """
+        Obtain a specific page pdf preview of a specific revision of content.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        revision = api.get_one_revision(
+            revision_id=hapic_data.path.revision_id,
+            content=content
+        )
+        pdf_preview_path = api.get_pdf_preview_path(
+            revision.content_id,
+            revision.revision_id,
+            page=hapic_data.query.page
+        )
+        return FileResponse(pdf_preview_path)
+
+    # jpg
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.handle_exception(PageOfPreviewNotFound, HTTPStatus.BAD_REQUEST)
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.input_query(PageQuerySchema())
+    @hapic.output_file([])
+    def preview_jpg(self, context, request: TracimRequest, hapic_data=None):
+        """
+        Obtain normally sied jpg preview of last revision of content.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        allowed_dim = api.get_jpg_preview_allowed_dim()
+        jpg_preview_path = api.get_jpg_preview_path(
+            content_id=content.content_id,
+            revision_id=content.revision_id,
+            page=hapic_data.query.page,
+            width=allowed_dim.dimensions[0].width,
+            height=allowed_dim.dimensions[0].height,
+        )
+        return FileResponse(jpg_preview_path)
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.handle_exception(PageOfPreviewNotFound, HTTPStatus.BAD_REQUEST)
+    @hapic.handle_exception(PreviewDimNotAllowed, HTTPStatus.BAD_REQUEST)
+    @hapic.input_query(PageQuerySchema())
+    @hapic.input_path(ContentPreviewSizedPathSchema())
+    @hapic.output_file([])
+    def sized_preview_jpg(self, context, request: TracimRequest, hapic_data=None):  # nopep8
+        """
+        Obtain resized jpg preview of last revision of content.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        jpg_preview_path = api.get_jpg_preview_path(
+            content_id=content.content_id,
+            revision_id=content.revision_id,
+            page=hapic_data.query.page,
+            height=hapic_data.path.height,
+            width=hapic_data.path.width,
+        )
+        return FileResponse(jpg_preview_path)
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.handle_exception(PageOfPreviewNotFound, HTTPStatus.BAD_REQUEST)
+    @hapic.handle_exception(PreviewDimNotAllowed, HTTPStatus.BAD_REQUEST)
+    @hapic.input_path(RevisionPreviewSizedPathSchema())
+    @hapic.input_query(PageQuerySchema())
+    @hapic.output_file([])
+    def sized_preview_jpg_revision(self, context, request: TracimRequest, hapic_data=None):  # nopep8
+        """
+        Obtain resized jpg preview of a specific revision of content.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        revision = api.get_one_revision(
+            revision_id=hapic_data.path.revision_id,
+            content=content
+        )
+        jpg_preview_path = api.get_jpg_preview_path(
+            content_id=content.content_id,
+            revision_id=revision.revision_id,
+            page=hapic_data.query.page,
+            height=hapic_data.path.height,
+            width=hapic_data.path.width,
+        )
+        return FileResponse(jpg_preview_path)
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.output_body(AllowedJpgPreviewDimSchema())
+    def allowed_dim_preview_jpg(self, context, request: TracimRequest, hapic_data=None):  # nopep8
+        """
+        Get allowed dimensions of jpg preview. If restricted is true,
+        only those dimensions are strictly accepted.
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        return api.get_jpg_preview_allowed_dim()
+
+    # File infos
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.output_body(FileContentSchema())
+    def get_file_infos(self, context, request: TracimRequest, hapic_data=None) -> ContentInContext:  # nopep8
+        """
+        Get thread content
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        return api.get_content_in_context(content)
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @hapic.handle_exception(EmptyLabelNotAllowed, HTTPStatus.BAD_REQUEST)
+    @require_workspace_role(UserRoleInWorkspace.CONTRIBUTOR)
+    @require_content_types([file_type])
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.input_body(FileContentModifySchema())
+    @hapic.output_body(FileContentSchema())
+    def update_file_info(self, context, request: TracimRequest, hapic_data=None) -> ContentInContext:  # nopep8
+        """
+        update thread
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        with new_revision(
+                session=request.dbsession,
+                tm=transaction.manager,
+                content=content
+        ):
+            api.update_content(
+                item=content,
+                new_label=hapic_data.body.label,
+                new_content=hapic_data.body.raw_content,
+
+            )
+            api.save(content)
+        return api.get_content_in_context(content)
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @require_workspace_role(UserRoleInWorkspace.READER)
+    @require_content_types([file_type])
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.output_body(FileRevisionSchema(many=True))
+    def get_file_revisions(
+            self,
+            context,
+            request: TracimRequest,
+            hapic_data=None
+    ) -> typing.List[RevisionInContext]:
+        """
+        get file revisions
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        revisions = content.revisions
+        return [
+            api.get_revision_in_context(revision)
+            for revision in revisions
+        ]
+
+    @hapic.with_api_doc(tags=[FILE_ENDPOINTS_TAG])
+    @hapic.handle_exception(EmptyLabelNotAllowed, HTTPStatus.BAD_REQUEST)
+    @require_workspace_role(UserRoleInWorkspace.CONTRIBUTOR)
+    @require_content_types([file_type])
+    @hapic.input_path(WorkspaceAndContentIdPathSchema())
+    @hapic.input_body(SetContentStatusSchema())
+    @hapic.output_body(NoContentSchema(), default_http_code=HTTPStatus.NO_CONTENT)  # nopep8
+    def set_file_status(self, context, request: TracimRequest, hapic_data=None) -> None:  # nopep8
+        """
+        set file status
+        """
+        app_config = request.registry.settings['CFG']
+        api = ContentApi(
+            current_user=request.current_user,
+            session=request.dbsession,
+            config=app_config,
+        )
+        content = api.get_one(
+            hapic_data.path.content_id,
+            content_type=ContentType.Any
+        )
+        with new_revision(
+                session=request.dbsession,
+                tm=transaction.manager,
+                content=content
+        ):
+            api.set_status(
+                content,
+                hapic_data.body.status,
+            )
+            api.save(content)
+        return
+
+    def bind(self, configurator: Configurator) -> None:
+        """
+        Add route to configurator.
+        """
+
+        # file info #
+        # Get file info
+        configurator.add_route(
+            'file_info',
+            '/workspaces/{workspace_id}/files/{content_id}',
+            request_method='GET'
+        )
+        configurator.add_view(self.get_file_infos, route_name='file_info')  # nopep8
+        # update file
+        configurator.add_route(
+            'update_file_info',
+            '/workspaces/{workspace_id}/files/{content_id}',
+            request_method='PUT'
+        )  # nopep8
+        configurator.add_view(self.update_file_info, route_name='update_file_info')  # nopep8
+
+        # raw file #
+        # upload raw file
+        configurator.add_route(
+            'upload_file',
+            '/workspaces/{workspace_id}/files/{content_id}/raw',  # nopep8
+            request_method='PUT'
+        )
+        configurator.add_view(self.upload_file, route_name='upload_file')  # nopep8
+        # download raw file
+        configurator.add_route(
+            'download_file',
+            '/workspaces/{workspace_id}/files/{content_id}/raw',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.download_file, route_name='download_file')  # nopep8
+        # download raw file of revision
+        configurator.add_route(
+            'download_revision',
+            '/workspaces/{workspace_id}/files/{content_id}/revisions/{revision_id}/raw',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.download_revisions_file, route_name='download_revision')  # nopep8
+
+        # previews #
+        # get preview pdf full
+        configurator.add_route(
+            'preview_pdf_full',
+            '/workspaces/{workspace_id}/files/{content_id}/preview/pdf/full',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.preview_pdf_full, route_name='preview_pdf_full')  # nopep8
+        # get preview pdf
+        configurator.add_route(
+            'preview_pdf',
+            '/workspaces/{workspace_id}/files/{content_id}/preview/pdf',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.preview_pdf, route_name='preview_pdf')  # nopep8
+        # get preview jpg allowed dims
+        configurator.add_route(
+            'allowed_dim_preview_jpg',
+            '/workspaces/{workspace_id}/files/{content_id}/preview/jpg/allowed_dims',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.allowed_dim_preview_jpg, route_name='allowed_dim_preview_jpg')  # nopep8
+        # get preview jpg
+        configurator.add_route(
+            'preview_jpg',
+            '/workspaces/{workspace_id}/files/{content_id}/preview/jpg',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.preview_jpg, route_name='preview_jpg')  # nopep8
+        # get preview jpg with size
+        configurator.add_route(
+            'sized_preview_jpg',
+            '/workspaces/{workspace_id}/files/{content_id}/preview/jpg/{width}x{height}',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.sized_preview_jpg, route_name='sized_preview_jpg')  # nopep8
+        # get jpg preview for revision
+        configurator.add_route(
+            'sized_preview_jpg_revision',
+            '/workspaces/{workspace_id}/files/{content_id}/revisions/{revision_id}/preview/jpg/{width}x{height}',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.sized_preview_jpg_revision, route_name='sized_preview_jpg_revision')  # nopep8
+        # get jpg preview for revision
+        configurator.add_route(
+            'preview_pdf_revision',
+            '/workspaces/{workspace_id}/files/{content_id}/revisions/{revision_id}/preview/pdf',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.preview_pdf_revision, route_name='preview_pdf_revision')  # nopep8
+        # others #
+        # get file revisions
+        configurator.add_route(
+            'file_revisions',
+            '/workspaces/{workspace_id}/files/{content_id}/revisions',  # nopep8
+            request_method='GET'
+        )
+        configurator.add_view(self.get_file_revisions, route_name='file_revisions')  # nopep8
+
+        # get file status
+        configurator.add_route(
+            'set_file_status',
+            '/workspaces/{workspace_id}/files/{content_id}/status',  # nopep8
+            request_method='PUT'
+        )
+        configurator.add_view(self.set_file_status, route_name='set_file_status')  # nopep8

tracim/views/core_api/schemas.py

@@ -14,6 +14,10 @@ from tracim.models.context_models import ActiveContentFilter
 from tracim.models.context_models import ContentIdsQuery
 from tracim.models.context_models import UserWorkspaceAndContentPath
 from tracim.models.context_models import ContentCreation
+from tracim.models.context_models import ContentPreviewSizedPath
+from tracim.models.context_models import RevisionPreviewSizedPath
+from tracim.models.context_models import PageQuery
+from tracim.models.context_models import WorkspaceAndContentRevisionPath
 from tracim.models.context_models import WorkspaceMemberInvitation
 from tracim.models.context_models import WorkspaceUpdate
 from tracim.models.context_models import RoleUpdate
@@ -114,6 +118,10 @@ class ContentIdPathSchema(marshmallow.Schema):
     )
 
 
+class RevisionIdPathSchema(marshmallow.Schema):
+    revision_id = marshmallow.fields.Int(example=6, required=True)
+
+
 class WorkspaceAndUserIdPathSchema(
     UserIdPathSchema,
     WorkspaceIdPathSchema
@@ -132,6 +140,52 @@ class WorkspaceAndContentIdPathSchema(
         return WorkspaceAndContentPath(**data)
 
 
+class WidthAndHeightPathSchema(marshmallow.Schema):
+    width = marshmallow.fields.Int(example=256)
+    height = marshmallow.fields.Int(example=256)
+
+
+class AllowedJpgPreviewSizesSchema(marshmallow.Schema):
+    width = marshmallow.fields.Int(example=256)
+    height = marshmallow.fields.Int(example=256)
+
+
+class AllowedJpgPreviewDimSchema(marshmallow.Schema):
+    restricted = marshmallow.fields.Bool()
+    dimensions = marshmallow.fields.Nested(
+        AllowedJpgPreviewSizesSchema,
+        many=True
+    )
+
+
+class WorkspaceAndContentRevisionIdPathSchema(
+    WorkspaceIdPathSchema,
+    ContentIdPathSchema,
+    RevisionIdPathSchema,
+):
+    @post_load
+    def make_path_object(self, data):
+        return WorkspaceAndContentRevisionPath(**data)
+
+
+class ContentPreviewSizedPathSchema(
+    WorkspaceAndContentIdPathSchema,
+    WidthAndHeightPathSchema
+):
+    @post_load
+    def make_path_object(self, data):
+        return ContentPreviewSizedPath(**data)
+
+
+class RevisionPreviewSizedPathSchema(
+    WorkspaceAndContentRevisionIdPathSchema,
+    WidthAndHeightPathSchema
+):
+    @post_load
+    def make_path_object(self, data):
+        return RevisionPreviewSizedPath(**data)
+
+
 class UserWorkspaceAndContentIdPathSchema(
     UserIdPathSchema,
     WorkspaceIdPathSchema,
@@ -164,6 +218,19 @@ class CommentsPathSchema(WorkspaceAndContentIdPathSchema):
         return CommentPath(**data)
 
 
+class PageQuerySchema(marshmallow.Schema):
+    page = marshmallow.fields.Int(
+        example=2,
+        default=0,
+        description='allow to show a specific page of a pdf file',
+        validate=Range(min=0, error="Value must be positive or 0"),
+    )
+
+    @post_load
+    def make_page_query(self, data):
+        return PageQuery(**data)
+
+
 class FilterContentQuerySchema(marshmallow.Schema):
     parent_id = marshmallow.fields.Int(
         example=2,
@@ -594,10 +661,19 @@ class TextBasedDataAbstractSchema(marshmallow.Schema):
     )
 
 
+class FileInfoAbstractSchema(marshmallow.Schema):
+    raw_content = marshmallow.fields.String(
+        description='raw text or html description of the file'
+    )
+
+
 class TextBasedContentSchema(ContentSchema, TextBasedDataAbstractSchema):
     pass
 
 
+class FileContentSchema(ContentSchema, FileInfoAbstractSchema):
+    pass
+
 #####
 # Revision
 #####
@@ -629,6 +705,10 @@ class TextBasedRevisionSchema(RevisionSchema, TextBasedDataAbstractSchema):
     pass
 
 
+class FileRevisionSchema(RevisionSchema, FileInfoAbstractSchema):
+    pass
+
+
 class CommentSchema(marshmallow.Schema):
     content_id = marshmallow.fields.Int(
         example=6,
@@ -673,6 +753,10 @@ class TextBasedContentModifySchema(ContentModifyAbstractSchema, TextBasedDataAbs
         return TextBasedContentUpdate(**data)
 
 
+class FileContentModifySchema(TextBasedContentModifySchema):
+    pass
+
+
 class SetContentStatusSchema(marshmallow.Schema):
     status = marshmallow.fields.Str(
         example='closed-deprecated',