Metadata-Version: 2.4
Name: PyHamCTY
Version: 1.0.1
Summary: Read and search hamradio country data for callsigns in a CTY database
Author-email: "Andreas Schawo, DF1ASC" <andreas@schawo.de>
Project-URL: Homepage, https://codeberg.org/dragoncode/pyhamcty#readme
Project-URL: Bug Tracker, https://codeberg.org/dragoncode/pyhamcty/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Ham Radio
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: requests~=2.34
Provides-Extra: bench
Requires-Dist: notctyparser~=26.8; extra == "bench"
Provides-Extra: dev
Requires-Dist: coverage>=7.16; extra == "dev"
Requires-Dist: ruff~=0.16; extra == "dev"
Dynamic: license-file

PyHamCTY
=========

[![PyPI Package](https://img.shields.io/pypi/v/pyhamcty?color=%2334D058&label=PyPI%20Package)](https://pypi.org/project/pyhamcty)
![Coverage](https://img.shields.io/badge/coverage-86%25-%2334D058?logo=umbrel)
[![Python versions](https://img.shields.io/pypi/pyversions/pyhamcty.svg?color=%2334D058&label=Python)](https://pypi.org/project/pyhamcty)

Author: Andreas Schawo, DF1ASC ([HamQTH](http://www.hamqth.com/DF1ASC), [eQSL](http://www.eqsl.cc/Member.cfm?DF1ASC))

This package provides reading [country databases](https://www.country-files.com/) (CTY files) and searching callsign
related information.

Also, it provides downloading of the most recent version. Per default, it acts with CTY files but BigCTY can also be
loaded.

Until October 2026 this library was part of [DragonLog](https://codeberg.org/dragoncode/DragonLog),
but I decided to place it as a separate project and did some enhancements.

Since May 2026 I also ported the cty module to Rust in [hamcty](https://codeberg.org/dragoncode/hamcty).
This speeds up even more thus I'm looking forward to generate Python bindings for it.


Remarks
-------

The longitude in the result (`lon` field in `Country`) is as commonly used
from 0° to 180° to the East and from 0° to -180° to the West.


Usage
-----

After installing the package you can simply do

```python
import pyhamcty

cty = pyhamcty.CountryData()  # Loads integrated CTY DB
res = cty.country('DA2CDE')
print(res.code, res.continent, res.cq, res.itu)
```

If you want to load a more recent CTY do

```python
import pyhamcty

pyhamcty.load_current('cty.csv')
cty = pyhamcty.CountryData('cty.csv')
```

If faster loading time is critical you can dump a `CountryData` to pickle file and restore it from there

```python
import os
import pyhamcty

if os.path.isfile('cty.pckl'):
    cty = pyhamcty.load_pickle('cty.pckl')
else:
    cty = pyhamcty.CountryData('cty.csv')
    pyhamcty.dump_pickle(cty, 'cty.pckl')
```

You also can run it from console to do a simple search. Without callsign it produces the version entity.

    pysearch_cty DA2CDE

or to download the most recent CTY file and use it (`-c` for CTY, `-b` for BigCTY)

    pysearch_cty -c cty.csv
    pysearch_cty DA2CDE cty.csv

Performance
-----------

I recently stumbled upon `ctyparser` and `notctyparser` as I examined [Not1MM](https://github.com/mbridak/not1mm).
So I was curious how both will compare.
I measured the memory footprint, loading time and searching with 20 callsigns 100 times.

The data for the bench is the same version VER20260603 (3DA, Kingdom of Eswatini).
I tested the correct country resolution with "LU1DD", "LU1ZB", "LU1ZA", "LU1ZAW".

_Remark:_ `ctyparser` and `notctyparser` both do not provide a complete callsign resolution, so I took the function from
Not1MM

The first value is for CTY, the second for BigCTY.

| Lib      | pyhamcty (.csv)     | pyhamcty (.pckl)   | [not]ctyparser (.dat) | [not]ctyparser (.json) |
|----------|---------------------|--------------------|-----------------------|------------------------|
| Size     | 102.3 / 293.7 kB    | 624.4 kB / 2 MB    | 99.8 / 339.9 kB       | 1.1 / 4.8 MB           |
| Memory   | 149.4 / 474.8 kB    | 153.8 / 481.9 kB   | 202.8 / 938.8 kB      | same as .dat           |
| Load     | 39.132 / 117.4 ms   | 14.239 / 44.081 ms | 63.72 / 267.932 ms    | 20.296 / 92.563 ms     |
| Search   | 311.125 / 501.82 ms | same as .csv       | 5.041 / 24.489 s      | same as .dat           |
| Per call | 0.16 / 0.25 ms      | same as .csv       | 2.52 / 12.2 ms        | same as .dat           |


Copyright
---------

&copy; 2026 by Andreas Schawo is licensed under [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)

except the included CTY database files (see corresponding copyright) and
some code in bench_notctyparser.py (see code comments).
