feat(compat): add compatibility module and feed-level GeoRSS support

Phase 3 (final) of namespace completion:

- Add compat module with Python feedparser compatibility helpers:
  - normalize_version() converts FeedVersion to Python format
  - format_duration() converts seconds to HH:MM:SS
  - is_valid_version() validates version identifiers
- Add geo field to FeedMeta for feed-level geographic data
- Add handle_feed_element() to GeoRSS namespace handler
- Add is_georss_tag() helper to parser common module
- Integrate GeoRSS parsing at channel level in RSS and RSS 1.0 parsers
- Add comprehensive tests for all new functionality

Author: bug-ops

crates/feedparser-rs-core/src/compat/mod.rs

@@ -1,6 +1,180 @@
-// Compatibility utilities for feedparser API
-//
-// This module provides utilities to ensure API compatibility with
-// Python's feedparser library.
+//! Compatibility utilities for feedparser API
+//!
+//! This module provides utilities to ensure API compatibility with
+//! Python's feedparser library.
 
-// TODO: Implement in later phases as needed
+use crate::types::FeedVersion;
+
+/// Normalize feed type string to Python feedparser format
+///
+/// Converts version enum to Python feedparser-compatible string format:
+/// - "RSS 2.0" -> "rss20"
+/// - "Atom 1.0" -> "atom10"
+/// - etc.
+///
+/// # Arguments
+///
+/// * `version` - Feed version to normalize
+///
+/// # Returns
+///
+/// Normalized version string compatible with Python feedparser
+///
+/// # Examples
+///
+/// ```
+/// use feedparser_rs::{compat::normalize_version, FeedVersion};
+///
+/// assert_eq!(normalize_version(FeedVersion::Rss20), "rss20");
+/// assert_eq!(normalize_version(FeedVersion::Atom10), "atom10");
+/// assert_eq!(normalize_version(FeedVersion::Unknown), "");
+/// ```
+#[must_use]
+pub fn normalize_version(version: FeedVersion) -> String {
+    version.as_str().to_string()
+}
+
+/// Convert duration in seconds to HH:MM:SS format
+///
+/// Formats duration for display in podcast feeds and other contexts
+/// where human-readable time format is needed.
+///
+/// # Arguments
+///
+/// * `seconds` - Duration in seconds
+///
+/// # Returns
+///
+/// Duration string in HH:MM:SS format
+///
+/// # Examples
+///
+/// ```
+/// use feedparser_rs::compat::format_duration;
+///
+/// assert_eq!(format_duration(0), "0:00:00");
+/// assert_eq!(format_duration(90), "0:01:30");
+/// assert_eq!(format_duration(3661), "1:01:01");
+/// assert_eq!(format_duration(36000), "10:00:00");
+/// ```
+#[must_use]
+pub fn format_duration(seconds: u32) -> String {
+    let hours = seconds / 3600;
+    let minutes = (seconds % 3600) / 60;
+    let secs = seconds % 60;
+    format!("{hours}:{minutes:02}:{secs:02}")
+}
+
+/// Check if a string is a valid feed version identifier
+///
+/// Validates whether a version string matches one of the known
+/// feed format versions supported by feedparser.
+///
+/// # Arguments
+///
+/// * `version` - Version string to validate
+///
+/// # Returns
+///
+/// `true` if version is valid, `false` otherwise
+///
+/// # Examples
+///
+/// ```
+/// use feedparser_rs::compat::is_valid_version;
+///
+/// assert!(is_valid_version("rss20"));
+/// assert!(is_valid_version("atom10"));
+/// assert!(is_valid_version("json11"));
+/// assert!(!is_valid_version("invalid"));
+/// assert!(!is_valid_version(""));
+/// ```
+#[must_use]
+pub fn is_valid_version(version: &str) -> bool {
+    matches!(
+        version,
+        "rss090" | "rss091" | "rss092" | "rss10" | "rss20" | "atom03" | "atom10" | "json10"
+            | "json11"
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_normalize_version() {
+        assert_eq!(normalize_version(FeedVersion::Rss20), "rss20");
+        assert_eq!(normalize_version(FeedVersion::Rss10), "rss10");
+        assert_eq!(normalize_version(FeedVersion::Atom10), "atom10");
+        assert_eq!(normalize_version(FeedVersion::Atom03), "atom03");
+        assert_eq!(normalize_version(FeedVersion::JsonFeed10), "json10");
+        assert_eq!(normalize_version(FeedVersion::JsonFeed11), "json11");
+        assert_eq!(normalize_version(FeedVersion::Unknown), "");
+    }
+
+    #[test]
+    fn test_format_duration_zero() {
+        assert_eq!(format_duration(0), "0:00:00");
+    }
+
+    #[test]
+    fn test_format_duration_seconds_only() {
+        assert_eq!(format_duration(30), "0:00:30");
+        assert_eq!(format_duration(59), "0:00:59");
+    }
+
+    #[test]
+    fn test_format_duration_minutes() {
+        assert_eq!(format_duration(60), "0:01:00");
+        assert_eq!(format_duration(90), "0:01:30");
+        assert_eq!(format_duration(150), "0:02:30");
+        assert_eq!(format_duration(3599), "0:59:59");
+    }
+
+    #[test]
+    fn test_format_duration_hours() {
+        assert_eq!(format_duration(3600), "1:00:00");
+        assert_eq!(format_duration(3661), "1:01:01");
+        assert_eq!(format_duration(7200), "2:00:00");
+        assert_eq!(format_duration(36000), "10:00:00");
+    }
+
+    #[test]
+    fn test_format_duration_large() {
+        assert_eq!(format_duration(86399), "23:59:59");
+        assert_eq!(format_duration(86400), "24:00:00");
+        assert_eq!(format_duration(90061), "25:01:01");
+    }
+
+    #[test]
+    fn test_is_valid_version_valid() {
+        assert!(is_valid_version("rss090"));
+        assert!(is_valid_version("rss091"));
+        assert!(is_valid_version("rss092"));
+        assert!(is_valid_version("rss10"));
+        assert!(is_valid_version("rss20"));
+        assert!(is_valid_version("atom03"));
+        assert!(is_valid_version("atom10"));
+        assert!(is_valid_version("json10"));
+        assert!(is_valid_version("json11"));
+    }
+
+    #[test]
+    fn test_is_valid_version_invalid() {
+        assert!(!is_valid_version(""));
+        assert!(!is_valid_version("invalid"));
+        assert!(!is_valid_version("rss30"));
+        assert!(!is_valid_version("atom20"));
+        assert!(!is_valid_version("RSS20")); // Case sensitive
+        assert!(!is_valid_version("json12"));
+        assert!(!is_valid_version("rdf"));
+    }
+
+    #[test]
+    fn test_is_valid_version_edge_cases() {
+        assert!(!is_valid_version(" rss20"));
+        assert!(!is_valid_version("rss20 "));
+        assert!(!is_valid_version("rss 20"));
+    }
+}

crates/feedparser-rs-core/src/lib.rs

@@ -38,7 +38,8 @@
 //! for representing parsed feed data. The main entry point is the [`parse`] function which
 //! automatically detects feed format and returns parsed results.
 
-mod compat;
+/// Compatibility utilities for Python feedparser API
+pub mod compat;
 mod error;
 #[cfg(feature = "http")]
 /// HTTP client module for fetching feeds from URLs

crates/feedparser-rs-core/src/namespace/georss.rs

@@ -16,7 +16,7 @@
 //! GeoRSS Simple: <http://www.georss.org/simple>
 
 use crate::limits::ParserLimits;
-use crate::types::Entry;
+use crate::types::{Entry, FeedMeta};
 
 /// `GeoRSS` namespace URI
 pub const GEORSS: &str = "http://www.georss.org/georss";
@@ -204,6 +204,53 @@ pub fn handle_entry_element(
     }
 }
 
