Extract palace.util into a uv workspace package (PP-4076) (#3231)

## Description

Convert the repo into a [`uv`
workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) and
carve out a new namespace package `palace-util` (namespace
`palace.util`) that sits at the bottom of the Palace dependency graph —
other Palace packages depend on it; it depends on no other Palace
package. The package holds the small set of reusable, dependency-light
utilities:

- `palace.util.exceptions` — the base of Palace exception hierarchy 
- `palace.util.datetime_helpers` — timezone-aware datetime helpers.
- `palace.util.log` — the standardized logging toolkit 

## Motivation and Context

Sets up the monorepo as a `uv` workspace and extracts the minimum subset
of palace-manager that needs to come along with the upcoming
`palace-opds` extraction (#3230). Having `palace-util` as its own
workspace member lets both `palace-manager` and `palace-opds` (and
eventually any other Palace project) depend on it without any of them
pulling in each other.

JIRA: PP-4076

## How Has This Been Tested?

- Tests run in CI

## Checklist

- [x] I have updated the documentation accordingly.
- [x] All new and existing tests passed.

Author: jonathangreen

.pre-commit-config.yaml

@@ -76,8 +76,8 @@ repos:
       -   id: check-namespace-package
           name: Check that palace is a namespace package
           language: fail
-          entry: Please remove src/palace/__init__.py
-          files: ^src/palace/__init__.py$
+          entry: Please remove src/palace/__init__.py - palace must remain a PEP 420 namespace.
+          files: (^|/)src/palace/__init__\.py$
 
 # Exclude test files, since they may be intentionally malformed
 exclude: ^tests/files/

CLAUDE.md

@@ -49,7 +49,10 @@ through mobile and web applications.
 
 ## Project Structure
 
-- `/src/palace/manager` - Main application source code
+This repository is a [`uv` workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/). The main
+`palace-manager` application is at the repo root; reusable namespace packages live under `/packages`.
+
+- `/src/palace/manager` - Main application source code (`palace-manager`)
   - `/api` - REST API endpoints for mobile applications
     - `/admin` - Administrative API endpoints for the web dashboard
   - `/celery` - Background worker processes and task definitions
@@ -64,12 +67,21 @@ through mobile and web applications.
   - `/service` - Dependency injection container and service layer
   - `/sqlalchemy` - Database models and schema definitions
   - `/util` - Reusable utility functions and helpers
-- `/tests` - Test files
+- `/packages` - Workspace member packages (each is independently buildable/publishable)
+  - `/palace-util` - Shared utilities under the `palace.util` namespace: exceptions
+    (`BasePalaceException`, `PalaceValueError`, `PalaceTypeError`), datetime helpers, and the full
+    logging toolkit. Import from `palace.util.*` directly.
+- `/tests` - Test files for the whole repository (both `palace-manager` and workspace-member packages)
   - `/files` - Test fixture files
   - `/fixtures` - pytest fixtures shared across test functions
-  - `/manager` - pytest test files (should mirror `src/palace/manager` structure)
+  - `/manager` - pytest test files for `palace-manager` (should mirror `src/palace/manager` structure)
   - `/migration` - Database migration tests
   - `/mocks` - Test mocks (**being phased out - avoid in new code**)
+  - `/palace_util` - pytest test files for the `palace-util` workspace package
+- Workspace-member tests live under the root `tests/<package_name>/` rather than
+  `packages/<name>/tests/` so they share the repo's pytest fixtures and conftest plugins and
+  tooling (mypy, coverage, `testpaths`) has a single tests tree to reason about. When adding a
+  new workspace package, create its test tree as `tests/<package_name>/` alongside the others.
 
 ## Architecture Overview
 

README.md

@@ -15,6 +15,15 @@ Palace Manager is a backend service for digital library systems, maintained by [
 - [Patron Blocking Rules — Allowed Functions](docs/FUNCTIONS.md) —
   Reference for the functions available in patron blocking rule expressions.
 
+## Repository Layout
+
+This repository is a [`uv` workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/). The main
+`palace-manager` application lives at the repo root (`src/palace/manager/`). Reusable namespace packages
+live under `packages/`:
+
+- [`palace-util`](packages/palace-util/README.md) — shared utilities (exceptions, datetime helpers,
+  `LoggerMixin`) under the `palace.util` namespace.
+
 ## Installation
 
 Docker images created from this code are available at:

docker/Dockerfile

@@ -18,8 +18,11 @@ COPY --chmod=644 docker/services/logrotate /etc/
 RUN mv /etc/cron.daily/logrotate /etc/cron.hourly/logrotate
 
 # Copy our uv files into the image and install our dependencies.
+# We copy the workspace-member pyproject.toml files (but not their source) so that
+# uv can resolve workspace members without invalidating this layer on source changes.
 COPY --chown=palace:palace uv.lock pyproject.toml /var/www/circulation/
-RUN uv sync --frozen --no-dev --no-install-project
+COPY --chown=palace:palace packages/palace-util/pyproject.toml /var/www/circulation/packages/palace-util/
+RUN uv sync --frozen --no-dev --no-install-workspace
 
 COPY --chown=palace:palace . /var/www/circulation
 

docker/Dockerfile.baseimage

@@ -60,13 +60,17 @@ RUN useradd -ms /bin/bash -U palace && \
 
 WORKDIR /var/www/circulation
 COPY --chown=palace:palace uv.lock pyproject.toml /var/www/circulation/
+# Workspace-member pyproject.toml files are needed for uv sync to resolve the
+# workspace; we copy just the manifests (not the source) so this layer doesn't
+# get invalidated by source changes.
+COPY --chown=palace:palace packages/palace-util/pyproject.toml /var/www/circulation/packages/palace-util/
 
 # Setup virtualenv and install our python dependencies.
 # What we install is based on the uv.lock file in the repo at the time this
 # image is built. These may get out of date, but we always rerun this step when
 # building the final image, so it will be up to date then. This gives is a base
 # to work from which speeds up the final image build.
-RUN uv sync --frozen --no-dev --no-install-project && \
+RUN uv sync --frozen --no-dev --no-install-workspace && \
     SIMPLIFIED_ENVIRONMENT=/var/www/circulation/environment.sh && \
     echo "if [ -f $SIMPLIFIED_ENVIRONMENT ]; then source $SIMPLIFIED_ENVIRONMENT; fi" >> env/bin/activate && \
     . env/bin/activate && \
@@ -76,5 +80,6 @@ RUN uv sync --frozen --no-dev --no-install-project && \
     rm -Rf /root/.cache && \
     rm pyproject.toml && \
     rm uv.lock && \
+    rm -rf packages && \
     rm -rf /root/.cache && \
     /bd_build/cleanup.sh

packages/palace-util/README.md

@@ -0,0 +1,36 @@
+# palace-util
+
+Small, dependency-light utilities shared across [Palace Project](https://thepalaceproject.org)
+Python packages. Lives in the `palace.util` namespace.
+
+This package exists so that the handful of cross-cutting helpers that *every* Palace package needs
+— a common exception hierarchy, timezone-aware datetime handling, a standardized
+`LoggerMixin` — can be depended on without pulling in the heavier `palace-manager` application.
+Packages that need only these primitives depend on `palace-util` directly; `palace-manager` is
+also just a consumer.
+
+## Scope
+
+`palace-util` sits at the bottom of the Palace dependency graph: **other Palace packages depend
+on `palace-util`; `palace-util` depends on no other Palace package.**
+
+If a utility is only useful inside the Palace Manager application, it does not belong here —
+keep it in `src/palace/manager/util/`. Candidates for `palace-util` should be:
+
+- **Reusable** outside the manager application (e.g., by other Palace services, CLI tools, or
+  by future extracted packages like `palace-opds`).
+- **Runtime-dependency-light** — stdlib-only is the ideal, and in the rare case a third-party
+  library is justified it must be tiny and widely-used. Consumers of `palace-util` should be
+  able to add it to their `pyproject.toml` without materially growing their install footprint.
+- **No intra-Palace dependencies**.
+- **Stable** enough that the wider ecosystem can rely on it without expecting frequent breaking
+  changes.
+
+## Development
+
+This package is a [`uv` workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) member
+of the main [`circulation`](../../README.md) repository. Work on it from the repo root — `uv sync`
+picks up all workspace members automatically; `tox -e py312-docker` runs the full test suite.
+Tests for this package live at the repository root under `tests/palace_util/` (workspace-member
+tests are kept under the root `tests/` tree so they share the repo's pytest fixtures and conftest
+plugins).

packages/palace-util/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[project]
+authors = [{name = "The Palace Project", email = "info@thepalaceproject.org"}]
+dependencies = [
+    "python-dateutil>=2.8,<3",
+]
+description = "Shared utilities for Palace Project packages."
+license = "Apache-2.0"
+name = "palace-util"
+readme = "README.md"
+requires-python = ">=3.12,<4"
+version = "0"
+
+[project.urls]
+Homepage = "https://thepalaceproject.org"
+Repository = "https://github.com/ThePalaceProject/circulation"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/palace"]
+
+[tool.isort]
+combine_as_imports = true
+known_first_party = ["palace.util"]
+profile = "black"
+sections = "FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER"

packages/palace-util/src/palace/util/__init__.py

@@ -0,0 +1,35 @@
+from typing import Any
+
+
+class BasePalaceException(Exception):
+    """Base class for all Exceptions in Palace packages."""
+
+    def __init__(self, message: str | None = None):
+        """Initializes a new instance of BasePalaceException class
+
+        :param message: String containing description of the exception that occurred
+        """
+        super().__init__(message)
+        self.message = message
+
+    def __getstate__(self) -> dict[str, Any]:
+        return {"dict": self.__dict__, "args": self.args}
+
+    def __setstate__(self, state: dict[str, Any] | None) -> None:
+        # The signature must accept None to match BaseException.__setstate__ for mypy.
+        # In practice, state is always a dict from our __getstate__ implementation.
+        assert (
+            state is not None
+        ), "__setstate__ received None; expected dict from __getstate__"
+        self.__dict__.update(state["dict"])
+        self.args = state["args"]
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        state = self.__getstate__()
+        return self.__class__.__new__, (self.__class__,), state
+
+
+class PalaceValueError(BasePalaceException, ValueError): ...
+
+
+class PalaceTypeError(BasePalaceException, TypeError): ...