feat(py): add FeedParserDict field mapping for backward compatibility

Implement Phase 1 of Python feedparser compatibility improvements:

- Add deprecated field aliases (description→subtitle, tagline→subtitle,
  modified→updated, copyright→rights, date→updated/published, url→link)
- Add entry aliases (guid→id, description→summary, issued→published,
  modified→updated, date→updated/published)
- Add container aliases (channel→feed, items→entries)
- Use once_cell::Lazy<HashMap> for O(1) alias lookups
- Add __getattr__ methods to PyFeedMeta, PyEntry, PyParsedFeed
- Add comprehensive Python tests (19 test cases)

This allows users migrating from Python feedparser to access data using
familiar deprecated field names while the modern field names remain
the primary API.

Author: bug-ops

Cargo.lock

@@ -29,6 +29,7 @@ memchr = "2.7"
 mockito = "1.6"
 napi = "3.7"
 napi-derive = "3.4"
+once_cell = "1.20"
 pyo3 = "0.27"
 quick-xml = "0.38"
 regex = "1.11"

Cargo.toml

@@ -18,6 +18,7 @@ crate-type = ["cdylib"]
 feedparser-rs = { path = "../feedparser-rs-core" }
 pyo3 = { workspace = true, features = ["extension-module", "chrono"] }
 chrono = { workspace = true, features = ["clock"] }
+once_cell = { workspace = true }
 
 [features]
 default = ["http"]

crates/feedparser-rs-py/Cargo.toml

@@ -0,0 +1,120 @@
+/// Python feedparser backward compatibility field mappings.
+///
+/// This module provides field alias mappings for deprecated Python feedparser field names.
+/// Old field names map to new field names for backward compatibility.
+///
+/// Example: `feed.description` → `feed.subtitle`
+///          `entry.guid` → `entry.id`
+use std::collections::HashMap;
+use once_cell::sync::Lazy;
+
+/// Feed-level field mappings: old name → list of new names (tried in order).
+///
+/// Some aliases can map to multiple fields (e.g., description → subtitle OR summary).
+/// The resolver tries each new field in order until it finds a non-None value.
+pub static FEED_FIELD_MAP: Lazy<HashMap<&'static str, Vec<&'static str>>> = Lazy::new(|| {
+    let mut map = HashMap::new();
+
+    // Description aliases
+    map.insert("description", vec!["subtitle", "summary"]);
+    map.insert("description_detail", vec!["subtitle_detail", "summary_detail"]);
+
+    // Tagline aliases (old Atom 0.3 field)
+    map.insert("tagline", vec!["subtitle"]);
+    map.insert("tagline_detail", vec!["subtitle_detail"]);
+
+    // Info alias (RSS 1.0)
+    map.insert("info", vec!["subtitle"]);
+    map.insert("info_detail", vec!["subtitle_detail"]);
+
+    // Copyright alias
+    map.insert("copyright", vec!["rights"]);
+    map.insert("copyright_detail", vec!["rights_detail"]);
+
+    // Modified alias
+    map.insert("modified", vec!["updated"]);
+    map.insert("modified_parsed", vec!["updated_parsed"]);
+
+    // Date alias (generic fallback)
+    map.insert("date", vec!["updated", "published"]);
+    map.insert("date_parsed", vec!["updated_parsed", "published_parsed"]);
+
+    // URL alias
+    map.insert("url", vec!["link"]);
+
+    map
+});
+
+/// Entry-level field mappings: old name → list of new names (tried in order).
+pub static ENTRY_FIELD_MAP: Lazy<HashMap<&'static str, Vec<&'static str>>> = Lazy::new(|| {
+    let mut map = HashMap::new();
+
+    // GUID alias (RSS)
+    map.insert("guid", vec!["id"]);
+
+    // Description alias
+    map.insert("description", vec!["summary"]);
+    map.insert("description_detail", vec!["summary_detail"]);
+
+    // Issued alias (old feedparser field)
+    map.insert("issued", vec!["published"]);
+    map.insert("issued_parsed", vec!["published_parsed"]);
+
+    // Modified alias
+    map.insert("modified", vec!["updated"]);
+    map.insert("modified_parsed", vec!["updated_parsed"]);
+
+    // Date alias (generic fallback)
+    map.insert("date", vec!["updated", "published"]);
+    map.insert("date_parsed", vec!["updated_parsed", "published_parsed"]);
+
+    map
+});
+
+/// Container-level field mappings for PyParsedFeed.
+pub static CONTAINER_FIELD_MAP: Lazy<HashMap<&'static str, &'static str>> = Lazy::new(|| {
+    let mut map = HashMap::new();
+
+    // RSS uses <channel>, Atom uses <feed>
+    map.insert("channel", "feed");
+
+    // RSS uses <item>, Atom uses <entry>
+    map.insert("items", "entries");
+
+    map
+});
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_feed_field_map_description() {
+        let targets = FEED_FIELD_MAP.get("description").unwrap();
+        assert_eq!(targets, &vec!["subtitle", "summary"]);
+    }
+
+    #[test]
+    fn test_feed_field_map_modified() {
+        let targets = FEED_FIELD_MAP.get("modified").unwrap();
+        assert_eq!(targets, &vec!["updated"]);
+    }
+
+    #[test]
+    fn test_entry_field_map_guid() {
+        let targets = ENTRY_FIELD_MAP.get("guid").unwrap();
+        assert_eq!(targets, &vec!["id"]);
+    }
+
+    #[test]
+    fn test_entry_field_map_issued() {
+        let targets = ENTRY_FIELD_MAP.get("issued").unwrap();
+        assert_eq!(targets, &vec!["published"]);
+    }
+
+    #[test]
+    fn test_container_field_map_channel() {
+        let target = CONTAINER_FIELD_MAP.get("channel").unwrap();
+        assert_eq!(*target, "feed");
+    }
+}

