aggregators.pdpj.client.PdpjScraper

aggregators.pdpj.client.PdpjScraper(
    verbose=0,
    download_path=None,
    sleep_time=0.5,
    token=None,
    politica=None,
)

Raspador para a API DATALAKE - Processos do PDPJ.

A API consome JWT do SSO PJe (mesmo provedor do JusBR), entao o uso tipico e: obter o token via portal do PDPJ logado, chamar auth e usar os endpoints de consulta/download.

Os metodos por processo (cpopg, documentos, movimentos, partes e existe com lista) e download_documents devolvem uma linha de falha quando a requisicao de um item falha, com o motivo na coluna motivo_falha (vocabulario em juscraper.core.failures) e um UserWarning agregado ao fim.

Nos metodos por processo, o processo ausente do data lake sai com o motivo nao_encontrado. A API diz isso de duas formas: 404 no endpoint do processo, ou 500 no endpoint com 404 na pesquisa por numeroProcesso. No primeiro 500 de um processo, o raspador faz essa pesquisa, numa tentativa so: com 404, para de retentar; com qualquer outra resposta, segue as tentativas do perfil. Assim o processo ausente custa duas requisicoes, e nao as seis tentativas do perfil. O 401 e a falha do SSO ao renovar o token (ErroSsoPdpj) interrompem a coleta. Metodos sem linha por item (existe com str, contar e pesquisa) levantam o erro.

As requisicoes usam os perfis "listagem" e "documento" de RequestPolicy, ajustaveis no construtor com politica=.

Methods

Name	Description
auth	Define o JWT usado em todas as chamadas autenticadas.
contar	Total de processos que casam com os filtros (/processos:contar).
cpopg	Recupera os detalhes de processo(s) via API /processos/{n}.
documentos	Lista documentos do(s) processo(s) (sem baixar conteudo).
download_documents	Baixa textos e/ou binarios dos documentos listados.
existe	Checa presenca de processo(s) no Data Lake.
movimentos	Lista movimentos do(s) processo(s).
partes	Lista partes do(s) processo(s).
pesquisa	Busca profunda em GET /api/v1/processos (com paginacao).

auth

aggregators.pdpj.client.PdpjScraper.auth(token)

Define o JWT usado em todas as chamadas autenticadas.

O token passa por juscraper.core.auth.validar_jwt, que recusa token malformado ou vencido antes do primeiro uso. O conteudo do JWT nao e logado.

Raises

Name	Type	Description
	ValueError	Quando o token e malformado ou ja expirou. O token e o header anteriores ficam como estavam.

contar

aggregators.pdpj.client.PdpjScraper.contar(**kwargs)

Total de processos que casam com os filtros (/processos:contar).

Aceita o mesmo subconjunto de filtros de pesquisa exceto os relacionados a paginacao/ordenacao. Retorna int.

Raises

Name	Type	Description
	requests.ConnectionError	Quando a requisicao falha.
	InvalidJSONResponseError	Quando a resposta nao traz um inteiro.

cpopg

aggregators.pdpj.client.PdpjScraper.cpopg(id_cnj)

Recupera os detalhes de processo(s) via API /processos/{n}.

Parameters

Name	Type	Description	Default
id_cnj	str | list[str]	Numero CNJ ou lista de numeros.	required

Returns

Name	Type	Description
	pd.DataFrame	DataFrame com uma linha por tramitacao do processo. Colunas
principais	pd.DataFrame	processo (CNJ pesquisado, dignos de digito),
	pd.DataFrame	numero_processo (formatado pela API), sigla_tribunal,
	pd.DataFrame	segmento_justica, data_atualizacao, detalhes
	pd.DataFrame	(dict com a resposta completa) e motivo_falha. A API que
	pd.DataFrame	responde lista vazia gera uma linha com
	pd.DataFrame	status_consulta="Nao encontrado"; a consulta que falha gera
	pd.DataFrame	uma linha com status_consulta igual a
	pd.DataFrame	data:juscraper.core.failures.STATUS_CONSULTA_FALHA e o motivo.
	pd.DataFrame	O processo ausente do data lake (ver a classe) sai nessa linha,
	pd.DataFrame	com o motivo nao_encontrado.

Raises

