credchain 0.1.0__tar.gz

credchain-0.1.0/.gitattributes

@@ -0,0 +1,10 @@
+# Store and check out text files as LF on every platform, overriding a local
+# core.autocrlf=true that would otherwise produce phantom EOL-only diffs.
+# text=auto leaves detected binaries untouched; eol=lf pins the *working tree*.
+* text=auto eol=lf
+
+# cmd.exe reads batch files by byte offset, so LF-only endings break labels
+# and goto. Do NOT add *.ps1 here: PowerShell is cross-platform, and CRLF
+# breaks the shebang of a .ps1 meant to run on Linux/macOS.
+*.bat text eol=crlf
+*.cmd text eol=crlf

credchain-0.1.0/.github/workflows/publish-test.yml

@@ -0,0 +1,40 @@
+name: Publish to TestPyPI
+on:
+  workflow_dispatch:
+
+jobs:
+  test-pypi-publish:
+    name: Upload to TestPyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # For PyPI's trusted publishing
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build
+        run: uv build
+
+      - name: Check version format
+        run: |
+          # Extract version from the built package
+          VERSION=$(ls dist/*.whl | head -n1 | sed -E 's/.*-([0-9].*)-.*/\1/')
+          echo "Package version: $VERSION"
+
+          # Check if version contains dev/post markers (development version)
+          if [[ "$VERSION" =~ (dev|post.*dev) ]]; then
+            echo "❌ ERROR: Cannot publish development version: $VERSION"
+            echo "Please create a proper Git tag first (e.g., 'git tag v0.1.0')"
+            exit 1
+          fi
+
+          echo "✅ Version $VERSION is valid for publishing"
+
+      - name: Publish to TestPyPI
+        run: uv publish --publish-url https://test.pypi.org/legacy/ -v dist/*

credchain-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Upload to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # For PyPI's trusted publishing
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build
+        run: uv build
+
+      - name: Check version format
+        run: |
+          # Extract version from the built package
+          VERSION=$(ls dist/*.whl | head -n1 | sed -E 's/.*-([0-9].*)-.*/\1/')
+          echo "Package version: $VERSION"
+
+          # Check if version contains dev/post markers (development version)
+          if [[ "$VERSION" =~ (dev|post.*dev) ]]; then
+            echo "❌ ERROR: Cannot publish development version: $VERSION"
+            echo "Please create a proper Git tag first (e.g., 'git tag v0.1.0')"
+            exit 1
+          fi
+
+          echo "✅ Version $VERSION is valid for publishing"
+
+      - name: Publish to PyPI
+        run: uv publish -v dist/*

credchain-0.1.0/.github/workflows/run-static.yml

@@ -0,0 +1,58 @@
+name: Run static analysis
+
+env:
+  # Enable colored output
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+
+  # Run on all pull requests because these checks are required and will block merges otherwise
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  static_analysis:
+    timeout-minutes: 2
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Check lockfile is up to date
+        run: |
+          if ! uv lock --check; then
+            echo "❌ Lockfile is out of date!"
+            echo "To update the lockfile, run 'uv lock'."
+            exit 1
+          fi
+          echo "✅ Lockfile is up to date"
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Check formatting
+        run: uv run ruff format --check src tests
+
+      - name: Type checking
+        run: uv run ty check src

credchain-0.1.0/.github/workflows/run-tests.yml

@@ -0,0 +1,51 @@
+name: Run tests
+
+env:
+  # Enable colored output
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+
+  # Run on all pull requests because these checks are required and will block merges otherwise
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  run_tests:
+    name: "Run tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10"]
+      fail-fast: false
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        # Run with frozen to use the current lockfile; static checks will determine if it needs updating
+        run: uv sync --frozen
+
+      - name: Run tests
+        run: uv run pytest

credchain-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv/
+
+# Log files
+*.log
+
+# Coverage reports
+.coverage
+htmlcov/
+.pytest_cache/
+
+# VSCode settings
+.vscode/PythonImportHelper-v2-Completion.json
+
+# Claude Code local settings (tool permissions, personal overrides — not shared)
+.claude/settings.local.json

credchain-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+fail_fast: false
+
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    hooks:
+      - id: prettier
+        types_or: [yaml, json]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.15.12
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      # Run the formatter.
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        entry: uv run ty check
+        language: system
+        types: [python]
+        files: ^src/|^tests/
+        pass_filenames: false
+        require_serial: true
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell # See pyproject.toml for args
+        additional_dependencies:
+          - tomli

credchain-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing <!-- omit in toc -->
+
+Thank you for your interest in contributing to `credchain`! This document
+provides guidelines for setting up a development environment, making changes,
+and testing them locally before pushing to GitHub.
+
+- [Development Setup](#development-setup)
+  - [Prerequisites](#prerequisites)
+  - [Clone and install](#clone-and-install)
+- [Code Quality](#code-quality)
+  - [Enable automatic execution on git commit](#enable-automatic-execution-on-git-commit)
+  - [Manual execution](#manual-execution)
+- [Testing](#testing)
+- [Release Process](#release-process)
+  - [Testing a release first](#testing-a-release-first)
+- [Building Packages Locally](#building-packages-locally)
+- [Dependency Management](#dependency-management)
+
+## Development Setup
+
+### Prerequisites
+
+- [Python 3.10](https://www.python.org/downloads) or later
+- [uv](https://docs.astral.sh/uv/) — fast Python package manager
+
+### Clone and install
+
+```bash
+git clone https://github.com/stephaneberle9/python-credchain.git
+cd python-credchain
+uv sync
+```
+
+## Code Quality
+
+This project uses `pre-commit` hooks for static checks to maintain high code
+quality standards:
+
+| Hook | Purpose |
+| ---- | ------- |
+| `ruff-check` | Python linting (with auto-fix) |
+| `ruff-format` | Python code formatting |
+
+### Enable automatic execution on git commit
+
+```bash
+uv run pre-commit install
+```
+
+### Manual execution
+
+```bash
+# Run all checks on all files
+uv run pre-commit run --all-files
+
+# Run individual tools
+uv run ruff format src tests      # Code formatting
+uv run ruff check --fix src tests # Linting with auto-fix
+uv run ty check src               # Type checking
+```
+
+## Testing
+
+```bash
+# Run all tests with coverage
+uv run pytest
+
+# Run a specific test file
+uv run pytest tests/test_chain.py
+
+# Run with verbose output
+uv run pytest -v
+
+# Show only a coverage summary (skip HTML report)
+uv run pytest --cov-report=term-missing --no-cov-on-fail
+```
+
+Coverage is collected from `src/credchain` and an HTML report is written
+to `htmlcov/`.
+
+## Release Process
+
+1. Ensure all changes are committed and the `main` branch is up to date.
+
+2. Create and push a version tag:
+
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+3. Create a GitHub release from the tag and add release notes. The
+   `publish.yml` workflow triggers automatically and uploads the package to
+   PyPI.
+
+The package version is derived automatically from the git tag by
+[uv-dynamic-versioning](https://github.com/nicoddemus/uv-dynamic-versioning).
+
+### Testing a release first
+
+To publish to TestPyPI before a real release, trigger the `publish-test.yml`
+workflow manually from the **Actions** tab on GitHub (select **Run workflow**).
+
+## Building Packages Locally
+
+```bash
+uv build
+ls dist/
+```
+
+This produces both a wheel (`.whl`) and a source distribution (`.tar.gz`).
+
+## Dependency Management
+
+Dependencies are pinned in `uv.lock` for reproducible installs. After adding or
+changing dependencies in `pyproject.toml`:
+
+```bash
+uv lock        # update the lockfile
+uv sync        # sync your environment to the new lockfile
+```
+
+> [!IMPORTANT]
+> Always commit both `pyproject.toml` and `uv.lock` together.

credchain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephan Eberle
+
+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.

credchain-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: credchain
+Version: 0.1.0
+Summary: Credential provider chain: read usernames, passwords and tokens from environment variables, the OS keychain or secret files, with automatic fallback.
+Author-email: Stephan Eberle <stephaneberle9@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Provides-Extra: keyring
+Requires-Dist: keyring>=25.0.0; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# credchain <!-- omit in toc -->
+
+Read the credentials an application needs — a username and password, or an
+API token — from environment variables, the OS keychain or secret files, with
+automatic fallback through a priority chain.
+
+`credchain` has no framework dependency. FastMCP servers that also take
+credentials from HTTP headers use
+[fastmcp-creds](https://github.com/stephaneberle9/fastmcp-creds), which builds
+on it.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Credential provider chain](#credential-provider-chain)
+  - [Environment variables](#environment-variables)
+  - [OS keychain](#os-keychain)
+  - [Secret files](#secret-files)
+- [Logging](#logging)
+- [API Reference](#api-reference)
+  - [`CredentialsProvider`](#credentialsprovider)
+  - [`CredentialsProviderChain`](#credentialsproviderchain)
+  - [`EnvironmentCredentialsProvider`](#environmentcredentialsprovider)
+  - [`KeyringCredentialsProvider`](#keyringcredentialsprovider)
+  - [`FileCredentialsProvider`](#filecredentialsprovider)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+The package is not published to PyPI yet. Install it from its Git repository
+or a local checkout:
+
+```bash
+uv add "credchain @ git+https://github.com/stephaneberle9/python-credchain.git"
+# with the OS keychain provider:
+uv add "credchain[keyring] @ git+https://github.com/stephaneberle9/python-credchain.git"
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+### Credential provider chain
+
+Compose providers in priority order. The chain tries each in sequence and
+returns the first result where both username and password (or token) are
+non-empty.
+
+```python
+from credchain import CredentialsProviderChain, EnvironmentCredentialsProvider
+from credchain.keyring import KeyringCredentialsProvider  # optional dep
+
+chain = CredentialsProviderChain([
+    EnvironmentCredentialsProvider("MY_USERNAME", "MY_PASSWORD"),
+    KeyringCredentialsProvider("my-service"),
+])
+
+username, password = chain.get_credentials()
+```
+
+A provider that raises is logged (exception type only) and skipped.
+
+### Environment variables
+
+```python
+from credchain import EnvironmentCredentialsProvider
+
+provider = EnvironmentCredentialsProvider("MY_USERNAME", "MY_PASSWORD")
+token_provider = EnvironmentCredentialsProvider.for_token("MY_API_TOKEN")
+```
+
+### OS keychain
+
+Reads credentials stored in the OS keychain via
+[`keyring`](https://pypi.org/project/keyring/). Requires `credchain[keyring]`.
+
+```python
+from credchain.keyring import KeyringCredentialsProvider
+
+provider = KeyringCredentialsProvider("my-service")            # "username" + "password" entries
+provider = KeyringCredentialsProvider.for_token("my-service")  # one "token" entry
+provider = KeyringCredentialsProvider("my-service", timeout=10)
+```
+
+The keychain lookup is bounded by a timeout (default 5 seconds), so a locked
+or unresponsive keychain, e.g. one waiting for an unlock prompt in a headless
+session, cannot hang the caller. On timeout, a warning is logged and
+`(None, None)` is returned, so a chain falls through to its next provider.
+
+### Secret files
+
+Reads one value per file, such as a secret mounted into a container. One
+trailing line break is removed; a missing file means no credentials.
+
+```python
+from credchain import FileCredentialsProvider
+
+provider = FileCredentialsProvider("/run/secrets/username", "/run/secrets/password")
+token_provider = FileCredentialsProvider.for_token("/run/secrets/api-token")
+```
+
+## Logging
+
+Providers log at debug level where they looked and whether they found
+something, never a credential or any part of one: in token mode the token is
+returned in both positions, so even a "username" can be a secret. Errors are
+logged with their exception type only, because messages may quote values.
+
+## API Reference
+
+### `CredentialsProvider`
+
+A `Protocol`: any object with a
+`get_credentials() -> tuple[str | None, str | None]` method satisfies it.
+
+### `CredentialsProviderChain`
+
+`CredentialsProviderChain(providers)` — tries each provider in order and
+returns the first result where both values are non-empty, else
+`(None, None)`.
+
+### `EnvironmentCredentialsProvider`
+
+`EnvironmentCredentialsProvider(username_env_var_name, password_env_var_name)`
+reads two environment variables;
+`EnvironmentCredentialsProvider.for_token(token_env_var_name)` reads one and
+returns it as both elements.
+
+### `KeyringCredentialsProvider`
+
+`KeyringCredentialsProvider(service, username_key="username", password_key="password", timeout=5.0)`
+reads two keychain entries of `service`;
+`KeyringCredentialsProvider.for_token(service, token_key="token", timeout=5.0)`
+reads one. `timeout=None` waits indefinitely. Requires `credchain[keyring]`.
+
+### `FileCredentialsProvider`
+
+`FileCredentialsProvider(username_file, password_file)` reads two files;
+`FileCredentialsProvider.for_token(token_file)` reads one. Errors other than a
+missing file propagate.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).