feat: expose workbook document properties

Cargo.toml

@@ -8,7 +8,7 @@ name = "python_calamine"
 crate-type = ["cdylib"]
 
 [dependencies]
-calamine = { version = "0.37.0", features = ["chrono"] }
+calamine = { version = "0.38.0", features = ["chrono"] }
 pyo3 = { version = "0.30.1", features = ["chrono"] }
 chrono = { version = "0.4.42", features = ["serde"] }
 pyo3-file = "0.18.0"

README.md

@@ -50,6 +50,21 @@ workbook = CalamineWorkbook.from_path("file.xlsx").get_sheet_by_name("Sheet1").t
 # ]
 ```
 
+Workbook document properties, such as the author, are available for xlsx, xlsb, xls and ods files.
+```python
+from python_calamine import CalamineWorkbook
+
+properties = CalamineWorkbook.from_path("file.xlsx").workbook_properties
+properties.creator
+# "John"
+properties.last_modified_by
+# "Jane"
+properties.modified
+# datetime.datetime(2024, 6, 20, 14, 22, tzinfo=datetime.timezone.utc)
+properties.custom_properties
+# {"Department": "Finance"}
+```
+
 Pandas 2.2 and above have built-in support of python-calamine.
 
 Also, you can find additional examples in [tests](https://github.com/dimastbk/python-calamine/blob/master/tests/test_base.py).

python/python_calamine/__init__.py

@@ -11,6 +11,7 @@
     TablesNotLoaded,
     TablesNotSupported,
     WorkbookClosed,
+    WorkbookProperties,
     WorksheetNotFound,
     XmlError,
     ZipError,
@@ -30,6 +31,7 @@
     "TablesNotLoaded",
     "TablesNotSupported",
     "WorkbookClosed",
+    "WorkbookProperties",
     "WorksheetNotFound",
     "XmlError",
     "ZipError",

python/python_calamine/_python_calamine.pyi

@@ -174,6 +174,57 @@ class CalamineTable:
     ]:
         """Returning data from table as list of lists."""
 
+@typing.final
+class WorkbookProperties:
+    """Document properties of a workbook.
+
+    Fields that the file doesn't store are `None`. `created` and `modified` are
+    timezone-aware when the file stores a UTC offset (xlsx, xlsb and xls always do)
+    and naive otherwise, for example in ods files saved by LibreOffice. A date the
+    file stores in another format is `None`.
+    """
+
+    creator: str | None
+    """Creator (author) of the workbook."""
+    last_modified_by: str | None
+    """User who last saved the workbook."""
+    created: datetime.datetime | None
+    """Creation date."""
+    modified: datetime.datetime | None
+    """Last modification date."""
+    title: str | None
+    """Title."""
+    subject: str | None
+    """Subject."""
+    description: str | None
+    """Description or comments."""
+    keywords: str | None
+    """Keywords."""
+    category: str | None
+    """Category."""
+    content_status: str | None
+    """Content status."""
+    revision: str | None
+    """Revision number."""
+    version: str | None
+    """Version."""
+    application: str | None
+    """Name of the application that created the workbook."""
+    app_version: str | None
+    """Version of the application that created the workbook."""
+    company: str | None
+    """Company."""
+    template: str | None
+    """Template the workbook is based on."""
+    manager: str | None
+    """Manager."""
+    custom_properties: dict[str, str]
+    """Custom document properties, keyed by name.
+
+    Values are returned as the text stored in the file, for example `"4"`,
+    `"true"` or `"2020-08-24T20:19:22Z"`.
+    """
+
 @typing.final
 class CalamineWorkbook:
     path: str | None
@@ -184,6 +235,17 @@ class CalamineWorkbook:
     """All sheets metadata of this workbook, in workbook order."""
     table_names: list[str] | None
     """All table names of this workbook."""
+    @property
+    def workbook_properties(self) -> WorkbookProperties:
+        """Document properties of this workbook, such as the creator and title.
+
+        Supported for xlsx, xlsb, xls and ods. The properties are read when this
+        attribute is first accessed, not when the workbook is opened.
+
+        Raises:
+            WorkbookClosed: If workbook already closed.
+        """
+
     @classmethod
     def from_object(
         cls, path_or_filelike: str | os.PathLike | ReadBuffer, load_tables: bool = False
@@ -309,6 +371,7 @@ __all__ = [
     "TablesNotLoaded",
     "TablesNotSupported",
     "WorkbookClosed",
+    "WorkbookProperties",
     "WorksheetNotFound",
     "XmlError",
     "ZipError",

src/lib.rs

@@ -4,7 +4,7 @@ mod types;
 use crate::types::{
     CalamineError, CalamineSheet, CalamineTable, CalamineWorkbook, CellValue, Error, PasswordError,
     SheetMetadata, SheetTypeEnum, SheetVisibleEnum, TableNotFound, TablesNotLoaded,
-    TablesNotSupported, WorkbookClosed, WorksheetNotFound, XmlError, ZipError,
+    TablesNotSupported, WorkbookClosed, WorkbookProperties, WorksheetNotFound, XmlError, ZipError,
 };
 
 #[pyfunction]
@@ -26,6 +26,7 @@ fn _python_calamine(py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<SheetTypeEnum>()?;
     m.add_class::<SheetVisibleEnum>()?;
     m.add_class::<CalamineTable>()?;
+    m.add_class::<WorkbookProperties>()?;
     m.add("CalamineError", py.get_type::<CalamineError>())?;
     m.add("PasswordError", py.get_type::<PasswordError>())?;
     m.add("WorksheetNotFound", py.get_type::<WorksheetNotFound>())?;

src/types/mod.rs

@@ -3,6 +3,7 @@ mod errors;
 mod sheet;
 mod table;
 mod workbook;
+mod workbook_properties;
 pub use cell::CellValue;
 pub use errors::{
     CalamineError, Error, PasswordError, TableNotFound, TablesNotLoaded, TablesNotSupported,
@@ -11,3 +12,4 @@ pub use errors::{
 pub use sheet::{CalamineSheet, SheetMetadata, SheetTypeEnum, SheetVisibleEnum};
 pub use table::CalamineTable;
 pub use workbook::CalamineWorkbook;
+pub use workbook_properties::WorkbookProperties;

src/types/workbook.rs

@@ -10,7 +10,9 @@ use pyo3::prelude::*;
 use pyo3::types::PyType;
 use pyo3_file::PyFileLikeObject;
 
-use crate::{CalamineSheet, CalamineTable, Error, SheetMetadata, WorksheetNotFound};
+use crate::{
+    CalamineSheet, CalamineTable, Error, SheetMetadata, WorkbookProperties, WorksheetNotFound,
+};
 
 enum SheetsEnum {
     File(Sheets<BufReader<File>>),
@@ -65,6 +67,15 @@ impl SheetsEnum {
         }
     }
 
+    fn workbook_properties(&mut self) -> Result<WorkbookProperties, Error> {
+        match self {
+            SheetsEnum::File(f) => f.workbook_properties().map_err(Error::Calamine),
+            SheetsEnum::FileLike(f) => f.workbook_properties().map_err(Error::Calamine),
+            SheetsEnum::None => Err(Error::WorkbookClosed),
+        }
+        .map(WorkbookProperties::from)
+    }
+
     fn worksheet_range(&mut self, name: &str) -> Result<calamine::Range<calamine::Data>, Error> {
         match self {
             SheetsEnum::File(f) => f.worksheet_range(name).map_err(Error::Calamine),
@@ -265,6 +276,11 @@ impl CalamineWorkbook {
         }
     }
 
+    #[getter]
+    fn workbook_properties(&mut self, py: Python<'_>) -> PyResult<WorkbookProperties> {
+        py.detach(|| Ok(self.sheets.workbook_properties()?))
+    }
+
     #[pyo3(name = "get_table_by_name")]
     fn py_get_table_by_name(&mut self, py: Python<'_>, name: &str) -> PyResult<CalamineTable> {
         py.detach(|| self.get_table_by_name(name))

src/types/workbook_properties.rs

@@ -0,0 +1,134 @@
+use std::collections::BTreeMap;
+
+use chrono::{DateTime, FixedOffset, NaiveDateTime};
+use pyo3::prelude::*;
+
+/// A document property date, with a UTC offset if the file stores one.
+#[derive(Clone, Debug, PartialEq, IntoPyObject)]
+enum PropertyDate {
+    Aware(DateTime<FixedOffset>),
+    Naive(NaiveDateTime),
+}
+
+impl PropertyDate {
+    /// Parse a date such as "2024-01-15T08:30:00Z" (xlsx, xlsb, xls) or
+    /// "2024-06-20T14:22:00.123456789" (ods). Other formats return `None`.
+    fn parse(value: &str) -> Option<Self> {
+        let value = value.trim();
+        if let Ok(date) = DateTime::parse_from_rfc3339(value) {
+            return Some(PropertyDate::Aware(date));
+        }
+        NaiveDateTime::parse_from_str(value, "%Y-%m-%dT%H:%M:%S%.f")
+            .ok()
+            .map(PropertyDate::Naive)
+    }
+}
+
+/// Document properties of a workbook, such as the creator, title and company.
+#[pyclass(eq, from_py_object)]
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct WorkbookProperties {
+    #[pyo3(get)]
+    creator: Option<String>,
+    #[pyo3(get)]
+    last_modified_by: Option<String>,
+    #[pyo3(get)]
+    created: Option<PropertyDate>,
+    #[pyo3(get)]
+    modified: Option<PropertyDate>,
+    #[pyo3(get)]
+    title: Option<String>,
+    #[pyo3(get)]
+    subject: Option<String>,
+    #[pyo3(get)]
+    description: Option<String>,
+    #[pyo3(get)]
+    keywords: Option<String>,
+    #[pyo3(get)]
+    category: Option<String>,
+    #[pyo3(get)]
+    content_status: Option<String>,
+    #[pyo3(get)]
+    revision: Option<String>,
+    #[pyo3(get)]
+    version: Option<String>,
+    #[pyo3(get)]
+    application: Option<String>,
+    #[pyo3(get)]
+    app_version: Option<String>,
+    #[pyo3(get)]
+    company: Option<String>,
+    #[pyo3(get)]
+    template: Option<String>,
+    #[pyo3(get)]
+    manager: Option<String>,
+    #[pyo3(get)]
+    custom_properties: BTreeMap<String, String>,
+}
+
+#[pymethods]
+impl WorkbookProperties {
+    fn __repr__(&self, py: Python<'_>) -> PyResult<String> {
+        let fields = [
+            ("creator", self.creator.clone().into_pyobject(py)?),
+            (
+                "last_modified_by",
+                self.last_modified_by.clone().into_pyobject(py)?,
+            ),
+            ("created", self.created.clone().into_pyobject(py)?),
+            ("modified", self.modified.clone().into_pyobject(py)?),
+            ("title", self.title.clone().into_pyobject(py)?),
+            ("subject", self.subject.clone().into_pyobject(py)?),
+            ("description", self.description.clone().into_pyobject(py)?),
+            ("keywords", self.keywords.clone().into_pyobject(py)?),
+            ("category", self.category.clone().into_pyobject(py)?),
+            (
+                "content_status",
+                self.content_status.clone().into_pyobject(py)?,
+            ),
+            ("revision", self.revision.clone().into_pyobject(py)?),
+            ("version", self.version.clone().into_pyobject(py)?),
+            ("application", self.application.clone().into_pyobject(py)?),
+            ("app_version", self.app_version.clone().into_pyobject(py)?),
+            ("company", self.company.clone().into_pyobject(py)?),
+            ("template", self.template.clone().into_pyobject(py)?),
+            ("manager", self.manager.clone().into_pyobject(py)?),
+        ];
+        let mut parts = Vec::new();
+        for (name, value) in fields {
+            if !value.is_none() {
+                parts.push(format!("{name}={}", value.repr()?));
+            }
+        }
+        if !self.custom_properties.is_empty() {
+            let custom = (&self.custom_properties).into_pyobject(py)?;
+            parts.push(format!("custom_properties={}", custom.repr()?));
+        }
+        Ok(format!("WorkbookProperties({})", parts.join(", ")))
+    }
+}
+
+impl From<calamine::WorkbookProperties> for WorkbookProperties {
+    fn from(props: calamine::WorkbookProperties) -> Self {
+        WorkbookProperties {
+            creator: props.creator,
+            last_modified_by: props.last_modified_by,
+            created: props.created.as_deref().and_then(PropertyDate::parse),
+            modified: props.modified.as_deref().and_then(PropertyDate::parse),
+            title: props.title,
+            subject: props.subject,
+            description: props.description,
+            keywords: props.keywords,
+            category: props.category,
+            content_status: props.content_status,
+            revision: props.revision,
+            version: props.version,
+            application: props.application,
+            app_version: props.app_version,
+            company: props.company,
+            template: props.template,
+            manager: props.manager,
+            custom_properties: props.custom_properties.into_iter().collect(),
+        }
+    }
+}