histwardb 0.1.0__tar.gz

histwardb-0.1.0/LICENSE

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

histwardb-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: histwardb
+Version: 0.1.0
+Summary: A dynamic, programmatic historical and sovereign war dataset built on Wikidata.
+Author: Vincenzo Manto
+License: MIT License
+        
+        Copyright (c) 2026 Vincenzo Manto
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/VincenzoManto/histwardb
+Project-URL: Repository, https://github.com/VincenzoManto/histwardb
+Project-URL: Issues, https://github.com/VincenzoManto/histwardb/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.28
+Requires-Dist: plotly>=5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# HistWarDB 🌍⚔️
+> *Advanced Historical & Sovereign War Dataset powered by Wikidata*
+
+[![Tests](https://github.com/VincenzoManto/histwardb/actions/workflows/tests.yml/badge.svg)](https://github.com/VincenzoManto/histwardb/actions/workflows/tests.yml)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/1410596751.svg)](https://doi.org/10.5281/zenodo.23243673)
+
+**HistoricalWarDB** (HistWarDB) is a dynamic, programmatic Python toolkit designed to extract, clean, and analyze global warfare data from Wikidata spanning from 1700 to the present. Built for researchers, historians, and data scientists, it bridges the gap between crowdsourced knowledge and rigorous historical data pipelines, supporting both modern sovereign states and historical empires.
+
+---
+
+## Key Features
+
+* **Dynamic SPARQL Pipeline:** Fetches conflicts using 25-year temporal chunks to bypass query limits and ensure high data completeness.
+* **Rigorous Anti-Noise Filtering:** Automatically excludes peacekeeping missions (`wd:Q35349`), military exercises (`wd:Q1151430`), and non-state actors.
+* **Historical State Support:** Seamlessly tracks historical entities (e.g., *German Empire*, *Qing dynasty*, *Kingdom of Montenegro*) with built-in lifespan sanity checks.
+* **Flexible Analytical Views:** Instantly transforms data into long formats, binary matrices (`0/1`), conflict name mappings, or custom `LIKE` keyword search results.
+* **Interactive Visualizations:** Out-of-the-box Plotly heatmap generation to visualize global conflict intensity over centuries.
+* **Tested and reproducible:** Network I/O, SPARQL query construction, and data-cleaning logic are separated into independent, unit-tested modules — no live Wikidata access required to run the test suite.
+
+---
+
+## Project layout
+
+```
+src/histwardb/
+    query.py   # SPARQL query construction (pure, no I/O)
+    core.py    # HistWarDB class: fetch, parse, clean, analytical views
+tests/         # pytest suite (parsing, filtering, views, mocked network)
+HistWarDB.ipynb  # usage demo notebook (Colab-compatible)
+```
+
+## Installation
+
+```bash
+pip install git+https://github.com/VincenzoManto/histwardb.git
+```
+
+For local development (editable install + test/lint tooling):
+
+```bash
+git clone https://github.com/VincenzoManto/histwardb.git
+cd histwardb
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+from histwardb import HistWarDB
+
+# Initialize the dataset from 1700 to 2026
+gwd = HistWarDB(start_year=1700, end_year=2026)
+
+# Query specific countries in long format
+france_uk_wars = gwd(countries=["France", "United Kingdom"], view="long", only_in_war=True)
+print(france_uk_wars.head())
+
+# Get a binary matrix for specific historical periods
+binary_view = gwd(countries="German Empire", view="binary", from_date="1900-01-01", to_date="1918-12-31")
+
+# Plot an interactive heatmap for the top 15 conflict-prone states
+gwd.plot_heatmap(top_n=15, from_year=1800, to_year=2026).show()
+```
+
+---
+
+## Supported Views (`view` parameter)
+
+The dataset interface supports multiple analytical views via the `gwd(...)` call:
+
+* **`"long"`**: Standard tidy DataFrame containing columns: `Country`, `Year`, `War_State`, and `Active_Conflicts`.
+* **`"binary"`**: Wide pivot table with countries as rows, years as columns, and binary values (`1` = at war, `0` = peace).
+* **`"names"`**: Wide pivot table containing the literal names of active conflicts per year.
+* **`"list"`**: Alphabetical list of all unique conflict names extracted under current filters.
+* **`"countries"` / `"conflicts"`**: Sorted lists of active entities or unique conflicts matching the query criteria.
+
+---
+
+## Testing
+
+The test suite never queries the live Wikidata endpoint. The `HistWarDB`
+class accepts an injectable `session` object for its HTTP calls, and all
+parsing/filtering logic (`histwardb.core.parse_bindings`,
+`clean_dataframe`, `build_long_grid`) is pure and tested against static
+fixtures:
+
+```bash
+pip install -e ".[dev]"
+pytest --cov=histwardb
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## Citation
+
+If you use **HistWarDB** in your academic research, working paper, or data science project, please cite it using the following format (also available in machine-readable form in [`CITATION.cff`](CITATION.cff)):
+
+```bibtex
+@software{histwardb2026,
+  author = {Vincenzo Manto},
+  title = {HistWarDB: A Dynamic Wikidata-Based Historical War Dataset},
+  year = {2026},
+  url = {https://github.com/VincenzoManto/histwardb}
+}
+```
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.

histwardb-0.1.0/README.md

@@ -0,0 +1,117 @@
+# HistWarDB 🌍⚔️
+> *Advanced Historical & Sovereign War Dataset powered by Wikidata*
+
+[![Tests](https://github.com/VincenzoManto/histwardb/actions/workflows/tests.yml/badge.svg)](https://github.com/VincenzoManto/histwardb/actions/workflows/tests.yml)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/1410596751.svg)](https://doi.org/10.5281/zenodo.23243673)
+
+**HistoricalWarDB** (HistWarDB) is a dynamic, programmatic Python toolkit designed to extract, clean, and analyze global warfare data from Wikidata spanning from 1700 to the present. Built for researchers, historians, and data scientists, it bridges the gap between crowdsourced knowledge and rigorous historical data pipelines, supporting both modern sovereign states and historical empires.
+
+---
+
+## Key Features
+
+* **Dynamic SPARQL Pipeline:** Fetches conflicts using 25-year temporal chunks to bypass query limits and ensure high data completeness.
+* **Rigorous Anti-Noise Filtering:** Automatically excludes peacekeeping missions (`wd:Q35349`), military exercises (`wd:Q1151430`), and non-state actors.
+* **Historical State Support:** Seamlessly tracks historical entities (e.g., *German Empire*, *Qing dynasty*, *Kingdom of Montenegro*) with built-in lifespan sanity checks.
+* **Flexible Analytical Views:** Instantly transforms data into long formats, binary matrices (`0/1`), conflict name mappings, or custom `LIKE` keyword search results.
+* **Interactive Visualizations:** Out-of-the-box Plotly heatmap generation to visualize global conflict intensity over centuries.
+* **Tested and reproducible:** Network I/O, SPARQL query construction, and data-cleaning logic are separated into independent, unit-tested modules — no live Wikidata access required to run the test suite.
+
+---
+
+## Project layout
+
+```
+src/histwardb/
+    query.py   # SPARQL query construction (pure, no I/O)
+    core.py    # HistWarDB class: fetch, parse, clean, analytical views
+tests/         # pytest suite (parsing, filtering, views, mocked network)
+HistWarDB.ipynb  # usage demo notebook (Colab-compatible)
+```
+
+## Installation
+
+```bash
+pip install git+https://github.com/VincenzoManto/histwardb.git
+```
+
+For local development (editable install + test/lint tooling):
+
+```bash
+git clone https://github.com/VincenzoManto/histwardb.git
+cd histwardb
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+from histwardb import HistWarDB
+
+# Initialize the dataset from 1700 to 2026
+gwd = HistWarDB(start_year=1700, end_year=2026)
+
+# Query specific countries in long format
+france_uk_wars = gwd(countries=["France", "United Kingdom"], view="long", only_in_war=True)
+print(france_uk_wars.head())
+
+# Get a binary matrix for specific historical periods
+binary_view = gwd(countries="German Empire", view="binary", from_date="1900-01-01", to_date="1918-12-31")
+
+# Plot an interactive heatmap for the top 15 conflict-prone states
+gwd.plot_heatmap(top_n=15, from_year=1800, to_year=2026).show()
+```
+
+---
+
+## Supported Views (`view` parameter)
+
+The dataset interface supports multiple analytical views via the `gwd(...)` call:
+
+* **`"long"`**: Standard tidy DataFrame containing columns: `Country`, `Year`, `War_State`, and `Active_Conflicts`.
+* **`"binary"`**: Wide pivot table with countries as rows, years as columns, and binary values (`1` = at war, `0` = peace).
+* **`"names"`**: Wide pivot table containing the literal names of active conflicts per year.
+* **`"list"`**: Alphabetical list of all unique conflict names extracted under current filters.
+* **`"countries"` / `"conflicts"`**: Sorted lists of active entities or unique conflicts matching the query criteria.
+
+---
+
+## Testing
+
+The test suite never queries the live Wikidata endpoint. The `HistWarDB`
+class accepts an injectable `session` object for its HTTP calls, and all
+parsing/filtering logic (`histwardb.core.parse_bindings`,
+`clean_dataframe`, `build_long_grid`) is pure and tested against static
+fixtures:
+
+```bash
+pip install -e ".[dev]"
+pytest --cov=histwardb
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## Citation
+
+If you use **HistWarDB** in your academic research, working paper, or data science project, please cite it using the following format (also available in machine-readable form in [`CITATION.cff`](CITATION.cff)):
+
+```bibtex
+@software{histwardb2026,
+  author = {Vincenzo Manto},
+  title = {HistWarDB: A Dynamic Wikidata-Based Historical War Dataset},
+  year = {2026},
+  url = {https://github.com/VincenzoManto/histwardb}
+}
+```
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.

histwardb-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "histwardb"
+version = "0.1.0"
+description = "A dynamic, programmatic historical and sovereign war dataset built on Wikidata."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Vincenzo Manto" }]
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "pandas>=1.5",
+    "requests>=2.28",
+    "plotly>=5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/VincenzoManto/histwardb"
+Repository = "https://github.com/VincenzoManto/histwardb"
+Issues = "https://github.com/VincenzoManto/histwardb/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+
+[tool.ruff.lint]
+# UP006/UP007/UP045: keep typing.Optional/Union/List for readability and
+# consistency with the py3.9 floor, even though `from __future__ import
+# annotations` would allow the newer `X | None` syntax.
+ignore = ["UP006", "UP007", "UP045"]

histwardb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

histwardb-0.1.0/src/histwardb/__init__.py

@@ -0,0 +1,11 @@
+"""HistWarDB: a dynamic, Wikidata-based historical war dataset toolkit."""
+
+from .core import HistWarDB
+from .query import build_sparql_query
+
+# Backward-compatible alias used in earlier notebooks/scripts.
+FastWikidataWarDataset = HistWarDB
+
+__all__ = ["FastWikidataWarDataset", "HistWarDB", "build_sparql_query"]
+
+__version__ = "0.1.0"

histwardb-0.1.0/src/histwardb/core.py

@@ -0,0 +1,372 @@
+"""Core dataset class for HistWarDB.
+
+The design deliberately separates three concerns so each can be tested in
+isolation:
+
+1. Network I/O (:meth:`HistWarDB._fetch_chunk`) -- talks to Wikidata.
+2. Pure parsing/filtering (:func:`parse_bindings`, :func:`clean_dataframe`)
+   -- no I/O, fully unit-testable with static fixtures.
+3. Grid construction and the analytical ``__call__`` interface.
+"""
+
+from __future__ import annotations
+
+import datetime
+import re
+from collections.abc import Iterable, Sequence
+from typing import Optional, Union
+
+import pandas as pd
+import requests
+
+from .query import DEFAULT_USER_AGENT, WIKIDATA_SPARQL_ENDPOINT, build_sparql_query
+
+# Historical states whose real-world dissolution year is not reliably
+# captured by Wikidata's P576/P582 properties. Used to discard anachronistic
+# records (e.g. a "German Empire" war recorded after 1918).
+FORCED_MAX_YEARS = {
+    "German Empire": 1918,
+    "Qing dynasty": 1912,
+    "Kingdom of Montenegro": 1918,
+    "Principality of Montenegro": 1910,
+    "Russian Soviet Federative Socialist Republic": 1991,
+}
+
+VALID_VIEWS = ("long", "binary", "names", "list", "countries", "conflicts")
+
+_YEAR_RE = re.compile(r"([+-]?\d+)")
+
+
+def parse_year(date_str: Optional[str]) -> Optional[int]:
+    """Extract the leading year integer from a Wikidata date literal.
+
+    Returns ``None`` when the input is falsy/not a string or has no digits.
+    """
+    if not date_str or not isinstance(date_str, str):
+        return None
+    match = _YEAR_RE.search(date_str)
+    return int(match.group(1)) if match else None
+
+
+def parse_bindings(bindings: Iterable[dict], end_year: int) -> list[dict]:
+    """Turn raw SPARQL JSON ``bindings`` into flat conflict/country records."""
+    records: list[dict] = []
+    for item in bindings:
+        country = item["countryLabel"]["value"]
+        conflict = item["conflictLabel"]["value"]
+
+        start_year = parse_year(item["startDate"]["value"])
+        raw_end = item["endDate"]["value"] if "endDate" in item else None
+        finish_year = parse_year(raw_end) if raw_end else None
+
+        if start_year is None:
+            continue
+
+        if finish_year is None:
+            finish_year = end_year if start_year >= 1800 else (start_year + 5)
+        else:
+            finish_year = max(finish_year, start_year)
+
+        country_start = parse_year(item["countryStart"]["value"]) if "countryStart" in item else None
+        if "countryEnd" in item:
+            country_end = parse_year(item["countryEnd"]["value"])
+        elif "countryEndFallback" in item:
+            country_end = parse_year(item["countryEndFallback"]["value"])
+        else:
+            country_end = None
+
+        records.append(
+            {
+                "country": country,
+                "conflict_name": conflict,
+                "start_year": start_year,
+                "end_year": finish_year,
+                "country_start": country_start,
+                "country_end": country_end,
+            }
+        )
+    return records
+
+
+def _is_forced_dead(row: pd.Series) -> bool:
+    dead_year = FORCED_MAX_YEARS.get(row["country"])
+    if dead_year is None:
+        return False
+    return row["start_year"] > dead_year or row["end_year"] > dead_year
+
+
+def clean_dataframe(df_raw: pd.DataFrame, start_year: int, end_year: int) -> pd.DataFrame:
+    """Apply anachronism and chronological sanity filters to raw records.
+
+    Pure function: no network access, safe to unit test with synthetic
+    DataFrames.
+    """
+    if df_raw.empty:
+        return df_raw
+
+    df = df_raw.drop_duplicates()
+    df = df[~df["country"].str.contains(r"^Q\d+$", na=False)]
+    if df.empty:
+        return df
+
+    # Drop records for historical states active after their real dissolution.
+    df = df[~df.apply(_is_forced_dead, axis=1)]
+    if df.empty:
+        return df
+
+    # Discard wars entirely outside the requested [start_year, end_year] window.
+    df = df[(df["end_year"] >= start_year) & (df["start_year"] <= end_year)]
+
+    # State lifespan consistency: a war can't predate/postdate the state,
+    # when Wikidata provides those dates. Compare via nullable Float64 so
+    # NaN comparisons resolve to False instead of raising (pandas evaluates
+    # both sides of `|` eagerly, so a plain None/int comparison would blow
+    # up even behind an `isna()` guard).
+    country_start = df["country_start"].astype("Float64")
+    country_end = df["country_end"].astype("Float64")
+    end_year_f = df["end_year"].astype("Float64")
+    start_year_f = df["start_year"].astype("Float64")
+
+    consistent_start = (country_start.isna() | (end_year_f >= country_start)).fillna(False)
+    consistent_end = (country_end.isna() | (start_year_f <= country_end)).fillna(False)
+    df = df[consistent_start & consistent_end]
+
+    return df
+
+
+def build_long_grid(df_clean: pd.DataFrame, start_year: int, end_year: int) -> pd.DataFrame:
+    """Build the dense Country x Year long-format grid from cleaned records."""
+    countries = sorted(df_clean["country"].unique()) if not df_clean.empty else []
+    years = range(start_year, end_year + 1)
+
+    grid = pd.DataFrame(
+        [
+            {"Country": c, "Year": y, "War_State": 0, "Active_Conflicts": ""}
+            for c in countries
+            for y in years
+        ]
+    )
+    if grid.empty:
+        return grid
+
+    grid = grid.set_index(["Country", "Year"])
+
+    for _, row in df_clean.iterrows():
+        c = row["country"]
+        in_y = max(row["start_year"], start_year)
+        fi_y = min(row["end_year"], end_year)
+        name = row["conflict_name"]
+
+        for y in range(in_y, fi_y + 1):
+            key = (c, y)
+            if key not in grid.index:
+                continue
+            grid.at[key, "War_State"] = 1
+            existing = grid.at[key, "Active_Conflicts"]
+            grid.at[key, "Active_Conflicts"] = f"{existing}; {name}".strip("; ") if existing else name
+
+    return grid.reset_index()
+
+
+class HistWarDB:
+    """Dynamic, programmatic historical war dataset built on top of Wikidata.
+
+    Supports sovereign and historical states, anti-noise filtering of
+    non-conflict events, keyword search, and multiple analytical views.
+
+    Parameters
+    ----------
+    start_year, end_year:
+        Inclusive temporal window of the dataset. ``end_year`` defaults to
+        the current year.
+    chunk_size:
+        Size (in years) of the temporal windows used to page around
+        Wikidata's query result limits.
+    session:
+        Optional :class:`requests.Session`-like object used for HTTP calls;
+        override in tests to avoid real network access.
+    auto_fetch:
+        When ``True`` (default), data is fetched immediately on
+        construction. Set to ``False`` to construct an empty instance and
+        call :meth:`fetch_data` (or :meth:`load_records`) manually -- handy
+        for tests and offline usage.
+    """
+
+    def __init__(
+        self,
+        start_year: int = 1700,
+        end_year: Optional[int] = None,
+        chunk_size: int = 25,
+        session: Optional[requests.Session] = None,
+        auto_fetch: bool = True,
+    ) -> None:
+        self.start_year = start_year
+        self.end_year = end_year if end_year else datetime.datetime.now(tz=datetime.timezone.utc).year
+        self.chunk_size = chunk_size
+        self.session = session or requests
+        self.df_long: Optional[pd.DataFrame] = None
+
+        if auto_fetch:
+            self.fetch_data()
+
+    # -- Network layer -----------------------------------------------------
+
+    def _fetch_chunk(self, chunk_start: int, chunk_end: int) -> list[dict]:
+        """Fetch and parse a single temporal chunk. Returns raw bindings."""
+        query = build_sparql_query(chunk_start, chunk_end, self.end_year)
+        headers = {"User-Agent": DEFAULT_USER_AGENT}
+        response = self.session.get(
+            WIKIDATA_SPARQL_ENDPOINT,
+            params={"query": query, "format": "json"},
+            headers=headers,
+            timeout=30,
+        )
+        response.raise_for_status()
+        return response.json()["results"]["bindings"]
+
+    def fetch_data(self) -> None:
+        """Fetch all chunks from Wikidata and build the long-format grid."""
+        all_records: list[dict] = []
+        for chunk_start in range(self.start_year, self.end_year, self.chunk_size):
+            chunk_end = min(chunk_start + self.chunk_size, self.end_year)
+            try:
+                bindings = self._fetch_chunk(chunk_start, chunk_end)
+                all_records.extend(parse_bindings(bindings, self.end_year))
+            except requests.RequestException as exc:
+                print(f"Block {chunk_start}-{chunk_end} temporarily skipped: {exc}")
+                continue
+
+        self.load_records(all_records)
+
+    def load_records(self, records: list[dict]) -> None:
+        """Build the dataset from a list of flat conflict/country records.
+
+        Bypasses the network layer entirely -- used by :meth:`fetch_data`
+        and directly in tests/offline pipelines.
+        """
+        if not records:
+            self.df_long = pd.DataFrame(columns=["Country", "Year", "War_State", "Active_Conflicts"])
+            return
+
+        df_raw = pd.DataFrame(records)
+        df_clean = clean_dataframe(df_raw, self.start_year, self.end_year)
+        self.df_long = build_long_grid(df_clean, self.start_year, self.end_year)
+
+    # -- Query interface -----------------------------------------------------
+
+    def __call__(
+        self,
+        countries: Optional[Union[str, Sequence[str]]] = None,
+        view: str = "long",
+        from_date: Optional[Union[str, int]] = None,
+        to_date: Optional[Union[str, int]] = None,
+        only_in_war: bool = False,
+        keyword: Optional[str] = None,
+    ):
+        """Query the dataset. See module docstring for supported ``view`` values."""
+        if self.df_long is None:
+            raise ValueError("Dataset not initialized. Call fetch_data() or load_records() first.")
+        if view not in VALID_VIEWS:
+            raise ValueError(f"Invalid view {view!r}. Choose from: {', '.join(VALID_VIEWS)}")
+
+        df = self.df_long.copy()
+
+        if countries:
+            c_list = [countries] if isinstance(countries, str) else list(countries)
+            regex_pattern = "|".join(re.escape(c) for c in c_list)
+            df = df[df["Country"].str.contains(regex_pattern, case=False, na=False)]
+
+        if from_date is not None:
+            df = df[df["Year"] >= int(str(from_date).split("-")[0])]
+        if to_date is not None:
+            df = df[df["Year"] <= int(str(to_date).split("-")[0])]
+        if only_in_war:
+            df = df[df["War_State"] == 1]
+        if keyword:
+            df = df[df["Active_Conflicts"].str.contains(keyword, case=False, na=False)]
+
+        return self._render_view(df, view)
+
+    @staticmethod
+    def _render_view(df: pd.DataFrame, view: str):
+        if view == "long":
+            return df
+        if view == "binary":
+            return df.pivot(index="Country", columns="Year", values="War_State").fillna(0).astype(int)
+        if view == "names":
+            return df.pivot(index="Country", columns="Year", values="Active_Conflicts").fillna("")
+        if view == "list":
+            return sorted({item for s in df["Active_Conflicts"].dropna() for item in s.split("; ") if item})
+        if view == "countries":
+            active_df = df[df["War_State"] == 1]
+            return sorted(active_df["Country"].unique())
+        if view == "conflicts":
+            active_df = df[df["War_State"] == 1]
+            unique_conflicts = set()
+            for s in active_df["Active_Conflicts"].dropna():
+                for item in s.split("; "):
+                    if item:
+                        unique_conflicts.add(item)
+            return sorted(unique_conflicts)
+        raise AssertionError(f"Unhandled view: {view}")  # pragma: no cover
+
+    @property
+    def available_countries(self) -> list[str]:
+        if self.df_long is None or self.df_long.empty:
+            return []
+        return sorted(self.df_long["Country"].unique())
+
+    # -- Visualization / export ---------------------------------------------
+
+    def plot_heatmap(self, top_n: int = 20, from_year: Optional[int] = None, to_year: Optional[int] = None):
+        """Build (and return) a Plotly heatmap figure of war intensity over time.
+
+        Does not call ``.show()`` so it can be used headlessly / tested.
+        """
+        import plotly.graph_objects as go
+
+        from_year = self.start_year if from_year is None else from_year
+        to_year = self.end_year if to_year is None else to_year
+
+        df_range = self.df_long[(self.df_long["Year"] >= from_year) & (self.df_long["Year"] <= to_year)]
+        top_countries = df_range.groupby("Country")["War_State"].sum().nlargest(top_n).index.tolist()
+        df_filtered = df_range[df_range["Country"].isin(top_countries)]
+
+        matrix_val = df_filtered.pivot(index="Country", columns="Year", values="War_State").fillna(0)
+        matrix_txt = df_filtered.pivot(index="Country", columns="Year", values="Active_Conflicts").fillna(
+            "No recorded conflicts"
+        )
+
+        fig = go.Figure(
+            data=go.Heatmap(
+                z=matrix_val.values,
+                x=matrix_val.columns,
+                y=matrix_val.index,
+                text=matrix_txt.values,
+                hovertemplate="<b>Country:</b> %{y}<br><b>Year:</b> %{x}<br><b>Conflict(s):</b> %{text}<extra></extra>",
+                colorscale=[[0, "#ffffff"], [1, "#d9534f"]],
+                showscale=False,
+            )
+        )
+        fig.update_layout(
+            title=f"Global War State from Wikidata (Sovereign + Historical States) ({from_year}-{to_year})",
+            xaxis_title="Year",
+            yaxis_title="Country / Historical State",
+            xaxis={'dtick': 10},
+            height=700,
+        )
+        return fig
+
+    def export_csv(self, query_result: pd.DataFrame, filename: str = "histwardb_export.csv") -> str:
+        """Export a query result to CSV and return the written path.
+
+        In a Colab environment, also triggers a browser download.
+        """
+        query_result.to_csv(filename)
+        try:
+            from google.colab import files  # type: ignore
+
+            files.download(filename)
+        except ImportError:
+            pass
+        return filename

histwardb-0.1.0/src/histwardb/query.py

@@ -0,0 +1,72 @@
+"""SPARQL query construction for HistWarDB.
+
+Kept separate from the network/IO layer so the query text itself can be
+unit-tested without hitting the live Wikidata endpoint.
+"""
+
+WIKIDATA_SPARQL_ENDPOINT = "https://query.wikidata.org/sparql"
+
+DEFAULT_USER_AGENT = "HistWarDB/0.1 (academic-research; +https://github.com/VincenzoManto/histwardb)"
+
+# Conflict class: military conflict (and subclasses).
+CONFLICT_CLASS = "wd:Q198"
+
+# Classes excluded from being treated as a "war": peacekeeping missions and
+# military exercises are noise for a sovereign-war dataset.
+EXCLUDED_CONFLICT_CLASSES = ("wd:Q35349", "wd:Q1151430")
+
+# Entity types eligible as belligerents: sovereign state, historical country,
+# country.
+COUNTRY_TYPES = ("wd:Q3624078", "wd:Q3024240", "wd:Q6256")
+
+# Non-state entity classes excluded from the belligerent side: human,
+# organization, national sports team.
+EXCLUDED_COUNTRY_CLASSES = ("wd:Q5", "wd:Q83370", "wd:Q7278")
+
+
+def build_sparql_query(chunk_start: int, chunk_end: int, end_year: int) -> str:
+    """Build the SPARQL query fetching conflicts overlapping [chunk_start, chunk_end).
+
+    Parameters
+    ----------
+    chunk_start, chunk_end:
+        Temporal window (inclusive/exclusive) used to page around Wikidata's
+        query result limits.
+    end_year:
+        Overall dataset end year, used as a fallback for ongoing conflicts
+        with no recorded end date.
+    """
+    excluded_conflicts = "\n".join(
+        f"MINUS {{ ?conflict wdt:P31/wdt:279* {cls} . }}" for cls in EXCLUDED_CONFLICT_CLASSES
+    )
+    excluded_countries = "\n".join(
+        f"MINUS {{ ?country wdt:P31/wdt:279* {cls} . }}" for cls in EXCLUDED_COUNTRY_CLASSES
+    )
+    country_values = " ".join(COUNTRY_TYPES)
+
+    return f"""
+    SELECT DISTINCT ?conflictLabel ?countryLabel ?startDate ?endDate ?countryStart ?countryEnd ?countryEndFallback WHERE {{
+        ?conflict wdt:P31/wdt:279* {CONFLICT_CLASS} ;
+                wdt:P710 ?country ;
+                wdt:P580 ?startDate .
+
+        OPTIONAL {{ ?conflict wdt:P582 ?endDate . }}
+
+        {excluded_conflicts}
+
+        ?country wdt:P31/wdt:279* ?countryType .
+        VALUES ?countryType {{ {country_values} }}
+
+        OPTIONAL {{ ?country wdt:P571 ?countryStart . }}
+        OPTIONAL {{ ?country wdt:P576 ?countryEnd . }}
+        OPTIONAL {{ ?country wdt:P582 ?countryEndFallback . }}
+
+        {excluded_countries}
+
+        BIND(COALESCE(?endDate, "{end_year}-12-31T23:59:59Z"^^xsd:dateTime) as ?effEndDate)
+        FILTER(?startDate < "{chunk_end}-01-01T00:00:00Z"^^xsd:dateTime && ?effEndDate >= "{chunk_start}-01-01T00:00:00Z"^^xsd:dateTime)
+
+        SERVICE wikibase:label {{ bd:serviceParam wikibase:language "en". }}
+    }}
+    LIMIT 5000
+    """

histwardb-0.1.0/src/histwardb.egg-info/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: histwardb
+Version: 0.1.0
+Summary: A dynamic, programmatic historical and sovereign war dataset built on Wikidata.
+Author: Vincenzo Manto
+License: MIT License
+        
+        Copyright (c) 2026 Vincenzo Manto
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/VincenzoManto/histwardb
+Project-URL: Repository, https://github.com/VincenzoManto/histwardb
+Project-URL: Issues, https://github.com/VincenzoManto/histwardb/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.28
+Requires-Dist: plotly>=5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# HistWarDB 🌍⚔️
+> *Advanced Historical & Sovereign War Dataset powered by Wikidata*
+
+[![Tests](https://github.com/VincenzoManto/histwardb/actions/workflows/tests.yml/badge.svg)](https://github.com/VincenzoManto/histwardb/actions/workflows/tests.yml)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![DOI](https://zenodo.org/badge/1410596751.svg)](https://doi.org/10.5281/zenodo.23243673)
+
+**HistoricalWarDB** (HistWarDB) is a dynamic, programmatic Python toolkit designed to extract, clean, and analyze global warfare data from Wikidata spanning from 1700 to the present. Built for researchers, historians, and data scientists, it bridges the gap between crowdsourced knowledge and rigorous historical data pipelines, supporting both modern sovereign states and historical empires.
+
+---
+
+## Key Features
+
+* **Dynamic SPARQL Pipeline:** Fetches conflicts using 25-year temporal chunks to bypass query limits and ensure high data completeness.
+* **Rigorous Anti-Noise Filtering:** Automatically excludes peacekeeping missions (`wd:Q35349`), military exercises (`wd:Q1151430`), and non-state actors.
+* **Historical State Support:** Seamlessly tracks historical entities (e.g., *German Empire*, *Qing dynasty*, *Kingdom of Montenegro*) with built-in lifespan sanity checks.
+* **Flexible Analytical Views:** Instantly transforms data into long formats, binary matrices (`0/1`), conflict name mappings, or custom `LIKE` keyword search results.
+* **Interactive Visualizations:** Out-of-the-box Plotly heatmap generation to visualize global conflict intensity over centuries.
+* **Tested and reproducible:** Network I/O, SPARQL query construction, and data-cleaning logic are separated into independent, unit-tested modules — no live Wikidata access required to run the test suite.
+
+---
+
+## Project layout
+
+```
+src/histwardb/
+    query.py   # SPARQL query construction (pure, no I/O)
+    core.py    # HistWarDB class: fetch, parse, clean, analytical views
+tests/         # pytest suite (parsing, filtering, views, mocked network)
+HistWarDB.ipynb  # usage demo notebook (Colab-compatible)
+```
+
+## Installation
+
+```bash
+pip install git+https://github.com/VincenzoManto/histwardb.git
+```
+
+For local development (editable install + test/lint tooling):
+
+```bash
+git clone https://github.com/VincenzoManto/histwardb.git
+cd histwardb
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+from histwardb import HistWarDB
+
+# Initialize the dataset from 1700 to 2026
+gwd = HistWarDB(start_year=1700, end_year=2026)
+
+# Query specific countries in long format
+france_uk_wars = gwd(countries=["France", "United Kingdom"], view="long", only_in_war=True)
+print(france_uk_wars.head())
+
+# Get a binary matrix for specific historical periods
+binary_view = gwd(countries="German Empire", view="binary", from_date="1900-01-01", to_date="1918-12-31")
+
+# Plot an interactive heatmap for the top 15 conflict-prone states
+gwd.plot_heatmap(top_n=15, from_year=1800, to_year=2026).show()
+```
+
+---
+
+## Supported Views (`view` parameter)
+
+The dataset interface supports multiple analytical views via the `gwd(...)` call:
+
+* **`"long"`**: Standard tidy DataFrame containing columns: `Country`, `Year`, `War_State`, and `Active_Conflicts`.
+* **`"binary"`**: Wide pivot table with countries as rows, years as columns, and binary values (`1` = at war, `0` = peace).
+* **`"names"`**: Wide pivot table containing the literal names of active conflicts per year.
+* **`"list"`**: Alphabetical list of all unique conflict names extracted under current filters.
+* **`"countries"` / `"conflicts"`**: Sorted lists of active entities or unique conflicts matching the query criteria.
+
+---
+
+## Testing
+
+The test suite never queries the live Wikidata endpoint. The `HistWarDB`
+class accepts an injectable `session` object for its HTTP calls, and all
+parsing/filtering logic (`histwardb.core.parse_bindings`,
+`clean_dataframe`, `build_long_grid`) is pure and tested against static
+fixtures:
+
+```bash
+pip install -e ".[dev]"
+pytest --cov=histwardb
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## Citation
+
+If you use **HistWarDB** in your academic research, working paper, or data science project, please cite it using the following format (also available in machine-readable form in [`CITATION.cff`](CITATION.cff)):
+
+```bibtex
+@software{histwardb2026,
+  author = {Vincenzo Manto},
+  title = {HistWarDB: A Dynamic Wikidata-Based Historical War Dataset},
+  year = {2026},
+  url = {https://github.com/VincenzoManto/histwardb}
+}
+```
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.

histwardb-0.1.0/src/histwardb.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/histwardb/__init__.py
+src/histwardb/core.py
+src/histwardb/query.py
+src/histwardb.egg-info/PKG-INFO
+src/histwardb.egg-info/SOURCES.txt
+src/histwardb.egg-info/dependency_links.txt
+src/histwardb.egg-info/requires.txt
+src/histwardb.egg-info/top_level.txt
+tests/test_dataset.py
+tests/test_fetch.py
+tests/test_parsing.py
+tests/test_query.py

histwardb-0.1.0/src/histwardb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

histwardb-0.1.0/src/histwardb.egg-info/requires.txt

@@ -0,0 +1,8 @@
+pandas>=1.5
+requests>=2.28
+plotly>=5.0
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+ruff>=0.5

histwardb-0.1.0/src/histwardb.egg-info/top_level.txt

@@ -0,0 +1 @@
+histwardb

histwardb-0.1.0/tests/test_dataset.py

@@ -0,0 +1,71 @@
+import pytest
+
+from histwardb import HistWarDB
+
+
+def test_long_view_has_full_grid(dataset_from_bindings):
+    df = dataset_from_bindings(view="long")
+    # 1900-2026 inclusive = 127 years, for each of the 3 surviving countries
+    years = dataset_from_bindings.end_year - dataset_from_bindings.start_year + 1
+    assert len(df) == years * len(dataset_from_bindings.available_countries)
+
+
+def test_war_state_set_for_active_years(dataset_from_bindings):
+    df = dataset_from_bindings(countries="France", from_date=1939, to_date=1945, view="long")
+    assert (df["War_State"] == 1).all()
+    before = dataset_from_bindings(countries="France", from_date=1930, to_date=1938, view="long")
+    assert (before["War_State"] == 0).all()
+
+
+def test_german_empire_anachronism_excluded(dataset_from_bindings):
+    assert "German Empire" not in dataset_from_bindings.available_countries
+
+
+def test_binary_view_shape(dataset_from_bindings):
+    binary = dataset_from_bindings(countries=["France", "United Kingdom"], view="binary")
+    assert set(binary.index) == {"France", "United Kingdom"}
+    assert binary.loc["France", 1940] == 1
+
+
+def test_names_view_contains_conflict_name(dataset_from_bindings):
+    names = dataset_from_bindings(countries="France", from_date=1940, to_date=1940, view="names")
+    assert "Test War One" in names.loc["France", 1940]
+
+
+def test_list_view_returns_sorted_unique_names(dataset_from_bindings):
+    result = dataset_from_bindings(view="list")
+    assert result == sorted(set(result))
+
+
+def test_countries_view_only_includes_active(dataset_from_bindings):
+    result = dataset_from_bindings(from_date=1939, to_date=1945, view="countries")
+    assert "France" in result
+    assert "United Kingdom" in result
+
+
+def test_conflicts_view(dataset_from_bindings):
+    result = dataset_from_bindings(from_date=1939, to_date=1945, view="conflicts")
+    assert "Test War One" in result
+
+
+def test_keyword_filter(dataset_from_bindings):
+    result = dataset_from_bindings(keyword="Ongoing", view="countries", only_in_war=True)
+    assert result == ["Narnia"]
+
+
+def test_invalid_view_raises(dataset_from_bindings):
+    with pytest.raises(ValueError):
+        dataset_from_bindings(view="not-a-real-view")
+
+
+def test_uninitialized_dataset_raises():
+    db = HistWarDB(auto_fetch=False)
+    with pytest.raises(ValueError):
+        db(view="long")
+
+
+def test_load_records_with_empty_list_produces_empty_frame():
+    db = HistWarDB(auto_fetch=False)
+    db.load_records([])
+    assert db.df_long.empty
+    assert db.available_countries == []

histwardb-0.1.0/tests/test_fetch.py

@@ -0,0 +1,52 @@
+"""Tests for the network layer, using a fake requests session (no live calls)."""
+
+
+from histwardb import HistWarDB
+
+
+class FakeResponse:
+    def __init__(self, bindings, status_code=200):
+        self._bindings = bindings
+        self.status_code = status_code
+
+    def raise_for_status(self):
+        if self.status_code >= 400:
+            raise RuntimeError(f"HTTP {self.status_code}")
+
+    def json(self):
+        return {"results": {"bindings": self._bindings}}
+
+
+class FakeSession:
+    """Returns the same canned bindings for every chunk request."""
+
+    def __init__(self, bindings):
+        self.bindings = bindings
+        self.calls = []
+
+    def get(self, url, params=None, headers=None, timeout=None):
+        self.calls.append((url, params))
+        return FakeResponse(self.bindings)
+
+
+class FailingSession:
+    def get(self, url, params=None, headers=None, timeout=None):
+        import requests
+
+        raise requests.ConnectionError("simulated network failure")
+
+
+def test_fetch_data_uses_injected_session(sample_bindings):
+    session = FakeSession(sample_bindings)
+    db = HistWarDB(start_year=1925, end_year=1975, chunk_size=25, session=session)
+    assert db.df_long is not None
+    assert not db.df_long.empty
+    # one request per 25-year chunk in [1925, 1975)
+    assert len(session.calls) == 2
+
+
+def test_fetch_data_survives_network_failures():
+    db = HistWarDB(start_year=1900, end_year=1950, session=FailingSession())
+    # all chunks fail -> empty but initialized dataframe, no exception raised
+    assert db.df_long is not None
+    assert db.df_long.empty

histwardb-0.1.0/tests/test_parsing.py

@@ -0,0 +1,116 @@
+import pandas as pd
+import pytest
+
+from histwardb.core import clean_dataframe, parse_bindings, parse_year
+
+
+@pytest.mark.parametrize(
+    "value,expected",
+    [
+        (None, None),
+        ("", None),
+        (123, None),  # not a string
+        ("1939-01-01T00:00:00Z", 1939),
+        ("-0500-01-01T00:00:00Z", -500),
+        ("no digits here", None),
+    ],
+)
+def test_parse_year(value, expected):
+    assert parse_year(value) == expected
+
+
+def test_parse_bindings_fills_missing_end_date_recent(sample_bindings):
+    records = parse_bindings(sample_bindings, end_year=2026)
+    narnia = next(r for r in records if r["country"] == "Narnia")
+    assert narnia["start_year"] == 2020
+    assert narnia["end_year"] == 2026  # no end date, recent conflict -> runs to dataset end
+
+
+def test_parse_bindings_skips_entries_without_start_date():
+    bindings = [
+        {
+            "countryLabel": {"value": "Atlantis"},
+            "conflictLabel": {"value": "Mystery War"},
+            "startDate": {"value": "not-a-date"},
+        }
+    ]
+    # parse_year will return None for "not-a-date" has no digits -> skipped
+    records = parse_bindings(bindings, end_year=2026)
+    assert records == []
+
+
+def test_clean_dataframe_drops_forced_dead_states():
+    df_raw = pd.DataFrame(
+        [
+            {
+                "country": "German Empire",
+                "conflict_name": "Anachronistic War",
+                "start_year": 1925,
+                "end_year": 1925,
+                "country_start": None,
+                "country_end": None,
+            },
+            {
+                "country": "France",
+                "conflict_name": "Real War",
+                "start_year": 1940,
+                "end_year": 1944,
+                "country_start": None,
+                "country_end": None,
+            },
+        ]
+    )
+    cleaned = clean_dataframe(df_raw, start_year=1900, end_year=2026)
+    assert "German Empire" not in cleaned["country"].values
+    assert "France" in cleaned["country"].values
+
+
+def test_clean_dataframe_enforces_country_lifespan():
+    df_raw = pd.DataFrame(
+        [
+            {
+                "country": "Short-Lived Republic",
+                "conflict_name": "Post-dissolution War",
+                "start_year": 2000,
+                "end_year": 2001,
+                "country_start": 1990,
+                "country_end": 1995,  # dissolved before the war started
+            }
+        ]
+    )
+    cleaned = clean_dataframe(df_raw, start_year=1900, end_year=2026)
+    assert cleaned.empty
+
+
+def test_clean_dataframe_drops_wikidata_qid_placeholders():
+    df_raw = pd.DataFrame(
+        [
+            {
+                "country": "Q12345",
+                "conflict_name": "Unlabeled War",
+                "start_year": 1950,
+                "end_year": 1951,
+                "country_start": None,
+                "country_end": None,
+            }
+        ]
+    )
+    cleaned = clean_dataframe(df_raw, start_year=1900, end_year=2026)
+    assert cleaned.empty
+
+
+def test_clean_dataframe_out_of_range_is_discarded():
+    df_raw = pd.DataFrame(
+        [
+            {
+                "country": "Old Kingdom",
+                "conflict_name": "Ancient War",
+                "start_year": 1600,
+                "end_year": 1605,
+                "country_start": None,
+                "country_end": None,
+            }
+        ]
+    )
+    cleaned = clean_dataframe(df_raw, start_year=1900, end_year=2026)
+    assert cleaned.empty

histwardb-0.1.0/tests/test_query.py

@@ -0,0 +1,20 @@
+from histwardb.query import build_sparql_query
+
+
+def test_build_sparql_query_contains_temporal_bounds():
+    q = build_sparql_query(chunk_start=1900, chunk_end=1925, end_year=2026)
+    assert "1925-01-01T00:00:00Z" in q
+    assert "1900-01-01T00:00:00Z" in q
+    assert "2026-12-31T23:59:59Z" in q
+
+
+def test_build_sparql_query_excludes_noise_classes():
+    q = build_sparql_query(1900, 1925, 2026)
+    assert "wd:Q35349" in q  # peacekeeping missions
+    assert "wd:Q1151430" in q  # military exercises
+
+
+def test_build_sparql_query_is_valid_looking_sparql():
+    q = build_sparql_query(1900, 1925, 2026)
+    assert q.strip().startswith("SELECT DISTINCT")
+    assert q.count("{") == q.count("}")