uploads : Managing uploaded files

The lino.modlib.uploads plugin adds functionality for managing "uploads". It holds the minimal core functionality. There is also the lino_xl.lib.uploads plugin, which extends this plugin and which is described in Uploads with expiration date management.

This is a tested document. The following instructions are used for initialization:

>>> from lino import startup
>>> startup('lino_book.projects.min9.settings')
>>> from lino.api.doctest import *


upload entry

A database record that represents an independent media file that has been uploaded to the Lino site either via the web interface or as a library file.

upload file

A synonym for upload entry.

uploads folder

The root folder below which all uploaded files are being stored on the server.

We differentiate between web uploads and library uploads. They look quite similar to the end user who may even ignore that difference. But they differ by the way they arrived to the server. Web uploads were uploaded manually by some user via the web interface, while library uploads have been discovered by Lino in a library volume. Web uploads are stored below the uploads folder while library uploads are stored below the folder given by their library volume.

A third type of upload files are fileless uploads. Yes, you can even have upload files without an actual file. This represents the fact that some external document exists, but just hasn't been digitalized. There are people are interested in this kind of fact ;-)

All upload files are stored in a single database table called Upload.

upload controller

Any database object used as the controller of an upload file.

Every upload file is usually linked to its controller, i.e. some database object that inherits from UploadController. Upload files without a controller are considered useless, and the site manager should decide what to do with them.

library volume

A folder in the file system where library uploads are stored.

The site manager can configure library volumes via the menu command Configure ‣ Uploads ‣ Library volumes. Lino watches the files in the folder tree of a library volume and can automatically create an upload file for every new file.


upload type

The type of an upload file.

upload area

A group of upload types that are being displayed in a given upload panel.

Upload files

class lino.modlib.uploads.Upload

Django model representing an upload file.


Pointer to the uploaded file itself (a Django FileField).


The size of the file in bytes. Not yet implemented.


The media type of the uploaded file.

See also this thread about length of MIME type field.


The type of this upload.

Pointer to UploadType. The choices for this field are usually limited to those in the same upload area.


A short description entered manually by the user.


A pointer to the library volume where this file is stored.


The upload area this file belongs to.


The path of this file, relative the volume's root.

Almost the same as description, but if file is not empty, the text is clickable, and clicking on it opens the uploaded file in a new browser window.

class lino.modlib.uploads.AreaUploads

Mixin for tables of uploads where the area is known. Inherited by UploadsByController.

The summary displays the uploads related to this controller as a list grouped by uploads type.

Note that this also works on lino_welfare.modlib.uploads.models.UploadsByProject and their subclasses for the different _upload_area.

class lino.modlib.uploads.MyUploads

Shows my uploads (i.e. those whose author is the current user).

class lino.modlib.uploads.UploadsByController

Shows the uploads controlled by this database object.

class lino.modlib.uploads.UploadBase

Abstract base class of Upload. This was named lino.mixins.uploadable.Uploadable until 20210217. It encapsulates some really basic functionality. Its usage is deprecated. If you were inheriting from lino.mixins.Uploadable, you should convert that model to point to an Upload instead.

Upload areas

The application developer can define upload areas. Every upload area has its list of upload types. The default has only one upload area.

>>> rt.show(uploads.UploadAreas)
======= ========= =========
 value   name      text
------- --------- ---------
 90      general   Uploads
======= ========= =========

For example Lino Welfare extends this list.

Upload types

class lino.modlib.uploads.UploadType

Django model representing an upload type.


Optional pointer to a virtual upload shortcut field. If this is not empty, then the given shortcut field will manage uploads of this type. See also Shortcuts.

class lino.modlib.uploads.UploadTypes

The table with all existing upload types.

This usually is accessible via the Configure menu.

Upload controllers

class lino.modlib.uploads.UploadController

Model mixin that turns a model into an upload controller.

show_uploads(self, obj, ar=None)

Show uploads in a grid table.

Upload shortcuts

The application developer can define upload shortcuts. Every upload shortcut will create an upload shortcut field, a virtual field with a set of actions for quickly uploading or viewing uploads of a particular type for a given database object.


  • Declare your Site's upload shortcuts from within your workflows_module. For example:

    from lino.modlib.uploads.choicelists import add_shortcut as add
    add('contacts.Person', 'uploaded_foos', _("Foos"))
  • Make the uploaded_foos field visible in some detail layout.

  • Using the web interface, select Configure ‣ Office ‣ Upload types, create an upload type named "Foo" and set its shortcut field to "Foos".

  • Upload a file from your PC to the server.

  • Open the uploaded file in a new browser window

class lino.modlib.uploads.Shortcuts

The list of available upload shortcut fields in this application.

>>> rt.show(uploads.Shortcuts)
No data to display
lino.modlib.uploads.add_shortcut(*args, **kw)

Declare an upload shortcut field. This is designed to be called from within your workflows_module.


A directory below your media directory. This is where web uploads (i.e. files uploaded via the web interface) are stored. Lino creates this directory at startup if it doesn't exist.

Data checkers

This plugin defines two data checkers:

class lino.modlib.uploads.UploadChecker
class lino.modlib.uploads.UploadsFolderChecker

Find orphaned files in uploads folder.

Walks through the uploads folder and reports files for which there is no upload entry