qspylib package

Submodules

qspylib.clublog module

Functions and classes related to querying the ClubLog API.

class qspylib.clublog.ClubLogClient(email: str, callsign: str, password: str, timeout: int = 15)

Bases: object

This is a wrapper for the ClubLog API, holding a user’s authentication to perform actions on their behalf.

fetch_logbook() → Logbook

Fetch the user’s ClubLog logbook. :raises HTTPError: An error occurred while trying to make a connection.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

exception qspylib.clublog.ClubLogError(message='An error occurred while interfacing with the ClubLog API')

Bases: Exception

An error raised when an issue occurs with the ClubLog API.

qspylib.eqsl module

Functions and classes related to querying the eQSL API.

class qspylib.eqsl.eQSLClient(username: str, password: str, qth_nickname: str = None, timeout: int = 15)

Bases: object

API wrapper for eQSL.cc. This class holds a user’s authentication to perform actions on their behalf.

fetch_inbox(limit_date_lo: str = None, limit_date_hi: str = None, rcvd_since: str = None, confirmed_only: str = None, unconfirmed_only: str = None, archive: str = None, ham_only: str = None) → Logbook

Fetches INCOMING QSOs, from the user’s eQSL Inbox.

Parameters:

• limit_date_lo (str, optional) – Earliest QSO date to download (oddly, in MM/DD/YYYY format with escape code 2F for slashes), optionally append HH:MM otherwise the default is 00:00. Defaults to None.

• limit_date_hi (str, optional) – Latest QSO date to download (oddly, in MM/DD/YYYY format with escape code 2F), optionally append HH:MM otherwise the default is 23:59 to include the entire day. Defaults to None.

• rcvd_since (str, optional) – (YYYYMMDDHHMM) Everything that was entered into the database on or after this date/time (Valid range 01/01/1900 - 12/31/2078). Defaults to None.

• confirmed_only (str, optional) – Set to any value to signify you only want to download Inbox items you HAVE confirmed. Defaults to None.

• unconfirmed_only (str, optional) – Set to any value to signify you only want to download Inbox items you have NOT confirmed. Defaults to None.

• archive (str, optional) – 1 for Archived records ONLY; 0 for Inbox (non-archived) ONLY; omit this parameter to retrieve ALL records in Inbox and Archive. Defaults to None.

• ham_only (str, optional) – anything, filters out all SWL contacts. Defaults to None.

Raises:

• eQSLError – An error occurred interfacing with eQSL.

• HTTPError – An error occurred while trying to make a connection.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

fetch_inbox_qsls(limit_date_lo: str = None, limit_date_hi: str = None, rcvd_since: str = None, archive: str = None, ham_only: str = None) → Logbook

Fetches INCOMING QSLs, from the user’s eQSL Inbox.

limit_date_lo (str, optional): Earliest QSO date to download (oddly, in MM/DD/YYYY format with escape code 2F for slashes), optionally append HH:MM otherwise the default is 00:00. Defaults to None.

limit_date_hi (str, optional): Latest QSO date to download (oddly, in MM/DD/YYYY format with escape code 2F), optionally append HH:MM otherwise the default is 23:59 to include the entire day. Defaults to None. rcvd_since (str, optional): (YYYYMMDDHHMM) Everything that was entered into the database on or after this date/time (Valid range 01/01/1900 - 12/31/2078). Defaults to None. archive (str, optional): 1 for Archived records ONLY; 0 for Inbox (non-archived) ONLY; omit this parameter to retrieve ALL records in Inbox and Archive. Defaults to None. ham_only (str, optional): anything, filters out all SWL contacts. Defaults to None.

Raises:

• eQSLError – An error occurred interfacing with eQSL.

• HTTPError – An error occurred while trying to make a connection.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

fetch_outbox()

Fetches OUTGOING QSOs, from the user’s eQSL Outbox.

Raises:

• eQSLError – An error occurred interfacing with eQSL.

• HTTPError – An error occurred while trying to make a connection.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

static get_ag_list(timeout: int = 15)

Get a list of Authenticity Guaranteed members.

Parameters:

timeout (int, optional) – Seconds before connection times out. Defaults to 15.

