armatis 1.1.1
Armatis parses the website or web API response of Korean parcel delivery service company for tracking the parcel.
License: BSD
Keywords: parcel delivery korea

Armatis
=======

.. image:: https://img.shields.io/badge/License-BSD%202--Clause-blue.svg
   :target: https://opensource.org/licenses/BSD-2-Clause
.. image:: https://badge.fury.io/py/armatis.svg
   :target: https://badge.fury.io/py/armatis
.. image:: https://travis-ci.org/iBluemind/armatis.svg?branch=master
   :target: https://travis-ci.org/iBluemind/armatis
.. image:: https://readthedocs.org/projects/armatis/badge/
   :target: http://armatis.readthedocs.io/en/latest/

Armatis parses the website or web API response of Korean
parcel delivery service company for tracking the parcel.

Installation
------------

Install Armatis with this following command:

.. code:: sh

    $ pip install armatis

Usage
-----

Armatis is simple to use. Just need to type the delivery company code
and the invoice number.

To find the parcel, just use the method ``find()``:

.. code:: python

    from armatis import Armatis

    tracker = Armatis('cj', 123456789123)
    tracker.find()

You can use the method ``supported_companies()`` to find the supported
delivery company names and company codes.

.. code:: python

    tracker.supported_companies()

The returned data of the method ``find()`` is like below:

.. code:: json

    {
        "company": {
            "contact": "1588-1255",
            "name": "CJ대한통운"
        },
        "parcel": {
            "receiver": "(주*",
            "sender": "한만*",
            "note": "일반",
            "address": "경기도 성남시 분당구******"
        },
        "tracks": [
            {
                "time": "2016-10-13 18:07:13",
                "status": "간선상차",
                "location": "파주Sub",
                "phone1": "파주Sub(031-960-6566)",
                "phone2": null
            },
            {
                "time": "2016-10-13 21:22:09",
                "status": "집화처리",
                "location": "경기파주",
                "phone1": "경기파주(070-7779-1003)",
                "phone2": null
            },
            {
                "time": "2016-10-14 02:06:39",
                "status": "간선하차",
                "location": "옥천HUB",
                "phone1": null,
                "phone2": null
            },
            {
                "time": "2016-10-14 02:17:16",
                "status": "간선하차",
                "location": "옥천HUB",
                "phone1": null,
                "phone2": null
            },
            {
                "time": "2016-10-14 02:25:10",
                "status": "행낭포장",
                "location": "옥천HUB",
                "phone1": null,
                "phone2": null
            },
            {
                "time": "2016-10-14 04:06:49",
                "status": "간선상차",
                "location": "옥천HUB",
                "phone1": null,
                "phone2": null
            },
            {
                "time": "2016-10-14 11:10:05",
                "status": "간선하차",
                "location": "분당A",
                "phone1": "분당A(031-725-9222)",
                "phone2": null
            },
            {
                "time": "2016-10-14 11:12:07",
                "status": "배달출발",
                "location": "분당대리점a(C15F)",
                "phone1": "분당대리점a(C15F)(031-769-0516)",
                "phone2": "01012345678"
            },
            {
                "time": "2016-10-14 16:44:35",
                "status": "배달완료",
                "location": "분당대리점a(C15F)",
                "phone1": "분당대리점a(C15F)(031-769-0516)",
                "phone2": "01012345678"
            }
        ]
    }

Supported delivery companies
----------------------------

The following delivery companies are supported currently.

+--------------------------------+----------------+----------------+
| Company                        | Test existed   | Last Updated   |
+================================+================+================+
| CJ대한통운, CVSNet편의점택배   | o              | 2016-12-10     |
+--------------------------------+----------------+----------------+
| 로젠택배                       | o              | 2016-12-10     |
+--------------------------------+----------------+----------------+
| 현대택배                       | o              | 2016-12-10     |
+--------------------------------+----------------+----------------+
| 한진택배                       | o              | 2016-12-10     |
+--------------------------------+----------------+----------------+
| KG로지스                       | o              | 2016-12-10     |
+--------------------------------+----------------+----------------+
| GTX로지스                      | o              | 2017-01-02     |
+--------------------------------+----------------+----------------+
| 우체국택배                     | o              | 2017-01-06     |
+--------------------------------+----------------+----------------+
| 합동택배                       | o              | 2017-01-06     |
+--------------------------------+----------------+----------------+
| EMS                            | o              | 2017-01-02     |
+--------------------------------+----------------+----------------+
| KGB택배                        | o              | 2017-01-02     |
+--------------------------------+----------------+----------------+

How to add new company
----------------------

You can make the new delivery company parser easily.

First, create a class which inherit ``Parser``, and implement the method
``parse()``.

.. code:: python

    from armatis.models import Parcel, Track
    from armatis.parser import Parser, ParserRequest

    class NewCompanyParser(Parser):
        def __init__(self, invoice_number, config):
            super(NewCompanyParser, self).__init__(invoice_number, config)
            # Describe the information about the website or web API provided by the delivery company
            parser_request = ParserRequest(url='http://thecompany.co.kr/tracking?invno=%s' % self.invoice_number)
            self.add_request(parser_request)

        # Actually occurred parsing the website or web API provided above
        def parse(self, parser):
            tables = parser.find_all('tbody')

            parcel = Parcel()
            parcel.sender = ...         # Sender's name
            parcel.receiver = ...       # Receiver's name
            parcel.address = ...        # Receive address
            parcel.note = ...           # Describe about the parcel
            self.parcel = parcel        # Store the information about the parcel!

            trs = tables[1].find_all('tr')
            for tr in trs:
                track = Track()
                track.status = ...      # Status of the delivery history
                track.time = ...        # Time of the delivery history
                track.location = ...    # Location the parcel where it is
                track.phone1 = ...      # Contact of the location
                track.phone2 = ...      # Contact of the location
                self.add_track(track)   # Add the tracking information!

| And, make a ``Company`` instance that describe the company.
| Finally, register this ``Company`` object with the ``Parser`` class
  you made above.

.. code:: python

    from armatis import Armatis, Company

    tracker = Armatis()

    # Make a Company instance that describe the company
    the_new_company = Company('새로운회사', 'nc', '1234-5678', [10, 12])
    # Register the Company object with the Parser class you made
    tracker.parser_manager.register_parser(the_new_company, NewCompanyParser)

Documentation
-------------

Completed documentation for Armatis is available on
`ReadtheDocs <http://armatis.readthedocs.io/en/latest/>`__.

Contributing
------------

Welcome contributions! If you would like to contribute on Armatis,
please follow these steps:

1. Fork this repository
2. Make your changes
3. Install the requirements using ``pip install -r requirements.txt``
4. Submit a pull request after running ``make ready``