Reference

pyhamtools.locator

pyhamtools.qsl

pyhamtools.frequency

pyhamtools.frequency.freq_to_band(freq)

converts a Frequency [kHz] into the band and mode according to the IARU bandplan

Parameters:: frequency (float) – Frequency in kHz
Returns:: Dictionary containing the band (int) and mode (str)
Return type:: dict
Raises:: KeyError – Wrong frequency or out of band

Example

The following example converts the frequency 14005.3 kHz into band and mode.

>>> from pyhamtools.utils import freq_to_band
>>> print freq_to_band(14005.3)
{
     'band': 20,
     'mode': CW
}

Note

Modes are:

CW

USB

LSB

DIGITAL

pyhamtools.callinfo

class pyhamtools.callinfo.Callinfo(lookuplib, logger=None)

The purpose of this class is to return data (country, latitude, longitude, CQ Zone…etc) for an Amateur Radio callsign. The class can be used with any lookup database, provided through an Instance of LookupLib. An instance of Lookuplib has to be injected on object construction.

Parameters:

lookuplib (LookupLib) – instance of LookupLib
logger (logging.getLogger(__name__), optional) – Python logger

get_adif_id(callsign, timestamp=None)

Returns ADIF id of a callsign’s country

Parameters:

callsign (str) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

containing the country ADIF id

Return type:

int

Raises:

KeyError – No Country found for callsign

get_all(callsign, timestamp=None)

Lookup a callsign and return all data available from the underlying database

Parameters:

callsign (str) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

Dictionary containing the callsign specific data

Return type:

dict

Raises:

KeyError – Callsign could not be identified

Example

The following code returns all available information from the country-files.com database for the callsign “DH1TW”

>>> from pyhamtools import LookupLib, Callinfo
>>> my_lookuplib = LookupLib(lookuptype="countryfile")
>>> cic = Callinfo(my_lookuplib)
>>> cic.get_all("DH1TW")
{
    'country': 'Fed. Rep. of Germany',
    'adif': 230,
    'continent': 'EU',
    'latitude': 51.0,
    'longitude': -10.0,
    'cqz': 14,
    'ituz': 28
}

Note

The content of the returned data depends entirely on the injected LookupLib (and the used database). While the country-files.com provides for example the ITU Zone, Clublog doesn’t. Consequently, the item “ituz” would be missing with Clublog (API or XML) LookupLib.

get_continent(callsign, timestamp=None)

Returns the continent Identifier of a callsign

Parameters:

callsign (str) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

continent identified

Return type:

str

Raises:

KeyError – No Continent found for callsign

Note

The following continent identifiers are used:

EU: Europe
NA: North America
SA: South America
AS: Asia
AF: Africa
OC: Oceania
AN: Antarctica

get_country_name(callsign, timestamp=None)

Returns the country name where the callsign is located

Parameters:

callsign (str) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

name of the Country

Return type:

str

Raises:

KeyError – No Country found for callsign

Note

Don’t rely on the country name when working with several instances of py:class:Callinfo. Clublog and Country-files.org use slightly different names for countries. Example:

Country-files.com: “Fed. Rep. of Germany”
Clublog: “FEDERAL REPUBLIC OF GERMANY”

get_cqz(callsign, timestamp=None)

Returns CQ Zone of a callsign

Parameters:

callsign (str) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

containing the callsign’s CQ Zone

Return type:

int

Raises:

KeyError – no CQ Zone found for callsign

static get_homecall(callsign)

Strips off country prefixes (HC2/DH1TW) and activity suffixes (DH1TW/P).

Parameters:: callsign (str) – Amateur Radio callsign
Returns:: callsign without country/activity pre/suffixes
Return type:: str
Raises:: ValueError – No callsign found in string

Example

The following code retrieves the home call for “HC2/DH1TW/P”

>>> from pyhamtools import LookupLib, Callinfo
>>> my_lookuplib = LookupLib(lookuptype="countryfile")
>>> cic = Callinfo(my_lookuplib)
>>> cic.get_homecall("HC2/DH1TW/P")
DH1TW

get_ituz(callsign, timestamp=None)

Returns ITU Zone of a callsign

Parameters:

callsign (str) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

containing the callsign’s CQ Zone

Return type:

int

Raises:

KeyError – No ITU Zone found for callsign

Note

Currently, only Country-files.com lookup database contains ITU Zones

get_lat_long(callsign, timestamp=None)

Returns Latitude and Longitude for a callsign

Parameters:

callsign (str) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

Containing Latitude and Longitude

Return type:

dict

Raises:

KeyError – No data found for callsign

Example

The following code returns Latitude & Longitude for “DH1TW”

