From 7a0c2224bbdddd303823dddfb2efc9888ada6ad0 Mon Sep 17 00:00:00 2001 From: Roberto Rosario Date: Tue, 25 Apr 2017 14:21:30 -0400 Subject: [PATCH] Add model docstrings. Signed-off-by: Roberto Rosario --- mayan/apps/acls/models.py | 12 +++++-- mayan/apps/converter/classes.py | 4 +++ mayan/apps/converter/models.py | 8 ++++- mayan/apps/django_gpg/models.py | 5 +++ mayan/apps/document_indexing/models.py | 10 +++++- mayan/apps/document_signatures/models.py | 10 ++++++ mayan/apps/document_states/models.py | 32 ++++++++++++++++++ mayan/apps/documents/models.py | 23 ++++++++++++- mayan/apps/sources/models.py | 42 ++++++++++++++++++++++++ 9 files changed, 141 insertions(+), 5 deletions(-) diff --git a/mayan/apps/acls/models.py b/mayan/apps/acls/models.py index 57737b5114..3e7cc833ff 100644 --- a/mayan/apps/acls/models.py +++ b/mayan/apps/acls/models.py @@ -18,9 +18,17 @@ logger = logging.getLogger(__name__) @python_2_unicode_compatible class AccessControlList(models.Model): """ - Model that hold the permission, object, actor relationship + ACL means Access Control List it is a more fine-grained method of + granting access to objects. In the case of ACLs, they grant access using + 3 elements: actor, permission, object. In this case the actor is the role, + the permission is the Mayan permission and the object can be anything: + a document, a folder, an index, etc. This means = "Grant X permissions + to role Y for object Z". This model holds the permission, object, actor + relationship for one access control list. + Fields: + * Role - Custom role that is being granted a permission. Roles are created + in the Setup menu. """ - content_type = models.ForeignKey( ContentType, related_name='object_content_type' diff --git a/mayan/apps/converter/classes.py b/mayan/apps/converter/classes.py index f19d3b7b6b..9ab180e6fe 100644 --- a/mayan/apps/converter/classes.py +++ b/mayan/apps/converter/classes.py @@ -216,6 +216,10 @@ class ConverterBase(object): class BaseTransformation(object): + """ + Transformation can modify the appearance of the document's page preview. + Some transformation available are: Rotate, zoom, resize and crop. + """ arguments = () name = 'base_transformation' _registry = {} diff --git a/mayan/apps/converter/models.py b/mayan/apps/converter/models.py index 817ee605ee..32faf5ac45 100644 --- a/mayan/apps/converter/models.py +++ b/mayan/apps/converter/models.py @@ -21,8 +21,14 @@ class Transformation(models.Model): """ Model that stores the transformation and transformation arguments for a given object + Fields: + * order - Order of a Transformation - In case there are multiple + transformations for an object, this field list the order at which + they will be execute. + * arguments - Arguments of a Transformation - An optional field to hold a + transformation argument. Example: if a page is rotated with the Rotation + transformation, this field will show by how many degrees it was rotated. """ - content_type = models.ForeignKey(ContentType) object_id = models.PositiveIntegerField() content_object = GenericForeignKey('content_type', 'object_id') diff --git a/mayan/apps/django_gpg/models.py b/mayan/apps/django_gpg/models.py index feccaecc75..ebffe2c084 100644 --- a/mayan/apps/django_gpg/models.py +++ b/mayan/apps/django_gpg/models.py @@ -23,6 +23,11 @@ logger = logging.getLogger(__name__) @python_2_unicode_compatible class Key(models.Model): + """ + Fields: + * key_type - Will show private or public, the only two types of keys in + a public key infrastructure, the kind used in Mayan. + """ key_data = models.TextField( help_text=_('ASCII armored version of the key.'), verbose_name=_('Key data') diff --git a/mayan/apps/document_indexing/models.py b/mayan/apps/document_indexing/models.py index e3499c718a..a276a8113a 100644 --- a/mayan/apps/document_indexing/models.py +++ b/mayan/apps/document_indexing/models.py @@ -19,6 +19,10 @@ from .managers import ( @python_2_unicode_compatible class Index(models.Model): + """ + Parent model that defines an index and hold all the relationship for its + template and instance when resolved. + """ label = models.CharField( max_length=128, unique=True, verbose_name=_('Label') ) @@ -65,7 +69,6 @@ class Index(models.Model): """ Automatically create the root index template node """ - super(Index, self).save(*args, **kwargs) IndexTemplateNode.objects.get_or_create(parent=None, index=self) @@ -102,6 +105,11 @@ class IndexInstance(Index): @python_2_unicode_compatible class IndexTemplateNode(MPTTModel): + """ + The template to generate an index. Each entry represents a level in a + hierarchy of levels. Each level can contain further levels or a list of + documents but not both. + """ parent = TreeForeignKey('self', blank=True, null=True) index = models.ForeignKey( Index, related_name='node_templates', verbose_name=_('Index') diff --git a/mayan/apps/document_signatures/models.py b/mayan/apps/document_signatures/models.py index 53dcff0de7..fede657b90 100644 --- a/mayan/apps/document_signatures/models.py +++ b/mayan/apps/document_signatures/models.py @@ -26,6 +26,16 @@ def upload_to(*args, **kwargs): @python_2_unicode_compatible class SignatureBaseModel(models.Model): + """ + Fields: + * key_id - Key Identifier - This is what identifies uniquely a key. Not + two keys in the world have the same Key ID. The Key ID is also used to + locate a key in the key servers: http://pgp.mit.edu + * signature_id - Signature ID - Every time a key is used to sign something + it will generate a unique signature ID. No two signature IDs are the same, + even when using the same key. + """ + document_version = models.ForeignKey( DocumentVersion, editable=False, related_name='signatures', verbose_name=_('Document version') diff --git a/mayan/apps/document_states/models.py b/mayan/apps/document_states/models.py index 1f6b78965f..d58ebb527c 100644 --- a/mayan/apps/document_states/models.py +++ b/mayan/apps/document_states/models.py @@ -21,6 +21,11 @@ logger = logging.getLogger(__name__) @python_2_unicode_compatible class Workflow(models.Model): + """ + Fields: + * label - Identifier. A name/label to call the workflow + """ + label = models.CharField( max_length=255, unique=True, verbose_name=_('Label') ) @@ -66,6 +71,16 @@ class Workflow(models.Model): @python_2_unicode_compatible class WorkflowState(models.Model): + """ + Fields: + * completion - Completion Amount - A user defined numerical value to help + determine if the workflow of the document is nearing completion (100%). + The Completion Amount will be determined by the completion value of the + Actual State. Example: If the workflow has 3 states: registered, approved, + archived; the admin could give the follow completion values to the + states: 33%, 66%, 100%. If the Actual State of the document if approved, + the Completion Amount will show 66%. + """ workflow = models.ForeignKey( Workflow, related_name='states', verbose_name=_('Workflow') ) @@ -155,6 +170,12 @@ class WorkflowInstance(models.Model): pass def get_current_state(self): + """ + Actual State - The current state of the workflow. If there are + multiple states available, for example: registered, approved, + archived; this field will tell at the current state where the + document is right now. + """ try: return self.get_last_transition().destination_state except AttributeError: @@ -167,6 +188,10 @@ class WorkflowInstance(models.Model): return None def get_last_transition(self): + """ + Last Transition - The last transition used by the last user to put + the document in the actual state. + """ try: return self.get_last_log_entry().transition except AttributeError: @@ -224,6 +249,13 @@ class WorkflowInstance(models.Model): @python_2_unicode_compatible class WorkflowInstanceLogEntry(models.Model): + """ + Fields: + * user - The user who last transitioned the document from a state to the + Actual State. + * datetime - Date Time - The date and time when the last user transitioned + the document state to the Actual state. + """ workflow_instance = models.ForeignKey( WorkflowInstance, related_name='log_entries', verbose_name=_('Workflow instance') diff --git a/mayan/apps/documents/models.py b/mayan/apps/documents/models.py index 2461e89c64..a566bc5f90 100644 --- a/mayan/apps/documents/models.py +++ b/mayan/apps/documents/models.py @@ -141,6 +141,10 @@ class DocumentType(models.Model): class Document(models.Model): """ Defines a single document with it's fields and properties + Fields: + * uuid - UUID of a document, universally Unique ID. An unique identifier + generated for each document. No two documents can ever have the same UUID. + This ID is generated automatically. """ uuid = models.UUIDField(default=uuid.uuid4, editable=False) @@ -329,6 +333,18 @@ class DeletedDocument(Document): class DocumentVersion(models.Model): """ Model that describes a document version and its properties + Fields: + * mimetype - File mimetype. MIME types are a standard way to describe the + format of a file, in this case the file format of the document. + Some examples: "text/plain" or "image/jpeg". Mayan uses this to determine + how to render a document's file. More information: + http://www.freeformatter.com/mime-types-list.html + * encoding - File Encoding. The filesystem encoding of the document's + file: binary 7-bit, binary 8-bit, text, base64, etc. + * checksum - A hash/checkdigit/fingerprint generated from the document's + binary data. Only identical documents will have the same checksum. If a + document is modified after upload it's checksum will not match, used for + detecting file tampering among other things. """ _pre_open_hooks = {} _post_save_hooks = {} @@ -444,7 +460,9 @@ class DocumentVersion(models.Model): def exists(self): """ Returns a boolean value that indicates if the document's file - exists in storage + exists in storage. Returns True if the document's file is verified to + be in the document storage. This is a diagnostic flag to help users + detect if the storage has desynchronized (ie: Amazon's S3). """ return self.file.storage.exists(self.file.name) @@ -502,6 +520,9 @@ class DocumentVersion(models.Model): @property def page_count(self): + """ + The number of pages that the document posses. + """ return self.pages.count() def revert(self, _user=None): diff --git a/mayan/apps/sources/models.py b/mayan/apps/sources/models.py index ed8cc90c6b..a70344dec9 100644 --- a/mayan/apps/sources/models.py +++ b/mayan/apps/sources/models.py @@ -154,6 +154,21 @@ class InteractiveSource(Source): class StagingFolderSource(InteractiveSource): + """ + The Staging folder source is interactive but instead of displaying an + HTML form (like the Webform source) that allows users to freely choose a + file from their computers, shows a list of files from a filesystem folder. + When creating staging folders administrators choose a folder in the same + machine where Mayan is installed. This folder is then used as the + destination location of networked scanners or multifunctional copiers. + The scenario for staging folders is as follows: An user walks up to the + networked copier, scan several papers documents, returns to their + computer, open Mayan, select to upload a new document but choose the + previously defined staging folder source, now they see the list of + documents with a small preview and can proceed to process one by one and + convert the scanned files into Mayan EDMS documents. Staging folders are + useful when many users share a few networked scanners. + """ is_interactive = True source_type = SOURCE_CHOICE_STAGING @@ -234,6 +249,14 @@ class StagingFolderSource(InteractiveSource): class WebFormSource(InteractiveSource): + """ + The webform source is an HTML form with a drag and drop window that opens + a file browser on the user's computer. This Source is interactive, meaning + users control live what documents they want to upload. This source is + useful when admins want to allow users to upload any kind of file as + documents from their own computers such as when each user has their own + scanner. + """ is_interactive = True source_type = SOURCE_CHOICE_WEB_FORM @@ -331,6 +354,15 @@ class IntervalBaseModel(OutOfProcessSource): class EmailBaseModel(IntervalBaseModel): + """ + POP3 email and IMAP email sources are non-interactive sources that + periodically fetch emails from an email account using either the POP3 or + IMAP email protocol. These sources are useful when users need to scan + documents outside their office, they can photograph a paper document with + their phones and send the image to a designated email that is setup as a + Mayan POP3 or IMAP source. Mayan will periodically download the emails + and process them as Mayan documents. + """ host = models.CharField(max_length=128, verbose_name=_('Host')) ssl = models.BooleanField(default=True, verbose_name=_('SSL')) port = models.PositiveIntegerField(blank=True, null=True, help_text=_( @@ -572,6 +604,16 @@ class IMAPEmail(EmailBaseModel): class WatchFolderSource(IntervalBaseModel): + """ + The watch folder is another non-interactive source that like the email + source, works by periodically checking and processing documents. This + source instead of using an email account, monitors a filesystem folder. + Administrators can define watch folders, examples /home/mayan/watch_bills + or /home/mayan/watch_invoices and users just need to copy the documents + they want to upload as a bill or invoice to the respective filesystem + folder. Mayan will periodically scan these filesystem locations and + upload the files as documents, deleting them if configured. + """ source_type = SOURCE_CHOICE_WATCH folder_path = models.CharField(