Raises:

HTTPError – An error occurred while trying to make a connection.

Returns:

tuple contains a list of string callsigns, and a str header with the date the list was generated

Return type:

tuple, str

static get_ag_list_dated(timeout: int = 15)

Get a list of Authenticity Guaranteed eQSL members with the date of their last upload to eQSL.

Parameters:

timeout (int, optional) – Seconds before connection times out. Defaults to 15.

Raises:

HTTPError – An error occurred while trying to make a connection.

Returns:

First element is a dict with key: callsign and value: date, and second is a header of when this list was generated.

Return type:

tuple

static get_full_member_list(timeout: int = 15)

Get a list of all members of QRZ.

Parameters:

timeout (int, optional) – Seconds before connection times out. Defaults to 15.

Raises:

HTTPError – An error occurred while trying to make a connection.

Returns:

key is the callsign and the value is a tuple of: GridSquare, AG, Last Upload

Return type:

dict

get_last_upload_date() → datetime

Gets last upload date for the logged in user.

Raises:

• eQSLError – An error occurred interfacing with eQSL.

• HTTPError – An error occurred while trying to make a connection.

Returns:

datetime of last upload for the active user. Contains: Year, Month, Date, Hour, Minute (UTC).

Return type:

datetime.datetime

static get_users_data(callsign: str)

Get a specific user’s data from the full member list.

Note

This is incredibly slow. A better method probably involves doing some vectorization, but that would require adding a dependency.

Parameters:

callsign (str) – callsign to get data about

Returns:

contains: GridSquare, AG, Last Upload

Return type:

tuple

retrieve_graphic(callsign_from: str, qso_datetime: datetime, band: str, mode: str, timeout: int = 15) → BytesIO

Retrieve the graphic image for a QSO from eQSL. This is a simplified interface that uses a datetime object.

Parameters:

• callsign_from (str) – The callsign of the sender of the eQSL

• qso_datetime (datetime) – Datetime containing the Year, Month, Day, Hour, and Minute of the QSO.

• band (str) – 20m, 80M, 70cm, etc. (case insensitive)

• mode (str) – Must match exactly and should be an ADIF-compatible mode

• timeout (int, optional) – Seconds before query times out. Defaults to 15.

Raises:

• eQSLError – An error occurred interfacing with eQSL.

• HTTPError – An error occurred while trying to make a connection.

Returns:

A BytesIO binary stream containing the image data. This can be further processed with PIL or other image libraries; for instance, using PIL, Image.open(return_val) will give a PIL Image.

Return type:

BytesIO

set_timeout(timeout: int)

Set timeout for the Client to a new value.

Parameters:

timeout (int) – time to timeout in seconds.

static verify_eqsl(callsign_from: str, callsign_to: str, qso_band: str, qso_mode: str = None, qso_date: str = None, timeout: int = 15)

Verify a QSL with eQSL.

Parameters:

• callsign_from (str) – Callsign originating QSO (i.e. N5UP)

• callsign_to (str) – Callsign receiving QSO (i.e. TE5T)

• qso_band (str) – Band QSO took place on (i.e. 160m)

• qso_mode (str, optional) – Mode QSO took place with (i.e. SSB). Defaults to None.

• qso_date (str, optional) – Date QSO took place (i.e. 01/31/2000). Defaults to None.

• timeout (int, optional) – Seconds before connection times out. Defaults to 15.

Raises:

• eQSLError – An error occurred interfacing with eQSL.

• HTTPError – An error occurred while trying to make a connection.

Returns:

bool of whether the QSO was verified and a str of extra information eQSL reports, such as Authenticity Guaranteed status.

Return type:

bool, str

exception qspylib.eqsl.eQSLError(message='An error occurred interfacing with eQSL')

Bases: Exception

An error occurred interfacing with eQSL.

qspylib.logbook module

Classes to provide the backbone of qspylib’s logbook functionality

class qspylib.logbook.Logbook(callsign: str, unparsed_log: str)

Bases: object

A Logbook has both an adi field, holding all fields parsed from an .adi log per QSO, and a simplified log field, holding a simplified set of fields per QSO. A QSO is one of qspylib.logbook.QSO.

