Skip to content

Commit

Permalink
Merge branch 'release/3.4.0'
Browse files Browse the repository at this point in the history
  • Loading branch information
@fedelemantuano
fedelemantuano committed Jul 6, 2018
2 parents 2ef0ca6 + 537027b commit 35c4715
Show file tree
Hide file tree
Showing 10 changed files with 388 additions and 238 deletions.
29 changes: 20 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,14 @@ There are other properties to get:
- sender IP address
- to domains

To get custom headers you should replace "-" with "\_".
Example for header `X-MSMail-Priority`:

```
$ mail.X_MSMail_Priority
```


mail-parser can detect defect in mail:
- [defects](https://docs.python.org/2/library/email.message.html#email.message.Message.defects): mail with some not compliance RFC part

Expand Down Expand Up @@ -114,10 +122,11 @@ Import `mailparser` module:
```
import mailparser
mail = mailparser.parse_from_bytes(byte_mail)
mail = mailparser.parse_from_file(f)
mail = mailparser.parse_from_file_msg(outlook_mail)
mail = mailparser.parse_from_file_obj(fp)
mail = mailparser.parse_from_string(raw_mail)
mail = mailparser.parse_from_bytes(byte_mail)
```

Then you can get all parts
Expand Down Expand Up @@ -150,9 +159,10 @@ If you installed mailparser with `pip` or `setup.py` you can use it with command
These are all swithes:

```
usage: mailparser.py [-h] (-f FILE | -s STRING | -k) [-j] [-b] [-a] [-r] [-t] [-dt] [-m]
[-u] [-c] [-d] [-n] [-i Trust mail server string] [-p] [-z]
[-v]
usage: mailparser [-h] (-f FILE | -s STRING | -k)
[-l {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}] [-j] [-b]
[-a] [-r] [-t] [-dt] [-m] [-u] [-c] [-d] [-o]
[-i Trust mail server string] [-p] [-z] [-v]
Wrapper for email Python Standard Library
Expand All @@ -162,6 +172,8 @@ optional arguments:
-s STRING, --string STRING
Raw email string (default: None)
-k, --stdin Enable parsing from stdin (default: False)
-l {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}, --log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
Set log level (default: WARNING)
-j, --json Show the JSON of parsed mail (default: False)
-b, --body Print the body of mail (default: False)
-a, --attachments Print the attachments of mail (default: False)
Expand All @@ -172,7 +184,6 @@ optional arguments:
-u, --subject Print the subject of mail (default: False)
-c, --receiveds Print all receiveds of mail (default: False)
-d, --defects Print the defects of mail (default: False)
-n, --anomalies Print the anomalies of mail (default: False)
-o, --outlook Analyze Outlook msg (default: False)
-i Trust mail server string, --senderip Trust mail server string
Extract a reliable sender IP address heuristically
Expand Down Expand Up @@ -205,10 +216,10 @@ Exceptions hierarchy of mail-parser:
```
MailParserError: Base MailParser Exception
|
├── MailParserOutlookError: Raised with Outlook integration errors
\── MailParserOutlookError: Raised with Outlook integration errors
|
├── MailParserEnvironmentError: Raised when the environment is not correct
\── MailParserEnvironmentError: Raised when the environment is not correct
|
├── MailParserOSError: Raised when there is an OS error
\── MailParserOSError: Raised when there is an OS error
```
```
192 changes: 97 additions & 95 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
|PyPI version| |Build Status| |Coverage Status| |BCH compliance|
|image4|
`PyPI version <https://badge.fury.io/py/mail-parser>`__ `Build
Status <https://travis-ci.org/SpamScope/mail-parser>`__ `Coverage
Status <https://coveralls.io/github/SpamScope/mail-parser?branch=develop>`__
`BCH compliance <https://bettercodehub.com/>`__
` <https://microbadger.com/images/fmantuano/spamscope-mail-parser>`__

.. figure:: https://raw.githubusercontent.com/SpamScope/spamscope/develop/docs/logo/spamscope.png
:alt: SpamScope
Expand All @@ -15,7 +18,7 @@ Overview
mail-parser is not only a wrapper for
`email <https://docs.python.org/2/library/email.message.html>`__ Python
Standard Library. It give you an easy way to pass from raw mail to
Python object that you can use in your code. It's the key module of
Python object that you can use in your code. It’s the key module of
`SpamScope <https://github.com/SpamScope/spamscope>`__.

mail-parser can parse Outlook email format (.msg). To use this feature,
Expand All @@ -24,13 +27,13 @@ Debian based systems:

::

$ apt-get install libemail-outlook-message-perl
$ apt-get install libemail-outlook-message-perl

For more details:

::

$ apt-cache show libemail-outlook-message-perl
$ apt-cache show libemail-outlook-message-perl

mail-parser supports Python 3.

Expand All @@ -44,31 +47,38 @@ headers <https://www.iana.org/assignments/message-headers/message-headers.xhtml>
- bcc
- cc
- date
- delivered\_to
- delivered_to
- from\_ (not ``from`` because is a keyword of Python)
- message\_id
- message_id
- received
- reply\_to
- reply_to
- subject
- to

There are other properties to get: - body - headers - attachments -
sender IP address - to domains

To get custom headers you should replace “-” with “\_”. Example for
header ``X-MSMail-Priority``:

::

$ mail.X_MSMail_Priority

mail-parser can detect defect in mail: -
`defects <https://docs.python.org/2/library/email.message.html#email.message.Message.defects>`__:
mail with some not compliance RFC part

All properties have a JSON and raw property that you can get with: -
name\_json - name\_raw
name_json - name_raw

Example:

::

$ mail.to (Python object)
$ mail.to_json (JSON)
$ mail.to_raw (raw header)
$ mail.to (Python object)
$ mail.to_json (JSON)
$ mail.to_raw (raw header)

The command line tool use the JSON format.

Expand All @@ -83,7 +93,8 @@ Apache 2 Open Source License
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

mail-parser can be downloaded, used, and modified free of charge. It is
available under the Apache 2 license. |Donate|
available under the Apache 2 license.
`Donate <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=VEPXYP745KJF2>`__

Authors
-------
Expand All @@ -101,21 +112,21 @@ Clone repository

::

git clone https://github.com/SpamScope/mail-parser.git
git clone https://github.com/SpamScope/mail-parser.git

and install mail-parser with ``setup.py``:

::

$ cd mail-parser
$ cd mail-parser

$ python setup.py install
$ python setup.py install

or use ``pip``:

::

$ pip install mail-parser
$ pip install mail-parser

Usage in a project
------------------
Expand All @@ -124,35 +135,36 @@ Import ``mailparser`` module:

::

import mailparser
import mailparser

mail = mailparser.parse_from_file(f)
mail = mailparser.parse_from_file_obj(fp)
mail = mailparser.parse_from_string(raw_mail)
mail = mailparser.parse_from_bytes(byte_mail)
mail = mailparser.parse_from_bytes(byte_mail)
mail = mailparser.parse_from_file(f)
mail = mailparser.parse_from_file_msg(outlook_mail)
mail = mailparser.parse_from_file_obj(fp)
mail = mailparser.parse_from_string(raw_mail)

Then you can get all parts

::

mail.attachments: list of all attachments
mail.body
mail.date: datetime object in UTC
mail.defects: defect RFC not compliance
mail.defects_categories: only defects categories
mail.delivered_to
mail.from_
mail.get_server_ipaddress(trust="my_server_mail_trust")
mail.headers
mail.mail: tokenized mail in a object
mail.message: email.message.Message object
mail.message_as_string: message as string
mail.message_id
mail.received
mail.subject
mail.text_plain: only text plain mail parts in a list
mail.to
mail.to_domains
mail.attachments: list of all attachments
mail.body
mail.date: datetime object in UTC
mail.defects: defect RFC not compliance
mail.defects_categories: only defects categories
mail.delivered_to
mail.from_
mail.get_server_ipaddress(trust="my_server_mail_trust")
mail.headers
mail.mail: tokenized mail in a object
mail.message: email.message.Message object
mail.message_as_string: message as string
mail.message_id
mail.received
mail.subject
mail.text_plain: only text plain mail parts in a list
mail.to
mail.to_domains

Usage from command-line
-----------------------
Expand All @@ -164,46 +176,48 @@ These are all swithes:

::

usage: mailparser.py [-h] (-f FILE | -s STRING | -k) [-j] [-b] [-a] [-r] [-t] [-dt] [-m]
[-u] [-c] [-d] [-n] [-i Trust mail server string] [-p] [-z]
[-v]

Wrapper for email Python Standard Library

optional arguments:
-h, --help show this help message and exit
-f FILE, --file FILE Raw email file (default: None)
-s STRING, --string STRING
Raw email string (default: None)
-k, --stdin Enable parsing from stdin (default: False)
-j, --json Show the JSON of parsed mail (default: False)
-b, --body Print the body of mail (default: False)
-a, --attachments Print the attachments of mail (default: False)
-r, --headers Print the headers of mail (default: False)
-t, --to Print the to of mail (default: False)
-dt, --delivered-to Print the delivered-to of mail (default: False)
-m, --from Print the from of mail (default: False)
-u, --subject Print the subject of mail (default: False)
-c, --receiveds Print all receiveds of mail (default: False)
-d, --defects Print the defects of mail (default: False)
-n, --anomalies Print the anomalies of mail (default: False)
-o, --outlook Analyze Outlook msg (default: False)
-i Trust mail server string, --senderip Trust mail server string
Extract a reliable sender IP address heuristically
(default: None)
-p, --mail-hash Print mail fingerprints without headers (default:
False)
-z, --attachments-hash
Print attachments with fingerprints (default: False)
-v, --version show program's version number and exit

It takes as input a raw mail and generates a parsed object.
usage: mailparser [-h] (-f FILE | -s STRING | -k)
[-l {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}] [-j] [-b]
[-a] [-r] [-t] [-dt] [-m] [-u] [-c] [-d] [-o]
[-i Trust mail server string] [-p] [-z] [-v]

Wrapper for email Python Standard Library

optional arguments:
-h, --help show this help message and exit
-f FILE, --file FILE Raw email file (default: None)
-s STRING, --string STRING
Raw email string (default: None)
-k, --stdin Enable parsing from stdin (default: False)
-l {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}, --log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
Set log level (default: WARNING)
-j, --json Show the JSON of parsed mail (default: False)
-b, --body Print the body of mail (default: False)
-a, --attachments Print the attachments of mail (default: False)
-r, --headers Print the headers of mail (default: False)
-t, --to Print the to of mail (default: False)
-dt, --delivered-to Print the delivered-to of mail (default: False)
-m, --from Print the from of mail (default: False)
-u, --subject Print the subject of mail (default: False)
-c, --receiveds Print all receiveds of mail (default: False)
-d, --defects Print the defects of mail (default: False)
-o, --outlook Analyze Outlook msg (default: False)
-i Trust mail server string, --senderip Trust mail server string
Extract a reliable sender IP address heuristically
(default: None)
-p, --mail-hash Print mail fingerprints without headers (default:
False)
-z, --attachments-hash
Print attachments with fingerprints (default: False)
-v, --version show program's version number and exit

It takes as input a raw mail and generates a parsed object.

Example:

.. code:: shell
$ mailparser -f example_mail -j
$ mailparser -f example_mail -j
This example will show you the tokenized mail in a JSON pretty format.

Expand All @@ -219,23 +233,11 @@ Exceptions hierarchy of mail-parser:

::

MailParserError: Base MailParser Exception
|
├── MailParserOutlookError: Raised with Outlook integration errors
|
├── MailParserEnvironmentError: Raised when the environment is not correct
|
├── MailParserOSError: Raised when there is an OS error

.. |PyPI version| image:: https://badge.fury.io/py/mail-parser.svg
:target: https://badge.fury.io/py/mail-parser
.. |Build Status| image:: https://travis-ci.org/SpamScope/mail-parser.svg?branch=develop
:target: https://travis-ci.org/SpamScope/mail-parser
.. |Coverage Status| image:: https://coveralls.io/repos/github/SpamScope/mail-parser/badge.svg?branch=develop
:target: https://coveralls.io/github/SpamScope/mail-parser?branch=develop
.. |BCH compliance| image:: https://bettercodehub.com/edge/badge/SpamScope/mail-parser?branch=develop
:target: https://bettercodehub.com/
.. |image4| image:: https://images.microbadger.com/badges/image/fmantuano/spamscope-mail-parser.svg
:target: https://microbadger.com/images/fmantuano/spamscope-mail-parser
.. |Donate| image:: https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif
:target: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=VEPXYP745KJF2
MailParserError: Base MailParser Exception
|
\── MailParserOutlookError: Raised with Outlook integration errors
|
\── MailParserEnvironmentError: Raised when the environment is not correct
|
\── MailParserOSError: Raised when there is an OS error

4 changes: 1 addition & 3 deletions mailparser/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,8 @@

from .mailparser import (
MailParser,
get_header,
parse_from_bytes,
parse_from_file,
parse_from_file_msg,
parse_from_file_obj,
parse_from_string,
)
parse_from_string)
Loading

0 comments on commit 35c4715

Please sign in to comment.