core.filestorage
================

.. py:module:: core.filestorage

.. autoapi-nested-parse::

   Filestorage is a way to store files locally or on a remote server, with the
   interface being the same, no matter where the files are stored.

   Based on `<https://docs.pyfilesystem.org/en/latest/>`_

   See :attr:`onegov.core.framework.Framework.filestorage` for more information.



Classes
-------

.. autoapisummary::

   core.filestorage.FilestorageFile


Functions
---------

.. autoapisummary::

   core.filestorage.random_filename
   core.filestorage.get_filestorage_file
   core.filestorage.view_filestorage_file
   core.filestorage.delete_static_file


Module Contents
---------------

.. py:function:: random_filename() -> str

   Returns a random filename that can't be guessed. 


.. py:class:: FilestorageFile(path: str)

   Defines a static file served by the application. The difference
   between this and :class:`onegov.core.static.StaticFile` is the storage.

   Filestorage files are stored per application_id locally or on the cloud.
   Static files are the same for the whole application class and they are
   deployed statically. That means they are not content, but part of
   the distribution.

   Note that this is only used if the file is local. Files stored in the
   filestorage should be linked using
   :meth:`onegov.core.request.CoreRequest.filestorage_link`, which might
   result in a local path, for which this class is used. Or it might result in
   a remote path that is served by some different webserver.



   .. py:attribute:: storage
      :value: 'filestorage'



   .. py:attribute:: path


   .. py:property:: absorb
      :type: str



.. py:function:: get_filestorage_file(app: onegov.core.framework.Framework, absorb: str) -> FilestorageFile | None

.. py:function:: view_filestorage_file(self: FilestorageFile, request: core.request.CoreRequest) -> str

   Renders the given filestorage file in the browser. 


.. py:function:: delete_static_file(self: FilestorageFile, request: core.request.CoreRequest) -> None

   Deletes the given filestorage file. By default the permission is
   ``Private``. An application using the framework can override this though.

   Since a DELETE can only be sent through AJAX it is protected by the
   same-origin policy. That means that we don't need to use any CSRF
   protection here.

   That being said, browser bugs and future changes in the HTML standard
   make it possible for this to happen one day. Therefore, a time-limited
   token must be passed as query parameter to this function.

   New tokens can be acquired through ``request.new_csrf_token``.