kiosque 0.2.0__tar.gz

kiosque-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: Code Quality
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+      - name: Run ty type checking
+        run: uvx ty check kiosque/
+        continue-on-error: true
+
+      - name: Run tests (excluding login tests)
+        run: uv run pytest -v -m "not login"

kiosque-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: # Allow manual triggers
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for git info
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system mkdocs-material
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

kiosque-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,132 @@
+name: Build and Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*" # Triggers on version tags like v0.1.0, v1.2.3, etc.
+  workflow_dispatch: # Allow manual triggers
+
+permissions:
+  contents: write # Needed for creating GitHub releases
+  id-token: write # Needed for PyPI trusted publishing
+
+jobs:
+  quality-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run ruff check
+        run: uv run ruff check .
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+      - name: Run type checking
+        run: uvx ty check kiosque/
+        continue-on-error: true
+
+      - name: Run tests (excluding login tests)
+        run: uv run pytest -v -m "not login"
+
+  build:
+    needs: quality-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kiosque
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          # Get the previous tag
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+
+          # Generate changelog from commits since last tag
+          echo "notes<<EOF" >> $GITHUB_OUTPUT
+          echo "## What's Changed" >> $GITHUB_OUTPUT
+          echo "" >> $GITHUB_OUTPUT
+          git log $PREV_TAG..HEAD --pretty=format:"- %s (%h)" --no-merges >> $GITHUB_OUTPUT
+          echo "" >> $GITHUB_OUTPUT
+          echo "" >> $GITHUB_OUTPUT
+          echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/$PREV_TAG...${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: Release v${{ steps.version.outputs.version }}
+          body: ${{ steps.notes.outputs.notes }}
+          draft: false
+          prerelease: false
+          files: |
+            dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

kiosque-0.2.0/.gitignore

@@ -0,0 +1,100 @@
+# Local test/config files
+kiosque.conf
+plan.md
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+systemd/
+_ignore/
+Icon
+site/

kiosque-0.2.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: kiosque
+Version: 0.2.0
+Summary: Save newspaper articles in textual format
+Author-email: Xavier Olive <git@xoolive.org>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: appdirs>=1.4.4
+Requires-Dist: bs4>=0.0.2
+Requires-Dist: click>=8.1.7
+Requires-Dist: httpx-socks>=0.9.2
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: lxml>=5.3.0
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: pypandoc>=1.13
+Requires-Dist: pyperclip>=1.9.0
+Requires-Dist: stamina>=24.3.0
+Requires-Dist: textual>=0.81.0
+Description-Content-Type: text/markdown
+
+# kiosque
+
+A unified tool for news article extraction and bookmark management.
+
+## What is Kiosque?
+
+Kiosque combines three essential capabilities:
+
+1. **Article Extractor (CLI/API)** - Download full-text articles from several paywalled news websites as Markdown
+2. **Bookmark Manager (TUI)** - Browse and manage bookmarks from Raindrop.io and GitHub Stars in a beautiful terminal interface
+3. **Content Aggregator** - Unified tabbed interface for multiple content sources with smart context-aware actions
+
+## Quick Start
+
+```bash
+# Launch TUI (Terminal User Interface) - default
+kiosque
+
+# Extract article to file
+kiosque https://www.lemonde.fr/article output.md
+
+# Print to stdout
+kiosque https://www.nytimes.com/article - | bat - -l md
+
+# Download NYT front page PDF
+kiosque nyt
+```
+
+## Installation
+
+```bash
+# From PyPI
+pip install kiosque
+
+# Or with uv (recommended)
+uv tool install kiosque
+```
+
+**Requirements:** Python 3.12+, pandoc
+
+## Core Features
+
+### 📰 Article Extraction
+
+- **News Websites** - Le Monde, NYT, Guardian, Mediapart, and more
+- **Authentication** - Login support for paywalled sites
+- **Markdown Output** - Clean, readable format with metadata
+- **Proxy Support** - Access geo-blocked websites via SOCKS/HTTP proxies
+
+### 🔖 Bookmark Management
+
+- **Raindrop.io Integration** - Browse, preview, archive, delete, edit tags
+- **GitHub Stars** - Explore starred repos, preview READMEs, unstar
+- **Unified Search** - Filter by title, URL, tags, topics across all sources
+- **Beautiful Previews** - Markdown rendering with syntax highlighting
+
+### 🚀 Content Aggregation
+
+- **Tabbed Interface** - Switch between Raindrop and GitHub
+- **Progressive Loading** - Non-blocking, fast performance
+- **Smart Actions** - Context-aware keybindings (e.g., star GitHub repos from Raindrop)
+
+## Configuration
+
+Create `~/.config/kiosque/kiosque.conf`:
+
+```ini
+# Website authentication
+[https://www.lemonde.fr/]
+username = your.email@example.com
+password = your_password
+
+[https://www.nytimes.com/]
+cookie_nyt_s = your_nyt_cookie_value
+
+# Raindrop.io integration
+[raindrop.io]
+token = your_raindrop_api_token
+
+# GitHub Stars integration
+[github]
+token = ghp_your_github_personal_access_token
+
+# Proxy for geo-blocked sites (optional)
+[proxy]
+url = socks5://localhost:1080
+```
+
+## Python API
+
+```python
+from kiosque import Website
+
+# Extract article as Markdown
+url = "https://www.lemonde.fr/article"
+markdown = Website.instance(url).full_text(url)
+
+# Save to file
+Website.instance(url).save(url, "article.md")
+```
+
+## Documentation
+
+📚 **Full documentation:** https://www.xoolive.org/kiosque
+
+- [Installation](https://www.xoolive.org/kiosque/getting-started/installation/) - Detailed installation guide
+- [Configuration](https://www.xoolive.org/kiosque/getting-started/configuration/) - Authentication setup for all sites
+- [TUI Guide](https://www.xoolive.org/kiosque/features/tui-guide/) - Complete terminal interface reference
+- [Supported Sites](https://www.xoolive.org/kiosque/websites/supported-sites/) - Full list of websites
+- [Authentication](https://www.xoolive.org/kiosque/websites/authentication/) - Site-specific login instructions
+- [Adding Sites](https://www.xoolive.org/kiosque/websites/adding-sites/) - Contributing new website support
+- [Troubleshooting](https://www.xoolive.org/kiosque/troubleshooting/) - Common issues and solutions
+
+## TUI Keybindings
+
+| Key                     | Action                       |
+| ----------------------- | ---------------------------- |
+| `↑` or `k` / `↓` or `j` | Navigate entries             |
+| `1` / `2`               | Switch tabs                  |
+| `/`                     | Search                       |
+| `Space`                 | Preview article/README       |
+| `Enter` / `o`           | Open in browser              |
+| `t`                     | Edit tags (Raindrop)         |
+| `e`                     | Archive (Raindrop)           |
+| `d`                     | Delete (Raindrop)            |
+| `u`                     | Unstar (GitHub)              |
+| `s`                     | Star on GitHub (GitHub URLs) |
+| `r`                     | Refresh                      |
+| `q`                     | Quit                         |
+
+## Contributing
+
+Contributions welcome! See the [Contributing Guide](https://www.xoolive.org/kiosque/development/contributing/) for:
+
+- How to add support for new websites
+- Code style and testing guidelines
+- Architecture overview
+
+## License
+
+MIT

kiosque-0.2.0/agents.md

@@ -0,0 +1,28 @@
+# Agent development guide
+
+## Setup commands
+
+- Run `uv sync --dev`
+
+## Coding style
+
+- Run `uv run ruff check` and `uv run ruff format` to check and format code
+- Run `uvx ty check kiosque/ tests/` to check types
+- Use `prettier` to format markdown files
+
+## Commit rules
+
+- **NEVER COMMIT ANYTHING WITHOUT EXPLICIT APPROVAL**: encourage the developer to check the code before committing
+- **DO NOT COMMIT DIRECTLY TO THE MAIN BRANCH**
+- Create a feature branch from main for your changes
+
+## Project structure
+
+- kiosque/core/ - Core functionality (client, website base class, config)
+- kiosque/website/ - Individual website scrapers (30+ files)
+- kiosque/api/ - API integrations (Raindrop.io, Pocket - deprecated)
+- kiosque/tui/ - Terminal UI with Textual
+
+## Agent coding
+
+- If there is a file where the plan is written stored, update it after every step