wwvb 4.1.0a0__tar.gz → 5.0.0__tar.gz

wwvb-5.0.0/.coveragerc

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only
+[report]
+exclude_also =
+    def __repr__
+    if self.debug:
+    if settings.DEBUG
+    raise AssertionError
+    raise NotImplementedError
+    if 0:
+    if __name__ == .__main__.:
+    if TYPE_CHECKING:
+    class .*\bProtocol\):
+    @(abc\.)?abstractmethod

wwvb-5.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: 2022-2024 Jeff Epler
+#
+# SPDX-License-Identifier: CC0-1.0
+
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: "53 3 * * 5"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ python ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Dependencies (python)
+        run: pip3 install -r requirements-dev.txt
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-and-quality
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

wwvb-5.0.0/.github/workflows/cron.yml

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
+#
+# SPDX-License-Identifier: CC0-1.0
+
+name: Update DUT1 data
+
+on:
+  schedule:
+    - cron: '0 10 2 * *'
+  workflow_dispatch:
+
+jobs:
+  update-dut1:
+    runs-on: ubuntu-20.04
+    if: startswith(github.repository, 'jepler/')
+    steps:
+
+    - name: Dump GitHub context
+      env:
+        GITHUB_CONTEXT: ${{ toJson(github) }}
+      run: echo "$GITHUB_CONTEXT"
+
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install dependencies
+      run: pip install -e .
+
+    - name: Update DUT1 data
+      run: python -m wwvb.updateiers --dist
+
+    - name: Test
+      run: python -munittest
+
+    - name: Commit updates
+      run: |
+        git config user.name "${GITHUB_ACTOR} (github actions cron)"
+        git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+        git remote set-url --push origin https://${GITHUB_ACTOR}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+        if git commit -m"update iersdata" src/wwvb/iersdata.json; then git push origin HEAD:main; fi

{wwvb-4.1.0a0 → wwvb-5.0.0}/.github/workflows/release.yml

@@ -1,8 +1,8 @@
-# SPDX-FileCopyrightText: 2021 Jeff Epler
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
 #
 # SPDX-License-Identifier: CC0-1.0
 
-name: Release leapseconddata
+name: Release wwvbgen
 
 on:
   release:
@@ -11,7 +11,7 @@ on:
 jobs:
   release:
 
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     steps:
     - name: Dump GitHub context
       env:
@@ -23,10 +23,15 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: "3.x"
+        python-version: 3.9
 
     - name: Install deps
-      run: python -mpip install -r requirements-dev.txt
+      run: |
+        python -mpip install wheel
+        python -mpip install -r requirements-dev.txt
+
+    - name: Test
+      run: make coverage
 
     - name: Build release
       run: python -mbuild

{wwvb-4.1.0a0 → wwvb-5.0.0}/.github/workflows/test.yml

@@ -1,8 +1,8 @@
-# SPDX-FileCopyrightText: 2021 Jeff Epler
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
 #
 # SPDX-License-Identifier: CC0-1.0
 
-name: Test leapseconddata
+name: Test wwvbgen
 
 on:
   push:
@@ -19,7 +19,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
+        python-version: '3.12'
 
     - uses: actions/checkout@v4
 
@@ -31,6 +31,7 @@ jobs:
 
   test:
     strategy:
+      fail-fast: false
       matrix:
         python-version:
         - '3.9'
@@ -38,7 +39,6 @@ jobs:
         - '3.11'
         - '3.12'
         - '3.13.0-alpha.0 - 3.13'
-        - 'pypy-3.9'
         os-version:
         - 'ubuntu-latest'
         include:
@@ -46,9 +46,8 @@ jobs:
             python-version: '3.x'
           - os-version: 'windows-latest'
             python-version: '3.x'
-
-    env:
-      PYTHON: ${{ matrix.python-version }}
+          - os-version: 'ubuntu-latest'
+            python-version: 'pypy-3.10'
 
     runs-on: ${{ matrix.os-version }}
     steps:
