From b94adf438a1c53e8e1714f6da0b87894624aa441 Mon Sep 17 00:00:00 2001 From: Jacob Humble Date: Sat, 23 Nov 2024 22:48:52 -0600 Subject: [PATCH] update documentation pending 1.0.0 --- .github/workflows/pylint.yml | 2 +- README.md | 16 +++--- docs/source/examples.rst | 102 ++++++++++++++++++++++++++++++++--- pyproject.toml | 4 +- src/qspylib/_version.py | 2 +- 5 files changed, 106 insertions(+), 20 deletions(-) diff --git a/.github/workflows/pylint.yml b/.github/workflows/pylint.yml index 7d79401..caa70c4 100644 --- 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 index 5fe1aa9..056309b 100644 --- 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,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. diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 0dd846f..120d386 100644 --- 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,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 \ No newline at end of file + 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) + ... + 20231105 1228 TE3T MFSK Y 40M 20240120 Y EM17nt Y E +01 FT4 100.0000 + + 20231105 1230 TE5T MFSK Y 40M 20241015 Y EM12qt Y E -08 FT4 + + >>>str(eqsl_inbox.adi[0]) + '20231105 1228 TE3T MFSK Y 40M 20240120 Y EM17nt Y E +01 FT4 100.0000 \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\r\n\r\n\r\n\r\n\r\n\r\n Error - Result: QSO not on file\r\n \r\n \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': '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' \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 0036043..e333157 100644 --- a/pyproject.toml +++ b/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] diff --git a/src/qspylib/_version.py b/src/qspylib/_version.py index bf89ba7..71bc9da 100644 --- 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"