crates/feedparser-rs-py/src/types/compat.rs

@@ -1,6 +1,8 @@
 use feedparser_rs::Entry as CoreEntry;
 use pyo3::prelude::*;
+use pyo3::exceptions::PyAttributeError;
 
+use super::compat::ENTRY_FIELD_MAP;
 use super::common::{PyContent, PyEnclosure, PyLink, PyPerson, PySource, PyTag, PyTextConstruct};
 use super::datetime::optional_datetime_to_struct_time;
 use super::geo::PyGeoLocation;
@@ -301,4 +303,58 @@ impl PyEntry {
             self.inner.id.as_deref().unwrap_or("no-id")
         )
     }
+
+    /// Provides backward compatibility for deprecated Python feedparser field names.
+    ///
+    /// Maps old field names to their modern equivalents:
+    /// - `guid` → `id`
+    /// - `description` → `summary`
+    /// - `issued` → `published`
+    /// - `modified` → `updated`
+    /// - `date` → `updated` (or `published` as fallback)
+    ///
+    /// This method is called by Python when normal attribute lookup fails.
+    fn __getattr__(&self, py: Python<'_>, name: &str) -> PyResult<Py<PyAny>> {
+        // Check if this is a deprecated field name
+        if let Some(new_names) = ENTRY_FIELD_MAP.get(name) {
+            // Try each new field name in order
+            for new_name in new_names {
+                let value: Option<Py<PyAny>> = match *new_name {
+                    "id" => self.inner.id.as_deref().and_then(|v| {
+                        v.into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "summary" => self.inner.summary.as_deref().and_then(|v| {
+                        v.into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "summary_detail" => self.inner.summary_detail.as_ref().and_then(|tc| {
+                        Py::new(py, PyTextConstruct::from_core(tc.clone())).ok().map(|p: Py<PyTextConstruct>| p.into_any())
+                    }),
+                    "published" => self.inner.published.and_then(|dt| {
+                        dt.to_rfc3339().into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "published_parsed" => {
+                        optional_datetime_to_struct_time(py, &self.inner.published).ok().flatten()
+                    },
+                    "updated" => self.inner.updated.and_then(|dt| {
+                        dt.to_rfc3339().into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "updated_parsed" => {
+                        optional_datetime_to_struct_time(py, &self.inner.updated).ok().flatten()
+                    },
+                    _ => None,
+                };
+
+                // If we found a value, return it
+                if let Some(v) = value {
+                    return Ok(v);
+                }
+            }
+        }
+
+        // Field not found - raise AttributeError
+        Err(PyAttributeError::new_err(format!(
+            "'Entry' object has no attribute '{}'",
+            name
+        )))
+    }
 }

crates/feedparser-rs-py/src/types/entry.rs

@@ -1,6 +1,8 @@
 use feedparser_rs::FeedMeta as CoreFeedMeta;
 use pyo3::prelude::*;
+use pyo3::exceptions::PyAttributeError;
 
+use super::compat::FEED_FIELD_MAP;
 use super::common::{PyGenerator, PyImage, PyLink, PyPerson, PyTag, PyTextConstruct};
 use super::datetime::optional_datetime_to_struct_time;
 use super::geo::PyGeoLocation;
@@ -252,4 +254,71 @@ impl PyFeedMeta {
             self.inner.link.as_deref().unwrap_or("no-link")
         )
     }
+
+    /// Provides backward compatibility for deprecated Python feedparser field names.
+    ///
+    /// Maps old field names to their modern equivalents:
+    /// - `description` → `subtitle` (or `summary` as fallback)
+    /// - `tagline` → `subtitle`
+    /// - `modified` → `updated`
+    /// - `copyright` → `rights`
+    /// - `date` → `updated` (or `published` as fallback)
+    /// - `url` → `link`
+    ///
+    /// This method is called by Python when normal attribute lookup fails.
+    fn __getattr__(&self, py: Python<'_>, name: &str) -> PyResult<Py<PyAny>> {
+        // Check if this is a deprecated field name
+        if let Some(new_names) = FEED_FIELD_MAP.get(name) {
+            // Try each new field name in order
+            for new_name in new_names {
+                let value: Option<Py<PyAny>> = match *new_name {
+                    "subtitle" => self.inner.subtitle.as_deref().and_then(|v| {
+                        v.into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "subtitle_detail" => self.inner.subtitle_detail.as_ref().and_then(|tc| {
+                        Py::new(py, PyTextConstruct::from_core(tc.clone())).ok().map(|p: Py<PyTextConstruct>| p.into_any())
+                    }),
+                    "summary" => self.inner.subtitle.as_deref().and_then(|v| {
+                        v.into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "summary_detail" => self.inner.subtitle_detail.as_ref().and_then(|tc| {
+                        Py::new(py, PyTextConstruct::from_core(tc.clone())).ok().map(|p: Py<PyTextConstruct>| p.into_any())
+                    }),
+                    "rights" => self.inner.rights.as_deref().and_then(|v| {
+                        v.into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "rights_detail" => self.inner.rights_detail.as_ref().and_then(|tc| {
+                        Py::new(py, PyTextConstruct::from_core(tc.clone())).ok().map(|p: Py<PyTextConstruct>| p.into_any())
+                    }),
+                    "updated" => self.inner.updated.and_then(|dt| {
+                        dt.to_rfc3339().into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "updated_parsed" => {
+                        optional_datetime_to_struct_time(py, &self.inner.updated).ok().flatten()
+                    },
+                    "published" => self.inner.published.and_then(|dt| {
+                        dt.to_rfc3339().into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    "published_parsed" => {
+                        optional_datetime_to_struct_time(py, &self.inner.published).ok().flatten()
+                    },
+                    "link" => self.inner.link.as_deref().and_then(|v| {
+                        v.into_pyobject(py).map(|o| o.unbind().into()).ok()
+                    }),
+                    _ => None,
+                };
+
+                // If we found a value, return it
+                if let Some(v) = value {
+                    return Ok(v);
+                }
+            }
+        }
+
+        // Field not found - raise AttributeError
+        Err(PyAttributeError::new_err(format!(
+            "'FeedMeta' object has no attribute '{}'",
+            name
+        )))
+    }
 }

crates/feedparser-rs-py/src/types/feed_meta.rs

@@ -1,4 +1,5 @@
 pub mod common;
+pub mod compat;
 pub mod datetime;
 pub mod entry;
 pub mod feed_meta;

crates/feedparser-rs-py/src/types/mod.rs

@@ -1,7 +1,9 @@
 use feedparser_rs::ParsedFeed as CoreParsedFeed;
 use pyo3::prelude::*;
+use pyo3::exceptions::PyAttributeError;
 use pyo3::types::PyDict;
 
+use super::compat::CONTAINER_FIELD_MAP;
 use super::entry::PyEntry;
 use super::feed_meta::PyFeedMeta;
 
@@ -141,4 +143,41 @@ impl PyParsedFeed {
     fn __str__(&self) -> String {
         self.__repr__()
     }
+
+    /// Provides backward compatibility for deprecated Python feedparser container names.
+    ///
+    /// Maps old container names to their modern equivalents:
+    /// - `channel` → `feed` (RSS uses <channel>, Atom uses <feed>)
+    /// - `items` → `entries` (RSS uses <item>, Atom uses <entry>)
+    ///
+    /// This method is called by Python when normal attribute lookup fails.
+    fn __getattr__(&self, py: Python<'_>, name: &str) -> PyResult<Py<PyAny>> {
+        // Check if this is a deprecated container name
+        if let Some(new_name) = CONTAINER_FIELD_MAP.get(name) {
+            match *new_name {
+                "feed" => {
+                    // Convert Py<PyFeedMeta> to Py<PyAny>
+                    Ok(self.feed.clone_ref(py).into())
+                },
+                "entries" => {
+                    // Convert Vec<Py<PyEntry>> to Py<PyAny> (as Python list)
+                    let entries: Vec<_> = self.entries.iter().map(|e| e.clone_ref(py)).collect();
+                    match entries.into_pyobject(py) {
+                        Ok(list) => Ok(list.unbind()),
+                        Err(e) => Err(e),
+                    }
+                },
+                _ => Err(PyAttributeError::new_err(format!(
+                    "'FeedParserDict' object has no attribute '{}'",
+                    name
+                ))),
+            }
+        } else {
+            // Field not found - raise AttributeError
+            Err(PyAttributeError::new_err(format!(
+                "'FeedParserDict' object has no attribute '{}'",
+                name
+            )))
+        }
+    }
 }