courts.tjsp.client.TJSPScraper

courts.tjsp.client.TJSPScraper(
    verbose=0,
    download_path=None,
    sleep_time=0.5,
    **kwargs,
)

Main scraper for TJSP — eSAJ web + api.tjsp.jus.br.

Methods

Name	Description
cjpg	Pesquisa jurisprudencia de primeiro grau do TJSP (CJPG).
cjpg_download	Baixa as paginas HTML brutas do CJPG TJSP (sem parsear).
cjpg_parse	Parse downloaded CJPG HTML files into a DataFrame.
cjsg	Pesquisa jurisprudencia de segundo grau do TJSP (CJSG).
cjsg_download	Baixa as paginas HTML brutas do CJSG TJSP (sem parsear).
cpopg	Fetch a first-degree process by CNJ and return a DataFrame.
cpopg_download	Download raw CPOPG files for one or many CNJs via 'html' or 'api'.
cpopg_parse	Parse downloaded CPOPG files into a DataFrame.
cposg	Fetch a second-degree process by CNJ and return a DataFrame.
cposg_download	Download raw CPOSG files for one or many CNJs via 'html' or 'api'.
cposg_parse	Parse downloaded CPOSG files into a DataFrame.
set_download_path	Set download base dir; creates a tempdir when path is None.
set_method	Validate and store the access method ('html' or 'api') for cpopg/cposg.

cjpg

courts.tjsp.client.TJSPScraper.cjpg(pesquisa='', paginas=None, **kwargs)

Pesquisa jurisprudencia de primeiro grau do TJSP (CJPG).

Delega para :meth:cjpg_download + :meth:cjpg_parse e remove o diretorio temporario antes de retornar. Diferente do CJSG, aqui pesquisa aceita string vazia — o usuario pode buscar so por filtros (ex.: todas as decisoes de uma vara especifica num intervalo de datas).

Parameters