+/// Parse `GeoRSS` element and update feed metadata
+///
+/// # Arguments
+///
+/// * `tag` - Element local name (e.g., "point", "line", "polygon", "box")
+/// * `text` - Element text content
+/// * `feed` - Feed metadata to update
+/// * `_limits` - Parser limits (unused but kept for API consistency)
+///
+/// # Returns
+///
+/// `true` if element was recognized and handled, `false` otherwise
+pub fn handle_feed_element(
+    tag: &[u8],
+    text: &str,
+    feed: &mut FeedMeta,
+    _limits: &ParserLimits,
+) -> bool {
+    match tag {
+        b"point" => {
+            if let Some(loc) = parse_point(text) {
+                feed.geo = Some(loc);
+            }
+            true
+        }
+        b"line" => {
+            if let Some(loc) = parse_line(text) {
+                feed.geo = Some(loc);
+            }
+            true
+        }
+        b"polygon" => {
+            if let Some(loc) = parse_polygon(text) {
+                feed.geo = Some(loc);
+            }
+            true
+        }
+        b"box" => {
+            if let Some(loc) = parse_box(text) {
+                feed.geo = Some(loc);
+            }
+            true
+        }
+        _ => false,
+    }
+}
+
 /// Parse georss:point element
 ///
 /// Format: "lat lon" (space-separated)