@@ -60,17 +59,36 @@ jobs:
         python-version: ${{ matrix.python-version }}
 
     - name: Install deps
-      run: python -mpip install -r requirements-dev.txt
+      run: |
+        python -mpip install wheel
+        python -mpip install -r requirements-dev.txt
 
     - name: Check stubs
-      if: (startsWith(matrix.python-version, '3.12') && startswith(matrix.os-version, 'ubuntu-'))
-      run: make mypy
+      if: (! startsWith(matrix.python-version, 'pypy-'))
+      run: make mypy PYTHON=python
+
+    - name: Coverage
+      run: make coverage PYTHON=python
 
-    - name: Test
-      run: python -mcoverage run --branch -m unittest testleapseconddata.py && python -mcoverage report --fail-under=100 && python -mcoverage xml
+    - name: Test installed version
+      run: make test_venv PYTHON=python
+
+    - name: Upload Coverage as artifact
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage for ${{ matrix.python-version }} on ${{ matrix.os-version }}
+        path: coverage.xml
 
   pre-commit:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: pre-commit/action@v3.0.1
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - name: pre-commit
+      run: pip install pre-commit && pre-commit run --all

wwvb-5.0.0/.gitignore

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2021-2024 Jeff Epler
+#
+# SPDX-License-Identifier: CC0-1.0
+
+*,cover
+*.egg-info
+/.coverage*
+/.reuse
+/build
+/_build
+/coverage.xml
+/dist
+/finals2000A.all.csv
+/htmlcov
+/src/wwvb/__version__.py
+__pycache__

{wwvb-4.1.0a0 → wwvb-5.0.0}/.pre-commit-config.yaml

@@ -1,4 +1,5 @@
 # SPDX-FileCopyrightText: 2020 Diego Elio Pettenò
+# SPDX-FileCopyrightText: 2020-2024 Jeff Epler
 #
 # SPDX-License-Identifier: Unlicense
 
@@ -7,20 +8,20 @@ default_language_version:
 
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.6.0
+  rev: v5.0.0
   hooks:
   -   id: check-yaml
   -   id: end-of-file-fixer
       exclude: tests
   -   id: trailing-whitespace
-      exclude: tests
+      exclude: test/wwvbgen_testcases
 - repo: https://github.com/fsfe/reuse-tool
-  rev: v3.0.2
+  rev: v4.0.3
   hooks:
   - id: reuse
 - repo: https://github.com/astral-sh/ruff-pre-commit
   # Ruff version.
-  rev: v0.4.3
+  rev: v0.6.9
   hooks:
     # Run the linter.
     - id: ruff

wwvb-5.0.0/LICENSES/Apache-2.0.txt

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

wwvb-5.0.0/LICENSES/Unlicense.txt

@@ -0,0 +1,22 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or distribute
+this software, either in source code form or as a compiled binary, for any
+purpose, commercial or non-commercial, and by any means.
+
+In jurisdictions that recognize copyright laws, the author or authors of this
+software dedicate any and all copyright interest in the software to the public
+domain. We make this dedication for the benefit of the public at large and
+to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of relinquishment
+in perpetuity of all present and future rights to this software under copyright
+law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
+THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

wwvb-5.0.0/Makefile

