Initial Stable - Update documentation and perform final bug fixes (#9)

* Added Gitleaks action scan * Added definite 3.13 support * Added documentation * Added wrappers to our wrappers, so that you need less parameters * Implemented eQSL graphic retrieval * Added some logbook.QSO converters to shoot around with types * Added QRZ insert_record * Fixed delete_record * Fixed check_status * Added some QRZ error tests --------- Co-authored-by: Jacob Humble <contact@jacobhumble.com>
JayToTheAy · Nov 24, 2024 · 6e754e8 · 6e754e8
1 parent a8b0bc1
commit 6e754e8
Show file tree

Hide file tree

Showing 14 changed files with 498 additions and 161 deletions.
diff --git a/.github/workflows/gitleaks.yml b/.github/workflows/gitleaks.yml
@@ -0,0 +1,19 @@
+name: gitleaks
+on:
+  pull_request:
+  push:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * *" # run once a day at 4 AM
+jobs:
+  scan:
+    name: gitleaks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
diff --git a/.github/workflows/pylint.yml b/.github/workflows/pylint.yml
@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 QSPyLib is a bundle of API wrappers for various amateur radio-related sites, including QRZ, LOTW, eQSL, and ClubLog.
 
-It is currently in development and should be considered unstable version-to-version while the version number is still 0.x.x.
+QSPyLib is in active development; that said, major version numbers should maintain API stability. If you need absolute stability of the API, fix your version against the major.
 
 Issues and pull requests are welcome, and should be made on the [GitHub repository](https://github.com/jaytotheay/qspy).
 
@@ -32,12 +32,14 @@ This will generate a .whl and tar.gz, which you can then install locally.
 
 ## What works right now?
 
-As of v0.0.1:
+As of v1.0.0:
 
-* The LotW module is, in theory, finished -- no doubt something will come up about how it's not actually practical and needs more work.
-* The eQSL module has most of the functionality of eQSL's API, but is incredibly unpolished and needs more work.
-* The QRZ module exists; the Logbook API is currently only supported for FETCH operations, and the XML Interface is not supported yet.
-* The ClubLog module is on-hold pending the ready-status of the other modules.
+* The LotW module is, in theory, finished -- you can download QSOs in bulk or by criteria, check DXCC credit, get a list of users and their date of last upload, and upload a log.
+* The eQSL module has most of the functionality of eQSL's API, but is a bit unpolished -- at present, you can fetch inboxes and outboxes, get AG lists, get member lists, get last upload data for users, verify an eQSL, and retrieve the eQSL card graphic for a QSL.
+* The QRZ module is done; for logs, we support fetching logbooks, checking logbook statuses, and inserting and deleting records. For the XML API, we support looking up a callsign's data and looking up a DXCC's data.
+* The ClubLog module only supports grabbing logbooks from ClubLog at the moment.
+
+Everything has been tested to work when done "correctly" and simply; no doubt some edge case will pop up, or some failure state won't throw a good error. Please open an issue for *any* problems you come across, no matter how minor, even if it's just an exception that isn't descriptive.
 
 ## How do I use it?
 
@@ -60,8 +62,8 @@ Other functions of APIs are generally available, like checking if an eQSL is ver
 
 ```py
 from qspylib import eqsl
-confirmed, raw_result = eqsl.verify_eqsl('N5UP', 'TEST', '160m', 'SSB', '01/01/2000')
+confirmed, raw_result = eqsl.eQSLClient.verify_eqsl('N5UP', 'TEST', '160m', 'SSB', '01/01/2000')
 ```
-This will return a tuple; here, `confirmed` will be False, since this QSO is not verified on eQSL, and `raw_result` will contain any extra information eQSL provides, for instance, if it's Authenticity Guaranteed.
+This will return a tuple; here, `confirmed` will be False, since this QSO is not verified on eQSL, and `raw_result` will contain any extra information eQSL provides, for instance, if it's Authenticity Guaranteed. Note that verify_eqsl is a static method of the eQSLClient class, and can be called either from an eQSLClient object, or directly from the class.
 
 Modules, functions, and classes are documented in-code via docstrings, and you can learn more by reading those docstrings; you can also read the [Read the Docs](http://qspylib.readthedocs.io/) listings for a visually pleasing guide on what the docstrings say.
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -25,10 +25,10 @@ Pulling a LotW Logbook and Printing QSLs since Last Login, Using .adi Property
 .. code-block:: python
 
 	"""This example demonstrates logging into LOTW for a user 'CA7LSIGN' and fetching their QSLs with default parameters. By default, this will only return QSLs received since the last time a logbook was fetched from LOTW.
-	
+
 	This example also demonstrates using the .adi property of the Logbook; this property contains a parsed dictionary of the entire .adi log as received from LotW, and you can reference any present fields as dictionary keys.
-	""" 
-	
+	"""
+
 	>>> import qspylib
 	>>> LOTWSession = qspylib.lotw.LOTWClient("CA7LSIGN", "password")
 	>>> lotw_logbook = LOTWSession.fetch_logbook()
@@ -42,17 +42,17 @@ Pulling a LotW Logbook and Printing QSLs since Last Login, Using .adi Property
 	'TE5T'
 	>>> lotw_logbook.adi[0]["BAND"]
 	'20M'
-	
+
 Pulling a LotW Logbook and Printing QSOs since Last Login, Using .log Property
 *********************************************************************************
 
 .. code-block:: python
 
-	"""This example demonstrates logging into LOTW for a user 'CA7LSIGN' and fetching their QSOs since 2024-10-01, and then printing them out and grabbing the QSL index.
-	
+	"""This example demonstrates logging into LOTW for a user 'CA7LSIGN' and fetching their QSOs since 2024-10-01, and then printing them out.
+
 	This example also demonstrates using the .log property of the Logbook; this property contains a list of contacts, and each contains only very limited information about each QSO (the info as seen here.) The QSL property will "unify" the QSL fields as present in ClubLog, QRZ, LoTW, and eQSL, so it is handy for comparing confirmations between sources.
 	"""
-	
+
 	>>> import qspylib
 	>>> LOTWSession = qspylib.lotw.LOTWClient('CA7LSIGN', 'password')
 	>>> lotw_logbook = LOTWSession.fetch_logbook(qso_qsl='no', qso_qsorxsince='2024-10-01')
@@ -69,4 +69,114 @@ Pulling a LotW Logbook and Printing QSOs since Last Login, Using .log Property
 
 	CALL: TE5T BAND: 40M MODE: FT8 DATE: 20241003 TIME: 003700 QSL: N
 
-	CALL: TE6T BAND: 20M MODE: FT8 DATE: 20241003 TIME: 004500 QSL: N
+	CALL: TE6T BAND: 20M MODE: FT8 DATE: 20241003 TIME: 004500 QSL: N
+
+Note that you can also use the `fetch_qsos` method to fetch all QSOs; this has a simpler optional parameter set, but takes in a datetime object for date parameters. It also defaults to fetching as much information as LOTW will return about a QSO.
+
+.. code-block:: python
+
+	>>> import qspylib, datetime
+	>>> LOTWSession = qspylib.lotw.LOTWClient('CA7LSIGN', 'password')
+	>>> qsosince_datetime = datetime.datetime(2024, 10, 1)
+	>>> lotw_logbook = LOTWSession.fetch_qsos(qsorxsince=qsosince_datetime)
+	>>> for contact in lotw_logbook.log:
+	...     print(contact)
+	...
+	CALL: TE1T BAND: 12M MODE: FT8 DATE: 20241003 TIME: 025300 QSL: Y
+
+	CALL: TE2T BAND: 12M MODE: FT8 DATE: 20241003 TIME: 025500 QSL: Y
+
+	CALL: TE3T BAND: 20M MODE: FT8 DATE: 20241003 TIME: 012100 QSL: Y
+
+	CALL: TE4T BAND: 12M MODE: FT8 DATE: 20241003 TIME: 012900 QSL: N
+
+	CALL: TE5T BAND: 40M MODE: FT8 DATE: 20241003 TIME: 003700 QSL: N
+
+	CALL: TE6T BAND: 20M MODE: FT8 DATE: 20241003 TIME: 004500 QSL: N
+
+Pulling the inbox from eQSL, using .adi Property
+************************************************
+Pulling information from a user's eQSL inbox is relatively easy with qspylib. The `fetch_inbox` method will return a Logbook object with the inbox contents.
+The .adi portion of the Logbook object will contain all adif fields received from eQSL, and you can reference any present fields as dictionary keys.
+Note that the eQSL divides a logbook into an inbox, and an outbox; the inbox is the QSOs that the user has received, sent for confirmation by other users.
+
+.. code-block:: python
+
+	"""This example demonstrates logging into eQSL for a user 'CA7LSIGN' and fetching their inbox since 2024-01-01 00:00, and then printing them out.
+
+	This example also demonstrates using the .adi property of the Logbook; this property contains a dictionary of the entire .adi log as received from eQSL,
+	where each contact is one record. All the information received from eQSL will be present in the .adi portion of the Logbook object, unlike the .log portion.
+	"""
+
+	>>> import qspylib
+	>>> eQSLSession = qspylib.eqsl.eQSLClient('CA7LSIGN', 'password')
+	>>> eqsl_inbox = eQSLSession.fetch_inbox(rcvd_since='202401010000')
+	>>> for contact in eqsl_inbox.adi:
+	...     print(contact)
+	...
+	<QSO_DATE:8>20231105 <TIME_ON:4>1228 <CALL:5>TE3T <MODE:4>MFSK <APP_EQSL_AG:1>Y <BAND:3>40M <EQSL_QSLRDATE:8>20240120 <EQSL_QSL_RCVD:1>Y <GRIDSQUARE:6>EM17nt <QSL_SENT:1>Y <QSL_SENT_VIA:1>E <RST_SENT:3>+01 <SUBMODE:3>FT4 <TX_PWR:8>100.0000 <EOR>
+
+	<QSO_DATE:8>20231105 <TIME_ON:4>1230 <CALL:4>TE5T <MODE:4>MFSK <APP_EQSL_AG:1>Y <BAND:3>40M <EQSL_QSLRDATE:8>20241015 <EQSL_QSL_RCVD:1>Y <GRIDSQUARE:6>EM12qt <QSL_SENT:1>Y <QSL_SENT_VIA:1>E <RST_SENT:3>-08 <SUBMODE:3>FT4 <EOR>
+
+	>>>str(eqsl_inbox.adi[0])
+	'<QSO_DATE:8>20231105 <TIME_ON:4>1228 <CALL:5>TE3T <MODE:4>MFSK <APP_EQSL_AG:1>Y <BAND:3>40M <EQSL_QSLRDATE:8>20240120 <EQSL_QSL_RCVD:1>Y <GRIDSQUARE:6>EM17nt <QSL_SENT:1>Y <QSL_SENT_VIA:1>E <RST_SENT:3>+01 <SUBMODE:3>FT4 <TX_PWR:8>100.0000 <EOR>\n'
+	>>>str(eqsl_inbox.adi[0]['CALL'])
+	'TE3T'
+	>>>len(eqsl_inbox.adi)
+	2
+
+Verify a QSL with eQSL
+**********************
+eQSL provides for confirming that a QSL is confirmed -- if it was confirmed on eQSL. This can be done by *any* user, not just a logged in one, given they have the proper information.
+
+.. code-block:: python
+
+	"""This example demonstrates confirming an eQSL took place with eQSL."""
+
+	>>> from qspylib import eqsl
+	>>> confirmed, raw_result = eqsl.eQSLClient.verify_eqsl('N5UP', 'TEST', '160m', 'SSB', '01/01/2000')
+	>>> confirmed
+	False
+	>>> raw_result
+	'\r\n<HTML>\r\n<HEAD></HEAD>\r\n<BODY>\r\n\r\n\r\n\r\n  Error - Result: QSO not on file\r\n  </BODY>\r\n  </HTML>\r\n  '
+
+In current versions of qspylib, parsing raw_result for additional information, such as authenticity guaranteed status or the error cause, is left as an exercise for the reader.
+
+Retrieving an eQSL Graphic
+**************************
+eQSL provides for retrieving the graphic for the digital QSL card corresponding to a QSO. Note that they request you only do at most, six requests per minute.
+
+.. code-block:: python
+
+	"This example demonstrates retrieving an eQSL graphic for a given QSO and displaying it using PIL."
+
+	>>> import qspylib
+	>>> from datetime import datetime
+	>>> from PIL import Image
+	>>> eqsl_client = qspylib.eqsl.eQSLClient("CAL7SIGN", "notarealpassword")
+	>>> inbox = eqsl_client.fetch_inbox_qsls()
+	>>> str(inbox.adi[12])
+	'<QSO_DATE:8>20230101 <TIME_ON:4>0730 <CALL:5>TE5T <MODE:3>FT8 <APP_EQSL_AG:1>Y <BAND:3>20M <EQSL_QSLRDATE:8>20230101 <EQSL_QSL_RCVD:1>Y <GRIDSQUARE:6>EM12em <QSL_SENT:1>Y <QSL_SENT_VIA:1>E <RST_SENT:3>+00 <EOR>\n'
+	>>> qso_datetime = datetime(2023, 1, 1, 7, 30)
+	>>> image_data = eqsl_client.retrieve_graphic("te5t", qso_datetime, "20m", "FT8")
+	>>> image_data
+	<_io.BytesIO object at 0x0000000000000000>
+	>>> image = Image.open(image_data)
+	>>> image
+	<PIL.PngImagePlugin.PngImageFile image mode=RGB size=528x336 at 0x0000000000000000>
+	>>> image.show() # this will open the actual image file, showing you the image.
+
+Looking up a callsign on QRZ
+****************************
+QRZ allows an authenticated user to lookup certain information about a QRZ user. This information will be returned by qspylib as a dictionary that can be parsed, sharing a structure with the XML tree returned by QRZ.
+.. code-block:: python
+
+	"""This example demonstrates grabbing information about a callsign from QRZ's XML API."""
+
+	>>> from qspylib import qrz
+	>>> QRZXMLSession = qrz.QRZXMLClient('TE5T', 'password', agent='sample_program/0.0.1')
+	>>> info = QRZXMLSession.lookup_callsign('aa7bq')
+	>>> info
+	{'QRZDatabase': {'@version': '1.34', '@xmlns': 'http://xmldata.qrz.com', 'Callsign': {'call': 'AA7BQ', 'aliases': 'N6UFT,AA7BQ/DL1,KJ6RK,AA7BQ/HR6', 'dxcc': '291', 'attn': 'AA7BQ', 'fname': 'FRED L', 'name': 'LLOYD', 'addr1': '24 W. Camelback Rd, STE A-488', 'addr2': 'Phoenix', 'state': 'AZ', 'zip': '85013', 'country': 'United States', 'lat': '33.509665', 'lon': '-112.074142', 'grid': 'DM33xm', 'county': 'Maricopa', 'ccode': '271', 'fips': '04013', 'land': 'United States', 'efdate': '2022-04-29', 'expdate': '2030-01-20', 'class': 'E', 'codes': 'HAI', 'qslmgr': 'via QRZ', 'email': 'aa7bq@qrz.com', 'u_views': '345756', 'bio': '12804', 'biodate': '2023-02-17 17:37:29', 'image': 'https://cdn-xml.qrz.com/q/aa7bq/fred1962.jpg', 'imageinfo': '636:800:90801', 'moddate': '2022-10-09 17:32:38', 'MSA': '6200', 'AreaCode': '602', 'TimeZone': 'Mountain', 'GMTOffset': '-7', 'DST': 'N', 'eqsl': '0', 'mqsl': '0', 'cqzone': '3', 'ituzone': '6', 'born': '1953', 'lotw': '0', 'user': 'AA7BQ', 'geoloc': 'user', 'name_fmt': 'FRED L LLOYD'}, 'Session': {'Key': 'nicetrykiddo', 'Count': '539', 'SubExp': 'Mon Sep 15 02:38:30 2025', 'GMTime': 'Sun Nov 24 04:22:11 2024', 'Remark': 'cpu: 0.018s'}}}
+	>>> info['QRZDatabase']['Callsign']['TimeZone']
+	'Mountain'
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -26,16 +26,16 @@ QSPyLib
    :alt: PyPI - License
 
 
-``qsyplib`` is a bundle of API wrappers for various amateur radio-related websites, including QRZ, LOTW, eQSL, and ClubLog.
+``qsyplib`` is a bundle of API wrappers for various amateur radio-related sites, including QRZ, LOTW, eQSL, and ClubLog.
 
-It is currently in development and should be considered unstable version-to-version while the version number is still 0.x.x.
+QSPyLib is in active development; that said, major version numbers should maintain API stability. If you need absolute stability of the API, fix your version against the major.
 
 Issues and pull requests are welcome, and should be made on the [GitHub repository](https://github.com/JayToTheAy/QSPy).
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
-   
+
    modules
    qspylib
    examples

diff --git a/pyproject.toml b/pyproject.toml
@@ -17,20 +17,24 @@ authors = [
 ]
 description = "A set of API wrappers for different amateur radio websites, including LotW, QRZ, eQSL, and ClubLog"
 readme = "README.md"
-keywords = ["QRZ", "LOTW", "eQSL", "API", "amateur radio"]
+keywords = ["QRZ", "LOTW", "eQSL", "ClubLog", "API", "amateur radio", "ham radio"]
 classifiers = [
-    "Programming Language :: Python :: 3.9",
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Topic :: Communications :: Ham Radio",
+  "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
 	"Programming Language :: Python :: 3.10",
 	"Programming Language :: Python :: 3.11",
 	"Programming Language :: Python :: 3.12",
 	"Programming Language :: Python :: 3.13",
-    "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
-    "Operating System :: OS Independent",
-    "Development Status :: 2 - Pre-Alpha"
+  "Operating System :: OS Independent",
 ]
 
 [project.urls]
 Homepage = "https://github.com/JayToTheAy/QSPy"
+Documentation = "https://qspylib.readthedocs.io/en/"
 Issues = "https://github.com/JayToTheAy/QSPy/issues"
 
 [tool.hatch.version]

diff --git a/requirements.txt b/requirements.txt
diff --git a/src/qspylib/_version.py b/src/qspylib/_version.py
@@ -1,3 +1,3 @@
 """unified version string"""
 
-__version__ = "1.0.0a3"
+__version__ = "1.0.0"