Initial Instapaper API v2 Python SDK (0.1.0)

Signed-off-by: Brian Donohue <brian@team.instapaper.com>

Author: Donohue

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+      - name: Type check
+        run: mypy instapaper tests examples
+      - name: Test
+        run: pytest --cov=instapaper --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Check the tag matches the package version
+        run: |
+          version=$(python -c "import re, pathlib; print(re.search(r'__version__ = \"(.+?)\"', pathlib.Path('instapaper/__init__.py').read_text()).group(1))")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME doesn't match __version__ $version"
+            exit 1
+          fi
+      - name: Install
+        run: pip install -e ".[dev]" build twine
+      - name: Test
+        run: pytest
+      - name: Build
+        run: |
+          python -m build
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.swp
+*.swo
+*.egg-info/
+dist/
+build/
+venv/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/

BUILD.md

@@ -0,0 +1,96 @@
+# Build Instructions
+
+## Prerequisites
+
+- Python 3.10 or later
+- pip
+
+## Setup
+
+Create a virtual environment and install the package with the development extras:
+
+```sh
+python3 -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+```
+
+For builds and releases, also install the build extras:
+
+```sh
+pip install -e ".[build]"
+```
+
+## Running tests
+
+```sh
+pytest
+```
+
+With coverage:
+
+```sh
+pytest --cov=instapaper --cov-report=term-missing
+```
+
+## Linting and formatting
+
+```sh
+ruff check .
+ruff format --check .
+```
+
+Use `ruff format .` to apply formatting.
+
+## Type checking
+
+```sh
+mypy instapaper tests examples
+```
+
+## Building
+
+```sh
+python -m build
+twine check dist/*
+```
+
+This writes a source distribution and a wheel to `dist/`.
+
+## Releasing
+
+Releases are published to PyPI by GitHub Actions when a version tag is pushed.
+
+1. Update `__version__` in `instapaper/__init__.py`.
+2. Move the changes under a dated version heading in `CHANGELOG.md`.
+3. Commit, then tag and push:
+
+   ```sh
+   git tag v0.1.0
+   git push origin main v0.1.0
+   ```
+
+The `release` workflow checks that the tag matches `__version__`, builds the package, and publishes it.
+
+### One-time PyPI setup
+
+The release workflow uses PyPI trusted publishing, so no API token is stored in GitHub. Before the first release:
+
+1. Sign in to PyPI with the Instapaper account.
+2. Go to **Your projects > Publishing** (for a project that doesn't exist yet, use **Add a new pending publisher**).
+3. Add a GitHub publisher with:
+   - PyPI project name: `instapaper-api`
+   - Owner: `Instapaper`
+   - Repository: `instapaper-api-python`
+   - Workflow: `release.yml`
+   - Environment: `pypi`
+4. In the GitHub repository settings, create an environment named `pypi`. Adding required reviewers there makes each release wait for approval.
+
+### Publishing manually
+
+If you need to publish without the workflow:
+
+```sh
+python -m build
+twine upload dist/*
+```

CHANGELOG.md

@@ -0,0 +1,16 @@
+# 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).
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Client for the Instapaper API v2: bookmarks, folders, tags, highlights, and the current user.
+- Pagination with `bookmarks.iterate()` and change syncing with `bookmarks.changes()` and `bookmarks.sync()`.
+- Parsed article text with `bookmarks.parse()`, including Instaparser keys for non-personal use.
+- OAuth 2 helpers for building the authorization URL and exchanging a code for an access token.
+- Typed models and an exception hierarchy keyed on HTTP status.

CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thanks for helping improve the Instapaper API Python library. Bug reports, fixes, and documentation improvements are all welcome.
+
+## Reporting issues
+
+Open a [GitHub issue](https://github.com/Instapaper/instapaper-api-python/issues). Search existing issues first, and include:
+
+- The library version (`instapaper.__version__`) and your Python version
+- The method you called and the arguments you passed
+- What you expected to happen and what happened instead, including the full traceback
+
+Leave access tokens, client secrets, and Instaparser keys out of issues, logs, and code samples.
+
+For questions about the API itself, such as endpoints, rate limits, or application approval, see the [developer documentation](https://www.instapaper.com/developers/overview/getting-started) or email support@instapaper.com.
+
+### Security issues
+
+Don't open a public issue for a security vulnerability. Email support@instapaper.com instead.
+
+## Making changes
+
+1. Fork the repository and create a branch from `main`.
+2. Set up a development environment as described in [BUILD.md](BUILD.md).
+3. Make your change, with tests.
+4. Run the same checks CI runs:
+
+   ```sh
+   ruff check .
+   ruff format --check .
+   mypy instapaper tests examples
+   pytest
+   ```
+
+5. Open a pull request that explains what changed and why.
+
+### Guidelines
+
+- **No runtime dependencies.** The library uses only the Python standard library. Development tools belong in the `dev` extra in `pyproject.toml`.
+- **Python 3.10 and later.** CI runs on 3.10 through 3.13, so avoid features newer than 3.10.
+- **Everything is typed.** mypy runs with `disallow_untyped_defs`, including on tests and examples.
+- **Tests don't touch the network.** Use the `client` and `transport` fixtures from `tests/conftest.py`. `FakeTransport` records each request and returns responses you queue, so a test can assert on the method, URL, and body the client sent.
+- **Match the API.** Parameter names, defaults, and validation should follow the [API reference](https://www.instapaper.com/developers/overview/getting-started). This library aims to behave the same as the official TypeScript SDK, so a change to shared behavior may need a matching change there.
+- **Update the docs.** Add user-facing changes to the unreleased version at the top of [CHANGELOG.md](CHANGELOG.md), and update [README.md](README.md) when you add or change public API.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

LICENSE

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