Exploring the API

Summary

chzip	The chzip package provides a quick and easy Python interface to look for zip codes and cities in Switzerland.
chzip.ChZip([resource_dir])	The main entrance for the chzip library.
chzip.common	Common classes and utilities functions
chzip.zipcodes	Implementation classes that do the heavy lifting of the module

The chzip package

The chzip package provides a quick and easy Python interface to look for zip codes and cities in Switzerland.

chzip.download_and_unpack_all(download_dir='chzip/install/path/res')

Download and unpack all (available) resources.

Use upgrade_all() if you don’t want to re-download everything but only update what has changed. This method begins by erasing previous versions in the download directory.

Parameters:download_dir (str) – Download directory (with write permissions)

Note

You are very unlikely to ever call this method, except if you included chzip directly in your project, without installing it.

chzip.upgrade_all(download_dir='chzip/install/path/res', force=False)

Upgrade all resources.

Unlike download_all resources files that have not been changed will not be erased and downloaded again. Also, it takes care of keeping old (working) files if the upgrade fails (network error, bad download, corrupted file, error when unpacking, etc.)

It is recommended to run this method regularly to get up-to-date data.

Parameters:

• download_dir (str) – Download directory (with write permission) containing previous versions of the resource files.
• force (bool) – Force upgrade, even if files are up-to-date.

The ChZip class

class chzip.ChZip(resource_dir='chzip/install/path/res')

The main entrance for the chzip library.

all()

Returns all the localities from the database, in no particular order.

find(zip=None, long_name=None, short_name=None, canton=None, onrp=None)

Refer to Usage.

long_names(*args, **kwargs)

Is the same as find() but returns a list of long names instead.

The Common and Utility classes

Common classes and utilities functions

class chzip.common.Downloader

The parent (abstract) class of Downloaders. Can NOT be instantiated.

Subclasses can redefine DEFAULT_RES_DIRNAME.

DEFAULT_RES_DIRNAME = 'res'

The name of the directory that will contain the downloaded files.

download_and_unpack(download_dir)

Download and unpack resources files related to this downloader. This method should probably not be called on a UI thread or similar because this can be a long-running task.

upgrade_and_unpack(download_dir)

Similar to download_and_unpack() but does not do anything if files are up-to-date and does not let you with a broken installation in case of a download or unpacking failure.

class chzip.common.Locality(zip=0, short_name=None, long_name=None, canton=None, _zip_type_number=None, _onrp=None)

A locality is the name of a town, village or any “string” that goes after the ZIP code in the address.

canton = None

Canton. Official 2-letter uppercased abbreviation as used for vehicles number plates.

Note

FL is used for Liechtenstein addresses, and so is DE for 8238 Büsingen and IT for 66911 Campione. These are the only exceptions.

long_name = None

Long name (27 chars). Official designation. Must be preferred to short_name.

short_name = None

Short name (18 chars)

zip = 0

ZIP code

zip_type = None

A ZIP code might be only available for PO boxes, physical adresses, both of these, an entreprise, or dedicated for mail sorting.

See also

ZipType()

class chzip.common.ZipType

The ZipType tells if A ZIP code might be only available for PO boxes, physical adresses, both of these, an entreprise, or dedicated for mail sorting.

ENTERPRISES = 40

Enterprises

HOMES_AND_PO_BOXES = 10

Homes and PO boxes

HOMES_ONLY = 20

Homes only

INTERNAL = 80

For mail sorting by the post offices. Only used by the Post!

PO_BOXES_ONLY = 30

PO boxes only

static okay_for_stuff_delivery(zip_type)

Returns true if the specified ZIP type is appropriate to deliver merchandise. Returns False for a “PO boxes only” or “internal” ZIP code.

Where the magic happens

Implementation classes that do the heavy lifting of the module

class chzip.zipcodes.Downloader

The Downloader of Swiss Post MAT[CH] ZIP resources.

download_and_unpack(download_dir)

Downloads the ZIP files from MAT[CH], extract the text file, populate the internal SQLite3 database, and delete all the intermediary files.

Parameters:download_dir (str) – Resource directory that will contain both the temporary files (which will be deleted) and the database.

is_up_to_date(abs_resource_file)

Returns:true if the specified file is up-to-date.

upgrade_and_unpack(download_dir, force=False)

Does the same as download_and_unpack() but returns immediately if files are up-to-date and do not delete previous database. This can be handy in cases of failure, so is the recommended way to update the database.

Parameters:

• download_dir (str) – Resource directory that will contain both the temporary files (which will be deleted) and the database.
• force (bool) – Set to true to force update even if files are up-to-date.

class chzip.zipcodes.ResourceInstaller(zip_path, extract_dir, extract_to_filename)

Unzip the file downloaded from Swiss Post and install it at the appropriate location.

Usage: call unzip() and install() for a complete installation.

delete()

Delete temporary files

extracted_txt_path()

Returns:always returns the location of the text file, no matter if install() was called or not.

install()

Move file to its definitive location

real_path()

Returns:the path of the extracted text file, before moving it.

So this is the real path of the file just after unzipping.

If you want to work on the file before installing, call this method else call wanted_path(). extracted_txt_path() will figure this out for you.

unzip()

Unzip the first file from ZIP to the specified directory

Returns:the filename extracted

wanted_path()

Returns:the desired path of the extracted text file.