Rename PyPI distribution to diffbot (3.0.0); final diffbot-python 0.3.0

The import name stays `diffbot`; only the distribution name moves. 3.0.0 sorts
above the unrelated 2012-2015 releases (0.1-2.0.0, now yanked) on that name.

legacy/diffbot-python builds a final, frozen diffbot-python 0.3.0 with the
same code, a LEGACY README/summary, and no dependency on diffbot, so
`pip install -U diffbot-python` upgrades cleanly instead of deleting shared
files. Importing diffbot warns (FutureWarning) whenever diffbot-python is
installed, pointing at the migration command.

Makefile release targets take PKG/PYPROJECT; build-legacy, release-legacy
and release-test-legacy ship the final diffbot-python.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: shixish

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test test-live build clean bump-patch bump-minor bump-major set-token-pypi set-token-testpypi release-test release verify-release-test verify-release
+.PHONY: test test-live build build-legacy release-legacy release-test-legacy clean bump-patch bump-minor bump-major set-token-pypi set-token-testpypi release-test release _release-test _release verify-release-test verify-release
 
 test:
 	uv run --extra dev pytest
@@ -9,9 +9,24 @@ test-live:
 clean:
 	rm -rf dist build *.egg-info
 
+# Distribution to publish/verify. The legacy targets override this with
+# PKG=diffbot-python to ship the final diffbot-python release.
+PKG ?= diffbot
+PYPROJECT ?= pyproject.toml
+
 build: clean
 	uv build
 
+# Build the final diffbot-python release into dist/: today's src/diffbot under
+# the old name (see legacy/diffbot-python). Staged in build/ because the package
+# code lives outside that directory.
+build-legacy: clean
+	mkdir -p build
+	cp -R legacy/diffbot-python build/legacy
+	cp -R src build/legacy/src
+	find build/legacy -name __pycache__ -prune -exec rm -rf {} +
+	uv build build/legacy --out-dir dist
+
 # Version bumps: edits pyproject.toml in place and prints old => new.
 bump-patch:
 	uv version --bump patch
@@ -39,11 +54,13 @@ set-token-testpypi:
 
 # Publish to TestPyPI. Token comes from macOS Keychain (service: pypi-token-testpypi).
 # The `@` on the recipe lines hides the actual command so the token never appears in output.
-release-test: build
-	@VERSION=$$(grep '^version' pyproject.toml | head -1 | cut -d'"' -f2) && \
-	  STATUS=$$(curl -s -o /dev/null -w "%{http_code}" "https://test.pypi.org/pypi/diffbot-python/$$VERSION/json") && \
+release-test: build _release-test
+
+_release-test:
+	@VERSION=$$(grep '^version' $(PYPROJECT) | head -1 | cut -d'"' -f2) && \
+	  STATUS=$$(curl -s -o /dev/null -w "%{http_code}" "https://test.pypi.org/pypi/$(PKG)/$$VERSION/json") && \
 	  if [ "$$STATUS" = "200" ]; then \
-	    echo "ERROR: diffbot-python $$VERSION is already on TestPyPI. Bump the version in pyproject.toml."; \
+	    echo "ERROR: $(PKG) $$VERSION is already on TestPyPI. Bump the version in pyproject.toml."; \
 	    exit 1; \
 	  fi
 	@TOKEN=$$(security find-generic-password -s pypi-token-testpypi -w 2>/dev/null) && \
@@ -54,14 +71,16 @@ release-test: build
 	  UV_PUBLISH_TOKEN="$$TOKEN" uv publish --publish-url https://test.pypi.org/legacy/
 
 # Publish to real PyPI. Confirmation gate before upload (PyPI does not allow re-uploads).
-release: build
-	@VERSION=$$(grep '^version' pyproject.toml | head -1 | cut -d'"' -f2) && \
-	  STATUS=$$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/diffbot-python/$$VERSION/json") && \
+release: build _release
+
+_release:
+	@VERSION=$$(grep '^version' $(PYPROJECT) | head -1 | cut -d'"' -f2) && \
+	  STATUS=$$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/$(PKG)/$$VERSION/json") && \
 	  if [ "$$STATUS" = "200" ]; then \
-	    echo "ERROR: diffbot-python $$VERSION is already on PyPI. Bump the version in pyproject.toml."; \
+	    echo "ERROR: $(PKG) $$VERSION is already on PyPI. Bump the version in pyproject.toml."; \
 	    exit 1; \
 	  fi && \
-	  echo "About to publish diffbot-python $$VERSION to PyPI. This cannot be undone." && \
+	  echo "About to publish $(PKG) $$VERSION to PyPI. This cannot be undone." && \
 	  read -p "Type the version to confirm: " CONFIRM && \
 	  [ "$$CONFIRM" = "$$VERSION" ] || { echo "Aborted."; exit 1; }
 	@TOKEN=$$(security find-generic-password -s pypi-token-pypi -w 2>/dev/null) && \
