-------------------------------------------------------------------------

    ██╗    ██╗ ██╗  ██╗ ██╗ ███╗   ██╗ ████████╗ ██████╗  ██╗   ██╗
    ██║    ██║ ██║  ██║ ██║ ████╗  ██║ ╚══██╔══╝ ██╔══██╗ ╚██╗ ██╔╝
    ██║ █╗ ██║ ███████║ ██║ ██╔██╗ ██║    ██║    ██████╔╝  ╚████╔╝ 
    ██║███╗██║ ██╔══██║ ██║ ██║╚██╗██║    ██║    ██╔═══╝    ╚██╔╝  
    ╚███╔███╔╝ ██║  ██║ ██║ ██║ ╚████║    ██║    ██║         ██║   
     ╚══╝╚══╝  ╚═╝  ╚═╝ ╚═╝ ╚═╝  ╚═══╝    ╚═╝    ╚═╝         ╚═╝   

            a Python library for managing shared files

Copyright (C) 2024 Laboratoire Parole et Langage, Aix-en-Provence, France
-------------------------------------------------------------------------

WhintPy description

Overview

WhintPy is a pure Python-based solution for managing shared files locally or on a web server.

Use case

You have a web server that you want to use as a file server. You want all users in your local network to get access to all files stored in that server via web browser.
You then need a web-based file manager allowing any authenticated user to download or upload any file from anywhere via web browser.
You want a powerful solution to filter the list of available documents. WhintPy is the server-side of such a tool.

Features

WhintPy is a pure Python, free, open-source, self-hosted library for managing shared files locally or on a web server.
It is a lightweight library which aims to allow users to upload, download, delete, and efficiently search files from anywhere without the need for any additional software.

It allows a web-site to deal with:

• several authentication methods which can be combined;
• user documents deposit: you'll have access to the basic file operations create, edit, delete, download, and upload;
• a powerful system to get access to the documents with filters on the author, description, filename, extension and date.

Main advantages

• easily customizable: it's a pure python library in Object-Oriented Programming
• open-source: easily add new features and functionalities
• scalable: no limit to support numerous users and files
• portable: can be hosted on any web server - as soon as python is available, or used locally

Install WhintPy

From its pypi:

> python -m pip install WhintPy

From its repo:

Download the latest ".zip" from https://sourceforge.net/projects/whintpy/ and unpack it, or clone the repository with git.

WhintPy package includes the following folders and files:

1. "whintpy": the source code package
2. "docs": the documentation of whintpy library in Markdown
3. "tests": the unit tests of the source code
4. "sample": an application sample

> # Install from the zip archive:
> unzip WhintPy-xxx.zip 
> # or with git:
> git clone https://git.code.sf.net/p/whakerpy/code whakerpy-code
> # Install both the required external libraries and WintPy in your python environment
> python -m pip install .

Quick start

Create a document manager, add documents, and retrieve those matching some filter criteria by doing the following:

from whintpy.deposit import Document
>>> # Create several doc instances
>>> doc1 = Document("Sarah Connor", "Terminator's target.png", date=date.datetime(1984, 5, 12))
>>> doc2 = Document("T-800", "I'll be back.txt", date=date.datetime(1984, 5, 12))
>>> doc3 = Document("Skynet", "JudgementDay.TXT", date=date.datetime(1997, 8, 29))
>>> doc1.author
"Sarah-Connor"
>>> doc1.filename
"Terminators-target"
>>> doc3.filetype
"txt"

Add documents into a document manager:

>>> from whintpy.deposit import DocumentsManager
>>> manager = DocumentsManager("some_docs_path")
>>> manager.add_docs([doc1, doc2, doc3])
>>> # Add one more document directly to the manager
>>> doc4 = manager.add("Dani Ramos", "Dark Fate.txt", description="The Resistance sends Grace, an augmented soldier, back in time to defend Dani, who is also joined by Sarah Connor and Skynet's T-800.")
>>> # Get the most recent -- doc4
>>> most_recent = manager.get_docs_sorted_by_newest()[0]
>>> # Get the oldest -- either doc1 or doc2
>>> oldest = manager.get_docs_sorted_by_oldest()[0]

Retreive documents matching some criteria:

>> > from whintpy.deposit import DocumentsManager
>> >  # Create a document manager and retrieve existing documents
>> > manager = DocumentsManager("some_docs_path")
>> > manager.collect_docs()
>> >  # Get documents of date="1984-5-12" -- doc1 and doc2
>> > _docs = manager.filter(("date", "iexact", [datetime.date(1997, 8, 29)]))
>> >  # Get documents of filetype "txt" -- doc2, doc3 and doc4
>> > _docs = manager.filter(("filetype", "exact", ["txt"]))
>> >  # Get documents of both date="1984-5-12" and of filetype "txt" -- doc2
>> > _docs = manager.filter(("date", "iexact", [datetime.date(1997, 8, 29)], ("filetype", "exact", ["txt"])),
                            match_all=True)

The documents can also have a content - fortunately, a description, etc. They can be filtered with a large amount of criteria which can be combined together. And the API also allows to manage user's authentication to get a controlled access to the documents.

Make the doc

The API documentation is available in the docs folder in Markdown format. HTML format is available on the web at https://whintpy.sourceforge.io.

To generate the documentation files, install the required external programs, then launch the doc generator:

>python -m pip install ".[docs]"
>python makedoc.py

Click the file docs/index.html to browse throw the documented modules and classes.

Help / How to contribute

If you plan to contribute to the code or to report a bug, please send an e-mail to the author.
Any and all constructive comments are welcome.

License/Copyright

See the accompanying LICENSE and AUTHORS.md files for the full list of contributors.

Copyright (C) 2024 Brigitte Bigi, CNRS
Laboratoire Parole et Langage, Aix-en-Provence, France

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see https://www.gnu.org/licenses/.

Changes

v1.0 - 2024-06-13

Initial version of WhintPy, a Python library for managing shared files, which includes:

• authentication with either ldap3, jwt, both or none of them.
• manage a folder with documents deposit
• allows to assign a description and a number of download to each document
• retrieve documents sorted by names, or number of downloads
• get access to documents with filters on the author, filename, filetype, date or description

v1.1 - 2024-10-12

Same features as the initial version but with an optimized implementation.

next version

todo:

• implement a search engine
• add scripts and samples