Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More

files : Manage external files

Deprecated. This plugin was never used. See 2019-02-07.

The lino.modlib.files plugin adds functionality for managing references to external files stored somewhere in a file system.

Lines starting with >>> in this document are code snippets that get tested as part of our development workflow.

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


A volume is a folder on the file system that is to be observed by Lino. The Volumes choicelist holds the volumes and gives the base URL where these files are expected to be served.

For every file found in a volume, Lino will create an instance of the File model which represents the file.

The Receivable mixins is what we are going to use on invoices in Lino Così.

The PendingReceivables table shows all receivables that need a receipt but don’t have any.

The DanglingFiles table shows all unused files (i.e. which aren’t referred


To use this plugin, the local site manager must define volumes.

A volume is a folder on the file system that is to be observed by Lino. The volume gives the base URL where these files are expected to be served.

class lino.modlib.files.Volume

The Django model representing a file volume.


The primary key used to point to this volume from a database object.


The full path of the root folder.


A descriptive text.


The base URL where files of this volume are being served.


The file backend used to access the files on this volume.

Currently this is ignored, Lino supports only the “local filesystem” backend.

Files and directories

class lino.modlib.files.File

The Django model representing a file or directory on a file system.


Internal ID to be used as primary key.


The volume where this file is stored.


The parent directory.

This may be null only for the root folder of a volume.


Whether this is a directory, i.e. a special file which contains other files and has no content on its own.


The name of this file. Must be unique among siblings of a same parent.


The full path name relative to the root folder of the volume.

This field is a read-only summary field. And gets automatically updated e.g. when the name of a parent changes.


Whether the file no longer exists on the file system.


The state of this file, used to control the workflow.

This can be one of the values in FileStates.

Usages of a file

One of the main purposes of this plugin is to show where a given file is being referred to in our database.

class lino.modlib.files.UsagesByFile
class lino.modlib.files.FileStates

A choicelist with the possible states of a file.

class lino.modlib.files.Receivable

A mixin for models that require their every object to have a scan or pdf file of the “receipt”, i.e. the document serving as the legal proof of this database object. A usage example are purchase invoices in an accounting system.

Receivables without such a receipt will appear in the PendingReceivables table.


The file which serves as receipt for this database object.


Return True if this database object needs a receipt.

Application developer can define rules for exempting a given database object from needing a receipt by overriding this method.

Updating the database from the file system

When new files are stored to the file system, the scan_volumes() function detects them adds a new File object for each of them.

That function also checks whether the files found on previous scans still exist and marks them as broken.


Scan the file system below all volumes and create descriptors for every file that doesn’t yet have one. Mark file descriptors as broken if the file they describe does no longer exist.

This function is automatically run by linod.

Assign new receipts to their receivable

class lino.modlib.files.PendingReceivables

Shows all receivables that need a receipt but don’t have any.

class lino.modlib.files.BrokenFiles

Shows all unused files (i.e. which aren’t referred to by any database object).

Receipts folders

This is an idea to be discussed later. Not yet implemented.

A receipts folder is a folder with files that should be used as receivables. any file in such a folder which is not used by some Receivable will be mentioned in the DanglingReceipts table.

The local system administrator can specify a receipts folder like this:

AccountInvoice.add_receivable_folder("luc", "/receipts", "EKR")
class lino.modlib.files.DanglingReceipts

Shows all files that are a receipt but aren’t used as such by any receivable.