gedcomkit 0.1.5__tar.gz → 0.1.6__tar.gz

{gedcomkit-0.1.5 → gedcomkit-0.1.6}/CHANGELOG.md

@@ -5,6 +5,55 @@ format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 the project uses semantic versioning within the usual pre-1.0 compatibility
 rules.
 
+## [0.1.6] - 2026-09-25
+
+### Added
+
+- `build`, for a producer writing its own data as GEDCOM rather than
+  reading a file. `build::NodeSpec` describes a structure (tag, optional
+  identifier and payload, substructures) and `NodeSpec::into_node` checks
+  it under `Limits`, refusing with an error what `Node::new` would panic on;
+  with the `serde` feature it deserializes, refusing unknown keys.
+  `Document::append_records` adds records before the trailer, all or none,
+  refusing a repeated identifier or a second header or trailer, and
+  `Document::append_structures` adds substructures to any record or the
+  header (which 5.5.1 wants a `SUBM` pointer in, and `new_v551` cannot
+  supply), leaving every existing line as it was.
+- `Document::wrap_long_lines`, which fits a 5.5.1 document to a line limit
+  by splitting payloads across `CONC` lines — at character boundaries, and
+  not beside a space where the text allows — and names every structure it
+  rewrote. Lines that fit are untouched; a version 7 document is refused.
+- `dates::GedcomDate::to_gedcom_5_5_1`, the reading written in 5.5.1's own
+  date grammar (`about 5 January 1882` → `ABT 5 JAN 1882`), or `None` when
+  that grammar cannot hold it without loss. A dual year it can spell
+  (`1740/41`) is kept; a slashed pair it cannot makes an exact date an `INT`
+  date carrying the original as its phrase.
+- Python and JavaScript/WASM bindings: `Gedcom.new_v551` / `newV551`,
+  `new_v7` / `newV7`, `append_records` / `appendRecords` (records as plain
+  dicts/objects), `append_structures` / `appendStructures`, `wrap_long_lines` / `wrapLongLines`, and
+  `parse_date` / `parseDate`, a date reading with its `display` and
+  `gedcom551` renderings.
+- Python only: `ArchiveFileWriter`, a GEDZIP writer whose sink is a file,
+  with `add_file` streaming an entry from disk without the bytes passing
+  through Python — so a multi-gigabyte archive no longer has to fit in
+  memory twice. And type stubs (`gedcomkit.pyi`), so the package is typed
+  for mypy and pyright.
+
+### Fixed
+
+- The date reader accepts 5.5.1's `B.C.` epoch as well as 7.0's `BCE`.
+- The date reader matched its keywords by ASCII case only, so `après 12
+  juillet 1670` and `før 1679` went unread although both words were in its
+  tables. Keywords now compare case in every script, and may run straight
+  into the date (`abt1810`, `c1700`).
+- `April 9, 1950` read its `9` as September and failed; a month written as a
+  word now decides the order. `10 January 1566/67`, a dual year ending a full
+  date, now reads as 1566 as the bare `1566/67` already did.
+- More spellings: `vers`, `cir`, `c.`, `around`, `probably`, `omtrent`,
+  `cirka` (about); `før` (before); `etter`, `efter` (after); `entre … et …`,
+  `mellom … og …` (between); `du … au …`, `fra … til …` (from … to);
+  and the months `déc`, `févr`, `janv`, `avr`, `juil`, `desember`.
+
 ## [0.1.5] - 2026-09-18
 
 ### Added

{gedcomkit-0.1.5 → gedcomkit-0.1.6}/Cargo.lock

