readabs 0.2.2__tar.gz → 0.2.4__tar.gz

{readabs-0.2.2 → readabs-0.2.4}/CHANGELOG.md

@@ -1,3 +1,46 @@
+Version 0.2.4 released 21-Jun-2026 (Canberra Australia)
+
+ - Offline fallback: when fresh data cannot be downloaded (for example, there is
+   no internet connection), `get_file()` now returns a previously cached copy
+   with a prominent warning that the data may be out of date. The intent is to
+   let you keep working with your existing cached data while offline — e.g. on a
+   plane. Previously the freshness `HEAD` request was made before the cache was
+   ever consulted, so being offline raised a connection error on the very first
+   step. An error is now only raised when there is no cached copy to fall back to
+   (and `ignore_errors` is not set). This covers every retrieval path, as they
+   all funnel through `get_file()`.
+ - Caveat: the fallback can only return what is already in the cache. If the ABS
+   catalogue was never cached, the catalogue-based entry points can do nothing
+   offline, because a catalogue number is resolved to a URL via the catalogue.
+   Likewise, offline `grab_abs_url()` needs the landing page to have been cached,
+   since the file links are discovered by parsing it.
+ - `url` is now an explicit parameter of `read_abs_cat()` and `read_abs_series()`
+   (with a `""` default), instead of being smuggled through `**kwargs` as a
+   `ReadArgs` member. Existing calls are unaffected. This also fixes a latent bug
+   where a `url` passed to `read_abs_series()` was silently dropped (and so never
+   reached the download), and resolves the associated type-checker complaints.
+ - Type-checking cleanups (no behavioural change): `recalibrate()` now narrows
+   the Series/DataFrame branches so the column-label/series-name restoration is
+   type-safe (removing a `# pyright: ignore`), and `grab_abs_url()` reads Excel
+   sheets via `pd.read_excel()`. `mypy` now passes cleanly over `src/`.
+ - Docs: fixed a README example that called `read_abs_cat(url=...)` without the
+   required `cat` catalogue number.
+
+---
+
+Version 0.2.3 released 19-Jun-2026 (Canberra Australia)
+
+ - Pandas 3.0 compatibility: removed the deprecated `copy=` keyword from the
+   `set_axis()` call in `qtly_to_monthly()` (Copy-on-Write makes it redundant).
+   This was the only deprecated pandas usage in the package; the conversion is
+   unchanged and the caller's input series is still left untouched.
+ - Refreshed the modules' built-in self-tests for current ABS structures: the
+   labour-force (6202.0) and CPI (6401.0) table identifiers are now 8 digits, and
+   the trimmed-mean CPI example series is updated to the monthly series. The
+   local-zip test in `read_abs_cat` now skips cleanly when the fixture is absent.
+
+---
+
 Version 0.2.2 released 04-Jun-2026 (Canberra Australia)
 
  - A *selector* (in `select_one()`, `select()` and `select_and_splice()` sources)