Interacting with the log field can provide one field to check for if a QSO is confirmed on one or more of: LoTW, eQSL, QRZ, or ClubLog.

A Logbook is built by consuming an .adi formatted input string.

callsign

callsign of the logbook owner

Type:

str

adi

a dict, where each “entry” is itself a dict of fields parsed from an .adi log.

Type:

list[adif_io.QSO]

header

header of the .adi log.

Type:

adif_io.Headers

log

simplified set of fields per QSO.

Type:

list

discard_qso(contact: QSO)

Removes the corresponding QSO from the .log portion of a Logbook, if one exists.

Parameters:

contact (adif_io.QSO) – QSO to be deleted, if it exists, structured as from an adif.io QSO object

write_qso(contact: QSO)

Append a QSO to both the .log and .adi portions of the Logbook object.

Parameters:

contact (adif_io.QSO) – QSO object to be added, structured as from an adif.io QSO object

class qspylib.logbook.QSO(their_call: str, band: str, mode: str, qso_date: str, time_on: str, qsl_rcvd: str = 'N')

Bases: object

A hambaseio QSO obj. Contains simple info on a QSO.

their_call

callsign the QSO is with

Type:

str

band

band of QSO

Type:

str

mode

mode of QSO

Type:

str

qso_date

date of QSO

Type:

str

time_on

time start of QSO

Type:

str

qsl_rcvd

if QSO has been confirmed

Type:

str

qso_to_adif_io_qso() → QSO

Converts a QSO object into an adif.io QSO object.

Returns:

an adif.io QSO object

Return type:

adif_io.QSO

qso_to_adif_string() → str

Converts a QSO object into an adif formatted string.

Returns:

an adif formatted string

Return type:

str

qspylib.logbook.qso_from_adi(contact: QSO)

Transforms an adif_io.QSO object into a qspylib.logbook.QSO object.

Parameters:

contact (adif_io.QSO) – contact to transform into a .log friendly QSO

Returns:

a qspylib QSO object

Return type:

qspylib.logbook.QSO

qspylib.lotw module

Functions and classes related to querying the LotW API.

class qspylib.lotw.LOTWClient(username: str, password: str)

Bases: object

Wrapper for LOTW API functionality that requires a logged-in session. Fetching returns a Logbook object that must be assigned to something._

fetch_logbook(qso_query: int = 1, qso_qsl: str = 'yes', qso_qslsince: str = None, qso_qsorxsince: str = None, qso_owncall: str = None, qso_callsign: str = None, qso_mode: str = None, qso_band: str = None, qso_dxcc: str = None, qso_startdate: str = None, qso_starttime: str = None, qso_enddate: str = None, qso_endtime: str = None, qso_mydetail: str = None, qso_qsldetail: str = None, qsl_withown: str = None) → Logbook

Fetches the user’s logbook from LOTW. This function exposes all of the parameters that can be passed to the LOTW API, including ones that may be “contradictory” if used together.

Note

A provided helper that uses this function may be easier to use in most cases.

Parameters:

• qso_query (int, optional) – If absent, ADIF file will contain no QSO records. Defaults to 1.

• qso_qsl (str, optional) – If “yes”, only QSL records are returned (can be ‘yes’ or ‘no’). Defaults to ‘yes’.

• qso_qslsince (str, optional) – QSLs since specified datetime (YYYY-MM-DD HH:MM:SS). Ignored unless qso_qsl=”yes”. Defaults to None.

• qso_qsorxsince (str, optional) – QSOs received since specified datetime. Ignored unless qso_qsl=”no”. Defaults to None.

• qso_owncall (str, optional) – Returns records where “own” call sign matches. Defaults to None.

• qso_callsign (str, optional) – Returns records where “worked” call sign matches. Defaults to None.

• qso_mode (str, optional) – Returns records where mode matches. Defaults to None.

• qso_band (str, optional) – Returns records where band matches. Defaults to None.

• qso_dxcc (str, optional) – Returns matching DXCC entities, implies qso_qsl=’yes’. Defaults to None.

• qso_startdate (str, optional) – Returns only records with a QSO date on or after the specified value. Defaults to None.