@@ -35,7 +35,7 @@ dependencies = [
 
 [[package]]
 name = "gedcomkit"
-version = "0.1.5"
+version = "0.1.6"
 dependencies = [
  "flate2",
  "serde",

{gedcomkit-0.1.5 → gedcomkit-0.1.6}/Cargo.toml

@@ -3,7 +3,7 @@
 # was checked on crates.io, npm, and PyPI before the initial release.
 [package]
 name = "gedcomkit"
-version = "0.1.5"
+version = "0.1.6"
 description = "A byte-preserving GEDCOM document model: decoding, parsing, readings, version conversion, plausibility checks, and the GEDZIP container, for GEDCOM 5.5 through 7.x."
 edition = "2024"
 # The true minimum, not the workspace's toolchain: a parser library is a leaf

{gedcomkit-0.1.5 → gedcomkit-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gedcomkit
-Version: 0.1.5
+Version: 0.1.6
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython

{gedcomkit-0.1.5 → gedcomkit-0.1.6}/bindings/gedcomkit-py/Cargo.lock

@@ -35,7 +35,7 @@ dependencies = [
 
 [[package]]
 name = "gedcomkit"
-version = "0.1.5"
+version = "0.1.6"
 dependencies = [
  "flate2",
  "serde",
@@ -43,7 +43,7 @@ dependencies = [
 
 [[package]]
 name = "gedcomkit-py"
-version = "0.1.5"
+version = "0.1.6"
 dependencies = [
  "gedcomkit",
  "pyo3",

{gedcomkit-0.1.5 → gedcomkit-0.1.6}/bindings/gedcomkit-py/Cargo.toml

@@ -2,7 +2,7 @@
 # abi3 keeps it to one wheel per platform across Python versions.
 [package]
 name = "gedcomkit-py"
-version = "0.1.5"
+version = "0.1.6"
 description = "Python bindings for gedcomkit: an archival-grade GEDCOM library — byte-preserving round-trip, encoding detection, GEDCOM 5.5 through 7.x, GEDZIP."
 edition = "2024"
 rust-version = "1.88"

gedcomkit-0.1.6/bindings/gedcomkit-py/gedcomkit.pyi

@@ -0,0 +1,84 @@
+"""Type stubs for gedcomkit, an archival-grade GEDCOM library.
+
+Views, findings and reports are plain dicts built from the core's JSON
+serialization; their keys are camelCase, as the Rust types name them.
+"""
+
+from os import PathLike
+from typing import Any, TypedDict
+
+from typing_extensions import NotRequired
+
+__version__: str
+
+class RecordSpec(TypedDict):
+    """A structure to add: only ``tag`` is required, and any other key is refused."""
+
+    tag: str
+    xref: NotRequired[str | None]
+    value: NotRequired[str | None]
+    children: NotRequired[list[RecordSpec]]
+
+class WrappedLine(TypedDict):
+    record: str
+    path: list[int]
+    tag: str
+
+class Gedcom:
+    @staticmethod
+    def parse(data: bytes) -> Gedcom:
+        """Read a document from a file's bytes; raises ValueError past the bounds."""
+    @staticmethod
+    def new_v551(source_system: str) -> Gedcom:
+        """An empty GEDCOM 5.5.1 document naming its producing system, declaring UTF-8."""
+    @staticmethod
+    def new_v7() -> Gedcom:
+        """An empty GEDCOM 7.0 document."""
+    @property
+    def encoding(self) -> str: ...
+    @property
+    def version(self) -> str | None: ...
+    @property
+    def content_records(self) -> int: ...
+    def records(self) -> list[dict[str, Any]]: ...
+    def record(self, xref: str) -> dict[str, Any]: ...
+    def individuals(self) -> list[dict[str, Any]]: ...
+    def families(self) -> list[dict[str, Any]]: ...
+    def validate(self) -> list[dict[str, Any]]: ...
+    def unresolved_pointers(self) -> list[dict[str, Any]]: ...
+    def parents_of(self, xref: str) -> list[str]: ...
+    def children_of(self, xref: str) -> list[str]: ...
+    def partners_of(self, xref: str) -> list[str]: ...
+    def append_records(self, records: list[RecordSpec]) -> None:
+        """Add records before the trailer, all or none; raises ValueError."""
+    def append_structures(
+        self, record: str, path: list[int], structures: list[RecordSpec]
+    ) -> None:
+        """Add substructures under ``path`` in ``record`` (an xref, or "HEAD")."""
+    def wrap_long_lines(self, max_line_bytes: int = 255) -> list[WrappedLine]:
+        """Split lines over the limit across CONC lines and name each one rewritten."""
+    def set_logical_value(self, xref: str, path: list[int], value: str) -> None: ...
+    def to_text(self) -> str: ...
+    def to_bytes(self) -> bytes: ...
+    def to_version7(self) -> tuple[Gedcom, list[dict[str, Any]]]: ...
+    def to_version551(self) -> tuple[Gedcom, list[dict[str, Any]]]: ...
+    def __len__(self) -> int: ...
+
+class ArchiveWriter:
+    @staticmethod
+    def new() -> ArchiveWriter: ...
+    def add(self, name: str, data: bytes) -> None: ...
+    def finish(self) -> bytes: ...
+
+class ArchiveFileWriter:
+    """A GEDZIP archive written straight to a file, one entry at a time."""
+
+    def __init__(self, path: str | PathLike[str]) -> None: ...
+    def add(self, name: str, data: bytes) -> None: ...
+    def add_file(self, name: str, source: str | PathLike[str]) -> None: ...
+    def finish(self) -> int:
+        """Close the archive and return its size in bytes."""
+
+def archive_total_size(data: bytes) -> int: ...
+def parse_date(text: str) -> dict[str, Any]:
+    """A date reading; its ``gedcom551`` key is the 5.5.1 spelling, or None."""

{gedcomkit-0.1.5 → gedcomkit-0.1.6}/bindings/gedcomkit-py/src/lib.rs

@@ -4,17 +4,24 @@
 //! wrapping the document and its encoding report, read-only views handed
 //! over as plain Python objects (via JSON), and the one edit primitive the
 //! byte-preservation design blesses — `set_logical_value` addressed by
-//! record and structure path. Everything else stays in Rust.
+//! record and structure path. A producer writing its own data starts from
+//! `new_v551`/`new_v7` and adds records described as plain dicts. Everything
+//! else stays in Rust.
 
+use gedcomkit::build::NodeSpec;
+use gedcomkit::dates::GedcomDate;
 use gedcomkit::family::FamilyGraph;
 use gedcomkit::gedzip::{self, Archive};
 use gedcomkit::view::{FamilyView, IndividualView, RecordView};
-use gedcomkit::{Document, EncodingReport};
-use pyo3::exceptions::{PyKeyError, PyValueError};
+use gedcomkit::{Document, EncodingReport, GedcomEncoding, Limits};
+use pyo3::exceptions::{PyKeyError, PyOSError, PyValueError};
 use pyo3::prelude::*;
 use pyo3::types::{PyBytes, PyModule};
 use pyo3::wrap_pyfunction;
 use serde::Serialize;
+use std::fs::File;
+use std::io::{BufWriter, Write as _};
+use std::path::PathBuf;
 
 /// A parsed GEDCOM document and the report of how its bytes were read.
 #[pyclass]
@@ -34,11 +41,36 @@ fn to_py<T: Serialize>(py: Python<'_>, value: &T) -> PyResult<Py<PyAny>> {
     Ok(loads.call1((json,))?.unbind())
 }
 
+/// The Python object passed in, read as the JSON it would serialize to —
+/// the inverse of `to_py`, so both directions share one conversion.
+fn from_py<T: serde::de::DeserializeOwned>(
+    py: Python<'_>,
+    value: &Bound<'_, PyAny>,
+) -> PyResult<T> {
+    let dumps = py.import("json")?.getattr("dumps")?;
+    let json: String = dumps.call1((value,))?.extract()?;
+    serde_json::from_str(&json).map_err(value_error)
+}
+
+fn value_error(error: impl std::fmt::Display) -> PyErr {
+    PyValueError::new_err(error.to_string())
+}
+
 impl Gedcom {
     fn graph(&mut self) -> &FamilyGraph {
         self.graph
             .get_or_insert_with(|| FamilyGraph::new(&self.document))
     }
+
+    /// A handle on a document this process wrote rather than read: its text
+    /// is UTF-8 by construction.
+    fn written(document: Document) -> Self {
+        Self {
+            document,
+            report: EncodingReport::for_encoding(GedcomEncoding::Utf8),
+            graph: None,
+        }
+    }
 }
 
 #[pymethods]
@@ -56,6 +88,85 @@ impl Gedcom {
         })
     }
 
+    /// An empty GEDCOM 5.5.1 document — header and trailer — naming the
+    /// producing system, which 5.5.1 requires, and declaring UTF-8.
+    #[staticmethod]
+    fn new_v551(source_system: &str) -> Self {
+        Self::written(Document::new_v551(source_system))
+    }
+
+    /// An empty GEDCOM 7.0 document: header and trailer.
+    #[staticmethod]
+    fn new_v7() -> Self {
+        Self::written(Document::new_v7())
+    }
+
+    /// Adds records before the trailer, all or none. Each record is a dict
+    /// `{"tag", "xref", "value", "children"}` — only `tag` required, any
+    /// other key refused — and each child the same shape without `xref`. A
+    /// newline in a value becomes a `CONT` line. Raises `ValueError`, adding
+    /// nothing, for a tag or identifier the parser would not read back, a
+    /// repeated identifier, a header or trailer, or input past the default
+    /// bounds.
+    fn append_records(&mut self, py: Python<'_>, records: &Bound<'_, PyAny>) -> PyResult<()> {
+        let specs: Vec<NodeSpec> = from_py(py, records)?;
+        let nodes = specs
+            .into_iter()
+            .map(|spec| spec.into_node(Limits::DEFAULT))
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(value_error)?;
+        self.document.append_records(nodes).map_err(value_error)?;
+        self.graph = None;
+        Ok(())
+    }
+
+    /// Adds substructures, described as `append_records` describes records
+    /// but without `xref`, after the existing ones of the structure at
+    /// `path` in `record` — a cross-reference identifier, or `"HEAD"` for
+    /// the header. Every existing line stays as it was. Raises `ValueError`,
+    /// adding nothing, when nothing answers to the address or a description
+    /// is refused.
+    fn append_structures(
+        &mut self,
+        py: Python<'_>,
+        record: &str,
+        path: Vec<usize>,
+        structures: &Bound<'_, PyAny>,
+    ) -> PyResult<()> {
+        let specs: Vec<NodeSpec> = from_py(py, structures)?;
+        let nodes = specs
+            .into_iter()
+            .map(|spec| spec.into_substructure(Limits::DEFAULT))
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(value_error)?;
+        self.document
+            .append_structures(record, &path, nodes)
+            .map_err(value_error)?;
+        self.graph = None;
+        Ok(())
+    }
+
+    /// Splits every line longer than `max_line_bytes` (terminator included;
+    /// 255 is GEDCOM 5.5.1's limit) across `CONC` lines, and returns each
+    /// structure it rewrote as `{"record", "path", "tag"}`. Lines that fit
+    /// are left exactly as they are. Raises `ValueError` for a version 7
+    /// document, which has no `CONC`, or a limit under 32.
+    #[pyo3(signature = (max_line_bytes = 255))]
+    fn wrap_long_lines(
+        &mut self,
+        py: Python<'_>,
+        max_line_bytes: usize,
+    ) -> PyResult<Vec<Py<PyAny>>> {
+        let wrapped = self
+            .document
+            .wrap_long_lines(max_line_bytes)
+            .map_err(value_error)?;
+        if !wrapped.is_empty() {
+            self.graph = None;
+        }
+        wrapped.iter().map(|line| to_py(py, line)).collect()
+    }
+
     /// What decoding decided, one line — show it before accepting an import.
     #[getter]
     fn encoding(&self) -> String {
@@ -284,6 +395,104 @@ impl Default for ArchiveWriter {
     }
 }
 
+/// Writes a GEDZIP archive straight to a file, one entry at a time, so
+/// memory stays a small multiple of the largest single entry however large
+/// the archive grows. Python only: the WASM binding has no filesystem.
+///
+/// The file is created at once and is complete only after `finish`; an
+/// archive abandoned part-way (an error, or no `finish`) leaves a partial
+/// file behind. Write to a temporary path and rename it after `finish`.
+#[pyclass]
+struct ArchiveFileWriter {
+    /// `None` once `finish` has been called.
+    inner: Option<gedzip::ArchiveWriter<BufWriter<File>>>,
+    path: PathBuf,
+}
+
+#[pymethods]
+impl ArchiveFileWriter {
+    /// Creates (or truncates) the file at `path` and starts an archive in it
+    /// under the default bounds. Raises `OSError` when the file cannot be
+    /// created.
+    #[new]
+    fn new(path: PathBuf) -> PyResult<Self> {
+        let file = File::create(&path).map_err(|error| os_error(&path, &error))?;
+        Ok(Self {
+            inner: Some(gedzip::ArchiveWriter::new(BufWriter::new(file))),
+            path,
+        })
+    }
+
+    /// Adds one entry from bytes. Raises `ValueError` for an unsafe or
+    /// repeated path, one past the per-entry limit, a failed write, or a call
+    /// after `finish`.
+    fn add(&mut self, name: &str, data: &[u8]) -> PyResult<()> {
+        self.writer()?.add(name, data).map_err(value_error)
+    }
+
+    /// Adds one entry read from the file at `source`, without the bytes ever
+    /// passing through Python. Raises `OSError` when it cannot be opened and
+    /// `ValueError` as `add` does.
+    fn add_file(&mut self, name: &str, source: PathBuf) -> PyResult<()> {
+        let file = File::open(&source).map_err(|error| os_error(&source, &error))?;
+        self.writer()?.add(name, file).map_err(value_error)
+    }
+
+    /// Writes the central directory, flushes, and closes the file, returning
+    /// its size in bytes. Valid to call once.
+    fn finish(&mut self) -> PyResult<u64> {
+        let writer = self
+            .inner
+            .take()
+            .ok_or_else(|| PyValueError::new_err("finish() was already called"))?;
+        let mut sink = writer.finish().map_err(value_error)?;
+        sink.flush().map_err(|error| os_error(&self.path, &error))?;
+        drop(sink);
+        std::fs::metadata(&self.path)
+            .map(|metadata| metadata.len())
+            .map_err(|error| os_error(&self.path, &error))
+    }
+}
+
+impl ArchiveFileWriter {
+    fn writer(&mut self) -> PyResult<&mut gedzip::ArchiveWriter<BufWriter<File>>> {
+        self.inner
+            .as_mut()
+            .ok_or_else(|| PyValueError::new_err("finish() was already called"))
+    }
+}
+
+fn os_error(path: &std::path::Path, error: &std::io::Error) -> PyErr {
+    PyOSError::new_err(format!("{}: {error}", path.display()))
+}
+
+/// A date reading, with the two renderings a caller most often wants.
+#[derive(Serialize)]
+struct DateReading<'a> {
+    #[serde(flatten)]
+    date: &'a GedcomDate,
+    display: String,
+    gedcom551: Option<String>,
+}
+
+/// Reads a date as the library reads any `DATE` payload — every language
+/// and spelling it knows — and returns the reading as a dict: `original`,
+/// `calendar`, `kind`, `earliest`, `latest`, `phrase`, the `display` form,
+/// and `gedcom551`, the reading in GEDCOM 5.5.1's own grammar (`ABT 5 JAN
+/// 1882`), or `None` when that grammar cannot hold it without loss.
+#[pyfunction]
+fn parse_date(py: Python<'_>, text: &str) -> PyResult<Py<PyAny>> {
+    let date = GedcomDate::parse(text);
+    to_py(
+        py,
+        &DateReading {
+            display: date.display(),
+            gedcom551: date.to_gedcom_5_5_1(),
+            date: &date,
+        },
+    )
+}
+
 /// The sum of a GEDZIP archive's entries' claimed decompressed sizes, read
 /// from its central directory alone — nothing is decompressed to answer
 /// this. Raises `ValueError` for bytes that do not open as an archive.
@@ -304,7 +513,9 @@ fn archive_total_size(data: &[u8]) -> PyResult<u64> {
 fn gedcomkit_py(module: &Bound<'_, PyModule>) -> PyResult<()> {
     module.add_class::<Gedcom>()?;
     module.add_class::<ArchiveWriter>()?;
+    module.add_class::<ArchiveFileWriter>()?;
     module.add_function(wrap_pyfunction!(archive_total_size, module)?)?;
+    module.add_function(wrap_pyfunction!(parse_date, module)?)?;
     module.add("__version__", env!("CARGO_PKG_VERSION"))?;
     Ok(())
 }