@@ -432,4 +479,77 @@ mod tests {
         let loc = parse_point("  45.256   -71.92  ").unwrap();
         assert_eq!(loc.coordinates[0], (45.256, -71.92));
     }
+
+    #[test]
+    fn test_handle_feed_element_point() {
+        let mut feed = FeedMeta::default();
+        let limits = ParserLimits::default();
+
+        let handled = handle_feed_element(b"point", "45.256 -71.92", &mut feed, &limits);
+        assert!(handled);
+        assert!(feed.geo.is_some());
+
+        let geo = feed.geo.as_ref().unwrap();
+        assert_eq!(geo.geo_type, GeoType::Point);
+        assert_eq!(geo.coordinates[0], (45.256, -71.92));
+    }
+
+    #[test]
+    fn test_handle_feed_element_line() {
+        let mut feed = FeedMeta::default();
+        let limits = ParserLimits::default();
+
+        let handled =
+            handle_feed_element(b"line", "45.256 -71.92 46.0 -72.0", &mut feed, &limits);
+        assert!(handled);
+        assert!(feed.geo.is_some());
+        assert_eq!(feed.geo.as_ref().unwrap().geo_type, GeoType::Line);
+    }
+
+    #[test]
+    fn test_handle_feed_element_polygon() {
+        let mut feed = FeedMeta::default();
+        let limits = ParserLimits::default();
+
+        let handled = handle_feed_element(
+            b"polygon",
+            "45.0 -71.0 46.0 -71.0 46.0 -72.0 45.0 -71.0",
+            &mut feed,
+            &limits,
+        );
+        assert!(handled);
+        assert!(feed.geo.is_some());
+        assert_eq!(feed.geo.as_ref().unwrap().geo_type, GeoType::Polygon);
+    }
+
+    #[test]
+    fn test_handle_feed_element_box() {
+        let mut feed = FeedMeta::default();
+        let limits = ParserLimits::default();
+
+        let handled = handle_feed_element(b"box", "45.0 -72.0 46.0 -71.0", &mut feed, &limits);
+        assert!(handled);
+        assert!(feed.geo.is_some());
+        assert_eq!(feed.geo.as_ref().unwrap().geo_type, GeoType::Box);
+    }
+
+    #[test]
+    fn test_handle_feed_element_unknown() {
+        let mut feed = FeedMeta::default();
+        let limits = ParserLimits::default();
+
+        let handled = handle_feed_element(b"unknown", "data", &mut feed, &limits);
+        assert!(!handled);
+        assert!(feed.geo.is_none());
+    }
+
+    #[test]
+    fn test_handle_feed_element_invalid_data() {
+        let mut feed = FeedMeta::default();
+        let limits = ParserLimits::default();
+
+        let handled = handle_feed_element(b"point", "invalid data", &mut feed, &limits);
+        assert!(handled);
+        assert!(feed.geo.is_none());
+    }
 }

crates/feedparser-rs-core/src/parser/common.rs

@@ -237,6 +237,20 @@ pub fn is_media_tag(name: &[u8]) -> Option<&str> {
     extract_ns_local_name(name, b"media:")
 }
 
+/// Check if element is a `GeoRSS` namespaced tag
+///
+/// # Examples
+///
+/// ```ignore
+/// assert_eq!(is_georss_tag(b"georss:point"), Some("point"));
+/// assert_eq!(is_georss_tag(b"georss:line"), Some("line"));
+/// assert_eq!(is_georss_tag(b"dc:creator"), None);
+/// ```
+#[inline]
+pub fn is_georss_tag(name: &[u8]) -> Option<&str> {
+    extract_ns_local_name(name, b"georss:")
+}
+
 /// Check if element matches an iTunes namespace tag
 ///
 /// Supports both prefixed (itunes:author) and unprefixed (author) forms