• qso_starttime (str, optional) – Returns only records with a QSO time at or after the specified value on the starting date. This value is ignored if qso_startdate is not provided. Defaults to None.

• qso_enddate (str, optional) – Returns only records with a QSO date on or before the specified value. Defaults to None.

• qso_endtime (str, optional) – Returns only records with a QSO time at or before the specified value on the ending date. This value is ignored if qso_enddate is not provided. Defaults to None.

• qso_mydetail (str, optional) – If “yes”, returns fields that contain the Logging station’s location data, if any. Defaults to None.

• qso_qsldetail (str, optional) – If “yes”, returns fields that contain the QSLing station’s location data, if any. Defaults to None.

• qsl_withown (str, optional) – If “yes”, each record contains the STATION_CALLSIGN and APP_LoTW_OWNCALL fields to identify the “own” call sign used for the QSO. Defaults to None.

Raises:

• RetrievalFailure – A failure to retrieve information from LOTW. Contains the error received from LOTW.

• HTTPError – An error occurred while trying to make a connection.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

fetch_qsls(qslsince: datetime = None, owncall: str = None, callsign: str = None, mode: str = None, band: str = None, dxcc: str = None, start_datetime: datetime = None, end_datetime: datetime = None) → Logbook

Fetches matching QSLs (confirmed QSOs) from LOTW.

Parameters:

• qslsince (datetime, optional) – QSLs since specified datetime (YYYY-MM-DD HH:MM:SS). Defaults to None.

• owncall (str, optional) – Returns records where “own” call sign matches. Defaults to None.

• callsign (str, optional) – Returns records where “worked” call sign matches. Defaults to None.

• mode (str, optional) – Returns records where mode matches. Defaults to None.

• band (str, optional) – Returns records where band matches. Defaults to None.

• dxcc (str, optional) – Returns matching DXCC entities. Defaults to None.

• start_datetime (datetime, optional) – Returns only records with a QSO date on or after the specified value. Optionally, includes HH:MM:SS. Defaults to None.

• end_datetime (datetime, optional) – Returns only records with a QSO time at or before the specified value. Optionally, includes HH:MM:SS. Defaults to None.

Raises:

• RetrievalFailure – A failure to retrieve information from LOTW. Contains the error received from LOTW.

• HTTPError – An error occurred while trying to make a connection.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

fetch_qsos(qsorxsince: datetime = None, owncall: str = None, callsign: str = None, mode: str = None, band: str = None, dxcc: str = None, start_datetime: datetime = None, end_datetime: datetime = None) → Logbook

Fetches matching QSOs (confirmed & unconfirmed) from LOTW.

Parameters:

• qsorxsince (datetime, optional) – QSOs since specified datetime (YYYY-MM-DD HH:MM:SS). Defaults to None.

• owncall (str, optional) – Returns records where “own” call sign matches. Defaults to None.

• callsign (str, optional) – Returns records where “worked” call sign matches. Defaults to None.

• mode (str, optional) – Returns records where mode matches. Defaults to None.

• band (str, optional) – Returns records where band matches. Defaults to None.

• dxcc (str, optional) – Returns matching DXCC entities. Defaults to None.

• start_datetime (datetime, optional) – Returns only records with a QSO date on or after the specified value. Optionally, includes HH:MM:SS. Defaults to None.

• end_datetime (datetime, optional) – Returns only records with a QSO time at or before the specified value. Optionally, includes HH:MM:SS. Defaults to None.

Raises:

• RetrievalFailure – A failure to retrieve information from LOTW. Contains the error received from LOTW.

• HTTPError – An error occurred while trying to make a connection.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

get_dxcc_credit(entity: str = None, ac_acct: str = None) → Logbook

Gets DXCC award account credit, optionally for a specific DXCC Entity Code specified via entity.

Note

This only returns applied for and granted credit, not ‘presumed’ credits.

Parameters:

• entity (str, optional) – dxcc entity number to check for, if a specific entity is desired. Defaults to None.

• ac_acct (str, optional) – award account to check against, if multiple exist for the given account. Defaults to None.

Raises:

• RetrievalFailure – A failure to retrieve information from LOTW. Contains the error received from LOTW.