@@ -75,20 +94,28 @@ release: build
 # `cd $$TMP` before running python so CWD doesn't shadow the venv install with this repo's source.
 # Deps live on prod PyPI, so TestPyPI install needs --extra-index-url.
 verify-release-test:
-	@VERSION=$$(grep '^version' pyproject.toml | head -1 | cut -d'"' -f2) && \
+	@VERSION=$$(grep '^version' $(PYPROJECT) | head -1 | cut -d'"' -f2) && \
 	  TMP=$$(mktemp -d) && \
 	  uv venv --python 3.12 $$TMP/.venv >/dev/null 2>&1 && \
 	  uv pip install --quiet --python $$TMP/.venv/bin/python \
 	    --index-url https://test.pypi.org/simple/ \
 	    --extra-index-url https://pypi.org/simple/ \
-	    "diffbot-python==$$VERSION" && \
+	    "$(PKG)==$$VERSION" && \
 	  (cd $$TMP && $$TMP/.venv/bin/python -c "import diffbot; print('TestPyPI install OK:', diffbot.__version__)") && \
 	  rm -rf $$TMP
 
 verify-release:
-	@VERSION=$$(grep '^version' pyproject.toml | head -1 | cut -d'"' -f2) && \
+	@VERSION=$$(grep '^version' $(PYPROJECT) | head -1 | cut -d'"' -f2) && \
 	  TMP=$$(mktemp -d) && \
 	  uv venv --python 3.12 $$TMP/.venv >/dev/null 2>&1 && \
-	  uv pip install --quiet --python $$TMP/.venv/bin/python "diffbot-python==$$VERSION" && \
+	  uv pip install --quiet --python $$TMP/.venv/bin/python "$(PKG)==$$VERSION" && \
 	  (cd $$TMP && $$TMP/.venv/bin/python -c "import diffbot; print('PyPI install OK:', diffbot.__version__)") && \
 	  rm -rf $$TMP
+
+# Publish the final diffbot-python release. Reuses the targets above with the
+# legacy package's name/pyproject; `make build` is swapped for build-legacy.
+release-test-legacy: build-legacy
+	@$(MAKE) --no-print-directory _release-test PKG=diffbot-python PYPROJECT=legacy/diffbot-python/pyproject.toml
+
+release-legacy: build-legacy
+	@$(MAKE) --no-print-directory _release PKG=diffbot-python PYPROJECT=legacy/diffbot-python/pyproject.toml

README.md

@@ -1,5 +1,9 @@
 # Diffbot Python Library
 