@@ -0,0 +1,71 @@
+ifeq ("$(origin V)", "command line")
+BUILD_VERBOSE=$(V)
+endif
+ifndef BUILD_VERBOSE
+$(info Use make V=1, make V=2 or set BUILD_VERBOSE similarly in your environment to increase build verbosity.)
+BUILD_VERBOSE = 0
+endif
+ifeq ($(BUILD_VERBOSE),0)
+Q = @
+STEPECHO = @:
+else ifeq ($(BUILD_VERBOSE),1)
+Q = @
+STEPECHO = @echo
+else
+Q =
+STEPECHO = @echo
+endif
+
+PYTHON ?= python3
+ifeq ($(OS),Windows_NT)
+ENVPYTHON ?= _env/Scripts/python.exe
+else
+ENVPYTHON ?= _env/bin/python3
+endif
+
+.PHONY: default
+default: coverage mypy
+
+COVERAGE_INCLUDE=--include "src/**/*.py"
+.PHONY: coverage
+coverage:
+	$(Q)$(PYTHON) -mcoverage erase
+	$(Q)env PYTHONPATH=src $(PYTHON) -mcoverage run --branch -p -m unittest discover -s test
+	$(Q)$(PYTHON) -mcoverage combine -q
+	$(Q)$(PYTHON) -mcoverage html $(COVERAGE_INCLUDE)
+	$(Q)$(PYTHON) -mcoverage xml $(COVERAGE_INCLUDE)
+	$(Q)$(PYTHON) -mcoverage report --fail-under=100 $(COVERAGE_INCLUDE)
+
+.PHONY: test_venv
+test_venv:
+	$(Q)$(PYTHON) -mvenv --clear _env
+	$(Q)$(ENVPYTHON) -mpip install .
+	$(Q)$(ENVPYTHON) -m unittest discover -s test
+
+.PHONY: mypy
+mypy:
+	$(Q)mypy --strict --no-warn-unused-ignores src
+
+.PHONY: update
+update:
+	$(Q)env PYTHONPATH=src $(PYTHON) -mwwvb.updateiers --dist
+
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -a -E -j auto
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = doc
+BUILDDIR      = _build
+
+# Route particular targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+.PHONY: html
+html:
+	$(Q)$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# SPDX-FileCopyrightText: 2024 Jeff Epler
+#
+# SPDX-License-Identifier: GPL-3.0-only

