update documentation pending 1.0.0

.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 }}

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,12 @@ 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 incredibly unpolished -- at present, you can fetch inboxes and outboxes, get AG lists, get member lists, get last upload data for users, and verify an eQSL.
+* The QRZ module is mostly done, but has a few holes; for logs, we currently support fetching logbooks, checking logbook statuses, 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.
 
 ## How do I use it?
 
@@ -60,8 +60,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.

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,90 @@ 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.
+
+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': '[email protected]', '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'

pyproject.toml

@@ -17,7 +17,7 @@ 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"]
 classifiers = [
     "Programming Language :: Python :: 3.9",
 	"Programming Language :: Python :: 3.10",
@@ -26,7 +26,7 @@ classifiers = [
 	"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"
+    "Development Status :: 5 - Production/Stable"
 ]
 
 [project.urls]

src/qspylib/_version.py

@@ -1,3 +1,3 @@
 """unified version string"""
 
-__version__ = "1.0.0a3"
+__version__ = "1.0.0"