misocialpy 0.4.0__tar.gz

misocialpy-0.4.0/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+.Rproj.user
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+plano/
+plano_misocial.html
+REVISAO_*.md
+ANALISE_*.md
+RELATORIO_*.md
+ESTADO_*.md
+misocialr/docs/
+.Rhistory
+*.Rcheck/
+misocialr_*.tar.gz
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+tests/testthat/api.bak/
+tests/testthat/_problems/

misocialpy-0.4.0/LICENSE

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

misocialpy-0.4.0/NEWS.md

@@ -0,0 +1,56 @@
+# misocialpy 0.4.0
+
+Same changes as misocialr 0.4.0: paging by `cursorMark`, `nature` and
+`nature_basis` columns in `mds_fields()`, corrected label of the Fomento
+Rural `..._ano_f` field and `set_cache_ttl(seconds)`.
+
+# misocialpy 0.3.1
+
+Same fixes as misocialr 0.3.1, plus the Python-specific ones:
+
+* Results of `mds_periods()`, `mds_api_fields()` and `mds_localities()` are
+  copies: editing a result no longer changes the cache (F1).
+* `mds_drop_unpublished()`: a fractional period (`202401.9`) and a missing
+  `field` (`pd.NA`) are errors; `today=None` is the only default (F3).
+* `set_timeout()` requires a finite positive number and keeps the previous
+  value on error (F7).
+* Extras `test` (pytest, responses) and `dev` (plus ruff and build) (F8).
+* Numpy scalars and integer-valued numbers (`26.0`) are accepted, as in R.
+* Three attempts in total, as in R (previously 4); `Retry-After` capped at
+  30 s; retries allowed on POST.
+* `LICENSE` with the full MIT text (previously only the CRAN template).
+* The `live` mark is registered in `conftest.py`: the suite behaves the
+  same outside the project (tested against the wheel installed in a clean
+  environment).
+
+# misocialpy 0.3.0
+
+Same fixes as misocialr 0.3.0: single response contract, no caching of incomplete
+responses; `mds_localities()` paged and validated, with `period` and
+`refresh`; `mds_drop_unpublished()` never deleting a non-zero value, with a
+normalised period and `action="flag"`; identity and scalar value per
+document; conflicts as `DataConflictError`; consistent paging; facets in
+disjoint blocks; `refresh` and canonical cache keys; `HttpError`,
+`ResponseError` and `DataConflictError`, all inheriting from `MdsError`
+(and `ValidationError` also from `ValueError`); `storage_type`; local
+validation with `validate=False`; warning for a municipality without
+documents.
+
+# misocialpy 0.2.1
+
+Same fixes as misocialr 0.2.1: locality and period validated (empty, `None`, `NaN`,
+non-integer, wrong check digit, invalid next to `"BR"`), text field as a
+`ValidationError` (previously a `ValueError` without context), incomplete
+or partial response as an `MdsError`, `mds_api_fields()` paged,
+`mds_drop_unpublished()` with validation and `reference="brazil"`,
+`set_timeout()` and `df.attrs["retrieved_at"]`. Minimum versions of pandas
+and requests tested.
+
+# misocialpy 0.2.0
+
+Four new themes and shortcuts `mds_suas_rede()`, `mds_suas_financiamento()`,
+`mds_pbf_condicionalidades()` and `mds_seguranca_alimentar()`.
+
+# misocialpy 0.1.0
+
+First version, a port of misocialr 0.1.0.

