diff --git a/docs-src/webqueue2api Package/Configuration.md b/docs-src/webqueue2api Package/Configuration.md new file mode 100644 index 0000000..e379c3d --- /dev/null +++ b/docs-src/webqueue2api Package/Configuration.md @@ -0,0 +1,46 @@ +The configuration of webqueue2api can be managed in two different ways: + +- At launch with a configuration file in the same directory as the virtual environment +- At runtime by modifying the `webqueue2api.config` symbol directly + +## Configuration File +On import, a [ConfigParser INI formatted file](https://docs.python.org/3/library/configparser.html#supported-ini-file-structure) is read for configuartion options. This file must be located in the same directory as the virtual environment folder and must be named `webqueue2api_config.ini`. + +!!! example "A Full Config File" + ```ini + [parser] + # Absolute path to directory containing queue data. + # Default: /home/pier/e/queue/Mail + queue_directory = /etc/queue-cli/queues + + # List of queues to ignore. (Comma and space ", " delimited.) + # Default: archives, drafts, inbox, coral + queues_to_ignore = dogs, cats, particularly_pugs + + [api] + # Runtime configuration for secure production or convenient development settings. + # Valid options are: prod | dev + # Default: prod + environment = dev + + # Token used to encrypt JWT payloads. + # Default: webqueue2api.api.config.generate_random_string + jwt_secret_key = uV0liG9$YgcGE7J! + ``` + +## Changing Settings at Runtime +Each package contains package level configuration objects (see: [dataclasses on PyPI](https://pypi.org/project/dataclasses/)) in `config.py` files. All of the configurations are combined into the top level `webqueue2api.config` symbol. + +These configuration objects store default values for each package. Default values can be changed by editing these objects directly or by editing the object values before their use. + +!!! example "Changing the parser's queue directory by editing object values." + ```python + import webqueue2api + + # Load Queue from default directory + ce_queue = Queue("ce") + + # load Queue from modified directory + webqueue2api.config.parser.queue_directory = "/absolute/path" + other_queue = Queue("other") + ``` \ No newline at end of file diff --git a/docs-src/webqueue2api Package/Getting Started.md b/docs-src/webqueue2api Package/Getting Started.md index 69c6a0f..12db716 100644 --- a/docs-src/webqueue2api Package/Getting Started.md +++ b/docs-src/webqueue2api Package/Getting Started.md @@ -10,6 +10,31 @@ The webqueue2api Package has the following structure: ## Basic Usage +!!! example "Load all queues." + ```python + import webqueue2api + all_queues = webqueue2api.load_queues() + for queue in all_queues: + print(f"{queue.name} has {len(queue.items)} items." + ``` + ```python + # Expected Output + "tech has 72 items" + "ce has 38 items" + ... + ``` + +!!! example "Load some queues." + ```python + import webqueue2api + all_queues = webqueue2api.load_queues("che", "tech", "ce") + print( len( all_queues ) ) + ``` + ```python + # Expected Output + 3 + ``` + !!! example "Load a queue and get the number of items in it." ```python import webqueue2api diff --git a/docs-src/webqueue2api Package/Package Structure.md b/docs-src/webqueue2api Package/Package Structure.md index cd45585..6b4c370 100644 --- a/docs-src/webqueue2api Package/Package Structure.md +++ b/docs-src/webqueue2api Package/Package Structure.md @@ -5,21 +5,4 @@ The webqueue2api Package consists of four packages in total: - `webqueue2api`: The root packages. This contains both the `api` and the `parser` packages as well as global configuration. - `api`: Contains a [Flask](https://flask.palletsprojects.com/) app that can be used with any WSGI server to host the webqueue2 API and utilities such as authentication code. - `resources`: Contains [Flask-RESTful](https://flask-restful.readthedocs.io/en/latest/) resources for the webqueue2 API. - - `parser`: Contains parers for a Queue and an Item as well as utilities and custom errors. - -## Configuration -Each package contains package level configuration objects (see: [dataclasses on PyPI](https://pypi.org/project/dataclasses/)) in `config.py` files. All of the configurations are combined into the top level `webqueue2api.config` symbol. - -These configuration objects store default values for each package. Default values can be changed by editing these objects directly or by editing the object values before their use. - -!!! example "Changing the parser's queue directory by editing object values." - ```python - import webqueue2api - - # Load Queue from default directory - ce_queue = Queue("ce") - - # load Queue from modified directory - webqueue2api.config.parser.queue_directory = "/absolute/path" - other_queue = Queue("other") - ``` \ No newline at end of file + - `parser`: Contains parers for a Queue and an Item as well as utilities and custom errors. \ No newline at end of file diff --git a/docs-src/webqueue2api Package/Parser/Section Parsing Definitions.md b/docs-src/webqueue2api Package/Parser/Section Parsing Definitions.md new file mode 100644 index 0000000..53324c4 --- /dev/null +++ b/docs-src/webqueue2api Package/Parser/Section Parsing Definitions.md @@ -0,0 +1,387 @@ +Below are the derived definitions for each section of an item as it appears in the item's plaintext file and as it is output from the parser. + +## Directory Information +Information about the user such as alias, phone number and office location. This only appears once right after the headers and right before the initial message. This only occurs if the item is submitted through the [Trouble Reporting](https://engineering.purdue.edu/ECN/AboutUs/ContactUs) page. + +### Fields +| Key | Value | +| - | - | +|`type`|`directory_information`| +| `Name` | The real name of the sender. | +| `Login` | The career account alias of the sender. | +| `Computer` | The computer the item is related to. Formatting may vary. | +| `Location` | Where the computer is located. | +| `Email` | The email address of the sender. | +| `Phone` | The phone number of the sender. | +| `Office` | The office location of the sender. | +| `UNIX Dir` | The home directory for the user on non-Windows systems | +| `Zero Dir` | The home directory for the user via Active Directory | +| `User ECNDB` | Link to the sender's username report in ECNDB | +| `Host ECNDB` | Link to the computer report in ECNDB | +| `Subject` | The subject of the email sent to the queue | + +### Delimiters +- **Start**: The second line after the first newline followed by a tab `\n\t`. +- **End**: The first non-empty line after the start that begins with whitespace then "Subject:" + +### Plain Text Example +``` +\tName: Jerry L Guerrero\n + Login: jerry\n" + Computer: x-ee27å0bpc1 (128.46.164.29)\n + Location: EE 270B\n + Email: jerry@purdue.edu\n + Phone: \n + Office: \n + UNIX Dir: /home/pier/c/jerry\n + Zero Dir: U=\\\\pier.ecn.purdue.edu\\jerry\n + User ECNDB: http://eng.purdue.edu/jump/bcafa8\n + Host ECNDB: http://eng.purdue.edu/jump/2dbd461 \n + Subject: Win7 to Win10 Migration List - kevin\n +``` + +### Parsed Example +```json +{ + "type": "directory_information", + "Name": "Jerry L Guerrero", + "Login": "jerry", + "Computer": "x-ee27å0bpc1 (128.46.164.29)", + "Location": "EE 270B", + "Email": "jerry@purdue.edu", + "Phone": "", + "Office": "", + "UNIX Dir": "/home/pier/c/jerry", + "Zero Dir": "U=\\\\pier.ecn.purdue.edu\\jerry", + "User ECNDB": "http://eng.purdue.edu/jump/bcafa8", + "Host ECNDB": "http://eng.purdue.edu/jump/2dbd461", + "Subject": "Win7 to Win10 Migration List - kevin" +} +``` + +## Initial Message +The body of the email the item originated from. This usually appears directly after the headers unless directory information is present. + +### Fields +| Key | Value | +| - | - | +| `type` | `initial_message` | +| `datetime` | RFC 8061 formatted datetime string. Pulled from the `Date` header of the item. | +| `from_name` | The sender's real name. Formatting may vary. Pulled from the `From` header of the item. This can be empty. | +| `from_email` | The sender's email address. Pulled from the `From` header of the item.| +| `to` | A list of names(s) and email(s) of people this message was sent to. Pulled from the `To` header of the item. | +| `cc` | A list of name(s) and email(s) of people who were CC'd. Pulled from the `Cc` header of the item. This can be empty. | +| `subject` | The subject of the initial message. Pulled from the `Subject` header of the item. | +| `content` | The content of the message as an list of strings. | + +### Delimiters +- **Start**: First newline after directory information if present, otherwise first newline. +- **End**: Beginning of another delimiter if present, otherwise end of file. + +### Plain Text Example +``` +I need some help with something.\n +My printer stopped working.\n +``` + +### Parsed Example +```json +{ + "type": "initial_message", + "datetime": "2020-09-11T01:26:45+00:00", + "from_name": "Justin Campbell", + "from_email": "campb303@purdue.edu", + "to": [ + { "name": "John Doe", "email": "johndoe@example.com" }, + ], + "cc": [ + { "name": "", "email": "janesmith@example.com" } + ], + "subject": Maps to item.subject, + "content": [ + "I need some help with something.\n", + "My printer stopped working.\n" + ] +} +``` + +## Edit +Information added by someone at ECN, usually for internal use and/or communication. This can occur anywhere in the item after the initial message. + +### Fields +| Key | Value | +| - | - | +| `type` | `edit` | +| `datetime` | RFC 8061 formatted datetime string. | +| `by` | The career account alias of the person who added the edit. | +| `content` | The content of the edit as a list of strings. | + +### Delimiters +- **Start**: Line starting with `*** Edited` +- **End**: Beginning of another delimiter if present, otherwise end of file. + +### Plain Text Example +``` +*** Edited by: knewell at: 04/22/20 16:39:51 *** +This is related to another item. I need to do X next. +``` + +### Parsed Example +```json +{ + "type": "edit", + "datetime": "2020-04-22T16:39:51", + "by": "knewell", + "content": [ + "This is related to another item. I need to do X next.\n" + ] +} +``` + +## Status +A short message about the progress of the item. This can occur anywhere in the item after the initial message. + +### Fields +| Key | Value | +| - | - | +| `type` | `status` | +| `datetime` | RFC 8061 formatted datetime string. | +| `by` | The career account alias of the person who updated the status. | +| `content` | The content of the status as a list of strings. | + + +### Delimiters +- **Start**: Line starting with `*** Status` +- **End**: Beginning of another delimiter if present, otherwise end of file. + +### Plain Text Example +``` +*** Status updated by: knewell at: 4/23/2020 10:35:47 *** +Doing X thing. +``` + +### Parsed Example +```json +{ + "type": "status", + "datetime": "2020-04-23T10:35:47", + "by": "knewell", + "content": [ + "Doing X thing." + ] +} +``` + +## Assignment +Assigning the item to someone. This does not occur in the body of the item. It it tracked in the headers using three different entries: + + +- `Assigned-To-Updated-By`: the career account alias of the person who updated the assignment +- `Assigned-To-Updated-Time`: the time the assignment was updated +- `Assigned-To`: the career account alias of the person the item was assigned to + +### Fields +| Key | Value | +| - | - | +| `type` | `assignment` | +| `datetime` | RFC 8061 formatted datetime string. | +| `by` | The career account alias of the person who changed the |assignment. | +| `to` | The career account alias of the person who the item was assigned to. | + +### Delimiters +N/A + +### Plain Text Example +``` +Assigned-To: campb303 +Assigned-To-Updated-Time: Tue, 23 Jun 2020 13:27:00 EDT +Assigned-To-Updated-By: harley +``` + +### Parsed Example +```json +{ + "type": "assignment", + "datetime": "2020-06-23T13:27:00", + "by": "harley", + "to": "campb303", +} +``` + +## Reply To User +A message from ECN to the user and/or related parties. This can occur anywhere in the item after the initial message. + +### Fields +| Key | Value | +| - | - | +| `type` | `reply_to_user` | +| `datetime` | RFC 8061 formatted datetime string. | +| `by` | The sender's real name. Formatting may vary. This can be empty. | +| `content` | The content of the message as an list of strings | + + +### Delimiters +- **Start**: Line starting with `*** Replied` +- **End**: Beginning of another delimiter if present, otherwise end of file. + +### Plain Text Example +``` +*** Replied by: ewhile at: 05/08/20 09:21:43 *** +Sascha, + +Chicken kevin biltong, flank jowl prosciutto shoulder meatball meatloaf sirloin. + +Ethan White +ECN +``` + +### Parsed Example +```json +{ + "type": "reply_to_user", + "datetime": "2020-05-08T09:21:43", + "by": "ewhile", + "content": [ + "Sascha,\n", + "\n", + "Chicken kevin biltong, flank jowl prosciutto shoulder meatball meatloaf sirloin.\n", + "\n", + "Ethan White\n", + "ECN" + ] +} +``` + +## Reply from User +A message from the user and/or related parties. This is only found after two or more items have been merged together. This can occur anywhere in the item after the initial message. + +### Fields +| Key | Value | +| - | - | +| `type` | `reply_from_user` | +| `datetime` | RFC 8061 formatted datetime string. | +| `from_name` | The sender's real name. Formatting may vary. This can be empty. | +| `from_email` | The sender's email address. | +| `cc` | A list of name(s) and email(s) of people who were CC'd. This can be empty. | +| `headers` | A dictionary of headers from the reply. | +| `subject` | The subject of the reply. | +| `content` | The content of the message as an list of strings | + +### Delimiters: +- **Start**: Line starting with `=== ` +- **End**: Line starting with `====` + +### Plain Text Example +``` +=== Additional information supplied by user === + +Subject: RE: New Computer Deploy +From: "Reckowsky, Michael J." +Date: Fri, 8 May 2020 13:57:17 +0000 + +Ethan, + +Biltong beef ribs doner chuck, pork chop jowl salami cow filet mignon pork. + +Mike +=============================================== +``` + +### Parsed Example +```json +{ + "type": "reply_from_user", + "datetime": "2020-05-08T13:57:18+00:00", + "from_name": "Reckowsky, Michael J.", + "from_email": "mreckowsky@purdue.edu", + "cc": [ + { "name": "John Doe", "email": "johndoe@example.com" }, + { "name": "", "email": "janesmith@example.com" } + ], + "headers" : [ + { + "type": "Subject", + "content": "RE: New Computer Deploy" + }, + { + "type": "From", + "content": "\"Reckowsky, Michael J.\" " + }, + { + "type": "Date", + "content": "Fri, 8 May 2020 13:57:17 +0000" + }, + ], + "subject": "RE: New Computer Deploy", + "content": [ + "Ethan,\n", + "\n", + "Biltong beef ribs doner chuck, pork chop jowl salami cow filet mignon pork.\n", + "\n", + "Mike\n", + ] +} +``` + +## Parse Error +!!! note + This is not found in the item but generated when the item is parsed. +An error caused by unexpected formatting. + +### Fields +| Key | Value | +| - | - | +|`type`|`parse_error`| +| `datetime` | RFC 8061 formatted datetime string. | +| `file_path` | Full path of the item with the error. | +| `expected` | Description of what the parser was expecting. | +| `got` | Line that cause the parse error. | +| `line_num` | The line number in the item that caused the parse error. | + +### Plain Text Example +``` +(item aae2 in qsnapshot) +=== Additional information supplied by user === + +Subject: RE: Help with hardware upgrades +From: "Ezra, Kristopher L" +Date: Wed, 5 Feb 2020 18:11:58 +0000 + +If it makes no difference between windows and linux for the fileserver I'd +rather service a linux machine. + +Considering the switches, i could do 2 8s and 2 16s. Two of the switches +I'm replacing already service 9 connections and I'd rather not daisy chain. +Is there something driving the price here? I see gigabit switches from +tplink on amazon right now for $50. I dont need managed switches or +anything fancy. + +Kris +*** Replied by: emuffley at: 02/05/20 13:22:02 *** + +Kris, + +Thank you on the server operating question. We will kick that off to our linux folks for discussion. + +No daisy chain, agreed. These switches are unmanaged. + +For the workstations, are you wanting Windows, Linux or a mix? + + +Eric Muffley + +Systems Engineer, Engineering Computer Network + +=============================================== +``` +### Parsed Example +```json +{ + "type": "parse_error", + "datetime": "2020-10-16T10:44:45", + "file_path": "/home/pier/e/benne238/webqueue2/q-snapshot/aae/2", + "expected": "Did not encounter a reply_from_user ending delimiter", + "got": "Kris", + "line_num": 468 +} +``` diff --git a/docs-src/webqueue2api Package/Parser/awesome-pages.yaml b/docs-src/webqueue2api Package/Parser/awesome-pages.yaml new file mode 100644 index 0000000..e502d65 --- /dev/null +++ b/docs-src/webqueue2api Package/Parser/awesome-pages.yaml @@ -0,0 +1,4 @@ +# YAML Configuration for Awesome Pages mkdocs Plugin +# See: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin +nav: + - ... \ No newline at end of file diff --git a/docs-src/webqueue2api Package/awesome-pages.yaml b/docs-src/webqueue2api Package/awesome-pages.yaml index 7b85715..9c82ab4 100644 --- a/docs-src/webqueue2api Package/awesome-pages.yaml +++ b/docs-src/webqueue2api Package/awesome-pages.yaml @@ -2,4 +2,6 @@ # See: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin nav: - Getting Started.md - - Package Structure.md \ No newline at end of file + - Configuration.md + - Package Structure.md + - ... \ No newline at end of file diff --git a/docs/404.html b/docs/404.html index b6760fd..8b9621e 100644 --- a/docs/404.html +++ b/docs/404.html @@ -10,7 +10,7 @@ - + @@ -18,10 +18,10 @@ - + - + @@ -109,14 +109,18 @@