Name	Type	Description
	requests.HTTPError	No 401 (token ausente, expirado ou invalido), com as falhas anteriores numa nota do erro.
	ErroSsoPdpj	Quando o SSO do PJe recusa ou não consegue renovar o token no meio do lote. Propaga como o 401, com as falhas anteriores numa nota do erro.

Avisos

UserWarning: Quando pelo menos uma consulta falhou.

See Also

InputCnjPdpj – schema pydantic.

documentos

aggregators.pdpj.client.PdpjScraper.documentos(id_cnj)

Lista documentos do(s) processo(s) (sem baixar conteudo).

O processo cuja consulta falha sai numa linha so, com processo e motivo_falha preenchidos e as demais colunas vazias. O processo ausente do data lake sai assim, com nao_encontrado, e nao como lista sem documentos. O 401 interrompe; ver cpopg.

download_documents

aggregators.pdpj.client.PdpjScraper.download_documents(
    base_df,
    max_docs_per_process=None,
    *,
    with_text=True,
    with_binary=False,
)

Baixa textos e/ou binarios dos documentos listados.

base_df pode vir de documentos (uma linha por documento, ja com id_documento e numero_processo) ou de cpopg (uma linha por processo com detalhes – nesse caso a lista de documentos e extraida de detalhes['documentos']).

Um documento cujo download falha não interrompe a coleta: a linha sai com texto/_raw_texto e/ou binario iguais a None e o método segue para o próximo documento. Conta como falha qualquer erro HTTP diferente de 401 (inclusive o 403, que a API pode devolver para um documento isolado, como um sigiloso, e que por isso não é retentado), o retry de 429/5xx/timeout esgotado e o erro de conexão. A coluna motivo_falha guarda o motivo, no vocabulário de juscraper.core.failures; com texto e binário, guarda o do texto quando o texto falhou, senão o do binário, e o None de cada coluna diz qual conteúdo faltou. Ao fim, um único UserWarning informa quantos downloads falharam e cita alguns, com processo, documento, conteúdo e motivo. O 401 propaga, porque token inválido atinge o lote inteiro.

O documento sem arquivo (arquivo_id vazio, na base que traz a coluna) não tem conteúdo no data lake, e a API responde 404 ao pedido de texto dele. Ele sai com os conteúdos None e motivo_falha None, sem requisição e fora do aviso, e ocupa vaga do limite, como qualquer linha devolvida.

Parameters

Name	Type	Description	Default
base_df	pd.DataFrame	DataFrame fonte das chamadas.	required
max_docs_per_process	int | None	Limite de linhas devolvidas por processo, na ordem de base_df. Linhas sem id_documento sao puladas sem ocupar vaga do limite; um documento cujo download falhou ocupa vaga, como no JusBR, porque sua linha sai no resultado (com conteúdo None) e a requisição já foi feita. None = sem limite; 0 devolve DataFrame vazio sem fazer requisicao.	None
with_text	bool	Se True (default), baixa o texto via /documentos/{id}/texto.	True
with_binary	bool	Se True, baixa o binario via /documentos/{id}/binario. Default False para nao consumir banda quando o usuario so quer texto.	False

Returns

Name	Type	Description
	pd.DataFrame	DataFrame com uma linha por documento. Inclui colunas
	pd.DataFrame	texto e binario (quando solicitados), None nos
	pd.DataFrame	documentos cujo download falhou, e motivo_falha.

Raises

Name	Type	Description
	ValidationError	Quando base_df nao e um DataFrame ou max_docs_per_process e negativo.
	ValueError	Quando with_text e with_binary sao ambos False, ou quando base_df nao tem coluna id_documento nem detalhes.
	requests.HTTPError	Quando a API responde 401 (token ausente, expirado ou inválido). O erro atinge o lote inteiro, então propaga e as linhas já baixadas se perdem; as falhas anteriores ao 401 vão numa nota do próprio erro (__notes__), não no UserWarning.
	ErroSsoPdpj	Quando o SSO do PJe recusa ou não consegue renovar o token no meio do lote. Propaga como o 401, com as falhas anteriores numa nota do erro.

Avisos

UserWarning: Quando pelo menos um download de documento falhou. Um aviso por chamada, com a contagem e alguns exemplos, emitido só quando a coleta termina.

