Improve currency module cache: rename CACHE, add clear_cache() (Phase 7.2)

- Rename module-level CACHE to _CACHE (private by convention)
- Add public clear_cache() function that empties _CACHE; documented with
  rationale (avoid redundant HTTP requests within a session)
- Add caching Notes section to currency.get() docstring pointing to
  clear_cache()
- Update tests/conftest.py autouse fixture to call currency.clear_cache()
  instead of accessing _CACHE directly
- Add test_clear_cache() verifying that clear_cache() empties the cache
  and that subsequent calls re-populate it

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: wilsonfreitas

bcb/currency.py

@@ -27,12 +27,24 @@ def _currency_url(currency_id: int, start_date: DateInput, end_date: DateInput)
     )
 
 
-CACHE: dict[str, pd.DataFrame] = dict()
+_CACHE: dict[str, pd.DataFrame] = dict()
+
+
+def clear_cache() -> None:
+    """Clear the module-level session cache.
+
+    :func:`get` and :func:`get_currency_list` cache the currency ID list and
+    the full currency master table for the duration of the Python session so
+    that repeated calls do not make redundant HTTP requests.  Call this
+    function to force a fresh fetch on the next request (useful in tests or
+    long-running scripts where the master data may have changed).
+    """
+    _CACHE.clear()
 
 
 def _currency_id_list() -> pd.DataFrame:
-    if CACHE.get("TEMP_CURRENCY_ID_LIST") is not None:
-        return CACHE.get("TEMP_CURRENCY_ID_LIST")
+    if _CACHE.get("TEMP_CURRENCY_ID_LIST") is not None:
+        return _CACHE.get("TEMP_CURRENCY_ID_LIST")
     else:
         url1 = (
             "https://ptax.bcb.gov.br/ptax_internet/consultaBoletim.do?"
@@ -48,7 +60,7 @@ def _currency_id_list() -> pd.DataFrame:
         x = [(elm.text, elm.get("value")) for elm in doc.xpath(xpath)]
         df = pd.DataFrame(x, columns=["name", "id"])
         df["id"] = df["id"].astype("int32")
-        CACHE["TEMP_CURRENCY_ID_LIST"] = df
+        _CACHE["TEMP_CURRENCY_ID_LIST"] = df
         return df
 
 
@@ -76,8 +88,8 @@ def get_currency_list() -> pd.DataFrame:
     DataFrame :
         Tabela com a listagem de moedas disponíveis.
     """
-    if CACHE.get("TEMP_FILE_CURRENCY_LIST") is not None:
-        return CACHE.get("TEMP_FILE_CURRENCY_LIST")
+    if _CACHE.get("TEMP_FILE_CURRENCY_LIST") is not None:
+        return _CACHE.get("TEMP_FILE_CURRENCY_LIST")
     else:
         res = _get_valid_currency_list(date.today())
         df = pd.read_csv(StringIO(res.text), delimiter=";")
@@ -95,7 +107,7 @@ def get_currency_list() -> pd.DataFrame:
         df["country_code"] = df["country_code"].astype("int32")
         df["code"] = df["code"].astype("int32")
         df["symbol"] = df["symbol"].str.strip()
-        CACHE["TEMP_FILE_CURRENCY_LIST"] = df
+        _CACHE["TEMP_FILE_CURRENCY_LIST"] = df
         return df
 
 
@@ -180,6 +192,13 @@ def get(
     Returns
     -------
 
+    Notes
+    -----
+    The currency ID list and the master currency table are cached in memory
+    for the lifetime of the Python session so that multiple calls to
+    :func:`get` do not repeat the same HTTP requests.  Use
+    :func:`clear_cache` to invalidate the cache when fresh data is needed.
+
     DataFrame :
         Série temporal com cotações diárias das moedas solicitadas.
     """

tests/conftest.py

@@ -83,6 +83,6 @@
 @pytest.fixture(autouse=True)
 def clear_currency_cache():
     """Clear module-level currency cache before and after each test."""
-    currency.CACHE.clear()
+    currency.clear_cache()
     yield
-    currency.CACHE.clear()
+    currency.clear_cache()

tests/test_currency.py

@@ -65,6 +65,22 @@ def test_currency_id_list_cached(httpx_mock):
     assert df1 is df2
 
 
+def test_clear_cache(httpx_mock):
+    # Populate the cache with one call
+    add_id_list_mock(httpx_mock)
+    currency._currency_id_list()
+    assert currency._CACHE  # cache is non-empty
+
+    # clear_cache() empties it
+    currency.clear_cache()
+    assert not currency._CACHE
+
+    # A subsequent call re-fetches and re-populates
+    add_id_list_mock(httpx_mock)
+    currency._currency_id_list()
+    assert currency._CACHE
+
+
 # ---------------------------------------------------------------------------
 # get_currency_list
 # ---------------------------------------------------------------------------