escavador-api 0.1.8__tar.gz

escavador_api-0.1.8/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Murabei Data Science
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

escavador_api-0.1.8/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: escavador-api
+Version: 0.1.8
+Summary: Python API to interact with Escavador endpoints
+License: BSD-3-Clause License
+License-File: LICENSE
+Author: André Andrade Baceti
+Author-email: a.baceti@murabei.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Requires-Dist: tenacity (>=9.1.4,<10.0.0)
+Description-Content-Type: text/markdown
+
+# escavador-api
+
+A Python library for interacting with the Escavador API, providing access to Brazilian legal process data, documents, and monitoring services.
+
+## Features
+
+- **Process Information**: Retrieve detailed information about legal processes using CNJ numbers
+- **Process Movements**: Get chronological movement history of legal processes
+- **Document Access**: Download public and restricted process documents
+- **AI Summaries**: Generate and retrieve AI-powered process summaries
+- **Process Monitoring**: Set up monitoring for new processes or updates to existing processes
+- **Credit Management**: Check API usage credits and limits
+- **Process Updates**: Request fresh data updates from court sources
+- **Retry Logic**: Automatic retry with 5-second delays for network failures (max 5 retries)
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://github.com/Murabei-OpenSource-Codes/escavador-api.git
+cd escavador-api
+pip install .
+```
+
+## Requirements
+
+- Python >= 3.12
+- requests >= 2.32.5
+
+## Quick Start
+
+```python
+from escavador_api import EscavadorAPI
+
+# Initialize with your API token
+api = EscavadorAPI("your_auth_token_here")
+
+# Check credit balance
+balance = api.get_credit_balance()
+print(balance)
+
+# Get process information
+process_info = api.get_process_info("12345678901234567890")
+print(process_info)
+```
+
+## API Reference
+
+### Initialization
+
+```python
+EscavadorAPI(escavador_auth_token: str)
+```
+
+**Parameters:**
+- `escavador_auth_token` (str): Your Escavador API authentication token
+
+### Core Methods
+
+#### Credit Management
+
+```python
+get_credit_balance() -> dict
+```
+Returns current credit balance and monthly limits.
+
+#### Process Information
+
+```python
+get_process_info(process_number: str) -> dict
+```
+Retrieve basic process information.
+
+**Parameters:**
+- `process_number` (str): CNJ process number (20 digits, punctuation optional)
+
+```python
+get_process_movements(process_number: str) -> list
+```
+Get all movements for a process.
+
+```python
+get_process_public_documents(process_number: str) -> list
+```
+Get publicly available documents.
+
+```python
+get_process_all_documents(process_number: str) -> list
+```
+Get all documents (public and restricted, if authorized).
+
+#### Process Updates
+
+```python
+request_process_update_public(process_number: str) -> dict
+```
+Request update of public process information.
+
+```python
+request_process_update_full(
+    process_number: str,
+    auth_username: str = None,
+    auth_password: str = None,
+    certificate_id: int = None,
+    use_certificate: bool = False
+) -> dict
+```
+Request full update including restricted documents.
+
+```python
+get_process_update_status(process_number: str) -> dict
+```
+Check the status of an update request.
+
+#### Document Downloads
+
+```python
+download_process_file(process_number: str, file_key: str) -> bytes
+```
+Download a specific document as PDF bytes.
+
+#### AI Summaries
+
+```python
+request_ai_summary(process_number: str) -> dict
+```
+Request generation of an AI summary.
+
+```python
+get_ai_summary_status(process_number: str, summary_id: int) -> dict
+```
+Check AI summary generation status.
+
+```python
+get_ai_summary(process_number: str) -> dict
+```
+Retrieve the generated AI summary.
+
+### Monitoring
+
+#### New Process Monitoring
+
+```python
+create_monitoring_new_process(
+    keyword: str,
+    keyword_variations: list[str] = None,
+    aux_keywords: list[KeywordDict] = None,
+    courts: list[str] = None
+) -> dict
+```
+Create monitoring for new processes matching criteria.
+
+```python
+list_monitoring_new_process() -> list
+```
+List all new process monitorings.
+
+```python
+get_monitoring_new_process(monitoring_id: int) -> dict
+```
+Get details of a specific monitoring.
+
+```python
+edit_monitoring_new_process(
+    monitoring_id: int,
+    keyword_variations: list[str] = None,
+    aux_keywords: list[KeywordDict] = None,
+    courts: list[str] = None
+) -> dict
+```
+Edit an existing monitoring.
+
+```python
+delete_monitoring_new_process(monitoring_id: int) -> bool
+```
+Delete a monitoring.
+
+```python
+get_results_monitoring_new_process(monitoring_id: int) -> list
+```
+Get results from a monitoring.
+
+#### Existing Process Monitoring
+
+```python
+create_monitoring_existing_process(
+    process_number: str,
+    court: str = None,
+    frequency: str = None
+) -> dict
+```
+Monitor updates to an existing process.
+
+```python
+list_monitoring_existing_process() -> list
+```
+List existing process monitorings.
+
+```python
+get_monitoring_existing_process(monitoring_id: int) -> dict
+```
+Get monitoring details.
+
+```python
+delete_monitoring_existing_process(monitoring_id: int) -> bool
+```
+Delete monitoring.
+
+## Error Handling
+
+The library provides specific exception types:
+
+- `EscavadorAPIInvalidDocumentException`: Invalid process number format
+- `EscavadorAPIProblemAPIException`: API-specific errors (authentication, insufficient credits, etc.)
+- `EscavadorAPIUnmappedErrorException`: Unexpected errors or network issues
+
+## Retry Logic
+
+All API calls include automatic retry logic:
+- **Maximum retries**: 5 attempts
+- **Retry delay**: 5 seconds between attempts
+- **Retry conditions**: Network errors (connection failures, timeouts, chunked encoding errors)
+- **Non-retryable errors**: Validation errors, HTTP errors (4xx/5xx), and API-specific exceptions
+
+## Process Number Format
+
+Process numbers must follow the Brazilian CNJ (Conselho Nacional de Justiça) format:
+- 20 digits total
+- Format: NNNNNNN-DD.AAAA.J.TR.OOOO
+
+The library automatically validates process numbers and accepts them with or without punctuation.
+
+## Authentication
+
+To use the Escavador API, you need:
+1. An Escavador account
+2. An API authentication token
+3. Sufficient credits for API calls
+
+For restricted documents, additional authentication may be required (username/password or digital certificate).
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+pip install -e .
+
+# Run tests
+pytest
+
+# Build package
+./build.sh
+```
+
+### Testing
+
+Tests require environment variables:
+- `ESCAVADOR_AUTH_TOKEN`: Your API token
+- `TEST_PROCESS_NUMBER`: A valid CNJ process number for testing
+
+```bash
+export ESCAVADOR_AUTH_TOKEN="your_token"
+export TEST_PROCESS_NUMBER="process_number"
+pytest
+```
+
+## License
+
+BSD 3-Clause License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## Support
+
+For issues and questions:
+- Check the [Escavador API documentation](https://api.escavador.com/)
+- Open an issue on GitHub
+- Contact Murabei Data Science at a.baceti@murabei.com

escavador_api-0.1.8/README.md

@@ -0,0 +1,287 @@
+# escavador-api
+
+A Python library for interacting with the Escavador API, providing access to Brazilian legal process data, documents, and monitoring services.
+
+## Features
+
+- **Process Information**: Retrieve detailed information about legal processes using CNJ numbers
+- **Process Movements**: Get chronological movement history of legal processes
+- **Document Access**: Download public and restricted process documents
+- **AI Summaries**: Generate and retrieve AI-powered process summaries
+- **Process Monitoring**: Set up monitoring for new processes or updates to existing processes
+- **Credit Management**: Check API usage credits and limits
+- **Process Updates**: Request fresh data updates from court sources
+- **Retry Logic**: Automatic retry with 5-second delays for network failures (max 5 retries)
+
+## Installation
+
+### From Source
+
+```bash
+git clone https://github.com/Murabei-OpenSource-Codes/escavador-api.git
+cd escavador-api
+pip install .
+```
+
+## Requirements
+
+- Python >= 3.12
+- requests >= 2.32.5
+
+## Quick Start
+
+```python
+from escavador_api import EscavadorAPI
+
+# Initialize with your API token
+api = EscavadorAPI("your_auth_token_here")
+
+# Check credit balance
+balance = api.get_credit_balance()
+print(balance)
+
+# Get process information
+process_info = api.get_process_info("12345678901234567890")
+print(process_info)
+```
+
+## API Reference
+
+### Initialization
+
+```python
+EscavadorAPI(escavador_auth_token: str)
+```
+
+**Parameters:**
+- `escavador_auth_token` (str): Your Escavador API authentication token
+
+### Core Methods
+
+#### Credit Management
+
+```python
+get_credit_balance() -> dict
+```
+Returns current credit balance and monthly limits.
+
+#### Process Information
+
+```python
+get_process_info(process_number: str) -> dict
+```
+Retrieve basic process information.
+
+**Parameters:**
+- `process_number` (str): CNJ process number (20 digits, punctuation optional)
+
+```python
+get_process_movements(process_number: str) -> list
+```
+Get all movements for a process.
+
+```python
+get_process_public_documents(process_number: str) -> list
+```
+Get publicly available documents.
+
+```python
+get_process_all_documents(process_number: str) -> list
+```
+Get all documents (public and restricted, if authorized).
+
+#### Process Updates
+
+```python
+request_process_update_public(process_number: str) -> dict
+```
+Request update of public process information.
+
+```python
+request_process_update_full(
+    process_number: str,
+    auth_username: str = None,
+    auth_password: str = None,
+    certificate_id: int = None,
+    use_certificate: bool = False
+) -> dict
+```
+Request full update including restricted documents.
+
+```python
+get_process_update_status(process_number: str) -> dict
+```
+Check the status of an update request.
+
+#### Document Downloads
+
+```python
+download_process_file(process_number: str, file_key: str) -> bytes
+```
+Download a specific document as PDF bytes.
+
+#### AI Summaries
+
+```python
+request_ai_summary(process_number: str) -> dict
+```
+Request generation of an AI summary.
+
+```python
+get_ai_summary_status(process_number: str, summary_id: int) -> dict
+```
+Check AI summary generation status.
+
+```python
+get_ai_summary(process_number: str) -> dict
+```
+Retrieve the generated AI summary.
+
+### Monitoring
+
+#### New Process Monitoring
+
+```python
+create_monitoring_new_process(
+    keyword: str,
+    keyword_variations: list[str] = None,
+    aux_keywords: list[KeywordDict] = None,
+    courts: list[str] = None
+) -> dict
+```
+Create monitoring for new processes matching criteria.
+
+```python
+list_monitoring_new_process() -> list
+```
+List all new process monitorings.
+
+```python
+get_monitoring_new_process(monitoring_id: int) -> dict
+```
+Get details of a specific monitoring.
+
+```python
+edit_monitoring_new_process(
+    monitoring_id: int,
+    keyword_variations: list[str] = None,
+    aux_keywords: list[KeywordDict] = None,
+    courts: list[str] = None
+) -> dict
+```
+Edit an existing monitoring.
+
+```python
+delete_monitoring_new_process(monitoring_id: int) -> bool
+```
+Delete a monitoring.
+
+```python
+get_results_monitoring_new_process(monitoring_id: int) -> list
+```
+Get results from a monitoring.
+
+#### Existing Process Monitoring
+
+```python
+create_monitoring_existing_process(
+    process_number: str,
+    court: str = None,
+    frequency: str = None
+) -> dict
+```
+Monitor updates to an existing process.
+
+```python
+list_monitoring_existing_process() -> list
+```
+List existing process monitorings.
+
+```python
+get_monitoring_existing_process(monitoring_id: int) -> dict
+```
+Get monitoring details.
+
+```python
+delete_monitoring_existing_process(monitoring_id: int) -> bool
+```
+Delete monitoring.
+
+## Error Handling
+
+The library provides specific exception types:
+
+- `EscavadorAPIInvalidDocumentException`: Invalid process number format
+- `EscavadorAPIProblemAPIException`: API-specific errors (authentication, insufficient credits, etc.)
+- `EscavadorAPIUnmappedErrorException`: Unexpected errors or network issues
+
+## Retry Logic
+
+All API calls include automatic retry logic:
+- **Maximum retries**: 5 attempts
+- **Retry delay**: 5 seconds between attempts
+- **Retry conditions**: Network errors (connection failures, timeouts, chunked encoding errors)
+- **Non-retryable errors**: Validation errors, HTTP errors (4xx/5xx), and API-specific exceptions
+
+## Process Number Format
+
+Process numbers must follow the Brazilian CNJ (Conselho Nacional de Justiça) format:
+- 20 digits total
+- Format: NNNNNNN-DD.AAAA.J.TR.OOOO
+
+The library automatically validates process numbers and accepts them with or without punctuation.
+
+## Authentication
+
+To use the Escavador API, you need:
+1. An Escavador account
+2. An API authentication token
+3. Sufficient credits for API calls
+
+For restricted documents, additional authentication may be required (username/password or digital certificate).
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+pip install -e .
+
+# Run tests
+pytest
+
+# Build package
+./build.sh
+```
+
+### Testing
+
+Tests require environment variables:
+- `ESCAVADOR_AUTH_TOKEN`: Your API token
+- `TEST_PROCESS_NUMBER`: A valid CNJ process number for testing
+
+```bash
+export ESCAVADOR_AUTH_TOKEN="your_token"
+export TEST_PROCESS_NUMBER="process_number"
+pytest
+```
+
+## License
+
+BSD 3-Clause License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## Support
+
+For issues and questions:
+- Check the [Escavador API documentation](https://api.escavador.com/)
+- Open an issue on GitHub
+- Contact Murabei Data Science at a.baceti@murabei.com

escavador_api-0.1.8/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "escavador-api"
+version = "0.1.8"
+description = "Python API to interact with Escavador endpoints"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "BSD-3-Clause License" }
+authors = [
+    {name = "André Andrade Baceti", email = "a.baceti@murabei.com"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "requests (>=2.32.5,<3.0.0)",
+    "tenacity (>=9.1.4,<10.0.0)"
+]
+
+[tool.poetry]
+packages = [{include = "escavador_api", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 79 # Quantidade de caracteres que o linter irá considerar na linha
+indent-width = 4
+
+# Pastas onde o linter não atuara. Por padrão ele só lê arquivos python e ignora tudo dentro do .gitignore
+exclude = [
+  "secrets/",
+  "__init__.py",
+  "setup_template.py",
+  "setup.py"
+]
+
+# Lista de linters que serão aplicados. o ruff da suporte a vários e eles podem ser adicionados aqui.
+[tool.ruff.lint]
+select = [
+    "F", # Pyflakes - Procura bugs básicos no codigo
+    "E", # pycodestyle - Pep8
+    "W", # pycodestyle - Pep8
+    "D", # pydocstyle - Docstring
+    "I", # Isort - Imports
+    "PD", # pandas-vet - linter de pandas (não deixa usar inplace nem df como nome de variavel)
+    "N", # pep8-naming - nomes seguindo pep8
+    "S", # flake8-bandit - linter de vulnerabilidade (nmao deixa usar assert)
+]
+
+# Os códigos de erros colocados aqui são ignorados pelo linter. O erro abaixo é em relação ao assert. Está comentado por padrão.
+ignore = [
+  # "S101" # Use of `assert` detected
+  "E402", "N806", "I001"
+]
+
+# ativa um modo plus do ruff
+preview = true
+
+[tool.ruff.format]
+indent-style = "space"
+
+[tool.ruff.lint.pydocstyle]
+convention = "google" # seleciona as docstrings do google como padrão
+
+[tool.ruff.lint.isort]
+no-sections = true
+
+[dependency-groups]
+docs = [
+    "mkdocs (>=1.6.1,<2.0.0)"
+]