sitemap2atom 0.1.0__tar.gz

sitemap2atom-0.1.0/.flake8

@@ -0,0 +1,9 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203
+exclude =
+    .git,
+    .venv,
+    build,
+    dist,
+    __pycache__

sitemap2atom-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run flake8 src tests
+
+      - name: Run tests
+        run: uv run pytest

sitemap2atom-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sitemap2atom
+    permissions:
+      # Required for PyPI trusted publishing via OIDC.
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sitemap2atom-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Generated feeds
+*.atom
+enriched_feed.atom
+
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test / type-check / coverage caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/

sitemap2atom-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 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]
+
+## [0.1.0] - 2026-06-09
+
+### Added
+
+- Initial public release.
+- `sitemap2atom` command-line tool: fetch an XML sitemap and convert its URLs
+  into an enriched Atom feed using OpenGraph and Twitter Card metadata.
+- CLI options: `--output`, `--limit`, `--feed-title`, `--timeout`, `--verbose`.
+- Installable from PyPI and runnable with `uvx sitemap2atom`.
+- Offline test suite covering metadata parsing and Atom feed generation.
+
+[Unreleased]: https://github.com/darkflib/sitemap2atom/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/darkflib/sitemap2atom/releases/tag/v0.1.0

sitemap2atom-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to sitemap2atom
+
+Thanks for your interest in improving sitemap2atom! Contributions of all kinds
+are welcome — bug reports, feature ideas, documentation fixes, and pull requests.
+
+## Reporting issues
+
+Please open an issue on the
+[issue tracker](https://github.com/darkflib/sitemap2atom/issues) and include:
+
+- What you expected to happen and what actually happened.
+- The command you ran (and the sitemap URL, if it can be shared).
+- Your Python version and operating system.
+
+## Development setup
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+git clone https://github.com/darkflib/sitemap2atom.git
+cd sitemap2atom
+uv sync            # create the virtualenv and install runtime + dev deps
+```
+
+Run the CLI locally without installing it globally:
+
+```bash
+uv run sitemap2atom https://example.com/sitemap.xml --limit 5
+```
+
+## Tests, linting, and types
+
+The test suite is offline (no network access needed) and must stay that way so
+it can run in CI:
+
+```bash
+uv run pytest                 # run the tests
+uv run flake8 src tests       # lint
+uv run black --check src tests
+uv run isort --check src tests
+uv run mypy src               # type-check
+```
+
+Please make sure tests and lint pass before opening a pull request, and add
+tests for any new behaviour.
+
+## Pull requests
+
+1. Fork the repository and create a branch from `main`.
+2. Make your change, with tests and documentation as appropriate.
+3. Add an entry to the **Unreleased** section of [CHANGELOG.md](CHANGELOG.md).
+4. Open a pull request describing the change and the motivation.
+
+By contributing, you agree that your contributions will be licensed under the
+[MIT License](LICENSE).

sitemap2atom-0.1.0/LICENSE

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

sitemap2atom-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sitemap2atom
+Version: 0.1.0
+Summary: A tool to convert XML sitemaps to Atom feeds
+Project-URL: homepage, https://github.com/darkflib/sitemap2atom
+Project-URL: repository, https://github.com/darkflib/sitemap2atom
+Project-URL: issues, https://github.com/darkflib/sitemap2atom/issues
+Author-email: Mike Preston <darkflib@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: atom,feed,opengraph,rss,sitemap,syndication
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Text Processing :: Markup :: XML
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.9.3
+Requires-Dist: click>=7.1.2
+Requires-Dist: lxml>=4.6.3
+Requires-Dist: python-dateutil>=2.8.1
+Requires-Dist: requests>=2.25.1
+Description-Content-Type: text/markdown
+
+# sitemap2atom
+
+A simple tool to convert an XML sitemap into an [Atom](https://datatracker.ietf.org/doc/html/rfc4287)
+feed — especially useful for sites that don't have a CMS, or where the CMS
+doesn't produce a feed. Each URL in the sitemap is fetched and its OpenGraph and
+Twitter Card metadata (title, description, image, author, dates) is used to build
+a rich Atom entry.
+
+## Installation
+
+### Run without installing (uvx)
+
+Once published to PyPI you can run it directly with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx sitemap2atom https://example.com/sitemap.xml -o feed.atom
+```
+
+To run the latest code straight from GitHub (before a release, or to try `main`):
+
+```bash
+uvx --from git+https://github.com/darkflib/sitemap2atom sitemap2atom https://example.com/sitemap.xml
+```
+
+### Install as a tool / library
+
+```bash
+uv tool install sitemap2atom      # installs the `sitemap2atom` command
+# or
+pip install sitemap2atom
+```
+
+## Usage
+
+```bash
+sitemap2atom SITEMAP_URL [OPTIONS]
+```
+
+By default the feed is written to standard output; redirect it or use `-o` to
+save it to a file:
+
+```bash
+# Print to stdout
+sitemap2atom https://example.com/sitemap.xml
+
+# Write to a file, limiting to the first 20 URLs
+sitemap2atom https://example.com/sitemap.xml -o feed.atom --limit 20
+```
+
+### Options
+
+- `-o, --output PATH` — write the Atom feed to this file (default: stdout).
+- `--limit N` — maximum number of sitemap URLs to process (default: all).
+- `--feed-title TEXT` — title for the generated feed (default: `Enriched URL Feed`).
+- `--timeout SECONDS` — per-request timeout in seconds (default: `10`).
+- `-v, --verbose` — enable info-level logging on stderr.
+- `--version` — show the version and exit.
+
+### As a library
+
+```python
+from sitemap2atom import fetch_sitemap_urls, enrich_url_list_to_atom, feed_to_pretty_xml
+
+urls = fetch_sitemap_urls("https://example.com/sitemap.xml")
+feed = enrich_url_list_to_atom(urls[:10], feed_title="My Feed")
+print(feed_to_pretty_xml(feed))
+```
+
+## Example output
+
+See this gist for a sample of the kind of enriched Atom feed produced:
+<https://gist.github.com/Darkflib/989b8f3a5a1ea995e8e294669d5e282a>
+
+## Limitations
+
+This is a simple tool aimed at basic use cases. It does not support
+authentication, sitemap index files / pagination, or dynamic sitemaps, and may
+not handle every sitemap or page format. Treat the sitemap and the pages it
+references as untrusted input and run it against sources you trust.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/darkflib/sitemap2atom.git
+cd sitemap2atom
+uv sync
+uv run pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more, and
+[CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file
+for details.
+
+PS. If you do anything interesting with this code, please let me know! I'd love
+to hear about it.

sitemap2atom-0.1.0/README.md

@@ -0,0 +1,102 @@
+# sitemap2atom
+
+A simple tool to convert an XML sitemap into an [Atom](https://datatracker.ietf.org/doc/html/rfc4287)
+feed — especially useful for sites that don't have a CMS, or where the CMS
+doesn't produce a feed. Each URL in the sitemap is fetched and its OpenGraph and
+Twitter Card metadata (title, description, image, author, dates) is used to build
+a rich Atom entry.
+
+## Installation
+
+### Run without installing (uvx)
+
+Once published to PyPI you can run it directly with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx sitemap2atom https://example.com/sitemap.xml -o feed.atom
+```
+
+To run the latest code straight from GitHub (before a release, or to try `main`):
+
+```bash
+uvx --from git+https://github.com/darkflib/sitemap2atom sitemap2atom https://example.com/sitemap.xml
+```
+
+### Install as a tool / library
+
+```bash
+uv tool install sitemap2atom      # installs the `sitemap2atom` command
+# or
+pip install sitemap2atom
+```
+
+## Usage
+
+```bash
+sitemap2atom SITEMAP_URL [OPTIONS]
+```
+
+By default the feed is written to standard output; redirect it or use `-o` to
+save it to a file:
+
+```bash
+# Print to stdout
+sitemap2atom https://example.com/sitemap.xml
+
+# Write to a file, limiting to the first 20 URLs
+sitemap2atom https://example.com/sitemap.xml -o feed.atom --limit 20
+```
+
+### Options
+
+- `-o, --output PATH` — write the Atom feed to this file (default: stdout).
+- `--limit N` — maximum number of sitemap URLs to process (default: all).
+- `--feed-title TEXT` — title for the generated feed (default: `Enriched URL Feed`).
+- `--timeout SECONDS` — per-request timeout in seconds (default: `10`).
+- `-v, --verbose` — enable info-level logging on stderr.
+- `--version` — show the version and exit.
+
+### As a library
+
+```python
+from sitemap2atom import fetch_sitemap_urls, enrich_url_list_to_atom, feed_to_pretty_xml
+
+urls = fetch_sitemap_urls("https://example.com/sitemap.xml")
+feed = enrich_url_list_to_atom(urls[:10], feed_title="My Feed")
+print(feed_to_pretty_xml(feed))
+```
+
+## Example output
+
+See this gist for a sample of the kind of enriched Atom feed produced:
+<https://gist.github.com/Darkflib/989b8f3a5a1ea995e8e294669d5e282a>
+
+## Limitations
+
+This is a simple tool aimed at basic use cases. It does not support
+authentication, sitemap index files / pagination, or dynamic sitemaps, and may
+not handle every sitemap or page format. Treat the sitemap and the pages it
+references as untrusted input and run it against sources you trust.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/darkflib/sitemap2atom.git
+cd sitemap2atom
+uv sync
+uv run pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more, and
+[CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file
+for details.
+
+PS. If you do anything interesting with this code, please let me know! I'd love
+to hear about it.

sitemap2atom-0.1.0/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+sitemap2atom is currently pre-1.0. Security fixes are applied to the latest
+released version on PyPI.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a vulnerability
+
+Please **do not** report security vulnerabilities through public GitHub issues.
+
+Instead, report them privately via one of:
+
+- GitHub's [private vulnerability reporting](https://github.com/darkflib/sitemap2atom/security/advisories/new)
+  ("Report a vulnerability" on the Security tab), or
+- email to **darkflib@gmail.com**.
+
+Please include a description of the issue, steps to reproduce, and the impact
+you anticipate. You can expect an acknowledgement within a few days. Once the
+issue is confirmed and fixed, a new release will be published and the reporter
+credited (unless anonymity is requested).
+
+## Scope
+
+sitemap2atom fetches arbitrary URLs listed in a sitemap and parses the returned
+HTML. Treat sitemaps and the pages they reference as untrusted input, and run
+the tool against sources you trust.

sitemap2atom-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "sitemap2atom"
+version = "0.1.0"
+description = "A tool to convert XML sitemaps to Atom feeds"
+authors = [{name = "Mike Preston", email = "darkflib@gmail.com"}]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["sitemap", "atom", "feed", "opengraph", "syndication", "rss"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Text Processing :: Markup :: XML",
+]
+
+dependencies = [
+    "requests>=2.25.1",
+    "lxml>=4.6.3",
+    "beautifulsoup4>=4.9.3",
+    "python-dateutil>=2.8.1",
+    "click>=7.1.2",
+]
+
+[project.urls]
+homepage = "https://github.com/darkflib/sitemap2atom"
+repository = "https://github.com/darkflib/sitemap2atom"
+issues = "https://github.com/darkflib/sitemap2atom/issues"
+
+[project.scripts]
+sitemap2atom = "sitemap2atom.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sitemap2atom"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.16.0",
+    "pytest>=6.2.4",
+    "black>=21.7b0",
+    "isort>=5.9.3",
+    "flake8>=3.9.2",
+    "pre-commit>=2.13.0",
+    "coverage>=5.5",
+    "types-requests>=2.25.1",
+    "types-beautifulsoup4>=4.9.3",
+    "types-python-dateutil>=2.8.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

sitemap2atom-0.1.0/src/sitemap2atom/__init__.py

@@ -0,0 +1,22 @@
+"""sitemap2atom: convert an XML sitemap into an enriched Atom feed."""
+
+__version__ = "0.1.0"
+
+from .core import (
+    enrich_atom_entry,
+    enrich_url_list_to_atom,
+    extract_metadata,
+    feed_to_pretty_xml,
+    fetch_sitemap_urls,
+    parse_metadata,
+)
+
+__all__ = [
+    "__version__",
+    "enrich_atom_entry",
+    "enrich_url_list_to_atom",
+    "extract_metadata",
+    "feed_to_pretty_xml",
+    "fetch_sitemap_urls",
+    "parse_metadata",
+]

sitemap2atom-0.1.0/src/sitemap2atom/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m sitemap2atom``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

sitemap2atom-0.1.0/src/sitemap2atom/cli.py

@@ -0,0 +1,83 @@
+"""Command-line interface for sitemap2atom."""
+
+import logging
+import sys
+
+import click
+import requests
+
+from . import __version__
+from .core import (
+    DEFAULT_FEED_TITLE,
+    enrich_url_list_to_atom,
+    feed_to_pretty_xml,
+    fetch_sitemap_urls,
+)
+
+
+@click.command()
+@click.argument("sitemap_url")
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(dir_okay=False, writable=True),
+    default=None,
+    help="Write the Atom feed to this file (default: stdout).",
+)
+@click.option(
+    "--limit",
+    type=int,
+    default=None,
+    help="Maximum number of sitemap URLs to process (default: all).",
+)
+@click.option(
+    "--feed-title",
+    default=DEFAULT_FEED_TITLE,
+    show_default=True,
+    help="Title for the generated Atom feed.",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=10,
+    show_default=True,
+    help="Per-request timeout in seconds.",
+)
+@click.option("-v", "--verbose", is_flag=True, help="Enable info-level logging.")
+@click.version_option(__version__, prog_name="sitemap2atom")
+def main(sitemap_url, output, limit, feed_title, timeout, verbose):
+    """Convert the XML sitemap at SITEMAP_URL into an enriched Atom feed.
+
+    Each URL in the sitemap is fetched and its OpenGraph/Twitter metadata is
+    used to build a rich Atom entry (title, summary, image, author, dates).
+    """
+    logging.basicConfig(
+        level=logging.INFO if verbose else logging.WARNING,
+        format="%(levelname)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    try:
+        urls = fetch_sitemap_urls(sitemap_url, timeout=timeout)
+    except requests.RequestException as e:
+        raise click.ClickException(f"Failed to fetch sitemap {sitemap_url}: {e}")
+
+    if limit is not None:
+        urls = urls[:limit]
+
+    if not urls:
+        raise click.ClickException(f"No <loc> URLs found in sitemap: {sitemap_url}")
+
+    feed = enrich_url_list_to_atom(urls, feed_title=feed_title, timeout=timeout)
+    xml = feed_to_pretty_xml(feed)
+
+    if output:
+        with open(output, "w", encoding="utf-8") as f:
+            f.write(xml + "\n")
+        click.echo(f"Wrote {output}", err=True)
+    else:
+        click.echo(xml)
+
+
+if __name__ == "__main__":
+    main()