hdx-python-database 1.3.8__tar.gz → 1.4.0__tar.gz

hdx_python_database-1.4.0/.github/workflows/publish.yaml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hdx-python-database
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Get history and tags for versioning to work
+      run: |
+        git fetch --prune --unshallow
+        git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+
+    - name: Build with uv
+      run: uv build
+
+    - name: Publish distribution 📦 to PyPI
+      run: uv publish

hdx_python_database-1.4.0/.github/workflows/run-python-tests.yaml

@@ -0,0 +1,49 @@
+name: Run tests
+
+on:
+  workflow_dispatch:
+  push:
+    branches-ignore: [gh-pages, "dependabot/**"]
+  pull_request:
+    branches-ignore: [gh-pages]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Check styling
+        run: |
+          uv run ruff format --check
+          uv run ruff check
+
+      - name: Test with pytest
+        run: uv run pytest
+
+      - name: Publish Unit Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        if: always()
+        with:
+          files: test-results.xml
+
+      - name: Publish in Coveralls
+        uses: coverallsapp/github-action@v2
+        if: always()
+        with:
+          flag-name: tests
+          format: lcov

{hdx_python_database-1.3.8 → hdx_python_database-1.4.0}/.gitignore

@@ -94,5 +94,8 @@ ENV/
 # IntelliJ
 .idea/
 
-# setuptools_scm
+# hatch-vcs
 _version.py
+
+# Mac files
+.DS_Store

{hdx_python_database-1.3.8 → hdx_python_database-1.4.0}/.pre-commit-config.yaml

@@ -1,25 +1,25 @@
 default_language_version:
-    python: python3.13
+  python: python3
+
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-ast
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.0
+    rev: v0.14.13
     hooks:
       # Run the linter.
       - id: ruff-check
         args: [ --fix ]
       # Run the formatter.
       - id: ruff-format
+
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.7.14
+    rev: 0.9.25
     hooks:
-      # Run the pip compile
-      - id: pip-compile
-        name: pip-compile requirements.txt
-        files: pyproject.toml
-        args: [ pyproject.toml, --resolver=backtracking, --all-extras, --upgrade, -q, -o, requirements.txt ]
+      # Ensure the lockfile is up-to-date with pyproject.toml
+      - id: uv-lock

hdx_python_database-1.4.0/CLAUDE.md

@@ -0,0 +1,35 @@
+# HDX Python Database
+
+HDX Python Database Library — provides utilities for connecting to databases (including via SSH tunnel) using SQLAlchemy.
+
+## Setup
+
+```shell
+uv sync
+```
+
+## Running Tests
+
+```shell
+uv run pytest
+```
+
+## Linting
+
+```shell
+uv run ruff check
+uv run ruff format --check
+```
+
+## Building
+
+```shell
+uv build
+```
+
+## Package Management
+
+- Runtime dependencies go in `[project.dependencies]` in `pyproject.toml`
+- Dev/test dependencies go in `[dependency-groups] dev` in `pyproject.toml`
+- Optional runtime extras (`sshtunnel`, `postgresql`) stay in `[project.optional-dependencies]`
+- After changing dependencies, run `uv lock --upgrade` to regenerate `uv.lock`

{hdx_python_database-1.3.8 → hdx_python_database-1.4.0}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hdx-python-database
-Version: 1.3.8
+Version: 1.4.0
 Summary: HDX Python database utilities
 Project-URL: Homepage, https://github.com/OCHA-DAP/hdx-python-database
-Author-email: Michael Rans <rans@email.com>
+Author-email: Michael Rans <rans@un.org>
 License: MIT
 License-File: LICENSE
 Keywords: HDX,database,postgresql
@@ -16,29 +16,16 @@ Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: Unix
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: sqlalchemy>=2
-Provides-Extra: dev
-Requires-Dist: pre-commit; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkapi; extra == 'docs'
 Provides-Extra: postgresql
 Requires-Dist: psycopg[binary]; extra == 'postgresql'
 Provides-Extra: sshtunnel
