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	Baixa processos de primeiro grau pelo CNJ e devolve as tabelas extraidas.
cpopg_download	Download raw CPOPG files for one or many CNJs via `'html'` or `'api'`.
cpopg_parse	Le os arquivos baixados do CPOPG e devolve um dict de DataFrames.
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.
listar_varas	Lista as varas de primeiro grau disponiveis para filtrar (cjpg).
set_download_path	Set download base dir; with `None`, a tempdir is created on first use.
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 cjpg_download + 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 `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 `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 `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)

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 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 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 `cjpg` (validados por `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 EsajSearchScraper.cjsg so para ancorar a docstring TJSP-especifica: o schema validador e 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 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 `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)

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 validate_pesquisa_length antes do pydantic para que QueryTooLongError propague limpo (em vez de virar ValidationError). Aceita os mesmos filtros de 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 `download_path` para esta unica chamada. Default `None`.	`None`
**kwargs	`Any`	Mesmos filtros aceitos por `cjsg` (validados por `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')

Baixa processos de primeiro grau pelo CNJ e devolve as tabelas extraidas.

Parameters

Name	Type	Description	Default
id_cnj	`str` \| `list`[`str`]	Numero CNJ ou lista de numeros CNJ.	required
method	`str`	`"html"` (paginas do eSAJ) ou `"api"`. Default `"html"`.	`'html'`

Raises

Name	Type	Description
	`ValueError`	Quando `method` nao e suportado, ou quando nenhum arquivo baixado pode ser lido (nenhum arquivo candidato no diretorio de download, ou todos com erro de leitura). Nesse caso o diretorio de download nao e apagado.

Returns

Name	Type	Description
		dict[str, pd.DataFrame]: Tabelas `basicos`, `partes`,
		`movimentacoes` e `peticoes_diversas` no metodo `"html"`;
		no metodo `"api"`, uma tabela por tipo de JSON baixado.

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)

Le os arquivos baixados do CPOPG e devolve um dict de DataFrames.

Raises

Name	Type	Description
	`ValueError`	Quando `path` e um diretorio e nenhum arquivo dele pode ser lido, ou quando `path` e um arquivo com extensao diferente de `.html`/`.json`. Ver `cpopg_parse_manager`.

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.

listar_varas

courts.tjsp.client.TJSPScraper.listar_varas(grau='1')

Lista as varas de primeiro grau disponiveis para filtrar (cjpg).

Baixa a arvore de varas do eSAJ para descobrir os IDs aceitos pelo filtro vara de cjpg. A arvore agrupa as varas por comarca/foro, entao id_pai/caminho carregam essa hierarquia.

Parameters

Name	Type	Description	Default
grau	`str`	`"1"` (primeiro grau / cjpg). Unico valor aceito.	`'1'`

Raises

Name	Type	Description
	`ValueError`	Quando `grau` nao esta disponivel.

Returns

Name	Type	Description
	`pd`.`DataFrame`	pd.DataFrame: Arvore de varas (colunas `id`, `nome`,
	`pd`.`DataFrame`	`id_pai`, `nivel`, `selecionavel`, `caminho`).

set_download_path

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

Set download base dir; with None, a tempdir is created on first use.

set_method

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

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

courts.tjsp.client.TJSPScraper

Methods

cjpg

Parameters

Raises

Returns

Exemplo

See also

cjpg_download

Parameters

Raises

Returns

cjpg_parse

cjsg

Parameters

Raises

Returns

Exemplo

See also

cjsg_download

Parameters

Raises

Returns

cpopg

Parameters

Raises

Returns

cpopg_download

cpopg_parse

Raises

cposg

cposg_download

cposg_parse

listar_varas

Parameters

Raises

Returns

set_download_path

set_method