initial commit

tind_client/
  api.py
  fetch.py
adapted from https://github.com/BerkeleyLibrary/willa

claude-assisted

Author: jason-raitz

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[test,lint]"
+
+      - name: Lint with pylint
+        run: pylint tind_client/
+
+      - name: Type-check with mypy
+        run: mypy tind_client/
+
+      - name: Run tests
+        run: pytest

.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.eggs/
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checker caches
+.mypy_cache/
+.dmypy.json
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Env files
+.env
+.env.*

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release
+- Basic project structure
+- Implemented TINDClient to wrap API interactions
+
+### Changed
+- N/A
+
+### Deprecated
+- N/A
+
+### Removed
+- N/A
+
+### Fixed
+- N/A
+
+### Security
+- N/A

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Regents of the University of California
+
+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.

README.md

@@ -0,0 +1,79 @@
+# python-tind-client
+
+Python library for interacting with the [TIND ILS](https://tind.io) API.
+
+## Requirements
+
+- Python 3.13+
+
+## Installation
+
+```bash
+pip install python-tind-client
+```
+
+Install with optional development dependencies:
+
+```bash
+pip install "python-tind-client[dev]"    # test + lint + debug
+pip install "python-tind-client[test]"   # pytest + requests-mock
+pip install "python-tind-client[lint]"   # mypy + pydoclint + pylint
+pip install "python-tind-client[debug]"  # debugpy
+```
+
+## Configuration
+
+Create a `TINDClient` with explicit configuration values:
+
+- `api_key` (required): Your TIND API token
+- `api_url` (required): Base URL of the TIND instance (e.g. `https://tind.example.edu`)
+- `default_storage_dir` (optional): Default output directory for downloaded files
+
+## Usage
+
+```python
+from tind_client import TINDClient
+
+client = TINDClient(
+	api_key="your-token",
+	api_url="https://tind.example.edu",
+	default_storage_dir="/tmp",
+)
+
+# Fetch MARC metadata for a record
+record = client.fetch_metadata("12345")
+print(record["245"]["a"])  # title
+
+# Download a file
+path = client.fetch_file("https://tind.example.edu/files/12345/download")
+
+# Search and retrieve PyMARC records
+records = client.search("title:python programming", result_format="pymarc")
+```
+
+## Functional fetch API
+
+The functions in `tind_client.fetch` are available for direct use and now accept
+explicit credentials instead of a client object.
+
+```python
+from tind_client.fetch import fetch_metadata
+
+record = fetch_metadata(
+	"12345",
+	api_key="your-token",
+	api_url="https://tind.example.edu",
+)
+```
+
+For most use cases, prefer `TINDClient` methods as the primary interface.
+
+## Running tests
+
+```bash
+pytest
+```
+
+## License
+
+MIT — © 2026 The Regents of the University of California

pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-tind-client"
+version = "0.1.0"
+description = "Python library for interacting with the TIND API"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Jason Raitz", email = "raitz@berkeley.edu" },
+]
+requires-python = ">=3.13"
+dependencies = [
+    "requests>=2.32",
+    "pymarc>=5.2",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.3",
+    "requests-mock>=1.12",
+]
+lint = [
+    "mypy>=1.14",
+    "pydoclint>=0.5",
+    "pylint>=3.3",
+    "types-requests>=2.32",
+]
+debug = [
+    "debugpy>=1.8",
+]
+dev = [
+    "python-tind-client[test,lint,debug]",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tind_client*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+
+[tool.pylint.main]
+py-version = "3.13"
+
+[tool.pylint.messages_control]
+disable = ["C0114"]  # missing-module-docstring — already covered by file-level docstrings

tests/__init__.py

@@ -0,0 +1,43 @@
+"""
+Shared pytest fixtures for python-tind-client tests.
+"""
+
+import pytest
+from tind_client import TINDClient
+
+
+SAMPLE_MARC_XML = """\
+<?xml version="1.0" encoding="UTF-8"?>
+<collection xmlns="http://www.loc.gov/MARC21/slim">
+  <record>
+    <leader>00000nam a2200000 i 4500</leader>
+    <controlfield tag="001">12345</controlfield>
+    <datafield tag="245" ind1="1" ind2="0">
+      <subfield code="a">Sample Title</subfield>
+    </datafield>
+  </record>
+</collection>"""
+
+
+@pytest.fixture
+def tind_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Set required TIND environment variables for a test."""
+    monkeypatch.setenv("TIND_API_KEY", "test-api-key")
+    monkeypatch.setenv("TIND_API_URL", "https://tind.example.edu")
+    monkeypatch.setenv("DEFAULT_STORAGE_DIR", "/tmp")
+
+
+@pytest.fixture
+def sample_marc_xml() -> str:
+    """Return a minimal, valid MARC XML string containing one record."""
+    return SAMPLE_MARC_XML
+
+
+@pytest.fixture
+def client() -> TINDClient:
+    """Return a configured TINDClient instance for tests."""
+    return TINDClient(
+        api_key="test-api-key",
+        api_url="https://tind.example.edu",
+        default_storage_dir="/tmp",
+    )