misocialpy-0.4.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: misocialpy
+Version: 0.4.0
+Summary: Access the Brazilian MDS Social Information Matrix (MI Social) API from Python
+Project-URL: Homepage, https://github.com/StrategicProjects/misocial
+Project-URL: Repository, https://github.com/StrategicProjects/misocial
+Project-URL: Issues, https://github.com/StrategicProjects/misocial/issues
+Project-URL: Changelog, https://github.com/StrategicProjects/misocial/blob/main/misocialpy/NEWS.md
+Author-email: André Leite <leite@castlab.org>, Marcos Wasiliew <marcos.wasiliew@gmail.com>, Hugo Vasconcelos <hugo.vasconcelos@ufpe.br>, Carlos Amorim <carlos.agaf@ufpe.br>, Diogo Bezerra <diogo.bezerra@ufpe.br>
+License: MIT License
+        
+        Copyright (c) 2026 misocialpy authors
+        
+        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.
+License-File: LICENSE
+Keywords: BPC,Bolsa Familia,Brazil,Cadastro Unico,MDS,SUAS,open-data,pandas
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.3
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: responses>=0.23; extra == 'test'
+Description-Content-Type: text/markdown
+
+# misocialpy
+
+<!-- badges: start -->
+![License](https://img.shields.io/badge/license-MIT-darkviolet.svg)
+![](https://img.shields.io/badge/devel%20version-0.4.0-blue.svg)
+[![misocialpy](https://github.com/StrategicProjects/misocial/actions/workflows/misocialpy.yaml/badge.svg)](https://github.com/StrategicProjects/misocial/actions/workflows/misocialpy.yaml)
+<!-- badges: end -->
+
+Pandas-friendly Python interface to the **MI Social** API (Matriz de
+Informação Social) of the Brazilian Ministry of Development and Social
+Assistance (MDS/SAGI):
+<https://aplicacoes.mds.gov.br/sagi/servicos/misocial>.
+
+A port of the R package
+[`misocialr`](https://github.com/StrategicProjects/misocial/tree/main/misocialr),
+with the same
+functions, name by name, as `ibgepy` does with `ibger`. Both versions read
+the same field dictionary (`src/misocialpy/data/dictionary.csv`, a copy of
+`misocialr/inst/extdata/`) and are tested against the same recorded
+responses.
+
+| Theme | Function | Content |
+| --- | --- | --- |
+| `cadunico` | `mds_cadunico()` | Cadastro Único: registered families and people, by income bracket |
+| `bolsa_familia` | `mds_bolsa_familia()` | Bolsa Família programme: beneficiary families, benefits and transfers |
+| `bpc_suas` | `mds_bpc_suas()` | BPC benefit and the social assistance network (CRAS, CREAS) |
+| `suas_rede` | `mds_suas_rede()` | SUAS network (CadSUAS): CRAS, CREAS, Centro POP, day centres, shelters and staff per unit |
+| `suas_financiamento` | `mds_suas_financiamento()` | FNAS transfers and balances of the municipal funds, and IGD-M |
+| `pbf_condicionalidades` | `mds_pbf_condicionalidades()` | Education and health conditionality monitoring (SICON) and sanctions |
+| `seguranca_alimentar` | `mds_seguranca_alimentar()` | PAA, Fomento Rural and cisterns |
+
+Other functions: `mds_data()`, `mds_themes()`, `mds_fields()`,
+`mds_api_fields()`, `mds_periods()`, `mds_localities()`,
+`mds_drop_unpublished()`, `ibge_code7()`, `mds_clear_cache()`,
+`set_verbose()`.
+
+## Installation
+
+```sh
+pip install "git+https://github.com/StrategicProjects/misocial#subdirectory=misocialpy"
+
+# or, from a local clone:
+pip install ./misocialpy        # from the repository root
+pip install .                   # from inside misocialpy/
+```
+
+Requires Python >= 3.9, pandas >= 1.3 and requests >= 2.25 (tested with
+pandas 1.3.5 and requests 2.25.1 on Python 3.9, and with pandas 3.0.6 on
+Python 3.14).
+
+## Usage
+
+```python
+import misocialpy as m
+
+m.mds_bolsa_familia(
+    periods=[202508, 202509],
+    localities=2611606,  # Recife (6 or 7 digits)
+    fields=["qtd_familias_beneficiarias_bolsa_familia_i", "valor_repassado_bolsa_familia_f"],
+)
+#   ibge_code locality_name  period                                       field      unit       value
+# 0   2611606        RECIFE  202508  qtd_familias_beneficiarias_bolsa_familia_i  Famílias    140350.0
+# 1   2611606        RECIFE  202509  qtd_familias_beneficiarias_bolsa_familia_i  Famílias    139452.0
+# 2   2611606        RECIFE  202508             valor_repassado_bolsa_familia_f        R$  92124240.0
+# 3   2611606        RECIFE  202509             valor_repassado_bolsa_familia_f        R$  93354456.0
+```
+
+(Selected columns; output from 2026-10-19.)
+
+- `periods`: `None` (last 12 months), `-n`, years (`2024`) and/or `YYYYMM`.
+- `localities`: `"BR"`, states (`"PE"` or `26`), municipalities with 6 or 7
+  digits.
+
+The API answers **0** for months not yet published. `mds_periods()` shows
+how many municipalities have a non-zero value in each month, and
+`mds_drop_unpublished()` explicitly removes the trailing all-zero months;
+`reference="brazil"` decides by the whole country and preserves legitimate
+zeros of small selections.
+
+Validation is the same as in the R package. Invalid input is a
+`ValidationError`; an incomplete or malformed response (partial result,
+missing facet, total that changes while paging, repeated document, no
+municipality or several values) is a `ResponseError`; two values for the
+same observation are a `DataConflictError`; a network or HTTP failure is an
+`HttpError` (with `status`). All inherit from `MdsError`. None of this
+enters the cache.
+
+`mds_drop_unpublished()` never deletes a non-zero value; `action="flag"`
+classifies the rows (`publication_status`, `publication_reason`,
+`publication_reference`) without removing any.
+
+- `misocialpy.set_timeout(300)`: maximum time per request (default 180 s);
+  `misocialpy.set_verbose(False)` hides the messages.
+- `df.attrs["retrieved_at"]`: date and time (UTC) of the query.
+- `refresh=True` in `mds_periods()`, `mds_localities()` and
+  `mds_api_fields()`; `mds_localities(period=)` picks the month of the
+  list. Results are copies: editing them does not change the cache.
+- `misocialpy.set_cache_ttl(3600)`: cache validity in seconds (default: the
+  whole session).
+- `mds_fields()` brings `nature` (`estoque`, `fluxo`, `fluxo anual`,
+  `acumulado`, `taxa`, `média`, `índice`) and `nature_basis`; see the
+  summing table in the R README.
+- Paging by `cursorMark`.
+- Queries by POST (avoids the HTTP 414 of long URLs); 3 attempts in total
+  on 429/5xx and on connection failure, with `Retry-After` capped at 30 s.
+- Accepts numpy scalars (`np.int64(202401)`) and integer-valued numbers
+  (`26.0`), as in R. Years from 2000 to the year after the current one.
+
+Development: `pip install -e ".[dev]"` (pytest, responses, ruff and build);
+`pip install -e ".[test]"` for the tests only.
+
+See the `misocialr` README for the notes on the fields.
+
+## Tests
+
+```sh
+pytest            # offline, with recorded fixtures
+pytest -m live    # against the real API
+```

misocialpy-0.4.0/README.md

@@ -0,0 +1,119 @@
+# misocialpy
+
+<!-- badges: start -->
+![License](https://img.shields.io/badge/license-MIT-darkviolet.svg)
+![](https://img.shields.io/badge/devel%20version-0.4.0-blue.svg)
+[![misocialpy](https://github.com/StrategicProjects/misocial/actions/workflows/misocialpy.yaml/badge.svg)](https://github.com/StrategicProjects/misocial/actions/workflows/misocialpy.yaml)
+<!-- badges: end -->
+
+Pandas-friendly Python interface to the **MI Social** API (Matriz de
+Informação Social) of the Brazilian Ministry of Development and Social
+Assistance (MDS/SAGI):
+<https://aplicacoes.mds.gov.br/sagi/servicos/misocial>.
+
+A port of the R package
+[`misocialr`](https://github.com/StrategicProjects/misocial/tree/main/misocialr),
+with the same
+functions, name by name, as `ibgepy` does with `ibger`. Both versions read
+the same field dictionary (`src/misocialpy/data/dictionary.csv`, a copy of
+`misocialr/inst/extdata/`) and are tested against the same recorded
+responses.
+
+| Theme | Function | Content |
+| --- | --- | --- |
+| `cadunico` | `mds_cadunico()` | Cadastro Único: registered families and people, by income bracket |
+| `bolsa_familia` | `mds_bolsa_familia()` | Bolsa Família programme: beneficiary families, benefits and transfers |
+| `bpc_suas` | `mds_bpc_suas()` | BPC benefit and the social assistance network (CRAS, CREAS) |
+| `suas_rede` | `mds_suas_rede()` | SUAS network (CadSUAS): CRAS, CREAS, Centro POP, day centres, shelters and staff per unit |
+| `suas_financiamento` | `mds_suas_financiamento()` | FNAS transfers and balances of the municipal funds, and IGD-M |
+| `pbf_condicionalidades` | `mds_pbf_condicionalidades()` | Education and health conditionality monitoring (SICON) and sanctions |
+| `seguranca_alimentar` | `mds_seguranca_alimentar()` | PAA, Fomento Rural and cisterns |
+
+Other functions: `mds_data()`, `mds_themes()`, `mds_fields()`,
+`mds_api_fields()`, `mds_periods()`, `mds_localities()`,
+`mds_drop_unpublished()`, `ibge_code7()`, `mds_clear_cache()`,
+`set_verbose()`.
+
+## Installation
+
+```sh
+pip install "git+https://github.com/StrategicProjects/misocial#subdirectory=misocialpy"
+
+# or, from a local clone:
+pip install ./misocialpy        # from the repository root
+pip install .                   # from inside misocialpy/
+```
+
+Requires Python >= 3.9, pandas >= 1.3 and requests >= 2.25 (tested with
+pandas 1.3.5 and requests 2.25.1 on Python 3.9, and with pandas 3.0.6 on
+Python 3.14).
+
+## Usage
+
+```python
+import misocialpy as m
+
+m.mds_bolsa_familia(
+    periods=[202508, 202509],
+    localities=2611606,  # Recife (6 or 7 digits)
+    fields=["qtd_familias_beneficiarias_bolsa_familia_i", "valor_repassado_bolsa_familia_f"],
+)
+#   ibge_code locality_name  period                                       field      unit       value
+# 0   2611606        RECIFE  202508  qtd_familias_beneficiarias_bolsa_familia_i  Famílias    140350.0
+# 1   2611606        RECIFE  202509  qtd_familias_beneficiarias_bolsa_familia_i  Famílias    139452.0
+# 2   2611606        RECIFE  202508             valor_repassado_bolsa_familia_f        R$  92124240.0
+# 3   2611606        RECIFE  202509             valor_repassado_bolsa_familia_f        R$  93354456.0
+```
+
+(Selected columns; output from 2026-10-19.)
+
+- `periods`: `None` (last 12 months), `-n`, years (`2024`) and/or `YYYYMM`.
+- `localities`: `"BR"`, states (`"PE"` or `26`), municipalities with 6 or 7
+  digits.
+
+The API answers **0** for months not yet published. `mds_periods()` shows
+how many municipalities have a non-zero value in each month, and
+`mds_drop_unpublished()` explicitly removes the trailing all-zero months;
+`reference="brazil"` decides by the whole country and preserves legitimate
+zeros of small selections.
+
+Validation is the same as in the R package. Invalid input is a
+`ValidationError`; an incomplete or malformed response (partial result,
+missing facet, total that changes while paging, repeated document, no
+municipality or several values) is a `ResponseError`; two values for the
+same observation are a `DataConflictError`; a network or HTTP failure is an
+`HttpError` (with `status`). All inherit from `MdsError`. None of this
+enters the cache.
+
+`mds_drop_unpublished()` never deletes a non-zero value; `action="flag"`
+classifies the rows (`publication_status`, `publication_reason`,
+`publication_reference`) without removing any.
+
+- `misocialpy.set_timeout(300)`: maximum time per request (default 180 s);
+  `misocialpy.set_verbose(False)` hides the messages.
+- `df.attrs["retrieved_at"]`: date and time (UTC) of the query.
+- `refresh=True` in `mds_periods()`, `mds_localities()` and
+  `mds_api_fields()`; `mds_localities(period=)` picks the month of the
+  list. Results are copies: editing them does not change the cache.
+- `misocialpy.set_cache_ttl(3600)`: cache validity in seconds (default: the
+  whole session).
+- `mds_fields()` brings `nature` (`estoque`, `fluxo`, `fluxo anual`,
+  `acumulado`, `taxa`, `média`, `índice`) and `nature_basis`; see the
+  summing table in the R README.
+- Paging by `cursorMark`.
+- Queries by POST (avoids the HTTP 414 of long URLs); 3 attempts in total
+  on 429/5xx and on connection failure, with `Retry-After` capped at 30 s.
+- Accepts numpy scalars (`np.int64(202401)`) and integer-valued numbers
+  (`26.0`), as in R. Years from 2000 to the year after the current one.
+
+Development: `pip install -e ".[dev]"` (pytest, responses, ruff and build);
+`pip install -e ".[test]"` for the tests only.
+
+See the `misocialr` README for the notes on the fields.
+
+## Tests
+
+```sh
+pytest            # offline, with recorded fixtures
+pytest -m live    # against the real API
+```

misocialpy-0.4.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "misocialpy"
+version = "0.4.0"
+description = "Access the Brazilian MDS Social Information Matrix (MI Social) API from Python"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [
+    { name = "André Leite", email = "leite@castlab.org" },
+    { name = "Marcos Wasiliew", email = "marcos.wasiliew@gmail.com" },
+    { name = "Hugo Vasconcelos", email = "hugo.vasconcelos@ufpe.br" },
+    { name = "Carlos Amorim", email = "carlos.agaf@ufpe.br" },
+    { name = "Diogo Bezerra", email = "diogo.bezerra@ufpe.br" },
+]
+keywords = ["MDS", "Cadastro Unico", "Bolsa Familia", "BPC", "SUAS", "Brazil", "open-data", "pandas"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "requests>=2.25",
+    "pandas>=1.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/StrategicProjects/misocial"
+Repository = "https://github.com/StrategicProjects/misocial"
+Issues = "https://github.com/StrategicProjects/misocial/issues"
+Changelog = "https://github.com/StrategicProjects/misocial/blob/main/misocialpy/NEWS.md"
+
+[project.optional-dependencies]
+test = ["pytest>=7", "responses>=0.23"]
+dev = ["pytest>=7", "responses>=0.23", "ruff>=0.6", "build>=1.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/misocialpy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["live: hits the real MI Social API (run with -m live)"]
+addopts = "-m 'not live'"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

misocialpy-0.4.0/src/misocialpy/__init__.py

@@ -0,0 +1,66 @@
+"""misocialpy — access the MDS MI Social API from Python.
+
+A pandas-friendly port of the R package `misocialr`. Monthly municipal series
+of the Cadastro Unico, the Bolsa Familia programme and its conditionalities,
+the BPC, the social assistance network and its funding, and food security
+programmes, from the Social Information Matrix of the
+Brazilian Ministry of Development and Social Assistance (MDS/SAGI).
+
+Quick start
+-----------
+>>> import misocialpy
+>>> misocialpy.mds_bpc_suas(periods=2025, localities="PE")      # doctest: +SKIP
+>>> misocialpy.mds_periods("bpc_ben_i", localities="PE")        # doctest: +SKIP
+"""
+
+from __future__ import annotations
+
+from ._cache import clear_cache as mds_clear_cache
+from ._cache import set_cache_ttl
+from ._client import DataConflictError, HttpError, MdsError, ResponseError, set_timeout
+from ._msg import set_verbose
+from .data import (
+    mds_bolsa_familia,
+    mds_bpc_suas,
+    mds_cadunico,
+    mds_data,
+    mds_pbf_condicionalidades,
+    mds_seguranca_alimentar,
+    mds_suas_financiamento,
+    mds_suas_rede,
+)
+from .fields import mds_api_fields, mds_fields, mds_themes
+from .localities import ibge_code7, mds_localities
+from .periods import mds_periods
+from .publication import mds_drop_unpublished
+from .validation import ValidationError
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "DataConflictError",
+    "HttpError",
+    "MdsError",
+    "ResponseError",
+    "ValidationError",
+    "__version__",
+    "ibge_code7",
+    "mds_api_fields",
+    "mds_bolsa_familia",
+    "mds_bpc_suas",
+    "mds_cadunico",
+    "mds_clear_cache",
+    "mds_data",
+    "mds_drop_unpublished",
+    "mds_fields",
+    "mds_localities",
+    "mds_pbf_condicionalidades",
+    "mds_periods",
+    "mds_seguranca_alimentar",
+    "mds_suas_financiamento",
+    "mds_suas_rede",
+    "mds_themes",
+    "set_cache_ttl",
+    "set_timeout",
+    "set_verbose",
+]

misocialpy-0.4.0/src/misocialpy/_cache.py

@@ -0,0 +1,83 @@
+"""In-memory, per-session cache (equivalent to the R package's environment).
+
+Holds localities, field lists, period facets and fields already confirmed to
+exist.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from typing import Any
+
+_CACHE: dict[str, Any] = {}
+_STORED_AT: dict[str, float] = {}
+_TTL = math.inf
+
+
+def set_cache_ttl(seconds: float = math.inf) -> None:
+    """Set how long, in seconds, a cached result is used (default: the whole
+    session). Must be a non-negative number; on error the previous value is
+    kept."""
+    global _TTL
+    if (
+        not isinstance(seconds, (int, float))
+        or isinstance(seconds, bool)
+        or math.isnan(seconds)
+        or seconds < 0
+    ):
+        raise ValueError("`seconds` must be a non-negative number.")
+    _TTL = float(seconds)
+
+
+def _copy(value: Any) -> Any:
+    """Independent copy of a cached table, with its attrs.
+
+    Pandas objects are mutable: handing out the stored instance would let an
+    edit of a result change the metadata used by later calls (periods feed
+    the inference of publication).
+    """
+    if hasattr(value, "copy") and hasattr(value, "attrs"):
+        out = value.copy(deep=True)
+        out.attrs = dict(value.attrs)
+        return out
+    return value
+
+
+def cache_get(key: str, refresh: bool = False) -> Any:
+    """Read a copy of a cached value, unless a refresh is requested."""
+    if refresh or key not in _CACHE:
+        return None
+    if time.monotonic() - _STORED_AT.get(key, 0.0) > _TTL:
+        return None
+    return _copy(_CACHE[key])
+
+
+def cache_set(key: str, value: Any) -> Any:
+    """Store a copy of a value and return another (only complete, validated
+    responses reach here)."""
+    from datetime import datetime, timezone
+
+    if hasattr(value, "attrs"):
+        value.attrs["retrieved_at"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    _CACHE[key] = _copy(value)
+    _STORED_AT[key] = time.monotonic()
+    return _copy(value)
+
+
+def locality_key(loc: dict) -> str:
+    """Canonical key: ['PE', 'PB'] and ['PB', 'PE'] share the cached result."""
+    return f"uf={','.join(sorted(loc['states']))};mun={','.join(sorted(loc['municipalities']))}"
+
+
+def clear_cache() -> None:
+    """Remove all cached localities, field lists, periods and field checks.
+
+    Forces fresh API calls on subsequent requests. Public alias:
+    :func:`misocialpy.mds_clear_cache`.
+    """
+    _CACHE.clear()
+    _STORED_AT.clear()
+    from . import _msg
+
+    _msg.success("MI Social cache cleared.")