# gemmail-python: A Gemmail (and Gembox) Parser for Misfin Clients and Servers
A parser written in python for gemtext, gemmails, and gemboxes, to be used with the Misfin(B) and Misfin(C) formats.
A Note On PEP-8: PEP-8 is a style guide for the Python standard library ONLY, as detailed in the official PEP-8 document:
> This document gives coding conventions for the Python code comprising the standard library in the main Python distribution.
Requiring that all programmers use the exact same style guide as the Python standard library is stupid and makes absolutely no sense. Other people's libraries should follow a consistent style within their own code, but they should not be forced to use a style of irrelevant code that's not part of their own library.
Erroring out on blank lines, not having two whitespaces before each function and class definition, and other such things DOES NOT CATCH ERRORS AND DOES NOT MAKE YOUR CODE BETTER. It is purely so Python developers can spend their time writing "clean code" instead of good code that does stuff. Nobody cares that you were able to put two blank lines before each function definition, what people care about is that your library actually implements stuff and works. Blank lines are not code, they do nothing. They do not help nor hinder your code.
Also, having two blank lines before a function definition instead of one blank line doesn't make your code more readable. That is BS, and I think every sane person knows that it is BS.
## GemMail
Parses the raw metadata and message data transmitted over the wire in the Misfin(B) and Misfin(C) protocols.
### Create GemMail
* GemMail() - creates an empty GemMail
* createGemMailFromBody(body) - creates GemMail from message body alone (metadata is not passed in)
* parseGemMail_B(gemmail_b_text) - parses the text in Misfin(B) format. Text should include the metadata.
* parseGemMail_C(gemmail_c_text) - parses the text in Misfin(C) format. Text should include the 3 lines of metadata at the beginning of the text.
### GemMail Values
* gm.ID - Identifier (if used with gembox, the Message ID)
* gm.Subject - the Subject of the message. Also included in gm.GemText.
* gm.Senders - GemMailSender array
* gm.Receivers - dictionary of addresses as keys, empty tuples as values.
* gm.Timestamps - datetime array
* gm.Tags - tags dictionary, may be used with GMAP and gembox.
* gm.GemText - GemText instance containing the lines of the message body, including the Subject line. Use `gm.GemText.string()` to convert just the message body to a string.
### GemMail Methods
* deepcopy() - deep copy GemMail to a new value
* containsSender(address) - checks if address is in senders list. Returns a boolean.
* setGemTextBody(gemtext_string) - parses the gemtext string and sets the GemMail's message body to it.
* prependSender(address, blurb) - prepends a sender to the senders list. Use this on the misfin server when a mail is received.
* appendSender(address, blurb) - appends a sender to the senders list.
* removeSender(address) - unimplemented.
* prependTimestamp(datetime) - prepends datetime value to timestamps list. Use this on the misfin server when a mail is received.
* appendTimestamp(datetime) - appends datetime value to timestamps list.
* containsReceiver(address) - checks if address is in recipients list. Returns a boolean.
* addReceiver(address) - adds a receiver to the recipients list.
* hasTag(tagName) - returns bool whether message has a tag and the tag's value is set to True.
* addTag(tagName) - adds a tag to the message, setting its value to true and its last_modification_date to datetime.utcnow()
* setTag(tagName, last_modification_date, value) - sets a tag's data manually
* removeTag(tagName) - untags a message by setting its value to False and its last_modification_date to datetime.utcnow()
* string_C() - returns a string of the gemmail in Misfin(C) format, ready to be transmitted over the wire using the Misfin(C) protocol.
* string_B() - returns a string of the gemmail in Misfin(B) format, ready to be transmitted over the wire using the Misfin(B) protocol.
### Example Usage
```python
from gemmail_python import *
text_misfinC = """clseibold@auragem.letz.dev Christian Lee Seibold
2023-10-04T08:26:32Z
# Message Subject Line
Message body.
"""
gemmail = gemmail_python.parseGemmail_C(text_misfinC)
gemmail.prependSender(sender_address, sender_blurb)
newGemmailString = gemmail.string_B() # Converts to Misfin(B) format for transmission via Misfin(B) protocol
```
## GemBox
Parses a gembox file in the new format (or in the deprecated formats). See [NewGemBoxFormat.md](NewGemBoxFormat.md) for the format specification.
### Create a GemBox
* GemBox(identifier) - create empty GemBox. Identifier is for programmer's use to identify gemboxes.
* parseGemBox() - parses gembox file in new format.
Deprecated:
* parseGemBox_B_old(identifier, textString) - parses gembox file in deprecated format for Misfin(B)
* parseGemBox_C_old(identifier, textString) - parses gembox file in deprecated format for Misfin(C)
### GemBox Values
* Identifier - an identifier to be used by the programmer
* MailboxAddress - from Mailbox metadata field
* MailboxBlurb - from Mailbox metadata field
* Fingerprint - from Fingerprint metadata field
* Description - from Description metadata field
* CreatedTags - dictionary of CreatedTags metadata field
* Mails - GemMail array
### GemBox Methods
* deepcopy() - deep copy GemBox to a new value
* getGemMailWithID(id) - returns the GemMail that has the provided ID, along with its index in the Mails array
* getGemMailsWithTag(tagName) - returns list of GemMails that have the provided tag
* appendGemMail(gemmail) - appends a GemMail instance to the Mails array
* removeGemMail(index) - removes a GemMail instance at the specified index from the Mails array.
* removeGemMailAtID(id) - removes a GemMail that has the provided ID.
* string() - returns a string of the GemBox to be written to a file, in new format.
Deprecated:
* string_B() - returns a string of the GemBox to be written to a file, in deprecated format for Misfin(B).
* string_C() - returns a string of the GemBox to be written to a file, in deprecated format for Misfin(C).
## Example Usage
```python
from gemmail_python import *
gembox_text = ""
gembox = gemmail_python.parseGemBox("", gembox_text)
# Add all Inbox mails to Archive folder
mails = gembox.getGemMailsWithTag("Inbox") # Get array of all mails with "Inbox" tag
for mail in mails:
mail.addTag("Archive") # Automatically removes "Inbox" tag, since Archive and Inbox are mutually exclusive folder tags
print(gembox.string())
print(gembox.Mails[0].string_C()) # print first mail in misfin(C) wire format.
```
## GemText
Parses a Gemtext file (.gmi file) to be used with Gemini or the message body of a Gemmail.
### Create a GemText
* GemText() - empty gemtext
* parseGemText(text) - parses a gemtext file into a GemText instance
### GemText Values
* firstLevel1Heading - string of first level-1 heading of file, or None if doesn't appear in text. This may also be included in the lines array.
* lines - GemTextLine array
### GemText Methods
* deepcopy() - deep copy GemText to a new value
* string() - convert GemText instance back to a string.
## GemTextLine
A line within a Gemtext file.
### Create a GemTextLine
* GemTextLine(GemTextLineType, text, url)
### GemTextLine Values
* type - GemTextLineType
* text - string of text, excluding the linetype prefix
* url - string of url for Link line types
### GemTextLine Methods
* string() - Converts line to a string, including the linetype prefix.
### GemTextLineType Enum Values
* Text - regular text
* PreformattingToggle - preformat toggle line (\`\`\`)
* PreformattedText - text in between preformat toggle lines
* Link
* ListItem
* Heading1
* Heading2
* Heading3
* Quote - aka. Blockquote
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/clseibold/gemmail-python",
"name": "gemmail-python",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "misfin,gemini,gembox,gemtext,gemmail,mail,email",
"author": "Christian Lee Seibold",
"author_email": "christian.seibold32@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/18/42/16e0ce34334541f1d6e810bc8ae0f4f54393b13d5010b5a4200c09cafa1c/gemmail-python-1.0.32.tar.gz",
"platform": null,
"description": "# gemmail-python: A Gemmail (and Gembox) Parser for Misfin Clients and Servers\n\nA parser written in python for gemtext, gemmails, and gemboxes, to be used with the Misfin(B) and Misfin(C) formats.\n\nA Note On PEP-8: PEP-8 is a style guide for the Python standard library ONLY, as detailed in the official PEP-8 document:\n> This document gives coding conventions for the Python code comprising the standard library in the main Python distribution.\n\nRequiring that all programmers use the exact same style guide as the Python standard library is stupid and makes absolutely no sense. Other people's libraries should follow a consistent style within their own code, but they should not be forced to use a style of irrelevant code that's not part of their own library.\n\nErroring out on blank lines, not having two whitespaces before each function and class definition, and other such things DOES NOT CATCH ERRORS AND DOES NOT MAKE YOUR CODE BETTER. It is purely so Python developers can spend their time writing \"clean code\" instead of good code that does stuff. Nobody cares that you were able to put two blank lines before each function definition, what people care about is that your library actually implements stuff and works. Blank lines are not code, they do nothing. They do not help nor hinder your code.\n\nAlso, having two blank lines before a function definition instead of one blank line doesn't make your code more readable. That is BS, and I think every sane person knows that it is BS.\n\n## GemMail\n\nParses the raw metadata and message data transmitted over the wire in the Misfin(B) and Misfin(C) protocols.\n\n### Create GemMail\n* GemMail() - creates an empty GemMail\n* createGemMailFromBody(body) - creates GemMail from message body alone (metadata is not passed in)\n* parseGemMail_B(gemmail_b_text) - parses the text in Misfin(B) format. Text should include the metadata.\n* parseGemMail_C(gemmail_c_text) - parses the text in Misfin(C) format. Text should include the 3 lines of metadata at the beginning of the text.\n\n### GemMail Values\n* gm.ID - Identifier (if used with gembox, the Message ID)\n* gm.Subject - the Subject of the message. Also included in gm.GemText.\n* gm.Senders - GemMailSender array\n* gm.Receivers - dictionary of addresses as keys, empty tuples as values.\n* gm.Timestamps - datetime array\n* gm.Tags - tags dictionary, may be used with GMAP and gembox.\n* gm.GemText - GemText instance containing the lines of the message body, including the Subject line. Use `gm.GemText.string()` to convert just the message body to a string.\n\n### GemMail Methods\n* deepcopy() - deep copy GemMail to a new value\n* containsSender(address) - checks if address is in senders list. Returns a boolean.\n* setGemTextBody(gemtext_string) - parses the gemtext string and sets the GemMail's message body to it.\n* prependSender(address, blurb) - prepends a sender to the senders list. Use this on the misfin server when a mail is received.\n* appendSender(address, blurb) - appends a sender to the senders list.\n* removeSender(address) - unimplemented.\n* prependTimestamp(datetime) - prepends datetime value to timestamps list. Use this on the misfin server when a mail is received.\n* appendTimestamp(datetime) - appends datetime value to timestamps list.\n* containsReceiver(address) - checks if address is in recipients list. Returns a boolean.\n* addReceiver(address) - adds a receiver to the recipients list.\n* hasTag(tagName) - returns bool whether message has a tag and the tag's value is set to True.\n* addTag(tagName) - adds a tag to the message, setting its value to true and its last_modification_date to datetime.utcnow()\n* setTag(tagName, last_modification_date, value) - sets a tag's data manually\n* removeTag(tagName) - untags a message by setting its value to False and its last_modification_date to datetime.utcnow()\n\n* string_C() - returns a string of the gemmail in Misfin(C) format, ready to be transmitted over the wire using the Misfin(C) protocol.\n* string_B() - returns a string of the gemmail in Misfin(B) format, ready to be transmitted over the wire using the Misfin(B) protocol.\n\n### Example Usage\n```python\nfrom gemmail_python import *\n\ntext_misfinC = \"\"\"clseibold@auragem.letz.dev Christian Lee Seibold\n\n2023-10-04T08:26:32Z\n# Message Subject Line\n\nMessage body.\n\"\"\"\ngemmail = gemmail_python.parseGemmail_C(text_misfinC)\ngemmail.prependSender(sender_address, sender_blurb)\nnewGemmailString = gemmail.string_B() # Converts to Misfin(B) format for transmission via Misfin(B) protocol\n```\n\n## GemBox\n\nParses a gembox file in the new format (or in the deprecated formats). See [NewGemBoxFormat.md](NewGemBoxFormat.md) for the format specification.\n\n### Create a GemBox\n* GemBox(identifier) - create empty GemBox. Identifier is for programmer's use to identify gemboxes.\n* parseGemBox() - parses gembox file in new format.\n\nDeprecated:\n* parseGemBox_B_old(identifier, textString) - parses gembox file in deprecated format for Misfin(B)\n* parseGemBox_C_old(identifier, textString) - parses gembox file in deprecated format for Misfin(C)\n\n### GemBox Values\n* Identifier - an identifier to be used by the programmer\n* MailboxAddress - from Mailbox metadata field\n* MailboxBlurb - from Mailbox metadata field\n* Fingerprint - from Fingerprint metadata field\n* Description - from Description metadata field\n* CreatedTags - dictionary of CreatedTags metadata field\n* Mails - GemMail array\n\n### GemBox Methods\n* deepcopy() - deep copy GemBox to a new value\n* getGemMailWithID(id) - returns the GemMail that has the provided ID, along with its index in the Mails array\n* getGemMailsWithTag(tagName) - returns list of GemMails that have the provided tag\n* appendGemMail(gemmail) - appends a GemMail instance to the Mails array\n* removeGemMail(index) - removes a GemMail instance at the specified index from the Mails array.\n* removeGemMailAtID(id) - removes a GemMail that has the provided ID.\n* string() - returns a string of the GemBox to be written to a file, in new format.\n\nDeprecated:\n* string_B() - returns a string of the GemBox to be written to a file, in deprecated format for Misfin(B).\n* string_C() - returns a string of the GemBox to be written to a file, in deprecated format for Misfin(C).\n\n## Example Usage\n\n```python\nfrom gemmail_python import *\n\ngembox_text = \"\"\ngembox = gemmail_python.parseGemBox(\"\", gembox_text)\n\n# Add all Inbox mails to Archive folder\nmails = gembox.getGemMailsWithTag(\"Inbox\") # Get array of all mails with \"Inbox\" tag\nfor mail in mails:\n mail.addTag(\"Archive\") # Automatically removes \"Inbox\" tag, since Archive and Inbox are mutually exclusive folder tags\n\nprint(gembox.string())\nprint(gembox.Mails[0].string_C()) # print first mail in misfin(C) wire format.\n```\n\n## GemText\n\nParses a Gemtext file (.gmi file) to be used with Gemini or the message body of a Gemmail.\n\n### Create a GemText\n* GemText() - empty gemtext\n* parseGemText(text) - parses a gemtext file into a GemText instance\n\n### GemText Values\n* firstLevel1Heading - string of first level-1 heading of file, or None if doesn't appear in text. This may also be included in the lines array.\n* lines - GemTextLine array\n\n### GemText Methods\n* deepcopy() - deep copy GemText to a new value\n* string() - convert GemText instance back to a string.\n\n## GemTextLine\n\nA line within a Gemtext file.\n\n### Create a GemTextLine\n* GemTextLine(GemTextLineType, text, url)\n\n### GemTextLine Values\n* type - GemTextLineType\n* text - string of text, excluding the linetype prefix\n* url - string of url for Link line types\n\n### GemTextLine Methods\n* string() - Converts line to a string, including the linetype prefix.\n\n### GemTextLineType Enum Values\n* Text - regular text\n* PreformattingToggle - preformat toggle line (\\`\\`\\`)\n* PreformattedText - text in between preformat toggle lines\n* Link\n* ListItem\n* Heading1\n* Heading2\n* Heading3\n* Quote - aka. Blockquote\n\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A Gemmail (and Gembox) parser for misfin clients and servers",
"version": "1.0.32",
"project_urls": {
"GitHub Project": "https://gitlab.com/clseibold/gemmail-python",
"Homepage": "https://gitlab.com/clseibold/gemmail-python",
"Issue Tracker": "https://gitlab.com/clseibold/gemmail-python/-/issues"
},
"split_keywords": [
"misfin",
"gemini",
"gembox",
"gemtext",
"gemmail",
"mail",
"email"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "17a81f84a744c8a3af7ced18ca84d103fdbcfba2315dd74064e6bc74453ada89",
"md5": "4b25b0f65e203b5819b77a18e451e1c4",
"sha256": "d3d0dbfeb9ca38669ad8caa1a7129e070db0d05352a6d08c42ee637eb2902709"
},
"downloads": -1,
"filename": "gemmail_python-1.0.32-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4b25b0f65e203b5819b77a18e451e1c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10733,
"upload_time": "2024-02-11T21:51:25",
"upload_time_iso_8601": "2024-02-11T21:51:25.725643Z",
"url": "https://files.pythonhosted.org/packages/17/a8/1f84a744c8a3af7ced18ca84d103fdbcfba2315dd74064e6bc74453ada89/gemmail_python-1.0.32-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "184216e0ce34334541f1d6e810bc8ae0f4f54393b13d5010b5a4200c09cafa1c",
"md5": "6436cc0813cf3ba5326d9dd831696d9d",
"sha256": "66c729ec5d22b831b40d601ed7d054b06b6a86b34d296a0abb1588193ab8ea00"
},
"downloads": -1,
"filename": "gemmail-python-1.0.32.tar.gz",
"has_sig": false,
"md5_digest": "6436cc0813cf3ba5326d9dd831696d9d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11811,
"upload_time": "2024-02-11T21:51:27",
"upload_time_iso_8601": "2024-02-11T21:51:27.584409Z",
"url": "https://files.pythonhosted.org/packages/18/42/16e0ce34334541f1d6e810bc8ae0f4f54393b13d5010b5a4200c09cafa1c/gemmail-python-1.0.32.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-11 21:51:27",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "clseibold",
"gitlab_project": "gemmail-python",
"lcname": "gemmail-python"
}
JSON