Represent a file that will be uploaded to a server.
It is designed to maintain metadata associated with the document. Logging should be enabled to get some messages.
>>> # Create a new Document instance with all information
>>> doc = Document("Alice", "Doc1.txt", content="a cool content",
>>> date=datetime(2024, 1, 1), filetype="txt")
Initialize the document with the provided parameters.
When the document is created, it is saved in a folder with the following format: authordatefiletype_filename
>>> # Create a document without the extension in the filename (default: txt):
>>> doc = Document("Alice", "Doc1", "Your_content", date=datetime.datetime(2023, 1, 1))
>>> # Create a document with the extension in the filename:
>>> doc2 = Document("Alice", "Doc1.txt", "Your_content", date=datetime.date(2023, 1, 1))
>>> # Create a document without a date and filetype:
>>> doc1 = Document("Alice", "Doc1", "Your_content")
def __init__(self, author: str, filename: str, date: datetime.date | datetime.datetime | None=None, content: str | bytes='', description: str='', downloads: int=0):
"""Initialize the document with the provided parameters.
When the document is created, it is saved in a folder with the following format:
author_date_filetype_filename
:Example:
>>> # Create a document without the extension in the filename (default: txt):
>>> doc = Document("Alice", "Doc1", "Your_content", date=datetime.datetime(2023, 1, 1))
>>> # Create a document with the extension in the filename:
>>> doc2 = Document("Alice", "Doc1.txt", "Your_content", date=datetime.date(2023, 1, 1))
>>> # Create a document without a date and filetype:
>>> doc1 = Document("Alice", "Doc1", "Your_content")
:param filename: (str) The name of the file provided with the extension
:param author: (str) The author of the file
:param content: (str) The content of the file (optional)
:param date: (datetime|date) The date of the file (optional) (default: today)
:param description: (str) The description of the file (optional)
:raises: ValueError: if the filename is too short
:raises: TypeError: if the parameters are not in the correct format
"""
if len(filename) < ws.MIN_FILE_NAME_LENGTH:
raise ValueError('Document.__init__: filename must be at least 4 characters long.')
if len(author) < 1 or len(filename) < 1:
raise ValueError('Document.__init__: author and filename must be at least 1 character long.')
TypesDealer.check_types('Document.__init__', [(author, str), (filename, str), (description, (str, type(None)))])
TypesDealer.check_types('Document.__init__', [(content, (str, bytes))])
TypesDealer.check_types('Document.__init__', [(downloads, int)])
if date is not None:
TypesDealer.check_types('Document.__init__', [(date, (datetime.datetime, datetime.date))])
self.__author = DocumentUtils.format_author(author)
self.__filename = DocumentUtils.format_filename(filename)
self.__filetype = DocumentUtils.get_filetype(filename)
self.__date = DocumentUtils.format_date(date)
self.__downloads = downloads
self.__content = ''
self.__description = ''
self.set_description(description)
self.set_content(content)
Return an immutable copy of the document.
Creates and returns an immutable copy of the current Document instance. This ensures that the returned document cannot be modified, preserving its state at the time of the method call.
def to_immutable(self) -> ImmutableDocument:
"""Return an immutable copy of the document.
Creates and returns an immutable copy of the current Document instance.
This ensures that the returned document cannot be modified, preserving
its state at the time of the method call.
"""
return ImmutableDocument(author=self.__author, filename=self.__filename + '.' + self.__filetype, content=self.__content, date=self.__date, description=self.__description, downloads=self.__downloads)
Return the author of the document.
def get_author(self) -> str:
"""Return the author of the document."""
return self.__author
Return the filename of the document.
def get_filename(self) -> str:
"""Return the filename of the document."""
return self.__filename
Return the filetype of the document.
The filetype is the extension in lower-case and without the dot.
def get_filetype(self) -> str:
"""Return the filetype of the document.
The filetype is the extension in lower-case and without the dot.
"""
return self.__filetype
Return the date associated to the document.
def get_date(self) -> datetime.datetime | datetime.date | None:
"""Return the date associated to the document."""
return self.__date if self.__date is not None else None
Return the description of the document.
def get_description(self) -> str:
"""Return the description of the document.
:return: The description of the document or None if undefined
"""
return self.__description
Set the description of the document with no size limit.
def set_description(self, description: str):
"""Set the description of the document with no size limit.
:param description: (str) The description of the document
"""
TypesDealer.check_types('Document.set_description', [(description, str)])
self.__description = description
Return the name of the folder in which the document is stored.
The folder_name can be used for both:
def get_folder_name(self) -> str:
"""Return the name of the folder in which the document is stored.
The folder_name can be used for both:
- an identifier for the document, and
- get information about the document: author, filename, date and filetype
"""
return DocumentUtils.get_folder_name(self.__author, self.__filename, self.__date, self.__filetype)
Return the number of times the document was downloaded or 0.
def get_downloads(self) -> int:
"""Return the number of times the document was downloaded or 0.
:return: (int) The number of downloads or -1 if error
"""
return self.__downloads
Return the content of the document.
def get_content(self) -> str | bytes | None:
"""Return the content of the document.
:return: (str|bytes|None) The content of the document
"""
return self.__content
Set the content of the document.
def set_content(self, content: str | bytes):
"""Set the content of the document.
:param content: (str) The content of the document
"""
TypesDealer.check_types('Document.set_content', [(content, (str, bytes))])
self.__content = content
Increment the number of downloads of the document.
def increment_downloads(self) -> int:
"""Increment the number of downloads of the document."""
self.__downloads += 1
return self.__downloads
Create an ImmutableDocument().
@staticmethod
def create_document_by_folder_name(folder_name: str, description: str='', downloads: int=0) -> ImmutableDocument:
"""Create an ImmutableDocument().
:param folder_name: (str) Name of the document folder
:param description: (str) The description of the document
:param downloads: (int) The number of downloads of the document
:raises: TypeError: An invalid given parameter
:raises: ValueError: Invalid folder_name format
:return: (ImmutableDocument) An instance created from the given folder name
"""
TypesDealer.check_types('Document.get_document_by_folder_name', [(folder_name, str)])
array = folder_name.split(ws.FOLDER_NAME_SEPARATOR)
if len(array) > 4:
raise ValueError("Expected a folder name with at least 4 fields (author, date, filename, filetype) separated by '{:s}'. Got {:d} fields instead.".format(ws.FOLDER_NAME_SEPARATOR, len(array)))
return ImmutableDocument(array[0], array[3] + '.' + array[2], date=DocumentUtils.str_to_date(array[1]), description=description, downloads=downloads)
def __str__(self):
return f'Document({self.get_author()}, {self.filename}, {self.date}, {self.__filetype})'
def __repr__(self):
return f'Document(author={self.get_author()}, filename={self.filename}, date={self.date}, filetype={self.__filetype})'
Check equality of two documents.
Checks if two Document instances are equal by comparing their author, filename, filetype, and date.
def __eq__(self, other):
"""Check equality of two documents.
Checks if two Document instances are equal by comparing their author,
filename, filetype, and date.
:param other: (Document) The document to be compared
:return: (bool) True if the two documents are equal, False otherwise
"""
if self is other:
return True
if isinstance(other, (Document, ImmutableDocument)) is True:
return self.__author == other.author and self.__filename == other.filename and (DocumentUtils.date_to_str(self.__date) == DocumentUtils.date_to_str(other.date)) and (self.__filetype == other.filetype)
return False