R/availability.R

Defines functions .hf_list_dir caged_hf_files

Documented in caged_hf_files

# availability.R
# Lista as competências disponíveis no repositório HuggingFace do CAGED

#' Lista as competências disponíveis no repositório HuggingFace
#'
#' Consulta a API do HuggingFace e retorna os meses disponíveis
#' para download, ordenados do mais recente para o mais antigo.
#'
#' @param type character. Which series to query:
#'   `"novo"` (Novo CAGED, 2020+), `"antigo"` (CAGED antigo, até 2019)
#'   ou `"ajustes"` (CAGED Ajustes, série histórica de correções).
#'   Default: `"novo"`.
#' @param n integer. Number of most recent competencies to return.
#'   Use `Inf` to return all. Default: `12`.
#' @param timeout integer. Timeout in seconds. Default: 15.
#' @param verbose logical. If TRUE, exibe tabela no console. Default: TRUE.
#'
#' @return tibble invisível com colunas `competencia` (AAAAMM),
#'   `ano`, `mes` e `url`, ordenado do mais recente para o mais antigo.
#'
#' @examples
#' \dontrun{
#' # Últimos 12 meses disponíveis (padrão)
#' caged_hf_files()
#'
#' # Todos os meses do Novo CAGED
#' caged_hf_files(n = Inf)
#'
#' # CAGED antigo
#' caged_hf_files(type = "antigo")
#'
#' # CAGED Ajustes
#' caged_hf_files(type = "ajustes")
#'
#' # Usar o resultado para baixar automaticamente o mês mais recente
#' disp <- caged_hf_files(n = 1, verbose = FALSE)
#' caged_load(
#'   years    = disp$ano,
#'   months   = disp$mes,
#'   db_path = file.path(tempdir(), "caged.duckdb")
#' )
#' }
#'
#' @seealso [caged_status()] para verificar se o repositório HF está acessível.
#' @seealso [caged_load()] para baixar após identificar as competências.
#' @export
caged_hf_files <- function(type    = "novo",
                            n       = 12,
                            timeout = 15,
                            verbose = TRUE) {
  type <- match.arg(type, c("novo", "antigo", "ajustes"))

  if (!is.numeric(n) || length(n) != 1L || (!is.infinite(n) && (is.na(n) || n < 1L))) {
    cli::cli_abort(
      gettext("{.arg n} must be a positive integer or {.code Inf}, not {.val {n}}.")
    )
  }
  n <- if (is.infinite(n)) Inf else as.integer(n)

  # Pasta raiz no repositório HF para cada série
  pasta_raiz <- switch(type,
    novo    = .HF_PASTA_NOVO,
    antigo  = .HF_PASTA_ANTIGO,
    ajustes = .HF_PASTA_AJUSTES
  )

  hf_api_url <- .HF_API
  if (verbose) cli::cli_inform(gettext("Querying HuggingFace repository ({.url {hf_api_url}})..."))

  # Obtém a lista de anos disponíveis na pasta raiz
  anos_disponiveis <- .hf_list_dir(pasta_raiz, timeout)

  if (is.null(anos_disponiveis)) {
    cli::cli_abort(c(
      gettext("Could not access the HuggingFace repository."),
      "i" = gettext("Check your connection with {.fn caged_status}."),
      "i" = gettext("Repository: {.url https://huggingface.co/datasets/alexsandroprado/caged}")
    ))
  }

  ano_max <- as.integer(format(Sys.Date(), "%Y"))
  anos <- sort(
    unique(anos_disponiveis[
      !is.na(suppressWarnings(as.integer(anos_disponiveis))) &
      suppressWarnings(as.integer(anos_disponiveis)) >= 1992L &
      suppressWarnings(as.integer(anos_disponiveis)) <= ano_max
    ]),
    decreasing = TRUE
  )

  if (length(anos) == 0) {
    cli::cli_abort(
      gettext("No year found in the HuggingFace repository for series '{type}'.")
    )
  }

  # Competência máxima válida
  hoje     <- Sys.Date()
  ano_hoje <- as.integer(format(hoje, "%Y"))
  mes_hoje <- as.integer(format(hoje, "%m"))
  if (mes_hoje == 12L) {
    ano_max_comp <- ano_hoje + 1L; mes_max_comp <- 1L
  } else {
    ano_max_comp <- ano_hoje;      mes_max_comp <- mes_hoje + 1L
  }
  comp_max <- ano_max_comp * 100L + mes_max_comp

  competencias <- list()

  if (type == "novo") {
    # Novo CAGED: estrutura caged_novo/<AAAA>/<AAAAMM>/
    for (ano in anos) {
      subpastas <- .hf_list_dir(paste0(pasta_raiz, "/", ano), timeout)
      if (is.null(subpastas)) next

      comps <- sort(
        unique(subpastas[grepl("^\\d{6}$", subpastas)]),
        decreasing = TRUE
      )

      for (comp in comps) {
        a <- as.integer(substr(comp, 1, 4))
        m <- as.integer(substr(comp, 5, 6))
        if (is.na(a) || is.na(m) || m < 1L || m > 12L) next
        if (as.integer(comp) > comp_max) next

        competencias[[length(competencias) + 1L]] <- tibble::tibble(
          competencia = comp,
          ano         = a,
          mes         = m,
          url         = glue::glue("{.HF_BASE}/{pasta_raiz}/{ano}/{comp}")
        )
        if (!is.infinite(n) && length(competencias) >= n) break
      }
      if (!is.infinite(n) && length(competencias) >= n) break
    }

  } else {
    # CAGED antigo / Ajustes: estrutura <pasta>/<AAAA>/<arquivos>.7z
    padrao <- if (type == "ajustes") "^CAGEDEST_AJUSTES_\\d{6}\\.7z$" else "^CAGEDEST_\\d{6}\\.7z$"
    prefixo_len <- if (type == "ajustes") 17L else 9L

    # Para ajustes: incluir pasta especial "2002a2009" e limitar a <= 2019
    anos_busca <- if (type == "ajustes") {
      pastas_disponiveis <- anos_disponiveis[
        grepl("^\\d{4}$", anos_disponiveis) |
        grepl("^\\d{4}a\\d{4}$", anos_disponiveis)
      ]
      # Filtrar apenas anos válidos para ajustes (<= 2019)
      pastas_disponiveis <- pastas_disponiveis[
        !grepl("^\\d{4}$", pastas_disponiveis) |
        suppressWarnings(as.integer(pastas_disponiveis)) <= 2019L
      ]
      sort(unique(pastas_disponiveis), decreasing = TRUE)
    } else {
      anos
    }

    for (ano in anos_busca) {
      arquivos <- .hf_list_dir(paste0(pasta_raiz, "/", ano), timeout)
      if (is.null(arquivos) || length(arquivos) == 0L) next

      # Padrão mensal: CAGEDEST_AJUSTES_MMAAAA.7z
      # Padrão anual (2002a2009): CAGEDEST_AJUSTES_AAAA.7z
      padrao_anual <- "^CAGEDEST_AJUSTES_\\d{4}\\.7z$"
      todos <- arquivos[grepl(padrao, arquivos, ignore.case = TRUE)]

      # Para pasta 2002a2009 (arquivos anuais sem mês)
      if (length(todos) == 0L && grepl("a", ano)) {
        todos_anuais <- arquivos[grepl(padrao_anual, arquivos, ignore.case = TRUE)]
        if (length(todos_anuais) > 0L) {
          for (arq in todos_anuais) {
            aaaa <- substr(arq, 18L, 21L)  # "CAGEDEST_AJUSTES_" = 17 chars
            if (!grepl("^\\d{4}$", aaaa)) next
            a <- as.integer(aaaa)
            if (is.na(a) || a < 1992L || a > 2019L) next
            # Usar mes=0 para indicar arquivo anual
            for (m in 1:12) {
              competencias[[length(competencias) + 1L]] <- tibble::tibble(
                competencia = sprintf("%d%02d", a, m),
                ano         = a,
                mes         = as.integer(m),
                url         = glue::glue("{.HF_BASE}/{pasta_raiz}/{ano}/{arq}")
              )
              if (!is.infinite(n) && length(competencias) >= n) break
            }
          }
        }
        next
      }

      if (length(todos) == 0L) next

      mm_vec   <- substr(todos, prefixo_len + 1L, prefixo_len + 2L)
      aaaa_vec <- substr(todos, prefixo_len + 3L, prefixo_len + 6L)
      comps    <- sort(unique(paste0(aaaa_vec, mm_vec)), decreasing = TRUE)
      comps    <- comps[nchar(comps) == 6 & !is.na(suppressWarnings(as.integer(comps)))]

      for (comp in comps) {
        a <- as.integer(substr(comp, 1, 4))
        m <- as.integer(substr(comp, 5, 6))
        if (is.na(a) || is.na(m) || m < 1L || m > 12L) next
        if (as.integer(comp) > comp_max) next

        competencias[[length(competencias) + 1L]] <- tibble::tibble(
          competencia = comp,
          ano         = a,
          mes         = m,
          url         = glue::glue("{.HF_BASE}/{pasta_raiz}/{ano}")
        )
        if (!is.infinite(n) && length(competencias) >= n) break
      }
      if (!is.infinite(n) && length(competencias) >= n) break
    }
  }

  if (length(competencias) == 0) {
    cli::cli_warn(gettext("No competency found in the HuggingFace repository."))
    return(invisible(tibble::tibble()))
  }

  resultado <- dplyr::bind_rows(competencias) |>
    dplyr::arrange(dplyr::desc(competencia))

  if (!is.infinite(n)) {
    resultado <- utils::head(resultado, n)
  }

  if (verbose && nrow(resultado) > 0L) {
    serie <- switch(type,
      novo    = "Novo CAGED (2020+)",
      antigo  = "CAGED Antigo (ate 2019)",
      ajustes = "CAGED Ajustes (serie historica)"
    )
    cli::cli_h2(gettext("Available competencies - {serie}"))

    meses_fmt <- c("Jan","Fev","Mar","Abr","Mai","Jun",
                   "Jul","Ago","Set","Out","Nov","Dez")

    for (i in seq_len(nrow(resultado))) {
      r <- resultado[i, ]
      cli::cli_inform(
        "  {cli::col_cyan(r$competencia)}  {meses_fmt[r$mes]}/{r$ano}"
      )
    }

    yr <- resultado$ano[1]
    mo <- resultado$mes[1]
    fn <- if (type == "ajustes") "caged_adjustments_load" else "caged_load"
    cmd <- paste0(fn, "(years = ", yr, ", months = ", mo, ")")

    cli::cli_inform(c(
      "i" = gettext("{nrow(resultado)} competenc{?y/ies} listed"),
      "i" = gettext("Use {.code {cmd}} to download the most recent.")
    ))
  }

  invisible(resultado)
}