wwvb-5.0.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.1
+Name: wwvb
+Version: 5.0.0
+Summary: Generate WWVB timecodes for any desired time
+Author-email: Jeff Epler <jepler@gmail.com>
+Project-URL: Source, https://github.com/jepler/wwvbpy
+Project-URL: Documentation, https://github.com/jepler/wwvbpy
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: adafruit-circuitpython-datetime
+Requires-Dist: beautifulsoup4
+Requires-Dist: click
+Requires-Dist: leapseconddata
+Requires-Dist: platformdirs
+Requires-Dist: python-dateutil
+Requires-Dist: requests
+Requires-Dist: tzdata
+
+<!--
+SPDX-FileCopyrightText: 2021-2024 Jeff Epler
+
+SPDX-License-Identifier: GPL-3.0-only
+-->
+[![Test wwvbgen](https://github.com/jepler/wwvbpy/actions/workflows/test.yml/badge.svg)](https://github.com/jepler/wwvbpy/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/jepler/wwvbpy/branch/main/graph/badge.svg?token=Exx0c3Gp65)](https://codecov.io/gh/jepler/wwvbpy)
+[![Update DUT1 data](https://github.com/jepler/wwvbpy/actions/workflows/cron.yml/badge.svg)](https://github.com/jepler/wwvbpy/actions/workflows/cron.yml)
+[![PyPI](https://img.shields.io/pypi/v/wwvb)](https://pypi.org/project/wwvb)
+[![CodeQL](https://github.com/jepler/wwvbpy/actions/workflows/codeql.yml/badge.svg)](https://github.com/jepler/wwvbpy/actions/workflows/codeql.yml)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/jepler/wwvbpy/main.svg)](https://results.pre-commit.ci/latest/github/jepler/wwvbpy/main)
+
+# Purpose
+
+wwvbpy generates WWVB timecodes for any desired time.  These timecodes
+may be useful in testing WWVB decoder software.
+
+Where possible, wwvbpy uses existing facilities for calendar and time
+manipulation (datetime and dateutil).
+
+It uses DUT1/leap second data derived from IERS Bulletin "A" and from NIST's
+"Leap second and UT1-UTC information" page.  With regular updates to
+the "iersdata", wwvbpy should be able to correctly encode the time anywhere
+within the 100-year WWVB epoch.  (yes, WWVB uses a 2-digit year! In order to
+work with historical data, the epoch is arbitrarily assumed to run from 1970 to
+2069.)
+
+Programs include:
+ * `wwvbgen`, the main commandline generator program
+ * `wwvbdecode`, the main commandline decoder program
+ * `wwvbtk`, visualize the simulated WWVB signal in real-time using Tkinter
+ * `dut1table`, print the full history of dut1 values, including estimated future values
+ * `updateiers`, download the latest dut1 data including prospective data from IERS and NIST
+
+The package includes:
+ * `wwvb`, for generating WWVB timecodes
+ * `wwvb.decode`, a generator-based state machine for decoding WWVB timecodes (amplitude modulation only)
+ * `uwwvb`, a version of the decoder intended for use on constrained environments such as [CircuitPython](https://circuitpython.org).
+
+# Development status
+
+The author (@jepler) occasionally develops and maintains this project, but
+issues are not likely to be acted on.  They would be interested in adding
+co-maintainer(s).
+
+
+# WWVB Timecodes
+
+The National Institute of Standards and Technology operates the WWVB time
+signal service near Fort Collins, Colorado.  The signal can be received in most
+of the continental US.  Each minute, the signal transmits the current time,
+including information about leap years, daylight saving time, and leap seconds.
+The signal is composed of an amplitude channel and a phase modulation channel.
+
+The amplitude channel can be visualized as a sequence of (usually) 60 symbols,
+which by default wwvbgen displays as 0, 1, or 2.  The 0s and 1s encode
+information like the current day of the year, while the 2s appear in fixed
+locations to allow a receiver to determine the start of a minute.
+
+The phase channel (which is displayed with `--channel=phase` or
+`--channel=both`) consists of the same number of symbols per minute.  This
+channel is substantially more complicated than the phase channel.  It encodes
+the current time as minute-of-the-century, provides extended DST information,
+and includes error-correction information not available in the amplitude
+channel.
+
+# Usage
+
+~~~~
+Usage: python -m wwvb.gen [OPTIONS] [TIMESPEC]...
+
+  Generate WWVB timecodes
+
+  TIMESPEC: one of "year yday hour minute" or "year month day hour minute", or
+  else the current minute
+
+Options:
+  -i, --iers / -I, --no-iers      Whether to use IESR data for DUT1 and LS.
+                                  (Default: --iers)
+  -s, --leap-second               Force a positive leap second at the end of
+                                  the GMT month (Implies --no-iers)
+  -n, --negative-leap-second      Force a negative leap second at the end of
+                                  the GMT month (Implies --no-iers)
+  -S, --no-leap-second            Force no leap second at the end of the month
+                                  (Implies --no-iers)
+  -d, --dut1 INTEGER              Force the DUT1 value (Implies --no-iers)
+  -m, --minutes INTEGER           Number of minutes to show (default: 10)
+  --style [bar|cradek|default|duration|json|sextant]
+                                  Style of output
+  -t, --all-timecodes / -T, --no-all-timecodes
+                                  Show the 'WWVB timecode' line before each
+                                  minute
+  --channel [amplitude|phase|both]
+                                  Modulation to show (default: amplitude)
+  --help                          Show this message and exit.
+~~~~
+
+For example, to display the leap second that occurred at the end of 1998,
+~~~~
+$ python wwvbgen.py -m 7 1998 365 23 56
+WWVB timecode: year=98 days=365 hour=23 min=56 dst=0 ut1=-300 ly=0 ls=1
+'98+365 23:56  210100110200100001120011001102010100010200110100121000001002
+'98+365 23:57  210100111200100001120011001102010100010200110100121000001002
+'98+365 23:58  210101000200100001120011001102010100010200110100121000001002
+'98+365 23:59  2101010012001000011200110011020101000102001101001210000010022
+'99+001 00:00  200000000200000000020000000002000100101201110100121001000002
+'99+001 00:01  200000001200000000020000000002000100101201110100121001000002
+'99+001 00:02  200000010200000000020000000002000100101201110100121001000002
+~~~~
+(the leap second is the extra digit at the end of the 23:59 line; that minute
+consists of 61 seconds, instead of the normal 60)
+
+
+# How wwvbpy handles DUT1 data
+
+wwvbpy stores a compact representation of DUT1 values in `wwvb/iersdata_dist.py` or `wwvb_iersdata.py`.
+In this representation, one value is used for one day (0000UTC through 2359UTC).
+The letters `a` through `u` represent offsets of -1.0s through +1.0s
+in 0.1s increments; `k` represents 0s.  (In practice, only a smaller range
+of values, typically -0.7s to +0.8s, is seen)
+
+For 2001 through 2019, NIST has published the actual DUT1 values broadcast,
+and the date of each change, though it in the format of an HTML
+table and not designed for machine readability:
+
+https://www.nist.gov/pml/time-and-frequency-division/atomic-standards/leap-second-and-ut1-utc-information
+
+NIST does not update the value daily and does not seem to follow any
+specific rounding rule.  Rather, in WWVB "the resolution of the DUT1
+correction is 0.1 s, and represents an average value for an extended
+range of dates. Therefore, it will not agree exactly with the weekly
+UT1-UTC(NIST) values shown in the earlier table, which have 1 ms
+resolution and are updated weekly."  Like wwvbpy's compact
+representation of DUT1 values, the real WWVB does not appear to ever
+broadcast DUT1=-0.0.
+
+For a larger range of dates spanning 1973 through approximately one year from
+now, IERS publishes historical and prospective UT1-UTC values to multiple
+decimal places, in a machine readable fixed length format.
+
+wwvbpy merges the WWVB and IERS datasets, favoring the WWVB dataset for dates when it is available. There are some caveats to this, which are mostly commented in the `wwvb/updateiers.py` script.
+
+`wwvb/iersdata_dist.py` is updated monthly from github actions or with `iersdata --dist` from within the wwvbpy source tree. However, at this time, releases are not regularly made from the updated information.
+
+A site or user version of the file, `wwvb_iersdata.py` can be created or updated with `iersdata --site` or `iersdata --user`.  If the distributed iersdata is out of date, the generator will prompt you to run the update command.
+
+Leap seconds are inferred from the DUT1 data as follows: If X and Y are the
+1-digit-rounded DUT1 values for consecutive dates, and `X*Y<0`, then there is a
+leap second at the end of day X.  The direction of the leap second can be
+inferred from the sign of X, a 59-second minute if X is positive and a
+61-second minute if it is negative.  As long
+as DUT1 changes slowly enough during other times that there is at least one day
+of DUT1=+0.0, no incorrect (negative) leapsecond will be inferred. (something
+that should remain true for the next few centuries, until the length of the day
+is 100ms different from 86400 seconds)
+
+
+# The phase modulation channel
+
+This should be considered more experimental than the AM channel, as the
+tests only cover a single reference minute.  Further tests could be informed
+by the [other implementation I know of](http://www.leapsecond.com/tools/wwvb_pm.c), except that implementation appears incomplete.
+
+
+# Testing wwvbpy
+
+Run the testsuite, check coverage & type annotations with `gmake`.
+
+There are several test suites:
+ * `testwwvb.py`: Check output against expected values.  Uses hard coded leap seconds.  Tests amplitude and phase data, though the phase testcases are dubious as they were also generated by wwvbpy.
+ * `testuwwvb.py`: Test the reduced-functionality version against the main version
+ * `testls.py`: Check the IERS data through 2020-1-1 for expected leap seconds
+ * `testpm.py`: Check the phase modulation data against a test case from NIST documentation
+ * `testcli.py`: Check the commandline programs work as expected (limited tests to get 100% coverage)