• HTTPError – An error occurred while trying to make a connection.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

static get_last_upload(timeout: int = 15)

Queries LOTW for a list of callsigns and date they last uploaded.

Parameters:

timeout (int, optional) – time in seconds to connection timeout. Defaults to 15.

Raises:

HTTPError – An error occurred while trying to make a connection.

Returns:

a csv of callsigns and last upload date

Return type:

csv

static upload_logbook(file, timeout: int = 120)

Given a .tq5 or .tq8, uploads it to LOTW.

Note

The “handing this a file” part of this needs to be implemented.

Parameters:

• file (file) – file to be uploaded

• timeout (int, optional) – time in seconds to connection timeout. Defaults to 120.

Raises:

• UploadFailure – The upload was rejected by LotW.

• HTTPError – An error occurred while trying to make a connection.

Returns:

Return message from LOTW on file upload.

Return type:

str

exception qspylib.lotw.RetrievalFailure(message='Failed to retrieve information. Confirm log-in                  credentials are correct.')

Bases: Exception

A failure to retrieve information from LOTW. This can be due to a connection error, or a bad response from the server.

exception qspylib.lotw.UploadError(message='Failed to upload file.')

Bases: Exception

A failure to upload a file to LOTW. This is due to a file being rejected by LOTW. The error message from LOTW is provided in the exception.

qspylib.qrz module

Functions and classes related to querying the QRZ APIs.

exception qspylib.qrz.QRZInvalidSessionError(message='Got no session key back. This session is                invalid.')

Bases: Exception

Error for when session is invalid.

class qspylib.qrz.QRZLogbookClient(key: str, timeout: int = 15)

Bases: object

API wrapper for accessing QRZ Logbook data.

check_status(list_logids: list = None) → dict[str, list[str]]

Gets the status of a logbook based on the API Key supplied to the Client. This status can include information about the logbook like the owner, logbook name, DXCC count, confirmed QSOs, start and end date, etc.

Parameters:

list_logids (list, optional) – A list of LOGIDs. Defaults to None.

Raises:

• HTTPError – An error occurred trying to make a connection.

• QRZLogbookError – An error occurred trying to interact with the logbook.

Returns:

A dict containing the returned status information from QRZ. Keys correspond to the name given to the field by QRZ’s API, e.g. DXCC count is ‘DXCC_COUNT’, confirmed is ‘CONFIRMED’, etc.

Return type:

dict[str, list[str]]

static convert_logids_to_list(logids: str) → list

When QRZ returns a list of logids, they are returned as a weird, gross string. This parses that and returns an actual list of the integers.

Parameters:

logids (str) – list of logids as generated by QRZ’s API

Returns:

actual list of integer logids

Return type:

list

delete_record(list_logids: list) → dict[str, list[str]]

Deletes log records from the logbook corresponding to the Client’s API Key.

Note

This is permenant, and cannot be undone.

Parameters:

list_logids (list) – A list of logid values to delete from the logbook.

Raises:

• HTTPError – An error occurred trying to make a connection.

• QRZLogbookError – An error occurred trying to interact with the logbook.

Returns:

A dict containing the returned information from QRZ. This should include the RESULT, COUNT of records deleted, and LOGIDs not found, if any.

Return type:

dict[str, list[str]]

fetch_logbook(option: str = None) → Logbook

Fetches the logbook corresponding to the Client’s API Key.

Note

If too many records are fetched at once, parsing will fail to complete and not all response keys will be returned. To prevent this, you should fetch the logbook in chunks, using the highest logid to start fetching the next chunk. See fetch_logbook_paged, unless that hasn’t been implemented yet; then use this, and suffer.

Parameters:

option (str, optional) – Optional parameters as specified by QRZ, like “MODE:SSB,CALL:W1AW”. This should be a comma separated string. Defaults to None.

Raises:

• HTTPError – An error occurred trying to make a connection.

• QRZLogbookError – An error occurred trying to interact with the logbook.

Returns:

A logbook containing the user’s QSOs.

Return type:

qspylib.logbook.Logbook

insert_record(adif: QSO, option: str = None) → list

Insert records into the logbook corresponding to the Client’s API Key.