+> ⚠️ **The PyPI package is now [`diffbot`](https://pypi.org/project/diffbot/)** (`pip install diffbot`).
+> `diffbot-python` is legacy and its final release (0.3.0) will never be updated.
+> See [Installation](#installation) to migrate.
+
 Python client library for [Diffbot](https://www.diffbot.com) APIs.
 
 
@@ -14,9 +18,13 @@ curl -fsSL https://raw.githubusercontent.com/diffbot/diffbot-python/main/install
 If you prefer, the full Python library can also be installed with pip:
 
 ```bash
-python3 -m pip install diffbot-python
+python3 -m pip install diffbot
 ```
 
+> This package was formerly published as `diffbot-python`, whose final release (0.3.0) gets no further updates.
+> If you're upgrading from it, run `pip uninstall diffbot-python && pip install --force-reinstall diffbot`
+> and replace `diffbot-python` with `diffbot` in your requirements.
+
 For local development:
 
 ```bash

install.sh

@@ -127,7 +127,7 @@ if [ -e "$target" ]; then
     info "but your Python package manager still treats the file as its own — a later"
     info "'pip install --upgrade' / 'uv tool upgrade' could clobber it again, and an"
     info "uninstall would delete it. To avoid the conflict, remove the managed copy first:"
-    info "  pip uninstall diffbot-python    # or: uv tool uninstall diffbot-python"
+    info "  pip uninstall diffbot           # or: uv tool uninstall diffbot (older installs: diffbot-python)"
     info ""
     info "Proceeding to overwrite ${target}..."
   else
@@ -162,8 +162,8 @@ if [ -n "$existing" ] && [ "$existing" != "$target" ]; then
   info "Note: another '${BIN_NAME}' is first on your PATH and will take precedence:"
   info "  ${existing}"
   if is_python_console_script "$existing"; then
-    info "  (it looks pip/uv-managed; remove it with 'pip uninstall diffbot-python'"
-    info "   or 'uv tool uninstall diffbot-python', or put ${BIN_DIR} earlier on PATH.)"
+    info "  (it looks pip/uv-managed; remove it with 'pip uninstall diffbot'"
+    info "   or 'uv tool uninstall diffbot' (older installs: diffbot-python), or put ${BIN_DIR} earlier on PATH.)"
   fi
 fi
 

legacy/diffbot-python/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Diffbot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

legacy/diffbot-python/README.md

@@ -0,0 +1,36 @@
+# ⚠️ LEGACY PACKAGE — `diffbot-python` is now `diffbot` ⚠️
+
+> ## 🛑 Do not install `diffbot-python`. Install [`diffbot`](https://pypi.org/project/diffbot/) instead:
+>
+> ```bash
+> pip uninstall diffbot-python
+> pip install diffbot
+> ```
+>
+> **This is the final release of `diffbot-python` (0.3.0). It will never be updated again**:
+> no bug fixes, no new Diffbot API features, no security fixes.
+
+---
+
+The Diffbot Python library and `db` CLI now live at
+**[diffbot](https://pypi.org/project/diffbot/)**. The import name is unchanged
+(`import diffbot`), so no code changes are needed.
+
+This release contains the same code as `diffbot` 3.0.0 so existing installs keep
+working, but it prints a warning on every import until you migrate.
+
+## Migrating
+
+1. Replace `diffbot-python` with `diffbot` in your `requirements.txt`, `pyproject.toml`, etc.
+2. Uninstall the old package **before** installing the new one:
+
+   ```bash
+   pip uninstall diffbot-python
+   pip install diffbot
+   ```
+
+   Both packages provide the same `diffbot` module, so uninstalling
+   `diffbot-python` after `diffbot` is installed deletes files that `diffbot`
+   needs. If that happened, run `pip install --force-reinstall diffbot`.
+
+Source and issues: <https://github.com/diffbot/diffbot-python>.

legacy/diffbot-python/pyproject.toml

@@ -0,0 +1,46 @@
+# Final release under the old distribution name. diffbot-python was renamed to
+# diffbot (3.0.0+). This release freezes the current library code under the old
+# name and warns on import, so `pip install -U diffbot-python` keeps working
+# while pointing users at the new package. It deliberately does NOT depend on
+# diffbot: both ship the same top-level `diffbot` module, and installing them
+# together lets pip delete one's files when it uninstalls the other.
+#
+# `make build-legacy` copies ../../src next to this file before building, so
+# keep dependencies and scripts in step with the main pyproject.toml.
+# Published with `make release-legacy`.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "diffbot-python"
+version = "0.3.0"
+description = "⚠️ LEGACY — renamed to diffbot. Final release, no further updates: pip install diffbot"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Jerome Choo", email = "jerome@diffbot.com" },
+    { name = "Mike Tung", email = "miket@diffbot.com" }
+]
+classifiers = [
+    "Development Status :: 7 - Inactive",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "click>=8.1.0",
+    "rich>=13.0.0",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/diffbot/"
+Repository = "https://github.com/diffbot/diffbot-python"
+
+[project.scripts]
+db = "diffbot.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/diffbot"]

pyproject.toml

@@ -3,8 +3,8 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [project]
-name = "diffbot-python"
-version = "0.2.3"
+name = "diffbot"
+version = "3.0.0"
 description = "Python client library for Diffbot APIs"
 readme = "README.md"
 requires-python = ">=3.9"

scripts/build_binary.sh

@@ -111,7 +111,7 @@ log "Running PyInstaller"
   --workpath "$WORK_DIR" \
   --specpath "$WORK_DIR" \
   --collect-submodules diffbot \
-  --copy-metadata diffbot-python \
+  --copy-metadata diffbot \
   "$ENTRY_SCRIPT" >&2
 
 BINARY="${OUTPUT_DIR}/${ASSET}"

src/diffbot/__init__.py

@@ -2,12 +2,35 @@
 diffbot - Python client library for the Diffbot APIs.
 """
 
+import warnings as _warnings
 from importlib.metadata import PackageNotFoundError, version as _version
 
-try:
-    __version__ = _version("diffbot-python")
-except PackageNotFoundError:  # not installed (e.g. running from a source tree)
-    __version__ = "0.0.0"
+def _installed_version(dist: str):
+    try:
+        return _version(dist)
+    except PackageNotFoundError:
+        return None
+
+
+# The distribution was renamed from diffbot-python to diffbot. The final
+# diffbot-python release ships this same code (see legacy/diffbot-python), so
+# fall back to its version when that's what is installed.
+_legacy_version = _installed_version("diffbot-python")
+# "0.0.0" when not installed (e.g. running from a source tree).
+__version__ = _installed_version("diffbot") or _legacy_version or "0.0.0"
+
+# Both distributions ship this module, so a diffbot-python install (alone, or
+# left over next to diffbot) should migrate. FutureWarning, unlike
+# DeprecationWarning, is shown by default wherever the import happens.
+if _legacy_version is not None:
+    _warnings.warn(
+        "diffbot-python has been renamed to diffbot and will receive no further "
+        "updates. Run `pip uninstall diffbot-python && pip install "
+        "--force-reinstall diffbot` and replace diffbot-python with diffbot in "
+        "your requirements.",
+        FutureWarning,
+        stacklevel=2,
+    )
 
 from ._auth import resolve_token
 from .ask import json_schema_format