# -- Utilitário interno: lista diretório via API HuggingFace ------------------

#' Lista o conteúdo de uma pasta no repositório HuggingFace via API
#'
#' @param path Relative path within the repository (e.g. "NOVO_CAGED/2023")
#' @param timeout Timeout in seconds
#' @return character vector com nomes dos itens, ou NULL em caso de erro
#' @noRd
.hf_list_dir <- function(path, timeout = 15) {
  url <- paste0(.HF_API, "/", path)

  resp <- tryCatch({
    httr2::request(url) |>
      httr2::req_timeout(timeout) |>
      httr2::req_error(is_error = \(r) FALSE) |>
      httr2::req_perform()
  }, error = function(e) NULL)

  if (is.null(resp)) return(NULL)
  if (httr2::resp_status(resp) != 200L) return(NULL)

  parsed <- tryCatch(
    httr2::resp_body_json(resp),
    error = function(e) NULL
  )

  if (is.null(parsed) || length(parsed) == 0L) return(NULL)

  # A API retorna lista de objetos com campos "path", "type" ("file"/"directory"), etc.
  # Extraímos apenas o componente final do path (basename)
  nomes <- vapply(parsed, function(item) {
    p <- item[["path"]]
    if (is.null(p) || !nzchar(p)) return(NA_character_)
    ## sub() em vez de basename(): basename() converte para o encoding
    ## nativo e falha em locale C com nomes acentuados (ex.: layouts)
    sub(".*/", "", enc2utf8(p))
  }, character(1L))

  nomes[!is.na(nomes) & nzchar(nomes)]
}

Try the datacaged package in your browser

Any scripts or data that you put into this service are public.

datacaged documentation built on Oct. 13, 2026, 1:06 a.m.