Parameters:

• adif (adif_io.QSO) – adif_io.QSO object to insert into the logbook.

• option (str, optional) – REPLACE To automatically overwrite any existing QSOs. Defaults to None.

Raises:

• QRZLogbookError – The logbook API returned an error, and the reason is included.

• QRZLogbookError – An unknown condition was reached with the logbook API.

• HTTPError – An error occurred trying to make a connection.

Returns:

list of logids for records that were inserted or replaced.

Return type:

list

exception qspylib.qrz.QRZLogbookError(message='An error occurred interacting with the Logbook.')

Bases: Exception

Error for when a logbook error occurs.

class qspylib.qrz.QRZXMLClient(username: str = None, password: str = None, agent: str = None, timeout: int = 15)

Bases: object

A wrapper for the QRZ XML interface. This functionality requires being logged in and maintaining a session.

lookup_callsign(callsign: str) → OrderedDict[str, Any]

Looks up a callsign in the QRZ database.

Parameters:

callsign (str) – Callsign to lookup.

Raises:

• HTTPError – An error occurred trying to make a connection.

• QRZInvalidSessionError – An error occurred trying to instantiate a session.

Returns:

Data on the callsign looked up, organized as

a dict with each returned field as a key.

Return type:

OrderedDict[str, Any]

lookup_dxcc(dxcc: str) → OrderedDict[str, Any]

Looks up a DXCC by prefix or DXCC number.

Parameters:

dxcc (str) – DXCC or prefix to lookup. Note that callsigns must be uppercase, or QRZ won’t recognize it.

Raises:

• HTTPError – An error occurred trying to make a connection.

• QRZInvalidSessionError – An error occurred trying to instantiate a session.

Returns:

Data on the callsign looked up, organized as a dict with each returned field as a key. This data includes DXCC, CC, name, continent, ituzone, cqzone, timezone, lat, lon, & notes

Return type:

OrderedDict[str, Any]

qspylib.test_pytest module

A PyTest module for confirming functionality works None of these should be called; these are automatically ran by PyTest when pushes are made to the repo, or when the user runs pytest in the root directory of the project.

qspylib.test_pytest.test_adding_and_removing()

Test adding and removing a QSO

qspylib.test_pytest.test_bad_login_dxcc()

Test fetching DXCC credits with a bad login

qspylib.test_pytest.test_bad_login_fetch()

Test fetching a logbook with a bad login

qspylib.test_pytest.test_equality_of_qso()

Tests equality of qspylib.logbook.QSOs functions as expected

qspylib.test_pytest.test_generating_a_logbook()

Test generating a qspylib.logbook.Logbook

qspylib.test_pytest.test_get_user_data()

Test getting the data of a user, and verify it’s what we expect

qspylib.test_pytest.test_inequality_of_qso()

Tests inequality of qspylib.logbook.QSOs functions as expected

qspylib.test_pytest.test_logbook_attributes_match()

Confirm that the Logbook’s stored QSO matches what we read from text

qspylib.test_pytest.test_pull_a_call_from_ag_dated()

Test grabbing a call from the AG dated list

qspylib.test_pytest.test_pull_a_call_from_last_upload()

Test pulling a known call from the last upload

qspylib.test_pytest.test_pull_a_known_ag_call()

Test grabbing a call we know should be in the AG list

qspylib.test_pytest.test_pull_a_known_call_from_total_members()

Test grabbing a call that should be in the list of total members

qspylib.test_pytest.test_pull_a_known_nonag_call()

Test grabbing a call we know shouldn’t be in the AG list

qspylib.test_pytest.test_pull_a_missing_call_from_total_members()

Test grabbing a call that should be missing from the list of total members

qspylib.test_pytest.test_qrz_logbook_with_invalid_key()

Test a bad login to the QRZ Logbook API.

qspylib.test_pytest.test_qrz_xml_with_invalid_login()

Test a bad login to the QRZ XML API.

qspylib.test_pytest.test_verify_a_bad_eqsl()

Test verifying a known bad eqsl

qspylib.test_pytest.test_verify_a_good_eqsl()

Test verifying a known good eqsl

Module contents