iraqdata 1.0.0__tar.gz

iraqdata-1.0.0/.gitignore

@@ -0,0 +1,97 @@
+# ==============================================================================
+# iraqdata — Standard Python & Data Project .gitignore
+# ==============================================================================
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+
+# Distribution / packaging
+build/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+
+# Testing, coverage & linters
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+
+# Jupyter Notebook checkpoints
+.ipynb_checkpoints
+
+# IDEs & code editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+*.sublime-project
+*.sublime-workspace
+
+# Operating system files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# Temporary logs & local scratch files
+scratch/
+tmp/
+*.log
+*.bak
+
+# ==============================================================================
+# Kept on the maintainer's computer only (not published)
+# ==============================================================================
+# AI assistant and Spec Kit tooling, and the design specs
+.claude/
+.specify/
+specs/
+.pytest_cache/
+
+# Merge transaction files; they exist only while a merge runs or was interrupted
+*.parquet.new
+*.parquet.old
+.merge_journal.json
+# Atomic parser output; left only by an interrupted write
+*.parquet.part
+
+# Internal working documents
+docs/ground_rules.md
+docs/establishing_monorepo_skeleton.md
+docs/implement_client_library_interface.md
+docs/strategic_value_and_benefits.md

iraqdata-1.0.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to `iraqdata` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the code uses
+[Semantic Versioning](https://semver.org/). Data releases are dated separately
+(e.g. `data-2026-10`) and record the code version that built them.
+
+## [1.0.0] - 2026-10-28
+
+First release, with the data release `data-2026-10`.
+
+### Data
+
+- 62 series in 9 areas (money and banking, exchange rates, prices and inflation, oil, public
+  finance, GDP, balance of payments and trade, cross-border banking, development aid), in 10
+  single-frequency tables with 23,139 observations. Each table is released as a CSV and a Parquet
+  file, with `checksums.sha256`, a Frictionless `datapackage.json` and `release-assets.txt` (the
+  GitHub upload name of every file).
+- Every value has a status flag (`A` normal, `P` provisional, `B` break, `E` estimated, `M`
+  missing, `U` low reliability), decided in one place (`pipeline/flags.py`) from each series'
+  origin and the flag policy.
+- Every series says how each period was produced: read from an archived official file, computed
+  from other series, typed in from a publication, or from a source of unknown publisher. The list of
+  everything that was not read from an archived official file is in `docs/series.md`.
+- `cpi_headline` and `cpi_core` link the official CPI bases into continuous series, with a break
+  flag at each base change (method and sensitivity in `docs/linked_inflation_method.md`).
+  `cpi_core` before 2010 does not measure the same thing as after; read the warning there.
+- Every value in this release was first published on 2026-10-28, so the release has no vintage
+  history.
+- Known limits: GDP quarters before 2020 and a few later ones are typed in from documents that are
+  not archived (flag `U`); the 2004–2023 fiscal values come from a seed of unknown publisher
+  (flag `U`); the Basrah crude price has ten typed-in months only.
+
+### Python client
+
+- `get_series` and `get_table` return one series or table with its date index; several
+  frequencies come back as one table per frequency, never mixed. Options: `start`, `end`, `aliases`,
+  `wide`, `flags` (a `<label>_flag` column after each value column) and `as_of` (values as
+  published on a past date, from a release's vintage history).
+- `search` and `list_series` work in English and Arabic; `get_origin` and `get_series_info` describe
+  a series; `list_categories`, `list_tables` and `get_catalog` list what exists.
+- `set_release`, `get_data_source` and `refresh_latest` say and control which data release is read.
+  "Latest" is the newest `data-YYYY-MM` release, looked up once and kept until refreshed. A pin is
+  always honoured.
+- Every downloaded file is checked against the release's `checksums.sha256` when it is downloaded
+  and before every read from the cache; a file that does not match is never used. `clear_cache`
+  removes only files iraqdata created.
+- Errors in `iraqdata.errors` say what went wrong and what to do; wide output warns
+  (`FlagWarning`) about hidden breaks and provisional values.
+
+### Pipeline
+
+- Eleven parsers read the archived raw files and stop, naming the file and the sheet, cell or row,
+  rather than guess, skip or drop a value. Typed-in values live in transcription records under
+  `pipeline/raw/transcribed/` (`docs/transcription_records.md`), never in code.
+- The quality gate (`pipeline/validate.py`) checks schema, plausibility limits derived from each
+  series' own data, jumps, accounting identities, cross-source sanity, continuity and freshness.
+  `--release` fails on any review notice that has not been acknowledged by a named reviewer.
+- A merge into the published tables keeps every revised or withdrawn value in a vintage history,
+  writes all files as one recoverable transaction, and refuses to drop published rows silently.
+- A weekly, report-only update check fetches every automatically fetchable source into a scratch
+  folder, rebuilds and gatekeeps there, and keeps one GitHub issue per open problem. Downloads are
+  https-only, limited to each source's own hosts, size-capped and content-checked before they are
+  saved. A dead-man's switch reports a check that stopped running.
+- `pipeline/export_release.py` runs the gate and the catalog check first and never overwrites an
+  existing release; its output is byte-for-byte reproducible.
+- Documentation: `docs/collecting_data_doc.md` (how each source is collected and checked),
+  `docs/source_inventory.md` (sources and terms of reuse), `docs/series.md`,
+  `docs/transcription_records.md` and `docs/linked_inflation_method.md`.

iraqdata-1.0.0/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use this dataset or software in your research, please cite it as below."
+authors:
+  - family-names: "Khalid"
+    given-names: "Hussein"
+title: "iraqdata: Open, Documented, and Reproducible Iraqi Macroeconomic Data Package"
+version: 1.0.0
+date-released: 2026-10-28
+url: "https://github.com/husseinkh90/iraqdata"
+repository-code: "https://github.com/husseinkh90/iraqdata"
+keywords:
+  - iraq
+  - macroeconomics
+  - time-series
+  - econometrics
+  - central-bank-of-iraq
+license: MIT

iraqdata-1.0.0/LICENSE

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

iraqdata-1.0.0/LICENSE-DATA

@@ -0,0 +1,23 @@
+Creative Commons Attribution 4.0 International (CC-BY 4.0)
+
+Compiled, standardized, and derived dataset artifacts produced by the iraqdata project
+are licensed under Creative Commons Attribution 4.0 International.
+
+You are free to:
+- Share — copy and redistribute the material in any medium or format
+- Adapt — remix, transform, and build upon the material for any purpose, even commercially.
+
+Under the following terms:
+- Attribution — You must give appropriate credit, provide a link to the license,
+  and indicate if changes were made. You may do so in any reasonable manner, but
+  not in any way that suggests the licensor endorses you or your use.
+
+Scope: this licence covers the compiled and derived data only. The source data remain
+subject to the terms of reuse and copyright of each original publisher (Central Bank of
+Iraq, COSIT, Ministry of Finance, OPEC, JODI, EIA, FRED, BIS, World Bank and others).
+Some publishers state no licence; the project does not grant one on their behalf. Each
+source's terms, as recorded and with the date they were checked, are listed in
+docs/source_inventory.md ("Terms of reuse by source") and in the `sources` of each
+release's datapackage.json; every series names the sources it comes from.
+
+When you use the data, cite both the iraqdata package and the original publisher.

iraqdata-1.0.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.5
+Name: iraqdata
+Version: 1.0.0
+Summary: Open, documented, and reproducible macroeconomic data package for Iraq
+Project-URL: Homepage, https://github.com/husseinkh90/iraqdata
+Project-URL: Repository, https://github.com/husseinkh90/iraqdata.git
+Project-URL: Issues, https://github.com/husseinkh90/iraqdata/issues
+Author: Hussein Khalid
+License: MIT
+License-File: LICENSE
+License-File: LICENSE-DATA
+Keywords: cbi,cosit,data,econometrics,exchange-rates,inflation,iraq,macroeconomics,oil,time-series
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.17; extra == 'dev'
+Requires-Dist: packaging>=22; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: pipeline
+Requires-Dist: openpyxl>=3.1.0; extra == 'pipeline'
+Requires-Dist: pdfplumber>=0.10.0; extra == 'pipeline'
+Requires-Dist: xlrd>=2.0.1; extra == 'pipeline'
+Description-Content-Type: text/markdown
+
+# iraqdata
+
+**Iraq's economic statistics: clean, consistent and in one place.**
+
+[![Code licence: MIT](https://img.shields.io/badge/code-MIT-blue.svg)](https://github.com/husseinkh90/iraqdata/blob/main/LICENSE)
+[![Data licence: CC BY 4.0](https://img.shields.io/badge/data-CC%20BY%204.0-lightgrey.svg)](https://github.com/husseinkh90/iraqdata/blob/main/LICENSE-DATA)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+
+`iraqdata` gives you Iraq's main economic numbers (money, prices, exchange rates, oil, public
+finance, GDP, trade and more) as ready-to-use tables, with one line of code or one download.
+
+## Why this project matters
+
+Anyone who studies Iraq's economy runs into the same problems:
+
+- **The numbers are scattered.** They sit on the websites of the Central Bank of Iraq, the
+  statistics office (COSIT), the Ministry of Finance, the Ministry of Oil, OPEC and international
+  bodies. Pages move or change without notice.
+- **The files are hard to use.** Much of the data comes as multi-sheet Arabic spreadsheets or PDF
+  bulletins, not as tables you can analyse.
+- **The series have breaks.** Price indices were rebased several times (1993, 2007, 2012 and 2022),
+  and accounting standards changed. Joining the pieces correctly takes care.
+- **Everyone repeats the same work.** Researchers can spend most of a project collecting and
+  cleaning data before any analysis begins.
+
+`iraqdata` does that work once, carefully and in the open:
+
+- Every number names its source and how it was produced. <!-- share:begin -->91%<!-- share:end --> of
+  observations are read directly from archived official files; the rest are computed from them,
+  typed in from publications, compiled from a seed of unknown publisher, or come from a named
+  non-official source. They are listed in
+  [docs/series.md](https://github.com/husseinkh90/iraqdata/blob/main/docs/series.md#data-not-observed-from-an-archived-official-file) and flagged.
+- Breaks between series are marked rather than hidden.
+- The data are checked before each release.
+
+The result is a shared, free starting point. Studies of Iraq's economy become faster to do and
+easier to reproduce and check.
+
+## Who it is for
+
+- **Researchers and students:** start your analysis on day one, and let others reproduce your results.
+- **Journalists and the public:** free access to the country's economic record, without paid databases.
+- **Banks, businesses and investors:** reliable benchmarks for inflation, exchange rates, money and the budget.
+- **Policymakers and analysts:** a consistent picture across institutions, in one format.
+
+## What data is included
+
+Each *series* is one indicator measured over time, such as broad money (M2) month by month.
+There are 62 series in 9 areas:
+
+| Area | Examples | Original publisher |
+|---|---|---|
+| Money and banking | broad money `money.m2`, policy rate `money.policy_rate`, official reserves `money.reserves_official` | Central Bank of Iraq |
+| Exchange rates | official rate `fx.official`, Baghdad parallel-market rate `parallel_rate_iraq` | Central Bank of Iraq; Iraq-parallel-exchange-rate project |
+| Prices and inflation | consumer prices `cpi_headline` and `cpi_core` | COSIT, via the Central Bank of Iraq |
+| Oil | Brent price `oil_price_brent`, Basrah price `oil_price_basrah`, crude production `crude_production_direct` | Ministry of Oil and SOMO, OPEC and JODI, U.S. EIA |
+| Public finance | revenue `fiscal.revenue_total`, spending `fiscal.expenditure_total`, balance `fiscal.balance` | Ministry of Finance, via the Central Bank of Iraq |
+| GDP | nominal GDP `gdp.nominal`, real GDP `gdp.real`, non-oil GDP `gdp.nominal_nonoil` | COSIT |
+| Balance of payments and trade | current account `bop.current_account`, exports `trade.exports_total`, imports `trade.imports_total` | Central Bank of Iraq |
+| Cross-border banking | claims `bis.lbs.claims_total`, liabilities `bis.lbs.liabilities_total` | Bank for International Settlements |
+| Development aid | net aid received `oecd.dac.oda_total_net` | OECD / World Bank |
+
+See the [full list of all 62 series](https://github.com/husseinkh90/iraqdata/blob/main/docs/series.md).
+
+## Install
+
+```bash
+pip install iraqdata
+```
+
+You need Python 3.10 or newer. To try the latest development version, run
+`pip install git+https://github.com/husseinkh90/iraqdata` instead.
+
+## How to use
+
+Import the library:
+
+```python
+import iraqdata as id
+```
+
+Get one series as a table indexed by date:
+
+```python
+df = id.get_series("money.m2")
+print(df.tail())
+```
+
+Ask for several series at once. Series of different frequencies (monthly, daily) come back as one
+table per frequency, so nothing is mixed or averaged:
+
+```python
+tables = id.get_series(["money.m2", "fx.official"])
+print(tables["monthly"].tail())
+print(tables["daily"].tail())
+```
+
+Choose a date range and your own column names:
+
+```python
+df = id.get_series({"Broad money": "m2", "Narrow money": "m1"}, start="2020-01", end="2024-12")
+print(df.head())
+```
+
+Use short names for common indicators, such as `m2`, `cpi`, `official_rate`, `parallel_rate`,
+`brent` and `gdp`:
+
+```python
+df = id.get_series(["m2", "cpi"])
+print(df.tail())
+```
+
+Search in English or Arabic, or load a whole subject table:
+
+```python
+print(id.search("inflation"))
+print(id.search("دينار"))
+money = id.get_table("money_banking_monthly")
+print(money.head())
+```
+
+The data are downloaded the first time you ask for them and kept on your computer, so later
+requests work offline. Every downloaded file is checked against the checksums published with its
+release; a file that does not match is never used.
+
+### Status flags
+
+Every value has a status flag: `A` normal, `P` provisional, `B` break (for example a rebased
+index), `E` estimated, `M` missing, `U` low reliability. Ask for them next to the values with
+`flags=True`:
+
+```python
+df = id.get_series(["cpi", "m2"], flags=True)
+print(df[df["cpi_flag"].isin(["B", "P"])])
+```
+
+Without `flags=True`, a `FlagWarning` tells you when a table contains breaks or provisional
+values. To hide it: `warnings.filterwarnings("ignore", category=id.FlagWarning)`.
+
+### Values as published on a past date
+
+Values are revised over time. `as_of` returns them as they were published on a given date, from
+the vintage history that ships with a release. A release has a `history/` folder once a published
+value has been revised or withdrawn. The first release, `data-2026-10`, has none, because every
+value in it was first published on 2026-10-28; asking it for `as_of` raises
+`NoVintageHistoryError`. From the first release that has a history:
+
+<!-- not run: needs a release with a history folder -->
+```python
+then = id.get_series("cpi", wide=False, as_of="2026-10-28")
+print(then[["date", "value", "realtime_start"]].tail())
+```
+
+### Which data release you are using
+
+By default you get the latest data release. It is looked up the first time you use the library
+and then kept until you ask for a newer one with `id.refresh_latest()`, so your results do not
+change on their own. To make results reproducible, pin a dated release. A pinned release is
+always used, even inside a copy of this repository:
+
+```python
+id.set_release("data-2026-10")    # or set the environment variable IRAQDATA_RELEASE
+print(id.get_data_source())       # release data-2026-10 (pinned with set_release) from husseinkh90/iraqdata
+```
+
+`id.set_release()` takes precedence over `IRAQDATA_RELEASE`; `id.set_release(None)` removes the
+pin. Downloads are kept in `~/.cache/iraqdata/` (or `IRAQDATA_CACHE_DIR`), one folder per release.
+`id.clear_cache()` deletes only the files iraqdata downloaded there; anything else in that folder is
+left alone. Data are downloaded from the GitHub releases of `husseinkh90/iraqdata`; set
+`IRAQDATA_REPO` to use another repository.
+
+## Without Python
+
+Every table is available as a CSV file on the
+[latest release page](https://github.com/husseinkh90/iraqdata/releases/latest), one file per
+subject area (for example `money_banking_monthly.csv`).
+
+- **Excel:** Data → From Web, then paste
+  `https://github.com/husseinkh90/iraqdata/releases/latest/download/money_banking_monthly.csv`.
+- **Stata:**
+
+  ```stata
+  import delimited "https://github.com/husseinkh90/iraqdata/releases/latest/download/money_banking_monthly.csv", clear
+  ```
+
+- **R:**
+
+  ```r
+  money <- read.csv("https://github.com/husseinkh90/iraqdata/releases/latest/download/money_banking_monthly.csv")
+  ```
+
+## How to cite
+
+If you use `iraqdata`, please cite it:
+
+```bibtex
+@software{khalid2026iraqdata,
+  author  = {Khalid, Hussein},
+  title   = {iraqdata: Open, Documented, and Reproducible Iraqi Macroeconomic Data Package},
+  year    = {2026},
+  version = {1.0.0},
+  url     = {https://github.com/husseinkh90/iraqdata}
+}
+```
+
+A DOI will be added once the release is archived on Zenodo.
+
+Please cite both the package and the original publishers of the series you use (each series'
+sources are in `datapackage.json`, and their terms in
+[Terms of reuse by source](https://github.com/husseinkh90/iraqdata/blob/main/docs/source_inventory.md#terms-of-reuse-by-source)):
+- the Central Bank of Iraq;
+- the Central Organization for Statistics and Information Technology (COSIT);
+- the Ministry of Finance;
+- the Ministry of Oil and SOMO;
+- OPEC and JODI;
+- the U.S. Energy Information Administration and FRED;
+- the Bank for International Settlements;
+- the World Bank;
+- the Iraq-parallel-exchange-rate project (parallel exchange rate from 2023).
+
+## Licence
+
+- **Code:** [MIT](https://github.com/husseinkh90/iraqdata/blob/main/LICENSE).
+- **Data:** the compiled and derived data are [CC BY 4.0](https://github.com/husseinkh90/iraqdata/blob/main/LICENSE-DATA). The source data keep
+  their publishers' own terms, some of which state no licence; see
+  [Terms of reuse by source](https://github.com/husseinkh90/iraqdata/blob/main/docs/source_inventory.md#terms-of-reuse-by-source).
+
+## Contributing
+
+For contributors and maintainers, see [`docs/`](https://github.com/husseinkh90/iraqdata/tree/main/docs); publishing the repository and its data
+releases is described in [docs/publishing.md](https://github.com/husseinkh90/iraqdata/blob/main/docs/publishing.md).