Metadata-Version: 2.0
Name: postal-address
Version: 0.7.1
Summary: Parse, normalize and render postal addresses.
Home-page: http://github.com/scaleway/postal-address
Author: Scaleway
Author-email: opensource@scaleway.com
License: GPLv2+
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Localization
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Dist: awesome-slugify
Requires-Dist: pycountry (>=1.9)

Postal Address
==============

Python module to parse, normalize and render postal addresses.

.. image:: https://img.shields.io/pypi/v/postal-address.svg?style=flat
    :target: https://pypi.python.org/pypi/postal-address
    :alt: Last release
.. image:: https://img.shields.io/travis/scaleway/postal-address/develop.svg?style=flat
    :target: https://travis-ci.org/scaleway/postal-address
    :alt: Unit-tests status
.. image:: https://img.shields.io/coveralls/scaleway/postal-address/develop.svg?style=flat
    :target: https://coveralls.io/r/scaleway/postal-address?branch=develop
    :alt: Coverage Status
.. image:: https://img.shields.io/requires/github/scaleway/postal-address/master.svg?style=flat
    :target: https://requires.io/github/scaleway/postal-address/requirements/?branch=master
    :alt: Requirements freshness
.. image:: https://img.shields.io/scrutinizer/g/scaleway/postal-address.svg?style=flat
    :target: https://scrutinizer-ci.com/g/scaleway/postal-address/?branch=develop
    :alt: Code Quality
.. image:: https://img.shields.io/pypi/l/postal-address.svg?style=flat
    :target: https://www.gnu.org/licenses/gpl-2.0.html
    :alt: Software license
.. image:: https://img.shields.io/pypi/dm/postal-address.svg?style=flat
    :target: https://pypi.python.org/pypi/postal-address#downloads
    :alt: Popularity


Motivation
----------

    « What ties us to territory is tax. »
    -- Kevin Deldycke, 2014-11-07

The reason above is why we need fine-grained and meticulous territory
management and normalization. This project aims to solve this problem once for
all.

Don't get me wrong, this work is a huge undertaking. Postal address parsing,
normalization and rendering is hard. Much harder than you think. Please read the
famous `Falsehoods programmers believe about addresses
<http://www.mjt.me.uk/posts/falsehoods-programmers-believe-about-addresses/>`_
pamphlet.

This library is still in its early stages, but is good enough to implement
the new European Directives on VAT, which requires all e-commerce shops to
guess the locality of their EU customers depending on their billing address.


Stability policy
----------------

Here is a bunch of rules we're trying to follow regarding stability:

* Patch releases (``0.x.n`` → ``0.x.(n+1)`` upgrades) are bug-fix only. These
  releases must not break anything and keeps backward-compatibility with
  ``0.x.*`` and ``0.(x-1).*`` series.

* Minor releases (``0.n.*`` → ``0.(n+1).0`` upgrades) includes any non-bugfix
  changes. These releases must be backward-compatible with any ``0.n.*``
  version but are allowed to drop compatibility with the ``0.(n-1).*`` series
  and below.

* Major releases (``n.*.*`` → ``(n+1).0.0`` upgrades) are not planned yet:
  we're still in beta and the final feature set of the ``1.0.0`` release is not
  decided yet.


Release process
---------------

Start from the ``develop`` branch:

.. code-block:: bash

    git clone git@github.com:scaleway/postal-address.git
    git checkout develop

Update revision to its release number and update change log:

.. code-block:: bash

    vi ./postal_address/__init__.py
    vi ./CHANGES.rst

Create a release commit, tag it and merge it back to ``master`` branch:

.. code-block:: bash

    git add ./postal_address/__init__.py ./CHANGES.rst
    git commit -m "Release vXX.XX.XX"
    git tag "vXX.XX.XX"
    git push
    git push --tags
    git checkout master
    git pull
    git merge "vXX.XX.XX"
    git push

Push packaging to the test cheeseshop:

.. code-block:: bash

    python setup.py register -r testpypi
    pip install wheel
    rm -rf ./build ./dist
    python setup.py sdist bdist_egg bdist_wheel upload -r testpypi

Publish packaging to PyPi:

.. code-block:: bash

    python setup.py register -r pypi
    rm -rf ./build ./dist
    python setup.py sdist bdist_egg bdist_wheel upload -r pypi

Bump revision back to its development state:

.. code-block:: bash

    git checkout develop
    vi ./postal_address/__init__.py
    vi ./CHANGES.rst
    git add ./postal_address/__init__.py ./CHANGES.rst
    git commit -m "Post release version bump."


License
-------

This software is licensed under the `GNU General Public License v2 or later
(GPLv2+)
<https://github.com/scaleway/postal-address/blob/master/LICENSE>`_.

ChangeLog
=========


0.7.1 (2015-05-20)
------------------

* Add utility method to generate random addresses for test mockups.


0.7.0 (2015-04-14)
------------------

* Include internal fields disguised as properties when ``repr``-ing the
  ``Address`` object.
* Always use the common name of a country if available instead of its official
  default value.


0.6.1 (2015-04-07)
------------------

* Update all Online Labs references to Scaleway.


0.6.0 (2015-04-02)
------------------

* Add an option to bypass Address' strict normalization.


0.5.2 (2015-03-30)
------------------

* Always sort fields in error messages to improve reproducibility when
  unit testing.
* Deduplicate inconsistent field entries in custom address exception.


0.5.1 (2015-03-30)
------------------

* Fix bad released version.


0.5.0 (2015-03-30)
------------------

* Increase capabilities of alias resolution by ``country_aliases()`` method,
  which in turns increase address normalization efficiency.
* Remove backward compatibility with ``0.3`` series.
* Remove deprecated ``territory.territory_tree()`` method which provided
  backward compatibilityi with the ``0.1`` series. It should have been removed
  in the ``0.3.0`` release.
* Split-up ``supported_territory_codes()`` into ``supported_country_codes()``
  and ``supported_subdivision_codes()``.


0.4.3 (2015-03-26)
------------------

* Fix rendering of subdivision-less addresses.


0.4.2 (2015-03-26)
------------------

* Fix ``country_code`` to ``subdivision_code`` validation if the latter is not
  set.


0.4.1 (2015-03-26)
------------------

* Base our custom ``InvalidAddress`` exception on ``ValueError`` to increase
  backward compatibility.


0.4.0 (2015-03-25)
------------------

* Show subdivision as-is in rendered address if not already printed by state,
  country or city.
* Document stability policy. Closes #8.
* Change internals to refer to address components as ``fields``.
* Raise custom exception on address validation a detailed list of invalid
  fields in one go. Closes #7.


0.3.3 (2015-03-25)
------------------

* Fix bad released version.


0.3.2 (2015-03-25)
------------------

* Add backward compatibility to the ``0.2`` series following territory utils
  split out of the ``address`` module. See #8 and #9.


0.3.1 (2015-03-05)
------------------

* Fix rendering of state in address.


0.3.0 (2015-03-04)
------------------

* Remove backward compatibility with the ``0.1`` series.
* Allow direct import of classes from module root.
* Split territory utils out to their own file. See #3.
* Rename ``normalize_country_code`` to ``country_from_subdivision``. Mark the
  former as deprecated.
* Address normalization is now non-blocking. It simply reset invalid components
  to None. Only a call to ``validate`` method check data consistency.


0.2.1 (2014-12-22)
------------------

* Push a new release to fix cached desynced packages on cheeseshops and clones.


0.2.0 (2014-12-18)
------------------

* Package the whole module for proper distribution.


0.1.1 (2014-12-16)
------------------

* Restore partial backward compatibility with address module from the ``0.1``
  series.


0.1.0 (2014-12-15)
------------------

* First public release.


0.0.0 (2013-12-06)
------------------

* First commit.