-Requires-Dist: sshtunnel; extra == 'sshtunnel'
-Provides-Extra: test
-Requires-Dist: psycopg[binary]; extra == 'test'
-Requires-Dist: pytest; extra == 'test'
-Requires-Dist: pytest-cov; extra == 'test'
-Requires-Dist: sshtunnel; extra == 'test'
+Requires-Dist: cryptography>=48.0.1; extra == 'sshtunnel'
+Requires-Dist: sshtunnel>=0.5.1; extra == 'sshtunnel'
 Description-Content-Type: text/markdown
 
 [![Build Status](https://github.com/OCHA-DAP/hdx-python-database/actions/workflows/run-python-tests.yaml/badge.svg)](https://github.com/OCHA-DAP/hdx-python-database/actions/workflows/run-python-tests.yaml)
@@ -53,3 +40,78 @@ For more information, please read the [documentation](https://hdx-python-databas
 
 This library is part of the [Humanitarian Data Exchange](https://data.humdata.org/) (HDX) project. If you have
 humanitarian related data, please upload your datasets to HDX.
+
+# Development
+
+## Environment
+
+Development is currently done using Python 3.13. The environment can be created with:
+
+```shell
+    uv sync
+```
+
+This creates a .venv folder with the versions specified in the project's uv.lock file.
+
+### Pre-commit
+
+pre-commit will be installed when syncing uv. It is run every time you make a git
+commit if you call it like this:
+
+```shell
+    pre-commit install
+```
+
+With pre-commit, all code is formatted according to
+[ruff](https://docs.astral.sh/ruff/) guidelines.
+
+To check if your changes pass pre-commit without committing, run:
+
+```shell
+    pre-commit run --all-files
+```
+
+## Packages
+
+[uv](https://github.com/astral-sh/uv) is used for package management. If
+you've introduced a new package to the source code (i.e. anywhere in `src/`),
+please add it to the `project.dependencies` section of `pyproject.toml` with
+any known version constraints.
+
+To add packages required only for testing, add them to the
+`[dependency-groups]`.
+
+Any changes to the dependencies will be automatically reflected in
+`uv.lock` with `pre-commit`, but you can re-generate the files without committing by
+executing:
+
+```shell
+    uv lock --upgrade
+```
+
+## Project
+
+[uv](https://github.com/astral-sh/uv) is used for project management. The project can be
+built using:
+
+```shell
+    uv build
+```
+
+Linting and syntax checking can be run with:
+
+```shell
+    uv run ruff check
+```
+
+To run the tests and view coverage, execute:
+
+```shell
+    uv run pytest
+```
+
+## Documentation
+
+The documentation, including API documentation, is generated using ReadtheDocs and
+MkDocs with Material. As you change the source code, remember to update the
+documentation at `documentation/index.md`.

hdx_python_database-1.4.0/README.md

@@ -0,0 +1,87 @@
+[![Build Status](https://github.com/OCHA-DAP/hdx-python-database/actions/workflows/run-python-tests.yaml/badge.svg)](https://github.com/OCHA-DAP/hdx-python-database/actions/workflows/run-python-tests.yaml)
+[![Coverage Status](https://coveralls.io/repos/github/OCHA-DAP/hdx-python-database/badge.svg?branch=main&ts=1)](https://coveralls.io/github/OCHA-DAP/hdx-python-database?branch=main)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Downloads](https://img.shields.io/pypi/dm/hdx-python-database.svg)](https://pypistats.org/packages/hdx-python-database)
+
+The HDX Python Database Library provides utilities for connecting to databases in a standard way including
+through an ssh tunnel if needed. It is built on top of SQLAlchemy and simplifies its setup.
+
+For more information, please read the [documentation](https://hdx-python-database.readthedocs.io/en/latest/).
+
+This library is part of the [Humanitarian Data Exchange](https://data.humdata.org/) (HDX) project. If you have
+humanitarian related data, please upload your datasets to HDX.
+
+# Development
+
+## Environment
+
+Development is currently done using Python 3.13. The environment can be created with:
+
+```shell
+    uv sync
+```
+
+This creates a .venv folder with the versions specified in the project's uv.lock file.
+
+### Pre-commit
+
+pre-commit will be installed when syncing uv. It is run every time you make a git
+commit if you call it like this:
+
+```shell
+    pre-commit install
+```
+
+With pre-commit, all code is formatted according to
+[ruff](https://docs.astral.sh/ruff/) guidelines.
+
+To check if your changes pass pre-commit without committing, run:
+
+```shell
+    pre-commit run --all-files
+```
+
+## Packages
+
+[uv](https://github.com/astral-sh/uv) is used for package management. If
+you've introduced a new package to the source code (i.e. anywhere in `src/`),
+please add it to the `project.dependencies` section of `pyproject.toml` with
+any known version constraints.
+
+To add packages required only for testing, add them to the
+`[dependency-groups]`.
+
+Any changes to the dependencies will be automatically reflected in
+`uv.lock` with `pre-commit`, but you can re-generate the files without committing by
+executing:
+
+```shell
+    uv lock --upgrade
+```
+
+## Project
+
+[uv](https://github.com/astral-sh/uv) is used for project management. The project can be
+built using:
+
+```shell
+    uv build
+```
+
+Linting and syntax checking can be run with:
+
+```shell
+    uv run ruff check
+```
+
+To run the tests and view coverage, execute:
+
+```shell
+    uv run pytest
+```
+
+## Documentation
+
+The documentation, including API documentation, is generated using ReadtheDocs and
+MkDocs with Material. As you change the source code, remember to update the
+documentation at `documentation/index.md`.

{hdx_python_database-1.3.8 → hdx_python_database-1.4.0}/documentation/index.md

@@ -79,20 +79,26 @@ tunnel (which requires installing `hdx-python-database[sshtunnel]`):
 
     # Get SQLAlchemy session object given database parameters and
     # if needed SSH parameters. If database is PostgreSQL, will poll
-    # till it is up.
+    # till it is up (or until pg_timeout seconds if supplied).
     from hdx.database import Database
     with Database(database="db", host="1.2.3.4", username="user",
                   password="pass", dialect="dialect", driver="driver",
 
                   ssh_host="5.6.7.8", ssh_port=2222, ssh_username="sshuser",
-                  ssh_private_key="path_to_key", db_has_tz=True,
-                  reflect=True, prepare_fn=prepare_views) as database:
+                  ssh_private_key="path_to_key", ssh_host_key="AAAAC3...",
+                  db_has_tz=True, reflect=True, prepare_fn=prepare_views,
+                  pg_timeout=60) as database:
         engine = database.get_engine()
         session = database.get_session()
         reflected_classes = database.get_reflected_classes()
         views = database.get_prepare_results()
         session.query(...)
 
+`ssh_host_key` is the SSH server's public host key, used to verify the server's
+identity. Without it, the tunnel is open to man-in-the-middle attacks and a
+warning is logged. It can be obtained with `ssh-keyscan -t ed25519 5.6.7.8`
+(the base64 field of the output).
+
 `db_has_tz` which defaults to `False` indicates whether database datetime
 columns have timezones. If `db_has_tz` is `True`, use `Base` from
 `hdx.database.with_timezone`, otherwise use `Base` from

hdx_python_database-1.4.0/pyproject.toml

@@ -0,0 +1,132 @@
+#########################
+# Project Configuration #
+#########################
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hdx-python-database"
+description = "HDX Python database utilities"
+authors = [{name = "Michael Rans", email = "rans@un.org"}]
+license = {text = "MIT"}
+keywords = ["HDX", "database", "postgresql"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Unix",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+]
+readme = "README.md"
+dynamic = ["version"]
+requires-python = ">=3.11"
+
+dependencies = [
+    "sqlalchemy>=2",
+]
+
+[project.optional-dependencies]
+sshtunnel = ["sshtunnel>=0.5.1", "cryptography>=48.0.1"]
+postgresql = ["psycopg[binary]"]
+docs = ["mkapi"]
+
+[dependency-groups]
+dev = [
+    "sshtunnel>=0.5.1",
+    "psycopg[binary]",
+    "pytest",
+    "pytest-cov",
+    "pre-commit",
+    "ruff==0.14.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/OCHA-DAP/hdx-python-database"
+
+# ----------------------------------------------------------------------------
+# Hatchling (Build & Versioning)
+# ----------------------------------------------------------------------------
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+local_scheme = "no-local-version"
+version_scheme = "python-simplified-semver"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/hdx/database/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hdx"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+# ----------------------------------------------------------------------------
+# Ruff (Linting & Formatting)
+# ----------------------------------------------------------------------------
+
+[tool.ruff]
+target-version = "py311"
+src = ["src"]
+exclude = ["_version.py"]
+
+[tool.ruff.lint]
+# Defaults are E (pycodestyle) and F (pyflakes). We extend them:
+extend-select = [
+  "I",   # isort
+  "UP",  # pyupgrade
+]
+ignore = [
+    "E501", # Line too long
+]
+
+[tool.ruff.lint.isort]
+known-local-folder = ["hdx.database"]
+
+# ----------------------------------------------------------------------------
+# Pytest (Testing)
+# ----------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+pythonpath = "src"
+log_cli = true
+addopts = """
+    --color=yes
+    --rootdir=.
+    --junitxml=test-results.xml
+    --cov
+    --no-cov-on-fail
+    --cov-report=lcov
+    --cov-report=term-missing
+"""
+
+# ----------------------------------------------------------------------------
+# Coverage (Reporting)
+# ----------------------------------------------------------------------------
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/_version.py"]
+
+[tool.coverage.report]
+exclude_also = [
+    "from ._version",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@(abc\\.)?abstractmethod",
+]

hdx_python_database-1.4.0/src/hdx/database/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.4.0'
+__version_tuple__ = version_tuple = (1, 4, 0)
+
+__commit_id__ = commit_id = None