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.

A tested document

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

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

Overview

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

Volumes

To use this plugin, the local site administrator 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.

id

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

ref

The full path of the root folder.

text

A descriptive text.

base_url

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

backend

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.

id

Internal ID to be used as primary key.

volume

The volume where this file is stored.

parent

The parent directory.

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

is_folder

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

name

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

full_name

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.

broken

Whether the file no longer exists on the file system.

state

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.

receipt

The file which serves as receipt for this database object.

needs_receipt(self)

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.

lino.modlib.files.scan_volumes()

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.