See Also

InputDownloadDocumentsPdpj: schema pydantic e fonte da verdade dos parametros aceitos.

existe

aggregators.pdpj.client.PdpjScraper.existe(id_cnj)

Checa presenca de processo(s) no Data Lake.

Parameters

Name	Type	Description	Default
id_cnj	str | list[str]	Numero CNJ unico (str) ou lista de numeros.	required

Returns

Name	Type	Description
	bool | pd.DataFrame	bool quando id_cnj e str; pd.DataFrame com
	bool | pd.DataFrame	colunas processo, existe e motivo_falha quando e
	bool | pd.DataFrame	list. Na lista, o processo cuja consulta falhou sai com
	bool | pd.DataFrame	existe=None e o motivo, nao_encontrado no processo ausente
	bool | pd.DataFrame	(ver a classe).

Raises

Name	Type	Description
	requests.HTTPError	No 401, e com str em qualquer erro HTTP.
	ErroSsoPdpj	Quando o SSO do PJe recusa ou não consegue renovar o token; na lista, com as falhas anteriores numa nota do erro.
	InvalidJSONResponseError	Com str, quando a consulta falha; a resposta sem true/false levanta o ultimo.

See Also

InputCnjPdpj – schema pydantic.

movimentos

aggregators.pdpj.client.PdpjScraper.movimentos(id_cnj)

Lista movimentos do(s) processo(s).

Falha por processo como em documentos.

partes

aggregators.pdpj.client.PdpjScraper.partes(id_cnj)

Lista partes do(s) processo(s).

Falha por processo como em documentos.

pesquisa

aggregators.pdpj.client.PdpjScraper.pesquisa(paginas=None, **kwargs)

Busca profunda em GET /api/v1/processos (com paginacao).

Parameters

Name	Type	Description	Default
paginas	int | list[int] | range | None	Intervalo 1-based. Aceita int (3 -> primeiras 3 paginas), list, range ou None (todas).	None
**kwargs	Any	Filtros aceitos pelo schema InputPesquisaPdpj (todos opcionais; None = sem filtro): * numero_processo (str) * numero_processo_sintetico (str) * id (str): id interno do processo no Data Lake * cpf_cnpj_parte (str): com formatacao * nome_parte (str) * polo_parte (str): “ATIVO” ou “PASSIVO” * situacao_parte (str) * nome_representante / oab_representante (str) * id_classe (str): codigos separados por virgula * id_assunto_judicial (str): ids separados por virgula * id_orgao_julgador (str | list[str]) * instancia (str): “PRIMEIRO_GRAU”/“SEGUNDO_GRAU”/etc. * segmento_justica (str): “JUSTICA_FEDERAL”/“JUSTICA_ESTADUAL”/etc. * tribunal (str): siglas separadas por virgula (max 5) * data_atualizacao_inicio / _fim (str): ISO datetime * data_primeiro_ajuizamento_inicio / _fim (str): ISO datetime * campo_ordenacao (str): campo de ordenacao decrescente * itens_por_pagina (int): default 100. Vai a API como maxElementsSize, mas a API ignora o valor: a especificacao publica do data lake traz maxElementsSize so na resposta, como o maximo por consulta, e nao declara parametro de tamanho de pagina. Em campo, o pedido de 5 devolveu 100 itens. A pagina nao se corta no cliente, porque o cursor searchAfter da pagina seguinte vem da ultima linha que a API mandou; para limitar o total, use paginas.	{}

Returns

Name	Type	Description
	pd.DataFrame	DataFrame com uma linha por processo retornado. A API responde 404
	pd.DataFrame	(“Não foram encontrados registros”) a pagina seguinte a ultima com
	pd.DataFrame	dados e a busca sem resultado; o 404 encerra a coleta, e a busca
	pd.DataFrame	sem resultado devolve DataFrame vazio.

Raises

Name	Type	Description
	(requests.ConnectionError, InvalidJSONResponseError)	Quando a requisicao de qualquer pagina falha, com status diferente de 404. Pagina nao vira linha de falha, e devolver as paginas anteriores truncaria o resultado sem aviso.

See Also

InputPesquisaPdpj – schema pydantic e a fonte da verdade dos filtros aceitos.