{readabs-0.2.2 → readabs-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readabs
-Version: 0.2.2
+Version: 0.2.4
 Summary: Get ABS timeseries data in pandas DataFrames
 Project-URL: Repository, https://github.com/bpalmer4/readabs
 Project-URL: Homepage, https://github.com/bpalmer4/readabs
@@ -143,8 +143,8 @@ data_dict = ra.grab_abs_url(url="https://www.abs.gov.au/some/archived/page")
 # Access historical releases using the history parameter
 data, meta = ra.read_abs_cat("6202.0", history="dec-2023")
 
-# Or use a direct URL with read_abs_cat
-data, meta = ra.read_abs_cat(url="https://www.abs.gov.au/statistics/...")
+# Or fetch a discontinued series by URL (the catalogue number is still required)
+data, meta = ra.read_abs_cat("8501.0", url="https://www.abs.gov.au/statistics/...")
 ```
 
 These functions return a dictionary of DataFrames (one per Excel sheet), allowing you to work with data that may have been removed from the main ABS catalogue.

{readabs-0.2.2 → readabs-0.2.4}/README.md

@@ -121,8 +121,8 @@ data_dict = ra.grab_abs_url(url="https://www.abs.gov.au/some/archived/page")
 # Access historical releases using the history parameter
 data, meta = ra.read_abs_cat("6202.0", history="dec-2023")
 
-# Or use a direct URL with read_abs_cat
-data, meta = ra.read_abs_cat(url="https://www.abs.gov.au/statistics/...")
+# Or fetch a discontinued series by URL (the catalogue number is still required)
+data, meta = ra.read_abs_cat("8501.0", url="https://www.abs.gov.au/statistics/...")
 ```
 
 These functions return a dictionary of DataFrames (one per Excel sheet), allowing you to work with data that may have been removed from the main ABS catalogue.

readabs-0.2.4/TODO.md

@@ -0,0 +1,23 @@
+# TODO
+
+## Type-checker issues (pre-existing, not runtime bugs)
+
+These are flagged by `pyright src/readabs` and/or `mypy src/readabs`. All 14
+module self-tests pass; these are type-checker friction only.
+
+- [ ] **`grab_abs_url.py` — `url` declared twice.** `grab_abs_url()` has an explicit
+  `url: str = ""` parameter *and* `**kwargs: Unpack[ReadArgs]`, where `ReadArgs`
+  also declares `url: NotRequired[str]` (`read_support.py:29`). This produces three
+  errors: the param/TypedDict overlap (line 37/40) and the `check_kwargs`/`get_args`
+  arg-type mismatches (lines 78-79). `read_support.py:33` already documents that
+  `url` is meant to be handled separately — fix by dropping `url` from `ReadArgs`.
+
+- [ ] **`grab_abs_url.py:359` — `ExcelFile.parse` not in stubs.** `excel.parse(sheet_name)`
+  works at runtime but the pandas type stubs don't expose `.parse` on `ExcelFile`.
+  Add a targeted `# type: ignore` / `# pyright: ignore`, or switch to `pd.read_excel`.
+
+- [ ] **`recalibrate.py:78,80` — `Series | DataFrame` union not narrowed by `.shape`.**
+  `result` is typed `Series | DataFrame`; the `len(data.shape) == ...` guards don't
+  narrow the runtime class, so `result.columns` (line 78) and `result.name` (line 80)
+  each flag on the type that lacks the attribute. Narrow the branches with
+  `isinstance` so both checkers agree.

{readabs-0.2.2 → readabs-0.2.4}/docs/readabs/read_abs_by_desc.html

@@ -360,7 +360,7 @@ by their descriptions rather than series IDs.</p>
 </span><span id="L-299"><a href="#L-299"><span class="linenos">299</span></a>    <span class="k">def</span><span class="w"> </span><span class="nf">test2</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
 </span><span id="L-300"><a href="#L-300"><span class="linenos">300</span></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Test case: get a dictionary of dids.&quot;&quot;&quot;</span>
 </span><span id="L-301"><a href="#L-301"><span class="linenos">301</span></a>        <span class="n">gdp_table</span> <span class="o">=</span> <span class="s2">&quot;5206001_Key_Aggregates&quot;</span>
-</span><span id="L-302"><a href="#L-302"><span class="linenos">302</span></a>        <span class="n">uer_table</span> <span class="o">=</span> <span class="s2">&quot;6202001&quot;</span>
+</span><span id="L-302"><a href="#L-302"><span class="linenos">302</span></a>        <span class="n">uer_table</span> <span class="o">=</span> <span class="s2">&quot;62020001&quot;</span>
 </span><span id="L-303"><a href="#L-303"><span class="linenos">303</span></a>        <span class="n">sa</span> <span class="o">=</span> <span class="s2">&quot;Seasonally Adjusted&quot;</span>
 </span><span id="L-304"><a href="#L-304"><span class="linenos">304</span></a>        <span class="n">get_these</span> <span class="o">=</span> <span class="p">{</span>
 </span><span id="L-305"><a href="#L-305"><span class="linenos">305</span></a>            <span class="c1"># two series, each from two different ABS Catalogue Numbers</span>