API
===

.. method:: autocomplete(route_distribution[, unique = False][, kinds = None][, limit = 10][, offset = 0])

    Autocomplete the route_distribution entered by user.

.. method:: get_routes(route_distribution[, unique = False][, kinds = None][, limit = 10][, offset = 0])

    Return the maximum of corresponding routes

.. method:: guess_territory(route_distribution, territories  = None, kinds = None)

    Deduce a territory code and kind from a common code and/or name.
    Thee functions try to guarantee as much as possible that the returned common_code is the good one.
        * iter_condition
        * iter_condition_by_common_code
        * iter_condition_by_route_name

.. method:: retrieve_territory(route_distribution, territories = None, kinds = None, existing_routes_key = None)

    Retrieve the territory from a route_distribution(common_code and route_name).

.. method:: split_route_distribution(route_distribution):

    Separate the postal distribution into a pair (postal code, postal routing)

.. method:: register_route(author = None, date = None, mark = 1, territory = None, existing_routes_key = None, pobox = None, common_code = None, route_name = None)

    Record or update a route.
    if the route exist, this function vote for it, increasing or decreasing its 'score'. A user can vote several time,
    but only one vote will be affected: his own

.. method:: get_existing_routes_key(author):

    Retrive all routes entered by an author. This is usefull for scripts, to know what and when the scripts made
    changes. This method work in collaboration with the next one.

.. method:: delete_obsolete_routes(author, routes_key):

    Delete obsolete routes. When a script iterates overs its new entries, it remove entries from the list of existing
    routes (get by the previous method). And when the scripts ends, he can delete all routes remaining in the list
    (they are no longer maintained).

    Be carefull with this method, it can delete a significant amount of data.