>>> from pyhamtools import LookupLib, Callinfo
>>> my_lookuplib = LookupLib(lookuptype="countryfile")
>>> cic = Callinfo(my_lookuplib)
>>> cic.get_lat_long("DH1TW")
{
    'latitude': 51.0,
    'longitude': -10.0
}

Note

Unfortunately, in most cases the returned Latitude and Longitude are not very precise. Clublog and Country-files.com use the country’s capital coordinates in most cases, if no dedicated entry in the database exists. Best results will be retrieved with QRZ.com Lookup.

is_valid_callsign(callsign, timestamp=None)

Checks if a callsign is valid

Parameters:

callsign (str) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

True / False

Return type:

bool

Example

The following checks if “DH1TW” is a valid callsign

>>> from pyhamtools import LookupLib, Callinfo
>>> my_lookuplib = LookupLib(lookuptype="countryfile")
>>> cic = Callinfo(my_lookuplib)
>>> cic.is_valid_callsign("DH1TW")
True

pyhamtools.lookuplib

class pyhamtools.lookuplib.LookupLib(lookuptype='countryfile', apikey=None, apiv='1.3.3', filename=None, logger=None, username=None, pwd=None, redis_instance=None, redis_prefix=None)

This class is a wrapper for the following three Amateur Radio databases:

Clublog.org (daily updated XML File)
Clublog.org (HTTPS lookup)
Country-files.com (infrequently updated PLIST File)
QRZ.com (HTTP / XML Lookup)

It’s aim is to provide a homogeneous interface to different databases.

Typically an instance of this class is injected as a dependency in the Callinfo class, but it can also be used directly.

Even the interface is the same for all lookup sources, the returning data can be different. The documentation of the various methods provide more detail.

By default, LookupLib requires an Internet connection to download the libraries or perform the lookup against the Clublog API or QRZ.com.

The entire lookup data (where database files are downloaded) can also be copied into Redis, which an extremely fast in-memory Key/Value store. A LookupLib object can be instantiated to perform then all lookups in Redis, instead processing and loading the data from Internet / File. This saves some time and allows several instances of LookupLib to query the same data concurrently.

Parameters:

lookuptype (str) – “clublogxml” or “clublogapi” or “countryfile” or “redis” or “qrz”
apikey (str) – Clublog API Key
username (str) – QRZ.com username
pwd (str) – QRZ.com password
apiv (str, optional) – QRZ.com API Version
filename (str, optional) – Filename for Clublog XML or Country-files.com cty.plist file. When a local file is
used
necessary. (no Internet connection not API Key is)
logger (logging.getLogger(__name__), optional) – Python logger
redis_instance (redis.Redis(), optional) – Instance of Redis
redis_prefix (str, optional) – Prefix to identify the lookup data set in Redis

copy_data_in_redis(redis_prefix, redis_instance)

Copy the complete lookup data into redis. Old data will be overwritten.

Parameters:

redis_prefix (str) – Prefix to distinguish the data in redis for the different looktypes
redis_instance (str) – an Instance of Redis

Returns:

returns True when the data has been copied successfully into Redis

Return type:

bool

Example

Copy the entire lookup data from the Country-files.com PLIST File into Redis. This example requires a running instance of Redis, as well the python Redis connector (pip install redis-py).

>>> from pyhamtools import LookupLib
>>> import redis
>>> r = redis.Redis()
>>> my_lookuplib = LookupLib(lookuptype="countryfile")
>>> print my_lookuplib.copy_data_in_redis(redis_prefix="CF", redis_instance=r)
True

Now let’s create an instance of LookupLib, using Redis to query the data

>>> from pyhamtools import LookupLib
>>> import redis
>>> r = redis.Redis()
>>> my_lookuplib = LookupLib(lookuptype="redis", redis_instance=r, redis_prefix="CF")
>>> my_lookuplib.lookup_callsign("3D2RI")
{
  u'adif': 460,
  u'continent': u'OC',
  u'country': u'Rotuma Island',
  u'cqz': 32,
  u'ituz': 56,
  u'latitude': -12.48,
  u'longitude': 177.08
}

Note

This method is available for the following lookup type

clublogxml
countryfile

is_invalid_operation(callsign, timestamp=None)

Returns True if an operations is known as invalid

Parameters:

callsign (string) – Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

True if a record exists for this callsign (at the given time)

Return type:

bool

Raises:

KeyError – No matching callsign found
APIKeyMissingError – API Key for Clublog missing or incorrect

Example

The following code checks the Clublog XML database if the operation is valid for two dates.

