pychrony 2.0.3__tar.gz → 3.0.2__tar.gz

pychrony-3.0.2/MANIFEST.in

@@ -0,0 +1,22 @@
+# setuptools-scm adds every git-tracked file to the sdist. Strip the
+# development tooling so the sdist carries only what a downstream packager
+# needs: src/, tests/, setup.py, pyproject.toml, README.md, LICENSE, LICENSES/.
+
+prune .claude
+prune .github
+prune .specify
+prune docker
+prune docs
+prune specs
+exclude .dockerignore .gitignore .gitmodules .python-version
+exclude CLAUDE.md TESTING.md mkdocs.yml uv.lock
+
+# vendor/libchrony is deliberately left out. The release workflow's
+# build-sdist job checks out without submodules, so the published sdist never
+# had it; pruning it here keeps local builds (where the submodule may be
+# populated) identical to the released one. Building from the sdist links
+# against the system libchrony, as distro packagers expect, and leaving the
+# LGPL source out keeps the sdist itself MIT code plus license texts. The
+# LGPL source offer for the libchrony bundled into the binary wheels is met
+# by the pinned submodule commit in the public git repository.
+prune vendor

{pychrony-2.0.3/src/pychrony.egg-info → pychrony-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pychrony
-Version: 2.0.3
+Version: 3.0.2
 Summary: Python bindings for chrony NTP client
 Author-email: arunderwood <arunderwood@users.noreply.github.com>
 License-Expression: MIT AND LGPL-2.1-or-later
@@ -11,20 +11,24 @@ Project-URL: Issues, https://github.com/arunderwood/pychrony/issues
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
-Classifier: Programming Language :: Python :: 3.10
 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: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Topic :: System :: Networking :: Time Synchronization
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Operating System :: POSIX :: Linux
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: LICENSES/LGPL-2.1-or-later.txt
-Requires-Dist: cffi>=1.14.0
+Requires-Dist: cffi>=1.15.1; python_version == "3.11"
+Requires-Dist: cffi>=1.16.0; python_version == "3.12"
+Requires-Dist: cffi>=1.17.0; python_version == "3.13"
+Requires-Dist: cffi>=2.0.0; python_version == "3.14"
+Requires-Dist: cffi>=2.1.0; python_version >= "3.15"
 Dynamic: license-file
 
 # PyChrony: Python bindings for chrony NTP client
@@ -56,7 +60,18 @@ Pre-built wheels include libchrony—no system dependencies needed.
 <details>
 <summary><strong>Building from Source</strong></summary>
 
-Source installs (sdist or development) require [libchrony](https://gitlab.com/chrony/libchrony) to be installed on your system.
+Installing from source (the sdist, or any platform without a pre-built wheel)
+compiles the CFFI bindings, so it needs a C compiler, the libffi headers, and
+[libchrony](https://gitlab.com/chrony/libchrony) with its headers. libchrony is
+found through `pkg-config`; for a non-standard prefix, add
+`<prefix>/lib/pkgconfig` to `PKG_CONFIG_PATH`. A missing `chrony.h` or library
+stops the install with an error naming it.
+
+To build from source even where a wheel exists:
+
+```bash
+pip install --no-binary pychrony pychrony
+```
 
 #### libchrony Package Availability
 
@@ -73,7 +88,7 @@ Source installs (sdist or development) require [libchrony](https://gitlab.com/ch
 ```bash
 # Install build dependencies
 # Debian/Ubuntu:
-sudo apt-get install build-essential libtool libffi-dev
+sudo apt-get install build-essential libtool-bin libffi-dev python3-dev
 
 # Alpine:
 sudo apk add gcc make libtool libffi-dev musl-dev
@@ -96,9 +111,18 @@ git clone https://github.com/arunderwood/pychrony.git
 cd pychrony
 git submodule update --init
 uv sync --all-groups
-uv pip install -e .
 ```
 
+`uv sync` and `uv pip install` from the checkout install pychrony **without**
+the compiled bindings: `[tool.uv]` in `pyproject.toml` sets
+`PYCHRONY_SKIP_CFFI=1`, so development and the unit and contract tests need no
+libchrony. Connecting to chronyd from such an install raises
+`ChronyLibraryError`. Integration tests build the bindings in Docker (see
+[TESTING.md](TESTING.md)).
+
+With libchrony installed, `PYCHRONY_BUILD_CFFI=1 uv sync` or `pip install -e .`
+builds the bindings. With other installers, `PYCHRONY_SKIP_CFFI=1` skips them.
+
 </details>
 
 ## Usage
@@ -121,13 +145,12 @@ command port, using the first that connects — the same candidates
 The two are not equivalent in privilege. The Unix socket is chronyd's control
 channel, restricted to the root or `chrony` user; the command port serves
 monitoring commands only, which is everything pychrony reads. Read-only
-consumers should prefer the command port and can require it:
+consumers should prefer the command port, and can ask for it explicitly:
 
 ```python
-from pychrony import ChronyConnection, Transport
+from pychrony import ChronyConnection
 
-with ChronyConnection() as conn:
-    assert conn.transport is Transport.COMMAND_PORT
+with ChronyConnection("127.0.0.1") as conn:
     status = conn.get_tracking()
 ```
 
@@ -135,9 +158,33 @@ Note that joining the `chrony` group does **not** grant access to the Unix
 socket. See [Choosing a Transport](https://pychrony.org/#choosing-a-transport)
 for details.
 
+## Testing Your Code
+
+`pychrony.testing` has factories that build pychrony objects with realistic
+defaults. They work in any test framework and do not need pytest:
+
+```python
+from pychrony.testing import make_tracking
+
+status = make_tracking(stratum=16, reference_id=0)
+assert not status.is_synchronized()
+```
+
+pytest users can enable fixtures (`chrony_tracking_status`, `chrony_source`,
+`chrony_source_stats`, `chrony_rtc_data`) in their top-level `conftest.py`:
+
+```python
+pytest_plugins = ["pychrony.pytest_plugin"]
+```
+
+The plugin is not loaded automatically, so installing pychrony adds no
+fixtures to other projects' test runs. See
+[TESTING.md](https://github.com/arunderwood/pychrony/blob/main/TESTING.md#pytest-fixtures)
+for details.
+
 ## Compatibility
 
-- **Python**: 3.10, 3.11, 3.12, 3.13, 3.14, 3.15
+- **Python**: 3.11, 3.12, 3.13, 3.14, 3.15
 - **Platform**: Linux (primary), other platforms where libchrony is available
 - **chrony**: 4.x and later
 

{pychrony-2.0.3 → pychrony-3.0.2}/README.md

@@ -27,7 +27,18 @@ Pre-built wheels include libchrony—no system dependencies needed.
 <details>
 <summary><strong>Building from Source</strong></summary>
 
-Source installs (sdist or development) require [libchrony](https://gitlab.com/chrony/libchrony) to be installed on your system.
+Installing from source (the sdist, or any platform without a pre-built wheel)
+compiles the CFFI bindings, so it needs a C compiler, the libffi headers, and
+[libchrony](https://gitlab.com/chrony/libchrony) with its headers. libchrony is
+found through `pkg-config`; for a non-standard prefix, add
+`<prefix>/lib/pkgconfig` to `PKG_CONFIG_PATH`. A missing `chrony.h` or library
+stops the install with an error naming it.
+
+To build from source even where a wheel exists:
+
+```bash
+pip install --no-binary pychrony pychrony
+```
 
 #### libchrony Package Availability
 
@@ -44,7 +55,7 @@ Source installs (sdist or development) require [libchrony](https://gitlab.com/ch
 ```bash
 # Install build dependencies
 # Debian/Ubuntu:
-sudo apt-get install build-essential libtool libffi-dev
+sudo apt-get install build-essential libtool-bin libffi-dev python3-dev
 
 # Alpine:
 sudo apk add gcc make libtool libffi-dev musl-dev
@@ -67,9 +78,18 @@ git clone https://github.com/arunderwood/pychrony.git
 cd pychrony
 git submodule update --init
 uv sync --all-groups
-uv pip install -e .
 ```
 
+`uv sync` and `uv pip install` from the checkout install pychrony **without**
+the compiled bindings: `[tool.uv]` in `pyproject.toml` sets
+`PYCHRONY_SKIP_CFFI=1`, so development and the unit and contract tests need no
+libchrony. Connecting to chronyd from such an install raises
+`ChronyLibraryError`. Integration tests build the bindings in Docker (see
+[TESTING.md](TESTING.md)).
+
+With libchrony installed, `PYCHRONY_BUILD_CFFI=1 uv sync` or `pip install -e .`
+builds the bindings. With other installers, `PYCHRONY_SKIP_CFFI=1` skips them.
+
 </details>
 
 ## Usage
@@ -92,13 +112,12 @@ command port, using the first that connects — the same candidates
 The two are not equivalent in privilege. The Unix socket is chronyd's control
 channel, restricted to the root or `chrony` user; the command port serves
 monitoring commands only, which is everything pychrony reads. Read-only
-consumers should prefer the command port and can require it:
+consumers should prefer the command port, and can ask for it explicitly:
 
 ```python
-from pychrony import ChronyConnection, Transport
+from pychrony import ChronyConnection
 
-with ChronyConnection() as conn:
-    assert conn.transport is Transport.COMMAND_PORT
+with ChronyConnection("127.0.0.1") as conn:
     status = conn.get_tracking()
 ```
 
@@ -106,9 +125,33 @@ Note that joining the `chrony` group does **not** grant access to the Unix
 socket. See [Choosing a Transport](https://pychrony.org/#choosing-a-transport)
 for details.
 
+## Testing Your Code
+
+`pychrony.testing` has factories that build pychrony objects with realistic
+defaults. They work in any test framework and do not need pytest:
+
+```python
+from pychrony.testing import make_tracking
+
+status = make_tracking(stratum=16, reference_id=0)
+assert not status.is_synchronized()
+```
+
+pytest users can enable fixtures (`chrony_tracking_status`, `chrony_source`,
+`chrony_source_stats`, `chrony_rtc_data`) in their top-level `conftest.py`:
+
+```python
+pytest_plugins = ["pychrony.pytest_plugin"]
+```
+
+The plugin is not loaded automatically, so installing pychrony adds no
+fixtures to other projects' test runs. See
+[TESTING.md](https://github.com/arunderwood/pychrony/blob/main/TESTING.md#pytest-fixtures)
+for details.
+
 ## Compatibility
 
-- **Python**: 3.10, 3.11, 3.12, 3.13, 3.14, 3.15
+- **Python**: 3.11, 3.12, 3.13, 3.14, 3.15
 - **Platform**: Linux (primary), other platforms where libchrony is available
 - **chrony**: 4.x and later
 

pychrony-3.0.2/pyproject.toml

@@ -0,0 +1,164 @@
+[build-system]
+# PEP 639 license expressions + license-files need setuptools 77; the first
+# 77.x on PyPI is 77.0.1. cffi floors are the first release supporting each
+# Python (keep in sync with [project] dependencies).
+requires = [
+    "setuptools>=77.0.1",
+    "setuptools-scm>=8.0",
+    "cffi>=1.15.1; python_version == '3.11'",
+    "cffi>=1.16.0; python_version == '3.12'",
+    "cffi>=1.17.0; python_version == '3.13'",
+    "cffi>=2.0.0; python_version == '3.14'",
+    "cffi>=2.1.0; python_version >= '3.15'",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pychrony"
+dynamic = ["version"]
+description = "Python bindings for chrony NTP client"
+readme = "README.md"
+license = "MIT AND LGPL-2.1-or-later"
+license-files = ["LICENSE", "LICENSES/*"]
+requires-python = ">=3.11"
+authors = [
+    {name = "arunderwood", email = "arunderwood@users.noreply.github.com"}
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Programming Language :: Python :: Free Threading :: 3 - Stable",
+    "Topic :: System :: Networking :: Time Synchronization",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = [
+    # First cffi release supporting each Python version.
+    "cffi>=1.15.1; python_version == '3.11'",
+    "cffi>=1.16.0; python_version == '3.12'",
+    "cffi>=1.17.0; python_version == '3.13'",
+    "cffi>=2.0.0; python_version == '3.14'",
+    "cffi>=2.1.0; python_version >= '3.15'",
+]
+
+[project.urls]
+Homepage = "https://github.com/arunderwood/pychrony"
+Documentation = "https://pychrony.org/"
+Repository = "https://github.com/arunderwood/pychrony.git"
+Issues = "https://github.com/arunderwood/pychrony/issues"
+
+[tool.setuptools_scm]
+fallback_version = "0.0.0.dev0"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# _cffi_bindings.pyi types the CFFI extension, which only exists once built.
+[tool.setuptools.package-data]
+pychrony = ["py.typed", "_core/*.pyi"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+# specs/ holds frozen spec-kit design documents; they are historical records and
+# are not kept in sync with the code, so exclude them from linting/formatting.
+extend-exclude = ["specs/"]
+
+[tool.ruff.lint]
+extend-select = [
+    "B",    # flake8-bugbear
+    "BLE",  # flake8-blind-except
+    "C4",   # flake8-comprehensions
+    "I",    # isort
+    "PERF", # perflint
+    "PIE",  # flake8-pie
+    "PT",   # flake8-pytest-style
+    "RET",  # flake8-return
+    "RUF",  # ruff-specific rules
+    "SIM",  # flake8-simplify
+    "UP",   # pyupgrade
+]
+ignore = [
+    # __all__ entries are grouped by category (enums, models, exceptions) with
+    # explanatory comments; alphabetical sorting would destroy that structure.
+    "RUF022",
+    # try/except inside a loop is free on 3.11+ (zero-cost exceptions), which is
+    # our minimum, and the source-list retry loop needs a handler per attempt.
+    "PERF203",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = ["-v", "--tb=short"]
+
+[tool.uv]
+# The first uv with extra-build-variables; older uv rejects this file.
+required-version = ">=0.8.6"
+# Lets development and the CI test/lint/docs jobs run without libchrony; unit
+# and contract tests mock the bindings. Applies to uv installs of the project
+# only, not `uv build`, pip or cibuildwheel. PYCHRONY_BUILD_CFFI=1 overrides it.
+extra-build-variables = { pychrony = { PYCHRONY_SKIP_CFFI = "1" } }
+# Replaces uv's default (pyproject.toml, setup.py, setup.cfg), so those are
+# listed too.
+cache-keys = [
+    { file = "pyproject.toml" },
+    { file = "setup.py" },
+    { file = "src/pychrony/_core/_build_bindings.py" },
+    # setuptools-scm takes the version from git.
+    { git = { commit = true, tags = true } },
+    { env = "PYCHRONY_BUILD_CFFI" },
+    { env = "PYCHRONY_SKIP_CFFI" },
+]
+
+[tool.cibuildwheel]
+build-frontend = "build[uv]"
+build = "cp311-* cp312-* cp313-* cp314-* cp314t-* cp315-* cp315t-*"
+
+[tool.cibuildwheel.linux]
+archs = ["x86_64", "aarch64"]
+environment = { CIBUILDWHEEL = "1" }
+test-requires = "pytest"
+# The unit and contract tests mock the C library, so check the compiled bindings
+# directly: a wheel missing _cffi_bindings*.so would otherwise pass.
+test-command = [
+    "python -c 'import pychrony._core._cffi_bindings, pychrony._core._bindings as b; assert b._LIBRARY_AVAILABLE'",
+    "python -m pytest {project}/tests/unit {project}/tests/contract -v",
+]
+
+[[tool.cibuildwheel.overrides]]
+select = "*-manylinux_*"
+before-all = """
+dnf install -y gcc make libtool libffi-devel && \
+cd vendor/libchrony && make && make install prefix=/usr && ldconfig
+"""
+
+[[tool.cibuildwheel.overrides]]
+select = "*-musllinux_*"
+before-all = """
+apk add --no-cache gcc make libtool libffi-dev musl-dev && \
+cd vendor/libchrony && make && make install prefix=/usr
+"""
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "pyyaml>=6.0.3",
+    "ruff>=0.14.11",
+    "setuptools>=77.0.1",
+    "ty>=0.0.1",
+]
+docs = [
+    "mkdocs-material>=9.0.0",
+    "mkdocstrings[python]>=0.24.0",
+    "mike>=2.0.0",
+]

pychrony-3.0.2/setup.py

@@ -0,0 +1,93 @@
+"""Compiling by default means a source install either works or fails at build
+time, never yielding a package that cannot reach chronyd.
+
+PYCHRONY_SKIP_CFFI=1 is for development without libchrony; ``[tool.uv]`` in
+pyproject.toml sets it for uv installs of the project. Such an install imports,
+but connecting raises ChronyLibraryError. cibuildwheel always compiles because a
+wheel without bindings is broken.
+"""
+
+import os
+import tempfile
+
+from setuptools import setup
+from setuptools.command.build_ext import build_ext
+from setuptools.errors import CompileError, LinkError, PlatformError
+
+CFFI_EXTENSION = "pychrony._core._cffi_bindings"
+
+LIBCHRONY_HELP = """\
+pychrony needs libchrony to compile its CFFI bindings.
+Install libchrony and a C compiler, then retry:
+
+  Fedora 42+:  dnf install libchrony-devel gcc
+  RHEL 9:      dnf install epel-release
+               dnf install libchrony-devel gcc
+  Others:      build https://gitlab.com/chrony/libchrony
+               make && make install prefix=/usr && ldconfig
+
+For a non-standard prefix, add <prefix>/lib/pkgconfig to
+PKG_CONFIG_PATH (or set CFLAGS=-I<prefix>/include and
+LDFLAGS=-L<prefix>/lib).
+
+To install without the bindings (development only:
+pychrony cannot query chronyd), set PYCHRONY_SKIP_CFFI=1."""
+
+
+class build_ext_with_libchrony_check(build_ext):
+    """Without this, a missing libchrony surfaces as a raw compiler or linker
+    error from the CFFI-generated source."""
+
+    def build_extension(self, ext):
+        if ext.name == CFFI_EXTENSION:
+            self._check_libchrony(ext)
+        super().build_extension(ext)
+
+    def _check_libchrony(self, ext):
+        include_dirs = list(ext.include_dirs) + list(self.include_dirs or [])
+        library_dirs = list(ext.library_dirs) + list(self.library_dirs or [])
+        with tempfile.TemporaryDirectory() as tmp:
+            src = os.path.join(tmp, "check_libchrony.c")
+            with open(src, "w") as f:
+                f.write(
+                    "#include <chrony.h>\n"
+                    "int main(void) { return chrony_open_socket == 0; }\n"
+                )
+            try:
+                objects = self.compiler.compile(
+                    [src], output_dir=tmp, include_dirs=include_dirs
+                )
+            except CompileError:
+                raise PlatformError(
+                    f"chrony.h not found.\n\n{LIBCHRONY_HELP}"
+                ) from None
+            try:
+                self.compiler.link_executable(
+                    objects,
+                    "check_libchrony",
+                    output_dir=tmp,
+                    libraries=["chrony"],
+                    library_dirs=library_dirs,
+                )
+            except LinkError:
+                raise PlatformError(
+                    f"libchrony shared library not found.\n\n{LIBCHRONY_HELP}"
+                ) from None
+
+
+def should_build_cffi(environ=os.environ):
+    if environ.get("CIBUILDWHEEL") == "1" or environ.get("PYCHRONY_BUILD_CFFI") == "1":
+        return True
+    return environ.get("PYCHRONY_SKIP_CFFI") != "1"
+
+
+# setuptools' PEP 517 backend runs this file as __main__; the guard lets tests
+# import it without running setup().
+if __name__ == "__main__":
+    if should_build_cffi():
+        setup(
+            cffi_modules=["src/pychrony/_core/_build_bindings.py:ffibuilder"],
+            cmdclass={"build_ext": build_ext_with_libchrony_check},
+        )
+    else:
+        setup()

{pychrony-2.0.3 → pychrony-3.0.2}/src/pychrony/__init__.py

@@ -45,7 +45,12 @@ RTC Data:
     ...         print("RTC tracking not configured")
 
 Error Handling:
-    >>> from pychrony import ChronyConnection, ChronyError
+    >>> from pychrony import (
+    ...     ChronyConnection,
+    ...     ChronyConnectionError,
+    ...     ChronyLibraryError,
+    ...     ChronyPermissionError,
+    ... )
     >>> try:
     ...     with ChronyConnection() as conn:
     ...         status = conn.get_tracking()
@@ -67,9 +72,19 @@ Choosing a Transport:
     reads. Read-only consumers should prefer the command port. Note that
     joining the chrony group does not grant access to the Unix socket.
 
+    To use the command port, ask for it explicitly; an explicit address is
+    used as given, with no fallback:
+
     >>> from pychrony import ChronyConnection, Transport
+    >>> with ChronyConnection("127.0.0.1") as conn:
+    ...     status = conn.get_tracking()
+
+    With auto-detect, check what the connection settled on and refuse a
+    control channel rather than assume:
+
     >>> with ChronyConnection() as conn:
-    ...     assert conn.transport is Transport.COMMAND_PORT
+    ...     if conn.transport is not Transport.COMMAND_PORT:
+    ...         raise RuntimeError(f"refusing a control channel ({conn.address})")
     ...     status = conn.get_tracking()
 
 Custom Socket Path:
@@ -84,6 +99,15 @@ Remote chronyd via UDP:
     >>> with ChronyConnection("192.168.1.100") as conn:
     ...     status = conn.get_tracking()
 
+Timeouts:
+    Each request waits `timeout` seconds (default 1.0) for chronyd's answer and
+    is resent up to twice, so an unanswered request raises
+    ChronyConnectionError after at most three times `timeout`. The command
+    port is UDP: a dropped datagram or a firewalled port is never answered.
+
+    >>> with ChronyConnection("192.168.1.100", timeout=0.5) as conn:
+    ...     status = conn.get_tracking()
+
 Thread Safety:
     ChronyConnection is NOT thread-safe. The underlying libchrony session
     maintains stateful request/response cycles that cannot be safely shared
@@ -109,6 +133,9 @@ Thread Safety:
     The returned dataclasses (TrackingStatus, Source, etc.) are frozen and
     immutable, so they can be safely shared across threads after retrieval.
 
+    The same rules apply on free-threaded CPython builds (3.14t and later):
+    disabling the GIL does not make a single ChronyConnection safe to share.
+
 For more information, see:
 - https://github.com/arunderwood/pychrony
 - https://chrony-project.org/

{pychrony-2.0.3 → pychrony-3.0.2}/src/pychrony/_core/__init__.py

@@ -3,5 +3,5 @@
 This module contains the CFFI interface to libchrony for
 retrieving tracking status from chronyd.
 
-Internal implementation - use pychrony.get_tracking() instead.
+Internal implementation - use pychrony.ChronyConnection instead.
 """