diff --git a/docs/css/custom_css.css b/docs/css/custom_css.css index 9147825..5f6e922 100644 --- a/docs/css/custom_css.css +++ b/docs/css/custom_css.css @@ -7,3 +7,39 @@ table { display: table !important; border-spacing: 0px !important; } + +div.autodoc-docstring { + padding-left: 20px; + margin-bottom: 30px; + border-left: 5px solid rgba(230, 230, 230); +} + +div.autodoc-members { + padding-left: 20px; + margin-bottom: 15px; +} + +div.autodoc-signature *{ + /*display: none;*/ + all: initial !important; + /* + font-style: italic !important; + font-feature-settings: "kern","liga" !important; + font-family: var(--md-text-font-family,_),-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif !important; + */ + font-feature-settings: inherit !important; + font-family: inherit !important; + font-size: large !important; + font-weight: 600 !important; + /*color: #36464e !important;*/ + color: #7e54b9 !important; + /*background-color: #f5f5f5 !important;*/ +} +em.autodoc-param{ + font-style: italic !important; + font-weight: 500 !important; +} + +.autodoc-docstring{ + border-color: #977fb8 !important; +} \ No newline at end of file diff --git a/docs/ecnqueue.md b/docs/ecnqueue.md index 9f329aa..7d44c8a 100644 --- a/docs/ecnqueue.md +++ b/docs/ecnqueue.md @@ -1,21 +1,16 @@ # ECNQueue documentation -## Item Class - -::: webqueue2_api.ECNQueue.Item +::: webqueue2_api.ECNQueue :docstring: -### Item functions +## Item Class ::: webqueue2_api.ECNQueue.Item + :docstring: :members: ## Queue Class ::: webqueue2_api.ECNQueue.Queue :docstring: - -### Queue Functions - -::: webqueue2_api.ECNQueue.Queue - :memebers: + :members: diff --git a/docs/webqueue2 backend overview.md b/docs/webqueue2 backend overview.md index 2620d60..9c128d3 100644 --- a/docs/webqueue2 backend overview.md +++ b/docs/webqueue2 backend overview.md @@ -9,4 +9,9 @@ In order to function, the backend of Webqueue2 relies primarily on two scripts, ### ECNQueue.py The `ECNQueue.py` script does all of the data and information parsing. -Items are currently stored in plain text within text files and all updates to those items are documented directly into those textfiles via the `qcli`. The `ECNQueue.py` script parses these text files and stores all the information regarding the item into a custom `Item` object. \ No newline at end of file +Items are currently stored in plain text within text files and all updates to those items are documented directly into those textfiles via the `qcli`. The `ECNQueue.py` script parses these text files and stores all the information regarding the item into a custom `Item` object. + +### api.py +The `api.py` script does all of the interaction between the front end and the `ECNQueue.py` script. + +The front end makes requests, which are then routed to the `api.py` script, which are translated to functions within the `ECNQueue.py`. The json that the `ECNQueue.py` script returns is then returned to the `api.py` script which then routes the json to the frontend. \ No newline at end of file diff --git a/webqueue2_api/ECNQueue.py b/webqueue2_api/ECNQueue.py index 17d9c5a..4fbcd65 100644 --- a/webqueue2_api/ECNQueue.py +++ b/webqueue2_api/ECNQueue.py @@ -85,25 +85,31 @@ def isValidItemName(name: str) -> bool: class Item: """A single issue. - Example: - # Create an Item (ce100) - >>> item = Item("ce", 100) - - Attributes: - lastUpdated: An ISO 8601 formatted time string showing the last time the file was updated according to the filesystem. - headers: A list of dictionaries containing header keys and values. - content: A list of section dictionaries. - isLocked: A boolean showing whether or not a lockfile for the item is present. - userEmail: The email address of the person who this item is from. - userName: The real name of the person who this item is from. - userAlias: The Purdue career account alias of the person this item is from. - assignedTo: The Purdue career account alias of the person this item is assigned to - subject: The subject of the original message for this item. - status: The most recent status update for the item. - priority: The most recent priority for this item. - department: The most recent department for this item. - dateReceived: The date this item was created. - jsonData: A JSON serializable representation of the Item. + **Example:** + + ``` + # Create an Item (ce100) + >>> item = Item("ce", 100) + ``` + + **Attributes:** + + ``` + lastUpdated: An ISO 8601 formatted time string showing the last time the file was updated according to the filesystem. + headers: A list of dictionaries containing header keys and values. + content: A list of section dictionaries. + isLocked: A boolean showing whether or not a lockfile for the item is present. + userEmail: The email address of the person who this item is from. + userName: The real name of the person who this item is from. + userAlias: The Purdue career account alias of the person this item is from. + assignedTo: The Purdue career account alias of the person this item is assigned to + subject: The subject of the original message for this item. + status: The most recent status update for the item. + priority: The most recent priority for this item. + department: The most recent department for this item. + dateReceived: The date this item was created. + jsonData: A JSON serializable representation of the Item. + ``` """ def __init__(self, queue: str, number: int) -> None: @@ -155,11 +161,15 @@ def __init__(self, queue: str, number: int) -> None: def __getLastUpdated(self) -> str: """Returns last modified time of item reported by the filesystem in mm-dd-yy hh:mm am/pm format. - Example: - 07-23-20 10:34 AM + **Example:** + ``` + 07-23-20 10:34 AM + ``` - Returns: - str: last modified time of item reported by the filesystem in mm-dd-yy hh:mm am/pm format. + **Returns:** + ``` + str: last modified time of item reported by the filesystem in mm-dd-yy hh:mm am/pm format. + ``` """ # TODO: Simplify this code block by allowing __getFormattedDate to accept milliseconds since the epoch. unixTime = os.path.getmtime(self.__path) @@ -170,8 +180,10 @@ def __getLastUpdated(self) -> str: def __getRawItem(self) -> list: """Returns a list of all lines in the item file - Returns: - list: List of all the lines in the item file + **Returns:** + ``` + list: List of all the lines in the item file + ``` """ with open(self.__path, errors="replace") as file: return file.readlines() @@ -179,13 +191,18 @@ def __getRawItem(self) -> list: def __getHeaderBoundary(self) -> int: """Returns the 0 based line number where the Item headers stop. - Example: The header end would be on line 13 - 12: X-ECN-Queue-Original-URL: - 13: - 14: I need help. - - Returns: - int: line number where the Item headers end + **Example:** + ``` + The header end would be on line 13 + 12: X-ECN-Queue-Original-URL: + 13: + 14: I need help. + ``` + + **Returns:** + ``` + int: line number where the Item headers end + ``` """ for lineNumber, line in enumerate(self.__rawItem): if line == "\n": @@ -195,16 +212,20 @@ def __parseHeaders(self) -> list: """Returns a list containing dictionaries of header type and data. Removes queue prefixes and whitespace. - Examples: - "[ce] QStatus: Dont Delete\\nFrom: Justin Campbell \\n" - becomes - [ - {"QStatus": "Don't Delete"}, - {"From": "Justin Campbell "} - ] + **Examples:** + ``` + "[ce] QStatus: Dont Delete\\nFrom: Justin Campbell \\n" + becomes + [ + {"QStatus": "Don't Delete"}, + {"From": "Justin Campbell "} + ] + ``` - Returns: - list: Header dicts + **Returns:** + ``` + list: Header dicts + ``` """ headerString = "" @@ -413,25 +434,31 @@ def __parseSections(self) -> list: def __directoryParsing(self, directoryStartLine: int) -> dict: """Returns a dictionary with directory information - Example: - Name: Nestor Fabian Rodriguez Buitrago - Login: rodri563 - Computer: ce-205-38 (128.46.205.67) - Location: HAMP G230 - Email: rodri563@purdue.edu - Phone: 7654766893 - Office: HAMP G230 - UNIX Dir: /home/bridge/b/rodri563 - Zero Dir: U=\\bridge.ecn.purdue.edu\rodri563 - User ECNDB: http://eng.purdue.edu/jump/2e8399a - Host ECNDB: http://eng.purdue.edu/jump/2e83999 - Subject: Autocad installation - - Args: - directoryStartLine (int): line number within the item that the directory starts on - - Returns: - dict: dictionary that splits each line within the directory into a key and a value + **Example:** + + ``` + Name: Nestor Fabian Rodriguez Buitrago + Login: rodri563 + Computer: ce-205-38 (128.46.205.67) + Location: HAMP G230 + Email: rodri563@purdue.edu + Phone: 7654766893 + Office: HAMP G230 + UNIX Dir: /home/bridge/b/rodri563 + Zero Dir: U=\\\\bridge.ecn.purdue.edu\\rodri563 + User ECNDB: http://eng.purdue.edu/jump/2e8399a + Host ECNDB: http://eng.purdue.edu/jump/2e83999 + Subject: Autocad installation + ``` + + **Args:** + + `directoryStartLine (int)`: line number within the item that the directory starts on + + **Returns:** + ``` + dict: dictionary that splits each line within the directory into a key and a value + ``` """ directoryInformation = {"type": "directory_information"} @@ -525,22 +552,29 @@ def __directoryParsing(self, directoryStartLine: int) -> dict: def __assignmentParsing(self, contentStart: int) -> list: """Returns a list with assignment information dictionaries - Example: - Assigned-To: campb303 - Assigned-To-Updated-Time: Tue, 23 Jun 2020 13:27:00 EDT - Assigned-To-Updated-By: campb303 + **Example:** - Args: - contentStart (int): line number where the content starts + ``` + Assigned-To: campb303 + Assigned-To-Updated-Time: Tue, 23 Jun 2020 13:27:00 EDT + Assigned-To-Updated-By: campb303 + ``` - Returns: - list: [ - {"type": "assignment", - "datetime": datetime of the assignment, - "by": user who initiated the assignment, - "to": user who was assigned - }, - ] + **Args:** + + `contentStart (int)`: line number where the content starts + + **Returns:** + + ``` + list: [ + {"type": "assignment", + "datetime": datetime of the assignment, + "by": user who initiated the assignment, + "to": user who was assigned + }, + ] + ``` """ assignmentList = [] @@ -587,24 +621,28 @@ def __assignmentParsing(self, contentStart: int) -> list: def __initialMessageParsing(self, content: list) -> dict: """Returns a dictionary with initial message information - Example: - \n - Testtest\n - \n - - Args: - content (list): content of the initial message - - Returns: - dict: - "type": "initial_message", - "datetime": datetime the initial message was sent, - "from_name": from_name, - "from_email": user_email, - "to": [{email, name}], - "cc": [{email, name}], - "subject": initial message subject - "content": content of the initial message + **Example:** + ``` + \n + Testtest\n + \n + ``` + + **Args:** + `content (list)`: content of the initial message + + **Returns:** + ``` + dict: + "type": "initial_message", + "datetime": datetime the initial message was sent, + "from_name": from_name, + "from_email": user_email, + "to": [{email, name}], + "cc": [{email, name}], + "subject": initial message subject + "content": content of the initial message + ``` """ initialMessageDictionary = {} @@ -665,24 +703,27 @@ def __initialMessageParsing(self, content: list) -> dict: def __editParsing(self, content: list, lineNum: int) -> dict: """Returns a dictionary with edit information - Example: - *** Edited by: campb303 at: 06/23/20 13:27:56 ***\n - \n - This be an edit my boy\n - \n - \n - \n + **Example:** + ``` + \*\*\* Edited by: campb303 at: 06/23/20 13:27:56 \*\*\* + This be an edit my boy - Args: - content (list): content of an edit - lineNum (int): line number of an edit within an item - Returns: - dict: a dictionary with these keys, - "type": "edi", - "by": initiator of the edit, - "datetime": datetime of the edit, - "content": content of the edit + ``` + **Args:** + + `content (list)`: content of an edit + + `lineNum (int)`: line number of an edit within an item + + **Returns:** + ``` + dict: a dictionary with these keys: + "type": "edit", + "by": initiator of the edit, + "datetime": datetime of the edit, + "content": content of the edit + ``` """ # Edit Info dictionary @@ -724,25 +765,30 @@ def __editParsing(self, content: list, lineNum: int) -> dict: def __replyToParsing(self, content: list, lineNum: int) -> dict: """Returns a dictionary with reply to user information - Example: - *** Replied by: campb303 at: 06/23/20 13:28:18 ***\n - \n - This be a reply my son\n - \n - Justin\n - ECN\n - \n + **Example:** + ``` + \*\*\* Replied by: campb303 at: 06/23/20 13:28:18 \*\*\* - Args: - content (list): content of a reply to user - lineNum (int): line number of a reply to user in an item + This be a reply my son + + Justin + ECN + ``` - Returns: - dict: a dictionary with these keys, - "type": "reply_to_user", - "by": initiator of the reply to user, - "datetime": datetime of the reply to user, - "content": content of the reply to user + **Args:** + + `content (list)`: content of a reply to user + + `lineNum (int)`: line number of a reply to user in an item + + **Returns:** + ``` + dict: a dictionary with these keys, + "type": "reply_to_user", + "by": initiator of the reply to user, + "datetime": datetime of the reply to user, + "content": content of the reply to user + ``` """ replyInfo = {} @@ -781,20 +827,27 @@ def __replyToParsing(self, content: list, lineNum: int) -> dict: def __statusParsing(self, content: list, lineNum: int) -> dict: """Returns a dictionary with status information - Example: - *** Status updated by: campb303 at: 6/23/2020 13:26:55 ***\n - Dont Delete\n + **Example:** + ``` + \*\*\* Status updated by: campb303 at: 6/23/2020 13:26:55 \*\*\* + Dont Delete + \n + ``` - Args: - content (list): The content of a status update - lineNum (int): The line number of a status update in an item + **Args:** - Returns: - dict: a dictionary with these keys, - "type": "status", - "by": initiator of the status update, - "datetime": datetime of the status update, - "content": content of the status update + `content (list)`: The content of a status update + + `lineNum (int)`: The line number of a status update in an item + + **Returns:** + ``` + dict: a dictionary with these keys, + "type": "status", + "by": initiator of the status update, + "datetime": datetime of the status update, + "content": content of the status update + ``` """ statusInfo = {} @@ -836,41 +889,47 @@ def __statusParsing(self, content: list, lineNum: int) -> dict: def __userReplyParsing(self, replyContent: list, lineNumber: int) -> dict: """Returns a dictionary with user reply information - Example: - === Additional information supplied by user ===\n - \n - Subject: Re: Beepboop\n - From: Justin Campbell \n - Date: Tue, 23 Jun 2020 13:30:45 -0400\n - X-ECN-Queue-Original-Path: /home/pier/e/queue/Attachments/inbox/2020-06-23/212-original.txt\n - X-ECN-Queue-Original-URL: https://engineering.purdue.edu/webqueue/Attachments/inbox/2020-06-23/212-original.txt\n - \n - Huzzah!\n - \n - ===============================================\n - \n - Args: - replyContent (list): The entire section of a reply-from-user - lineNumber (int): The line number of the begining of a reply-from-user section within and item + **Example:** + ``` + === Additional information supplied by user === + + Subject: Re: Beepboop\n + From: Justin Campbell \n + Date: Tue, 23 Jun 2020 13:30:45 -0400\n + X-ECN-Queue-Original-Path: /home/pier/e/queue/Attachments/inbox/2020-06-23/212-original.txt\n + X-ECN-Queue-Original-URL: https://engineering.purdue.edu/webqueue/Attachments/inbox/2020-06-23/212-original.txt\n + + Huzzah! + + =============================================== + \n + ``` + **Args:** + + `replyContent (list)`: The entire section of a reply-from-user + + `lineNumber (int)`: The line number of the begining of a reply-from-user section within and item Returns: - dict: a dictionary with these keys, - "type": "reply_from_user", - "from_name": name of the user that sent the reply, - "from_email": email of the user that sent the reply, - "subject": subject of the reply, - "datetime": the datetime of the reply, - "cc": [ - {"name": name of the carbon copied recipient, - "email": email of the carbon copied recipient - }, - ] - "content": content of the reply - "headers": [ - {"type": headerType, - "content": content - }, - ] + ``` + dict: a dictionary with these keys, + "type": "reply_from_user", + "from_name": name of the user that sent the reply, + "from_email": email of the user that sent the reply, + "subject": subject of the reply, + "datetime": the datetime of the reply, + "cc": [ + {"name": name of the carbon copied recipient, + "email": email of the carbon copied recipient + }, + ] + "content": content of the reply + "headers": [ + {"type": headerType, + "content": content + }, + ] + ``` """ replyFromInfo = {} @@ -987,22 +1046,23 @@ def __userReplyParsing(self, replyContent: list, lineNumber: int) -> dict: def __getFormattedSectionContent(self, sectionContent: list) -> list: """Returns a list with message content that is stripped of unnecessary newlines and begining delimiters - Example: - *** Edited by: mph at: 02/21/20 10:27:16 ***\n - \n - Still need to rename machines - but the networking issue now seems to \n - be resolved via another ticket.\n - \n - \n - \n - \n - \n + **Example:** + ``` + \*\*\* Edited by: mph at: 02/21/20 10:27:16 \*\*\* + + Still need to rename machines - but the networking issue now seems to \n + be resolved via another ticket. + \n + ``` - Args: - sectionContent (list): The section content of a parsed section + **Args:** - Returns: - list: the section content of a parsed section without any delimiters and unnecessary newlines + `sectionContent (list)`: The section content of a parsed section + + **Returns:** + ``` + list: the section content of a parsed section without any delimiters and unnecessary newlines + ``` """ # Continually removes the first line of sectionContent if it is a newline or delimiter in each iteration while len(sectionContent) > 1: @@ -1037,22 +1097,29 @@ def __getFormattedSectionContent(self, sectionContent: list) -> list: def __errorParsing(self, line: str, lineNum: int, expectedSyntax: str) -> dict: """Returns a dictionary with error parse information when a line is malformed - Example: - "*** Status updated by: ewhile at: 5/7/2020 10:59:11 *** sharing between\n" + **Example:** + ``` + \*\*\* Status updated by: ewhile at: 5/7/2020 10:59:11 \*\*\* + ``` - Args: - line (str): line of that threw error - lineNum (int): line number in the item that threw error - expectedSyntax (str): a message stating the syntax the line should follow + **Args:** - Returns: - dict: a dictionary with these keys, - "type": "parse_error", - "datetime": time the error was encountered, - "file_path": path of the item with erroneos line, - "expected": expectedSyntax, - "got": line, - "line_num": lineNum + `line (str)`: line of that threw error + + `lineNum (int)`: line number in the item that threw error + + `expectedSyntax (str)`: a message stating the syntax the line should follow + + **Returns:** + ``` + dict: a dictionary with these keys, + "type": "parse_error", + "datetime": time the error was encountered, + "file_path": path of the item with erroneos line, + "expected": expectedSyntax, + "got": line, + "line_num": lineNum + ``` """ errorDictionary = {} @@ -1081,14 +1148,19 @@ def __errorParsing(self, line: str, lineNum: int, expectedSyntax: str) -> dict: def __getSortedSections(self, sectionsList: list) -> list: """Sorts the sections chronologically by datetime - Example: - [example] need to do + **Example:** + ``` + [example] need to do + ``` - Args: - sections (list): the list of sections to be sorted + **Args:** - Returns: - list: a list of sections sorted by datetime + `sections (list)`: the list of sections to be sorted + + **Returns:** + ``` + list: a list of sections sorted by datetime + ``` """ sectionsLength = len(sectionsList) sortedSections = [] @@ -1120,14 +1192,21 @@ def __getSortedSections(self, sectionsList: list) -> list: def __isLocked(self) -> Union[str, bool]: """Returns a string info about the lock if true and a bool False if false - Example: A file is locked - "CE 100 is locked by campb303 using qvi" + **Example:** + ``` + A file is locked + "CE 100 is locked by campb303 using qvi" + ``` - Example: a file is not locked - False + **Example:** + ``` + a file is not locked + False + ``` - Returns: - Union[str, bool]: String with info about lock if true, bool False if false + **Returns:** + + `Union[str, bool]`: String with info about lock if true, bool False if false """ lockFile = self.__path + ".lck" if os.path.exists(lockFile): @@ -1143,19 +1222,28 @@ def __getMostRecentHeaderByType(self, headerType: str) -> str: """Return the data of most recent header of the given type. If no header of that type exists, return an empty string. - Example: Requesting a Status header that does exist - __getMostRecentHeaderByType("Status") - becomes "Waiting for Reply" + **Example:** + ``` + Requesting a Status header that does exist + __getMostRecentHeaderByType("Status") + becomes "Waiting for Reply" + ``` - Example: Requesting a Status header that doesn't exist - __getMostRecentHeaderByType("Status") - becomes "" + **Example:** + ``` + Requesting a Status header that doesn't exist + __getMostRecentHeaderByType("Status") + becomes "" + ``` - Args: - headerType (str): Type of header to return. + **Args:** - Returns: - str: data of most recent header of the given type or empty string. + `headerType (str)`: Type of header to return. + + **Returns:** + ``` + str: data of most recent header of the given type or empty string. + ``` """ for header in self.headers: if header["type"] == headerType: @@ -1166,15 +1254,21 @@ def __parseFromData(self, data: str) -> str: """Parse From header and return requested data. Returns empty string if requested data is unavailable. - Examples: From data is "From: Campbell, Justin " - __parseFromData(data="userName") returns "Campbell, Justin" - __parseFromData(data="userEmail") returns "campb303@purdue.edu" + **Examples:** + ``` + From data is "From: Campbell, Justin " + __parseFromData(data="userName") returns "Campbell, Justin" + __parseFromData(data="userEmail") returns "campb303@purdue.edu" + ``` - Args: - data (str): The data desired; can be "userName" or "userEmail". + **Args:** - Returns: - str: userName, userEmail or empty string. + `data (str)`: The data desired; can be "userName" or "userEmail". + + **Returns:** + ``` + str: userName, userEmail or empty string. + ``` """ fromHeader = self.__getMostRecentHeaderByType("From") userName, userEmail = email.utils.parseaddr(fromHeader) @@ -1191,14 +1285,22 @@ def __getUserAlias(self) -> str: """Returns user's Career Account alias if present. If Career Account alias isn't present, returns empty string. - Example: Email from campb303@purdue.edu - userAlias = "campb303" - - Example: Email from spam@spammer.net - userAlias = "" - - Returns: - str: User's Career Account alias if present or empty string + **Example:** + ``` + Email from campb303@purdue.edu + userAlias = "campb303" + ``` + + **Example:** + ``` + Email from spam@spammer.net + userAlias = "" + ``` + + **Returns:** + ``` + str: User's Career Account alias if present or empty string + ``` """ @@ -1220,8 +1322,10 @@ def __getFormattedDate(self, date: str) -> str: Returns empty string if the string argument passed to the function is not a datetime. See: https://en.wikipedia.org/wiki/ISO_8601 - Returns: - str: Properly formatted date/time recieved or empty string. + **Returns:** + ``` + str: Properly formatted date/time recieved or empty string. + ``` """ try: # This date is never meant to be used. The default attribute is just to set timezone. @@ -1237,8 +1341,10 @@ def __getFormattedDate(self, date: str) -> str: def toJson(self) -> dict: """Returns a JSON safe representation of the item. - Returns: - dict: JSON safe representation of the item. + **Returns:** + ``` + dict: JSON safe representation of the item. + ``` """ return self.jsonData @@ -1249,14 +1355,20 @@ def __repr__(self) -> str: class Queue: """A collection of items. - Example: - # Create a queue (ce) - >>> queue = Queue("ce") + **Example:** + + ``` + # Create a queue (ce) + >>> queue = Queue("ce") + ``` + + **Attributes:** - Attributes: - name: The name of the queue. - items: A list of Items in the queue. - jsonData: A JSON serializable representation of the Queue. + ``` + name: The name of the queue. + items: A list of Items in the queue. + jsonData: A JSON serializable representation of the Queue. + ``` """ def __init__(self, name: str) -> None: @@ -1272,8 +1384,10 @@ def __init__(self, name: str) -> None: def __getItems(self) -> list: """Returns a list of items for this Queue - Returns: - list: a list of items for this Queue + **Returns:** + ``` + list: a list of items for this Queue + ``` """ items = [] @@ -1293,8 +1407,10 @@ def toJson(self) -> dict: The JSON representation of every item in the Queue is added to the Queue's JSON data then the Queue's JSON data is returned. - Returns: - dict: JSON safe representation of the Queue + **Returns:** + ``` + dict: JSON safe representation of the Queue + ``` """ items = [] for item in self.items: @@ -1312,11 +1428,15 @@ def __repr__(self) -> str: def getValidQueues() -> list: """Returns a list of queues on the filesystem excluding ignored queues. - Example: - ["bidc", "me", "ce"] + **Example:** + ``` + ["bidc", "me", "ce"] + ``` - Returns: - list: Valid queues + **Returns:** + ``` + list: Valid queues + ``` """ queues = [] @@ -1333,20 +1453,23 @@ def getValidQueues() -> list: def getQueueCounts() -> list: """Returns a list of dictionaries with the number of items in each queue. - Example: - [ - { - name: "me", - number_of_items: 42 - }, - { - name: "bidc", - number_of_items: 3 - } - ] - - Returns: - list: Dictionaries with the number of items in each queue. + **Example:** + ``` + [ + { + name: "me", + number_of_items: 42 + }, + { + name: "bidc", + number_of_items: 3 + } + ] + ``` + **Returns:** + ``` + list: Dictionaries with the number of items in each queue. + ``` """ queueInfo = [] for queue in getValidQueues(): @@ -1363,8 +1486,10 @@ def getQueueCounts() -> list: def loadQueues() -> list: """Return a list of Queues for each queue. - Returns: - list: list of Queues for each queue. + **Returns:** + ``` + list: list of Queues for each queue. + ``` """ queues = [] diff --git a/webqueue2_api/api.py b/webqueue2_api/api.py index 7fcefa4..f32a90d 100644 --- a/webqueue2_api/api.py +++ b/webqueue2_api/api.py @@ -109,20 +109,24 @@ class Login(Resource): def post(self) -> tuple: """Validates username/password and returns both access and refresh tokens. - Return Codes: - 200 (OK): On success. - 401 (Unauthroized): When username or password are incorrect. - 422 (Unprocessable Entitiy): When the username or password can't be parsed. - - Example: - curl -X POST - -H "Content-Type: application/json" - -d '{"username": "bob", "password": "super_secret"}' - - { "access_token": fjr09hfp09h932jp9ruj3.3r8ihf8h0w8hr08ifhj804h8i.8h48ith08ity409hip0t4 } - - Returns: - tuple: Response containing tokens and HTTP response code. + **Return Codes:** + ``` + 200 (OK): On success. + 401 (Unauthroized): When username or password are incorrect. + 422 (Unprocessable Entitiy): When the username or password can't be parsed. + ``` + **Example:** + ``` + curl -X POST + -H "Content-Type: application/json" + -d '{"username": "bob", "password": "super_secret"}' + + { "access_token": fjr09hfp09h932jp9ruj3.3r8ihf8h0w8hr08ifhj804h8i.8h48ith08ity409hip0t4 } + ``` + **Returns:** + ``` + tuple: Response containing tokens and HTTP response code. + ``` """ if not request.is_json: return ({ "message": "JSON missing from request body"}, 422) @@ -162,34 +166,41 @@ class Item(Resource): def get(self, queue: str, number: int) -> tuple: """Returns the JSON representation of the item requested. - Return Codes: - 200 (OK): On success. - - Example: - /api/ce/100 returns: - { - "lastUpdated": "07-23-20 10:11 PM", - "headers": [...], - "content": [...], - "isLocked": "ce 100 is locked by knewell using qvi", - "userEmail": "campb303@purdue.edu", - "userName": "Justin Campbell", - "userAlias": "campb303", - "assignedTo": "campb303", - "subject": "Beepboop", - "status": "Dont Delete", - "priority": "", - "deparment": "", - "building": "", - "dateReceived": "Tue, 23 Jun 2020 13:25:51 -0400" - } - - Args: - queue (str): The queue of the item requested. - item (int): The number of the item requested. - - Returns: - tuple: Item as JSON and HTTP response code. + **Return Codes:** + ``` + 200 (OK): On success. + ``` + + **Example:** + ``` + /api/ce/100 returns: + { + "lastUpdated": "07-23-20 10:11 PM", + "headers": [...], + "content": [...], + "isLocked": "ce 100 is locked by knewell using qvi", + "userEmail": "campb303@purdue.edu", + "userName": "Justin Campbell", + "userAlias": "campb303", + "assignedTo": "campb303", + "subject": "Beepboop", + "status": "Dont Delete", + "priority": "", + "deparment": "", + "building": "", + "dateReceived": "Tue, 23 Jun 2020 13:25:51 -0400" + } + ``` + **Args:** + ``` + queue (str): The queue of the item requested. + item (int): The number of the item requested. + ``` + + **Returns:** + ``` + tuple: Item as JSON and HTTP response code. + ``` """ return (ECNQueue.Item(queue, number).toJson(), 200) @@ -198,14 +209,20 @@ class Queue(Resource): def get(self, queues: str) -> tuple: """Returns the JSON representation of the queue requested. - Return Codes: - 200 (OK): On success. + **Return Codes:** + ``` + 200 (OK): On success. + ``` - Args: - queues (str): Plus (+) deliminited list of queues. + **Args:** + ``` + queues (str): Plus (+) deliminited list of queues. + ``` - Returns: - tuple: Queues as JSON and HTTP response code. + **Returns:** + ``` + tuple: Queues as JSON and HTTP response code. + ``` """ queues_requested = queues.split("+") @@ -220,23 +237,28 @@ class QueueList(Resource): def get(self) -> tuple: """Returns a list of dictionaries with the number of items in each queue. - Return Codes: - 200 (OK): On success. - - Example: - [ - { - name: "me", - number_of_items: 42 - }, - { - name: "bidc", - number_of_items: 3 - } - ] - - Returns: - tuple: Queues and item counts as JSON and HTTP response code. + **Return Codes:** + ``` + 200 (OK): On success. + ``` + + **Example:** + ``` + [ + { + name: "me", + number_of_items: 42 + }, + { + name: "bidc", + number_of_items: 3 + } + ] + ``` + **Returns:** + ``` + tuple: Queues and item counts as JSON and HTTP response code. + ``` """ return (ECNQueue.getQueueCounts(), 200)