Name	Type	Description	Default
pesquisa	str	Termo livre buscado na decisao. Default "" (sem termo). Limite de 120 caracteres (raises QueryTooLongError).	''
paginas	int | list | range | None	Paginas 1-based; None baixa todas. Default None.	None
**kwargs	Any	Filtros aceitos por :class:InputCJPGTJSP (todos opcionais; None = sem filtro): * classe (int | str | list[int | str]): ID(s) internos de classe processual. Backend: classeTreeSelection.values (CSV). * assunto (int | str | list[int | str]): ID(s) internos de assunto. Backend: assuntoTreeSelection.values (CSV). * vara (int | str | list[int | str]): ID(s) internos de vara, no formato em arvore do TJSP (ex.: "1-1-1"). Backend: varasTreeSelection.values (CSV). * id_processo (str): Numero CNJ formatado para filtrar uma instancia especifica. Normalizado via :func:clean_cnj antes do envio. * data_julgamento_inicio / data_julgamento_fim (str, DD/MM/AAAA): Intervalo de julgamento. * auto_chunk (bool): Default True. Quando o intervalo data_julgamento_* excede 366 dias, divide internamente em janelas, baixa cada uma e concatena com dedup por id_processo. Veja a secao “Auto-chunking” abaixo. * count_only (bool): Default False. Se True, faz so o GET inicial, extrai o total de resultados via cjpg_n_results e retorna int em vez de pd.DataFrame. Util pra estimar wall-clock antes de coleta longa (issue #92). Com auto_chunk=True + janela > 366 dias, itera janelas disjuntas e soma — soma bruta (sem dedup por id_processo). paginas e ignorado (emite UserWarning).	{}

Aliases deprecados (popados com DeprecationWarning antes do pydantic):

* ``query`` / ``termo`` -> ``pesquisa``
* ``classes`` -> ``classe``
* ``assuntos`` -> ``assunto``
* ``varas`` -> ``vara``
* ``data_inicio`` / ``data_fim`` -> ``data_julgamento_inicio`` / ``_fim``
* ``data_julgamento_de`` / ``_ate`` -> ``data_julgamento_inicio`` / ``_fim``

Raises

Name	Type	Description
	TypeError	Quando um kwarg desconhecido e passado (via :func:raise_on_extra_kwargs).
	ValidationError	Quando um filtro tem formato invalido.
	QueryTooLongError	Quando pesquisa excede 120 chars.
	ValueError	Quando classe e classes (ou par equivalente) sao passados simultaneamente.

Returns

Name	Type	Description
		pd.DataFrame | int: Resultados parseados (colunas conforme
		class:OutputCJPGTJSP — id_processo, cd_processo e
		campos extras emitidos pelo parser via extra='allow' —
		classe, assunto, magistrado, comarca,
		foro, vara, data_disponibilizacao, decisao);
		int com o total de resultados quando count_only=True.

Exemplo

import juscraper as jus tjsp = jus.scraper(“tjsp”) # Busca textual + filtro de vara: df = tjsp.cjpg(“dano moral”, paginas=range(1, 3), … vara=“1-1-1”) # So filtros (sem termo) — IDs como int ou list: df = tjsp.cjpg(paginas=1, classe=12728, assunto=[3607, 5885], … data_julgamento_inicio=“01/01/2024”, … data_julgamento_fim=“31/03/2024”) # Estimativa pre-scraping (issue #92): n = tjsp.cjpg(“dano moral”, count_only=True)

See also

— schema pydantic e a fonte da verdade dos filtros aceitos.

Auto-chunking (issue #130): Se auto_chunk=True (default herdado de :class:~juscraper.schemas.AutoChunkMixin) e o intervalo data_julgamento_* exceder 366 dias, a busca e dividida em janelas internas, baixadas e concatenadas com dedup por id_processo. Falhas por janela viram :class:UserWarning (parcial + warning). auto_chunk=True + paginas != None em janela > 366 dias e :class:ValueError.

cjpg_download

courts.tjsp.client.TJSPScraper.cjpg_download(
    pesquisa='',
    paginas=None,
    **kwargs,
)

Baixa as paginas HTML brutas do CJPG TJSP (sem parsear).

Delega a normalizacao de pesquisa ao pipeline (via consume_pesquisa_aliases=True + nullable_pesquisa=True — CJPG admite busca aberta com pesquisa=""). Roda :func:validate_pesquisa_length sobre o valor ja resolvido (apos consumir query/termo) para que QueryTooLongError propague mesmo quando o alias trouxe a string longa. Aceita os mesmos filtros de :meth:cjpg; veja la a lista completa.

Parameters

Name	Type	Description	Default
pesquisa	str	Termo livre. Default "". Limite de 120 chars.	''
paginas	int | list | range | None	Paginas 1-based; None baixa todas. Default None.	None
**kwargs	Any	Mesmos filtros aceitos por :meth:cjpg (validados por :class:InputCJPGTJSP).	{}

Raises

Name	Type	Description
	TypeError	Quando um kwarg desconhecido e passado.
	ValidationError	Quando um filtro tem formato invalido.
	QueryTooLongError	Quando pesquisa (ou alias resolvido) excede 120 chars.
	ValueError	Quando o usuario passa um alias deprecado e o nome canonico simultaneamente (ex.: classe e classes; refs #232).

Returns

Name	Type	Description
str	str	Caminho do diretorio onde os HTMLs foram salvos.

cjpg_parse

courts.tjsp.client.TJSPScraper.cjpg_parse(path)

Parse downloaded CJPG HTML files into a DataFrame.

cjsg

courts.tjsp.client.TJSPScraper.cjsg(pesquisa='', paginas=None, **kwargs)

Pesquisa jurisprudencia de segundo grau do TJSP (CJSG).

Override raso de :meth:EsajSearchScraper.cjsg so para ancorar a docstring TJSP-especifica: o schema validador e :class:InputCJSGTJSP, que difere do schema default da familia (sem numero_recurso/data_publicacao_*/origem; com baixar_sg). A logica de execucao continua na base.

Diferente da familia eSAJ pura, pesquisa aceita string vazia — o usuario pode buscar so por filtros (ex.: classe, assunto, data_julgamento_*) sem termo textual. Mesmo comportamento de :meth:cjpg (issue #229).

Parameters

Name	Type	Description	Default
pesquisa	str	Termo livre buscado no acordao/ementa. Default "" (sem termo, busca aberta por filtros). Limite de 120 caracteres (raises QueryTooLongError).	''
paginas	int | list | range | None	Paginas 1-based; None baixa todas. Default None.	None
**kwargs	Any	Filtros aceitos por :class:InputCJSGTJSP (todos opcionais; None = sem filtro): * ementa (str): Termo buscado especificamente na ementa. * classe (str): ID interno da classe processual. * assunto (str): ID interno do assunto. * comarca (str): ID interno da comarca. * orgao_julgador (str): ID interno do orgao julgador. * baixar_sg (bool): True (default) busca em segundo grau; False busca em colegio recursal. * tipo_decisao (Literal[“acordao”, “monocratica”]): Default "acordao". * data_julgamento_inicio / data_julgamento_fim (str, DD/MM/AAAA): Intervalo de julgamento. * auto_chunk (bool): Default True. Quando o intervalo data_julgamento_* excede 366 dias, divide internamente em janelas, baixa cada uma e concatena com dedup por cd_acordao. * count_only (bool): Default False. Se True, faz so a chamada inicial e retorna int com o total de resultados em vez de pd.DataFrame. Util pra estimar wall-clock antes de coleta longa (issue #92). Soma bruta cross-janela em auto_chunk=True.	{}

Aliases deprecados (popados com DeprecationWarning antes do pydantic):

* ``query`` / ``termo`` -> ``pesquisa``
* ``data_inicio`` / ``data_fim`` -> ``data_julgamento_inicio`` / ``_fim``
* ``data_julgamento_de`` / ``_ate`` -> ``data_julgamento_inicio`` / ``_fim``

Raises

Name	Type	Description
	TypeError	Quando um kwarg desconhecido e passado.
	ValidationError	Quando um filtro tem formato invalido.
	QueryTooLongError	Quando pesquisa excede 120 chars.

Returns

Name	Type	Description
		pd.DataFrame | int: Resultados parseados (colunas conforme
		class:OutputCJSGTJSP — processo, ementa,
		data_julgamento, cd_acordao, relator,
		orgao_julgador); int com o total de resultados quando
		count_only=True.

Exemplo

import juscraper as jus tjsp = jus.scraper(“tjsp”) df = tjsp.cjsg(“dano moral”, paginas=range(1, 3), … tipo_decisao=“acordao”, … data_julgamento_inicio=“01/01/2024”) # Estimativa pre-scraping (issue #92): n = tjsp.cjsg(“dano moral”, count_only=True)

See also

— schema pydantic e a fonte da verdade dos filtros aceitos. — descricao detalhada do auto-chunking (issue #130) para janelas data_julgamento_* > 366 dias.

cjsg_download

courts.tjsp.client.TJSPScraper.cjsg_download(
    pesquisa='',
    paginas=None,
    diretorio=None,
    **kwargs,
)

Baixa as paginas HTML brutas do CJSG TJSP (sem parsear).

Roda :func:validate_pesquisa_length antes do pydantic para que QueryTooLongError propague limpo (em vez de virar ValidationError). Aceita os mesmos filtros de :meth:cjsg; veja la a lista completa.

Parameters

Name	Type	Description	Default
pesquisa	str	Termo livre. Default "" (sem termo). Limite de 120 chars.	''
paginas	int | list | range | None	Paginas 1-based; None baixa todas. Default None.	None
diretorio	str | None	Sobrescreve :attr:download_path para esta unica chamada. Default None.	None
**kwargs	Any	Mesmos filtros aceitos por :meth:cjsg (validados por :class:InputCJSGTJSP).	{}

Raises

Name	Type	Description
	TypeError	Quando um kwarg desconhecido e passado.
	ValidationError	Quando um filtro tem formato invalido.
	QueryTooLongError	Quando pesquisa excede 120 chars.

Returns

Name	Type	Description
str	str	Caminho do diretorio onde os HTMLs foram salvos.

cpopg

courts.tjsp.client.TJSPScraper.cpopg(id_cnj, method='html')

Fetch a first-degree process by CNJ and return a DataFrame.

cpopg_download

courts.tjsp.client.TJSPScraper.cpopg_download(id_cnj, method='html')

Download raw CPOPG files for one or many CNJs via 'html' or 'api'.

cpopg_parse

courts.tjsp.client.TJSPScraper.cpopg_parse(path)

Parse downloaded CPOPG files into a DataFrame.

cposg

courts.tjsp.client.TJSPScraper.cposg(id_cnj, method='html')

Fetch a second-degree process by CNJ and return a DataFrame.

cposg_download

courts.tjsp.client.TJSPScraper.cposg_download(id_cnj, method='html')

Download raw CPOSG files for one or many CNJs via 'html' or 'api'.

cposg_parse

courts.tjsp.client.TJSPScraper.cposg_parse(path)

Parse downloaded CPOSG files into a DataFrame.

set_download_path

courts.tjsp.client.TJSPScraper.set_download_path(path=None)

Set download base dir; creates a tempdir when path is None.

set_method

courts.tjsp.client.TJSPScraper.set_method(method)

Validate and store the access method ('html' or 'api') for cpopg/cposg.