-------------------------------------------------------------------------
██╗ ██╗ ██╗ ██╗ ██╗ ███╗ ██╗ ████████╗ ██████╗ ██╗ ██╗
██║ ██║ ██║ ██║ ██║ ████╗ ██║ ╚══██╔══╝ ██╔══██╗ ╚██╗ ██╔╝
██║ █╗ ██║ ███████║ ██║ ██╔██╗ ██║ ██║ ██████╔╝ ╚████╔╝
██║███╗██║ ██╔══██║ ██║ ██║╚██╗██║ ██║ ██╔═══╝ ╚██╔╝
╚███╔███╔╝ ██║ ██║ ██║ ██║ ╚████║ ██║ ██║ ██║
╚══╝╚══╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚═══╝ ╚═╝ ╚═╝ ╚═╝
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:
- "whintpy": the source code package
- "docs": the documentation of
whintpylibrary in Markdown - "tests": the unit tests of the source code
- "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