>>> from pyhamtools import LookupLib
>>> from datetime import datetime, timezone
>>> my_lookuplib = LookupLib(lookuptype="clublogxml", apikey="myapikey")
>>> print my_lookuplib.is_invalid_operation("5W1CFN")
True
>>> try:
>>>   timestamp = datetime(year=2012, month=1, day=31, tzinfo=timezone.utc)
>>>   my_lookuplib.is_invalid_operation("5W1CFN", timestamp)
>>> except KeyError:
>>>   print "Seems to be invalid operation before 31.1.2012"
Seems to be an invalid operation before 31.1.2012

Note

This method is available for

clublogxml
redis

lookup_callsign(callsign=None, timestamp=None)

Returns lookup data if an exception exists for a callsign

Parameters:

callsign (string) – Amateur radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

Dictionary containing the country specific data of the callsign

Return type:

dict

Raises:

KeyError – No matching callsign found
APIKeyMissingError – API Key for Clublog missing or incorrect

Example

The following code queries the the online Clublog API for the callsign “VK9XO” on a specific date.

>>> from pyhamtools import LookupLib
>>> from datetime import datetime, timezone
>>> my_lookuplib = LookupLib(lookuptype="clublogapi", apikey="myapikey")
>>> timestamp = datetime(year=1962, month=7, day=7, tzinfo=timezone.utc)
>>> print my_lookuplib.lookup_callsign("VK9XO", timestamp)
{
 'country': u'CHRISTMAS ISLAND',
 'longitude': 105.7,
 'cqz': 29,
 'adif': 35,
 'latitude': -10.5,
 'continent': u'OC'
}

Note

This method is available for

clublogxml
clublogapi
countryfile
qrz.com
redis

lookup_entity(entity=None)

Returns lookup data of an ADIF Entity

Parameters:: entity (int) – ADIF identifier of country
Returns:: Dictionary containing the country specific data
Return type:: dict
Raises:: KeyError – No matching entity found

Example

The following code queries the the Clublog XML database for the ADIF entity Turkmenistan, which has the id 273.

>>> from pyhamtools import LookupLib
>>> my_lookuplib = LookupLib(lookuptype="clublogapi", apikey="myapikey")
>>> print my_lookuplib.lookup_entity(273)
{
 'deleted': False,
 'country': u'TURKMENISTAN',
 'longitude': 58.4,
 'cqz': 17,
 'prefix': u'EZ',
 'latitude': 38.0,
 'continent': u'AS'
}

Note

This method is available for the following lookup type

clublogxml
redis
qrz.com

lookup_prefix(prefix, timestamp=None)

Returns lookup data of a Prefix

Parameters:

prefix (string) – Prefix of a Amateur Radio callsign
timestamp (datetime, optional) – datetime in UTC (tzinfo=timezone.utc)

Returns:

Dictionary containing the country specific data of the Prefix

Return type:

dict

Raises:

KeyError – No matching Prefix found
APIKeyMissingError – API Key for Clublog missing or incorrect

Example

The following code shows how to obtain the information for the prefix “DH” from the countryfile.com database (default database).

>>> from pyhamtools import LookupLib
>>> myLookupLib = LookupLib()
>>> print myLookupLib.lookup_prefix("DH")
{
 'adif': 230,
 'country': u'Fed. Rep. of Germany',
 'longitude': 10.0,
 'cqz': 14,
 'ituz': 28,
 'latitude': 51.0,
 'continent': u'EU'
}

Note

This method is available for

clublogxml
countryfile
redis

lookup_zone_exception(callsign, timestamp=None)

Returns a CQ Zone if an exception exists for the given callsign

Args: callsign (string): Amateur radio callsign timestamp (datetime, optional): datetime in UTC (tzinfo=timezone.utc)

Returns:

Value of the the CQ Zone exception which exists for this callsign (at the given time)

Return type:

int

Raises:

KeyError – No matching callsign found
APIKeyMissingError – API Key for Clublog missing or incorrect

Example

The following code checks the Clublog XML database if a CQ Zone exception exists for the callsign DP0GVN.

>>> from pyhamtools import LookupLib
>>> my_lookuplib = LookupLib(lookuptype="clublogxml", apikey="myapikey")
>>> print my_lookuplib.lookup_zone_exception("DP0GVN")
38

The prefix “DP” It is assigned to Germany, but the station is located in Antarctica, and therefore in CQ Zone 38

Note

This method is available for

clublogxml
redis

pyhamtools.utils (deprecated)

pyhamtools.utils.freq_to_band(freq): converts a Frequency [kHz] into the band and mode according to the IARU bandplan

Note

DEPRECATION NOTICE This function has been moved to pyhamtools.frequency with PyHamTools 0.4.1 Please don’t use this module/function anymore. It will be removed soon.