splaz 0.1.0__tar.gz

splaz-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Braga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

splaz-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: splaz
+Version: 0.1.0
+Summary: API para facilitar o acesso a dados LiDAR do GeoSampa
+Author: João Braga
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: geopandas
+Requires-Dist: geopy
+Requires-Dist: shapely
+Requires-Dist: laspy
+Dynamic: license-file

splaz-0.1.0/README.md

@@ -0,0 +1,111 @@
+# SpLaz (Vagas Verdes)
+A SpLaz é uma biblioteca Python de alto nível projetada para automatizar a obtenção de dados LiDAR (nuvens de pontos) da cidade de São Paulo via portal GeoSampa. Ela resolve complexidades de geocodificação, conversão de sistemas de coordenadas (SIRGAS 2000 / UTM 23S) e instabilidades de download de servidores legados.
+
+Este projeto é a base técnica do projeto Vagas Verdes, focado em identificar áreas potenciais para arborização urbana utilizando sensoriamento remoto.
+
+## 🚀 Funcionalidades
+- Geocodificação por Endereço: Identifica automaticamente qual quadrante LiDAR baixar a partir de um endereço textual (ex: "Rua Quatá, 300").
+
+- Busca por Bairro: Lista e baixa todos os quadrantes que compõem um bairro específico.
+
+- Tratamento de Dados Espaciais: Download e extração automática da grade de articulação (Shapefile) da prefeitura.
+
+- Resiliência de Rede: Sistema de correção de encoding (ISO-8859-1) e verificação de integridade de arquivos ZIP.
+
+- Gestão de Cache: Armazenamento inteligente na pasta local .geosp_laz_api para evitar downloads repetitivos e poupar banda.
+
+## 📦 Instalação
+O próximo passo do projeto será a publicação no PyPI. Atualmente, a biblioteca pode ser instalada diretamente via pip a partir do diretório raiz:
+
+Bash
+
+### Instalação em modo editável (ideal para desenvolvimento)
+pip install -e .
+### 🛠 Exemplos de Uso
+#### 1. Configuração Inicial
+```Python
+
+from splaz import GeospLidarClient, GeospGeocoder
+
+client = SpLaz()
+geo = SpLazGeo(client=client)
+```
+#### 2. Download por Código do Quadrante
+Ideal quando você já possui o mapeamento da grade de 2020:
+
+```Python
+
+quadrante = client.download_quadrante("3316-153")
+quadrante.save("data/raw/laz")
+```
+#### 3. Download por Endereço (Geocodificação)
+A forma mais intuitiva de acessar os dados para um local específico:
+
+```Python
+
+endereco = "Avenida Santo Amaro, 1826"
+codigo = geo.get_quadrant_by_address(endereco)
+print(f"Quadrante identificado: {codigo}")
+client.download_quadrante(codigo).save("data/raw/laz")
+```
+#### 4. Download por Coordenadas (Lat/Lon)
+Para integração com GPS ou outros sistemas de mapeamento:
+
+```Python
+
+lat, lon = -23.598, -46.676
+codigo = geo.get_quadrant_by_coords(lat, lon)
+client.download_quadrante(codigo).save("data/raw/laz")
+```
+#### 5. Processamento por Bairro
+Obtenha todos os quadrantes que interceptam a área de um bairro:
+
+```Python
+
+bairro = "Itaim Bibi"
+codigos = geo.get_quadrants_by_neighborhood(bairro)
+
+for cod in codigos:
+    client.download_quadrante(cod).save(f"data/raw/laz/{bairro}")
+```
+#### 6. Manipulando a Classe LidarQuadrante
+A classe abstrai a complexidade dos binários baixados:
+
+```Python
+
+quadrante = client.download_quadrante("3316-153")
+
+# Atributos úteis
+print(quadrante.codigo)             # "3316-153"
+print(quadrante.esta_carregado)     # True
+print(len(quadrante.conteudo_binario)) # Tamanho em bytes do arquivo .laz
+
+# Salva o arquivo final no disco
+quadrante.save(dest_path="output/lidar")
+```
+## 📂 Estrutura do Projeto
+```Plaintext
+
+src/splaz/
+├── entities.py    # Representação de objetos LiDAR
+├── downloader.py  # Lógica de comunicação com GeoSampa
+├── geocoder.py    # Cálculos espaciais e geolocalização
+└── constants.py   # EPSG, URLs e parâmetros de API
+```
+## 🧪 Testes Automatizados
+A biblioteca possui uma suíte de testes robusta (Unitários, Integração e E2E) que valida desde a lógica de coordenadas até o download real. Para rodar:
+
+```Bash
+pytest
+```
+
+### 📄 Licença
+Distribuído sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.
+### 🎓 Contexto Acadêmico
+Este projeto foi desenvolvido como parte de um projeto de Iniciação Científica no Insper.
+
+Autor: João Braga
+
+Perfil: Aluno do 7° semestre de Engenharia da Computação.
+
+Objetivo: Apoiar a análise de dados geoespaciais para o projeto ambiental "Vagas Verdes".

splaz-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "splaz"
+version = "0.1.0"
+description = "API para facilitar o acesso a dados LiDAR do GeoSampa"
+authors = [
+    {name = "João Braga"}
+]
+dependencies = [
+    "requests",
+    "geopandas",
+    "geopy",
+    "shapely",
+    "laspy",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

splaz-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

splaz-0.1.0/src/splaz/__init__.py

@@ -0,0 +1,17 @@
+"""
+splaz: Uma biblioteca para facilitar o acesso e geocodificação 
+de dados LiDAR (MDS/MDT) do portal GeoSampa da cidade de São Paulo.
+"""
+
+from .entities import LidarQuadrante
+from .downloader import SpLaz
+from .geocoder import SpLazGeo
+
+__all__ = [
+    "LidarQuadrante",
+    "SpLaz",
+    "SpLazGeo",
+]
+
+__version__ = "0.1.0"
+__author__ = "João Braga"

splaz-0.1.0/src/splaz/constants.py

@@ -0,0 +1,18 @@
+import os
+from pathlib import Path
+
+CACHE_DIR = Path.home() / ".geosp_laz_api"
+GRID_CACHE_PATH = CACHE_DIR / "articulacao_2020"
+SHP_FILE_NAME = "SIRGAS_SHP_quadriculamdt.shp" 
+
+GEOSAMPA_DOWNLOAD_URL = "https://download.geosampa.prefeitura.sp.gov.br/PaginasPublicas/downloadArquivo.aspx"
+
+GRID_MDT_PARAMS_STR = "orig=DownloadCamadas&arq=21_Articulacao%20de%20Imagens%5C%5CArticula%E7%E3o%20MDT%5C%5CShapefile%5C%5CSIRGAS_SHP_quadriculamdt&arqTipo=Shapefile"
+
+LAZ_DOWNLOAD_PARAMS = {
+    "orig": "DownloadMapaArticulacao",
+    "arq_prefix": "MDS_2020",
+    "arq_tipo": "MAPA_ARTICULACAO"
+}
+
+EPSG_SAO_PAULO = 31983

splaz-0.1.0/src/splaz/downloader.py

@@ -0,0 +1,105 @@
+import requests
+import zipfile
+import io
+import os
+from datetime import datetime
+from .entities import LidarQuadrante
+from .constants import (
+    GEOSAMPA_DOWNLOAD_URL,
+    LAZ_DOWNLOAD_PARAMS,
+    GRID_MDT_PARAMS_STR,
+    GRID_CACHE_PATH,
+)
+
+class SpLaz:
+    """
+    Cliente para acessar e baixar dados LIDAR do portal GeoSampa.
+    Gerencia o download e cache da grade de articulação, além dos quadrantes específicos.
+    """
+    def __init__(self):
+        self.session = requests.Session()
+        self.session.headers.update({
+            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+        })
+
+    def ensure_grid_data(self) -> str:
+        """Garante que a grade exista, baixando-a se necessário, e encontra o arquivo .shp."""
+        download_necessario = False
+        
+        shp_files = list(GRID_CACHE_PATH.rglob("*.shp"))
+        shp_path = shp_files[0] if shp_files else None
+
+        if not shp_path:
+            download_necessario = True
+        else:
+            try:
+                response = self.session.head(f"{GEOSAMPA_DOWNLOAD_URL}?{GRID_MDT_PARAMS_STR}")
+                if response.status_code == 200:
+                    server_last_modified = response.headers.get('Last-Modified')
+                    if server_last_modified:
+                        local_time = datetime.fromtimestamp(os.path.getmtime(shp_path))
+                        server_time = datetime.strptime(server_last_modified, '%a, %d %b %Y %H:%M:%S GMT')
+                        if server_time > local_time:
+                            download_necessario = True
+            except Exception as e:
+                print(f"Aviso: Não foi possível checar atualizações ({e}). Usando cache local.")
+
+        if download_necessario:
+            self._download_and_extract_grid()
+            
+            shp_files = list(GRID_CACHE_PATH.rglob("*.shp"))
+            if not shp_files:
+                raise FileNotFoundError("Nenhum arquivo .shp foi encontrado dentro do ZIP baixado.")
+            shp_path = shp_files[0]
+
+        return str(shp_path)
+    
+    def _download_and_extract_grid(self):
+        print("Baixando grade de articulação...")
+        response = self.session.get(GEOSAMPA_DOWNLOAD_URL, params=GRID_MDT_PARAMS_STR)
+        response.raise_for_status()
+
+        if not response.content.startswith(b'PK'):
+            conteudo_texto = response.text[:200]
+            raise ValueError(
+                f"O GeoSampa não retornou um arquivo ZIP. Verifique os parâmetros.\n"
+                f"Resposta do servidor: {conteudo_texto}"
+            )
+
+        os.makedirs(GRID_CACHE_PATH, exist_ok=True)
+        with zipfile.ZipFile(io.BytesIO(response.content)) as z:
+            z.extractall(GRID_CACHE_PATH)
+        print("Grade baixada e extraída com sucesso.")
+
+    def download_quadrante(self, codigo_quadra: str) -> LidarQuadrante:
+        """
+        Baixa um quadrante LIDAR específico do GeoSampa.
+
+        Args:
+            codigo_quadra (str): Código do quadrante a ser baixado.
+
+        Returns:
+            LidarQuadrante: Objeto contendo os dados do quadrante baixado.
+        """
+        params = {
+            "orig": LAZ_DOWNLOAD_PARAMS["orig"],
+            "arq": f"{LAZ_DOWNLOAD_PARAMS['arq_prefix']}\\{codigo_quadra}.zip",
+            "arqTipo": LAZ_DOWNLOAD_PARAMS["arq_tipo"]
+        }
+
+        response = self.session.get(GEOSAMPA_DOWNLOAD_URL, params=params)
+        response.raise_for_status()
+
+        return self._processar_zip(codigo_quadra, response.content)
+
+    def _processar_zip(self, codigo: str, conteudo_zip: bytes) -> LidarQuadrante:
+        try:
+            with zipfile.ZipFile(io.BytesIO(conteudo_zip)) as z:
+                nome_laz = z.namelist()[0]
+                dados_laz = z.read(nome_laz)
+                return LidarQuadrante(codigo, dados_laz, nome_laz)
+        except zipfile.BadZipFile:
+            raise ValueError(f"Conteudo baixado para o quadrante {codigo} invalido.")
+
+    def download_lista(self, codigos: list) -> list:
+        return [self.download_quadrante(c) for c in codigos]

splaz-0.1.0/src/splaz/entities.py

@@ -0,0 +1,50 @@
+import os
+import io
+
+class LidarQuadrante:
+    """
+    Representa um quadrante LiDAR (MDS 2020) de São Paulo.
+    Encapsula o conteúdo binário e metadados do arquivo .laz.
+    """
+    def __init__(self, codigo: str, conteudo_binario: bytes = None, nome_arquivo: str = None): 
+        self.codigo = codigo
+        self.conteudo_binario = conteudo_binario
+        self.nome_arquivo = nome_arquivo
+
+    @property
+    def esta_carregado(self) -> bool:
+        """Verifica se o conteúdo binário já está na memória."""
+        return self.conteudo_binario is not None
+
+    def save(self, pasta_destino: str) -> str:
+        """
+        Salva o conteúdo binário em disco.
+        Retorna o caminho completo do arquivo salvo.
+        """
+        if not self.esta_carregado:
+            raise ValueError(f"O quadrante {self.codigo} não possui dados em memória.")
+
+        os.makedirs(pasta_destino, exist_ok=True)
+        caminho_final = os.path.join(pasta_destino, self.nome_arquivo)
+
+        with open(caminho_final, 'wb') as f:
+            f.write(self.conteudo_binario)
+        
+        return caminho_final
+
+    def to_laspy(self):
+        """
+        Retorna um objeto laspy.read() diretamente do conteúdo em memória.
+        Requer a biblioteca 'laspy' instalada.
+        """
+        try:
+            import laspy
+            if self.esta_carregado:
+                return laspy.read(io.BytesIO(self.conteudo_binario))
+        except ImportError:
+            raise ImportError("A biblioteca 'laspy' é necessária para converter dados em memória.")
+        return None
+
+    def __repr__(self):
+        status = "Carregado" if self.esta_carregado else "Vazio"
+        return f"<LidarQuadrante {self.codigo} | {status}>"

splaz-0.1.0/src/splaz/geocoder.py

@@ -0,0 +1,90 @@
+import geopandas as gpd
+from geopy.geocoders import Nominatim
+from shapely.geometry import Point, box
+from .constants import EPSG_SAO_PAULO
+from .downloader import SpLaz
+
+class SpLazGeo:
+    """
+    Gerenciador de geocodificação para dados LIDAR do GeoSampa.
+    """
+    def __init__(self, client: SpLaz = None):
+        self.client = client or SpLaz()
+        self._grid = None
+        self.geolocator = Nominatim(user_agent="geosp_laz_api_vagas_verdes")
+    @property
+    def grid(self) -> gpd.GeoDataFrame:
+        """
+        Carrega e prepara o Shapefile de articulação automaticamente.
+        Mantém os dados no Ryzen 7 para buscas rápidas.
+        """
+        if self._grid is None:
+            
+            shp_path = self.client.ensure_grid_data()
+            
+            
+            gdf = gpd.read_file(shp_path)
+            
+            
+            if gdf.crs is None:
+                
+                gdf = gdf.set_crs(epsg=EPSG_SAO_PAULO)
+            elif gdf.crs.to_epsg() != EPSG_SAO_PAULO:
+                
+                gdf = gdf.to_crs(epsg=EPSG_SAO_PAULO)
+            
+            self._grid = gdf
+        return self._grid
+
+    def get_quadrant_by_coords(self, lat: float, lon: float) -> str:
+        """
+        Determina o quadrante LIDAR correspondente a coordenadas geográficas.
+        Args:
+            lat (float): Latitude em graus decimais.
+            lon (float): Longitude em graus decimais.
+        Returns:
+            str: Código do quadrante LIDAR correspondente.
+        """
+        ponto_gps = gpd.GeoSeries([Point(lon, lat)], crs="EPSG:4326")
+        ponto_sp = ponto_gps.to_crs(epsg=EPSG_SAO_PAULO).iloc[0]
+        resultado = self.grid[self.grid.contains(ponto_sp)]
+        if resultado.empty:
+            raise ValueError(f"Coordenadas ({lat}, {lon}) fora da cobertura de SP.")
+        return str(resultado.iloc[0]['qmdt_cod'])
+
+    def get_quadrant_by_address(self, address: str) -> str:
+        """
+        Determina o quadrante LIDAR correspondente a um endereço.
+        Args:
+            address (str): Endereço completo ou parcial em São Paulo.
+        Returns:
+            str: Código do quadrante LIDAR correspondente.
+        """
+        search_query = f"{address}, São Paulo, SP, Brazil"
+        location = self.geolocator.geocode(search_query)
+        if not location:
+            raise ValueError(f"Endereço não localizado: {address}")
+        return self.get_quadrant_by_coords(location.latitude, location.longitude)
+
+    def get_quadrants_by_neighborhood(self, neighborhood: str) -> list[str]:
+        """
+        Retorna uma lista de quadrantes LIDAR que intersectam um bairro específico.
+        Args:
+            neighborhood (str): Nome do bairro em São Paulo.
+        Returns:
+            list[str]: Lista de códigos de quadrantes LIDAR que intersectam o bairro.
+        """
+        query = f"{neighborhood}, São Paulo, SP, Brazil"
+        location = self.geolocator.geocode(query)
+        if not location:
+            raise ValueError(f"Bairro não encontrado: {neighborhood}")
+
+        bbox = location.raw['boundingbox']
+        lat_min, lat_max, lon_min, lon_max = float(bbox[0]), float(bbox[1]), float(bbox[2]), float(bbox[3])
+        
+        area_gps = gpd.GeoSeries([box(lon_min, lat_min, lon_max, lat_max)], crs="EPSG:4326")
+        area_sp = area_gps.to_crs(epsg=EPSG_SAO_PAULO).iloc[0]
+
+        intersecao = self.grid[self.grid.intersects(area_sp)]
+        
+        return intersecao['qmdt_cod'].unique().tolist()

splaz-0.1.0/src/splaz.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: splaz
+Version: 0.1.0
+Summary: API para facilitar o acesso a dados LiDAR do GeoSampa
+Author: João Braga
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: geopandas
+Requires-Dist: geopy
+Requires-Dist: shapely
+Requires-Dist: laspy
+Dynamic: license-file

splaz-0.1.0/src/splaz.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/splaz/__init__.py
+src/splaz/constants.py
+src/splaz/downloader.py
+src/splaz/entities.py
+src/splaz/geocoder.py
+src/splaz.egg-info/PKG-INFO
+src/splaz.egg-info/SOURCES.txt
+src/splaz.egg-info/dependency_links.txt
+src/splaz.egg-info/requires.txt
+src/splaz.egg-info/top_level.txt
+tests/test_downloader.py
+tests/test_end2end.py
+tests/test_entities.py
+tests/test_geocoder.py

splaz-0.1.0/src/splaz.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

splaz-0.1.0/src/splaz.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests
+geopandas
+geopy
+shapely
+laspy

splaz-0.1.0/src/splaz.egg-info/top_level.txt

@@ -0,0 +1 @@
+splaz

splaz-0.1.0/tests/test_downloader.py

@@ -0,0 +1,52 @@
+import pytest
+import requests_mock
+import io
+import zipfile
+import os
+from splaz.downloader import SpLaz
+from splaz.entities import LidarQuadrante
+from splaz.constants import GEOSAMPA_DOWNLOAD_URL
+
+
+@pytest.fixture
+def client():
+    return SpLaz()
+
+@pytest.fixture
+def fake_zip_content():
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf,"w") as z:
+        z.writestr("3316-153.laz", b"fake_laz_binary_content")
+    return buf.getvalue()
+
+def test_download_quadrante_sucesso(client, requests_mock, fake_zip_content):
+    requests_mock.get(GEOSAMPA_DOWNLOAD_URL, content=fake_zip_content, status_code = 200)
+
+    resultado = client.download_quadrante("3316-153")
+
+    assert isinstance(resultado,LidarQuadrante)
+    assert resultado.codigo == "3316-153"
+    assert resultado.esta_carregado is True
+    assert resultado.conteudo_binario == b"fake_laz_binary_content"
+
+
+def test_download_quadrante_erro_404(client,requests_mock):
+    requests_mock.get(GEOSAMPA_DOWNLOAD_URL, status_code = 404 )
+    import requests
+
+    with pytest.raises(requests.exceptions.HTTPError):
+        client.download_quadrante("codigo-inexistente")
+
+def test_processar_zip_invalido(client):
+    codigo = "test"
+    with pytest.raises(ValueError, match= f"Conteudo baixado para o quadrante {codigo} invalido."):
+        client._processar_zip(codigo, b"not_a_zip_file")
+
+def test_download_lista_chama_multiplos(client, requests_mock, fake_zip_content):
+    requests_mock.get(GEOSAMPA_DOWNLOAD_URL, content=fake_zip_content)
+    
+    codigos = ["1111-111", "2222-222"]
+    resultados = client.download_lista(codigos)
+
+    assert len(resultados) == 2
+    assert requests_mock.call_count == 2

splaz-0.1.0/tests/test_end2end.py

@@ -0,0 +1,34 @@
+import pytest
+from splaz import SpLazGeo, SpLaz
+
+def test_fluxo_completo_insper_vagas_verdes():
+    """
+    TESTE DE SISTEMA (E2E):
+    Valida se a biblioteca consegue converter um endereço real,
+    identificar o quadrante e baixar o arquivo binário sem erros.
+    """
+    # 1. Inicialização (Sem mocks!)
+    client = SpLaz()
+    geo = SpLazGeo(client=client)
+    
+    # Endereço real do Insper
+    endereco = "Avenida Santo Amaro, 1826"
+    
+    # 2. Execução do fluxo
+    # O Geocoder deve baixar a grade automaticamente no primeiro uso
+    codigo_quadrante = geo.get_quadrant_by_address(endereco)
+    
+    # 3. Verificação do Geocoding
+    # Sabemos que o Insper fica no quadrante 3316-153
+    assert codigo_quadrante == "3316-153"
+    
+    # 4. Download Real
+    # Baixamos apenas um para não sobrecarregar sua rede
+    quadrante_obj = client.download_quadrante(codigo_quadrante)
+    
+    # 5. Verificações Finais
+    assert quadrante_obj.esta_carregado is True
+    assert len(quadrante_obj.conteudo_binario) > 0
+    assert quadrante_obj.nome_arquivo.endswith(".laz")
+    
+    print(f"\n[E2E] Sucesso: Quadrante {codigo_quadrante} baixado com {len(quadrante_obj.conteudo_binario)} bytes.")

splaz-0.1.0/tests/test_entities.py

@@ -0,0 +1,37 @@
+import pytest
+import os
+from splaz.entities import LidarQuadrante
+
+def test_lidar_quadrante_inicializacao_vazia():
+    quad = LidarQuadrante("3316-153")
+    assert quad.codigo == "3316-153"
+    assert quad.esta_carregado is False
+    assert "Vazio" in repr(quad)
+
+def test_lidar_quadrante_inicializa_com_dados():
+    dados_falsos = b"LAZ_BINARY_DATA"
+    quad = LidarQuadrante(codigo="3316-153", conteudo_binario=dados_falsos, nome_arquivo="3316-153.laz")
+
+    assert quad.esta_carregado is True
+    assert quad.conteudo_binario == dados_falsos
+    assert "Carregado" in repr(quad)
+
+def test_save_com_sucesso(tmp_path):
+    d = tmp_path / "data_test"
+    d.mkdir()
+    nome_arq = "test_vagas_verdes.laz"
+    dados = b"01010101"
+
+    quad = LidarQuadrante("3316-153", dados, nome_arq)
+    caminho_salvo = quad.save(str(d))
+
+    assert os.path.exists(caminho_salvo)
+    with open(caminho_salvo, "rb") as f:
+        assert f.read() == dados
+
+def test_save_sem_dados_levanta_erro():
+    codigo = "3316-153" 
+    quad = LidarQuadrante(codigo)
+    with pytest.raises(ValueError, match=f"O quadrante {codigo} não possui dados em memória."):
+        quad.save("pasta_qualquer")
+

splaz-0.1.0/tests/test_geocoder.py

@@ -0,0 +1,73 @@
+import pytest
+import geopandas as gpd
+import pandas as pd
+from shapely.geometry import Point, Polygon, box
+from unittest.mock import MagicMock, patch
+from splaz.geocoder import SpLazGeo
+
+
+@pytest.fixture
+def mock_client():
+    client = MagicMock()
+    client.ensure_grid_data.return_value = "caminho/falso/grade.shp"
+    return  client
+
+@pytest.fixture
+def mock_grid_gdf():
+    """Cria um GeoDataFrame minúsculo para simular a grade de SP."""
+    # Quadrado simples representando um quadrante fictício
+    poly = Polygon([(0, 0), (1000, 0), (1000, 1000), (0, 1000)])
+    gdf = gpd.GeoDataFrame(
+        {'qmdt_cod': ['3316-153'], 'geometry': [poly]},
+        crs="EPSG:31983"
+    )
+    return gdf
+
+
+def test_get_quadrant_by_coords_sucesso(mock_client, mock_grid_gdf):
+    with patch("geopandas.read_file", return_value = mock_grid_gdf):
+        geo = SpLazGeo(client=mock_client)
+
+        with patch.object(gpd.GeoSeries, "to_crs") as mock_to_crs:
+            mock_to_crs.return_value = gpd.GeoSeries([Point(500,500)])
+
+            codigo = geo.get_quadrant_by_coords(-23.5,-46.6)
+            assert codigo == '3316-153'
+
+def test_get_quadrant_by_address_sucesso(mock_client, mock_grid_gdf):
+    with patch("geopandas.read_file", return_value=mock_grid_gdf):
+        geo = SpLazGeo(client=mock_client)
+        
+        # Mock do retorno do Nominatim (Geopy)
+        mock_location = MagicMock()
+        mock_location.latitude = -23.59
+        mock_location.longitude = -46.67
+        
+        with patch.object(geo.geolocator, "geocode", return_value=mock_location):
+            with patch.object(geo, "get_quadrant_by_coords", return_value="3316-153"):
+                codigo = geo.get_quadrant_by_address("Rua Quatá, 300")
+                assert codigo == "3316-153"
+
+def test_get_quadrants_by_neighborhood_bbox(mock_client,mock_grid_gdf):
+    with patch("geopandas.read_file", return_value=mock_grid_gdf):
+        geo = SpLazGeo(client=mock_client)
+        
+        # 1. Simula o retorno do Nominatim (Bairro real)
+        mock_location = MagicMock()
+        mock_location.raw = {
+            'boundingbox': ['-23.6', '-23.5', '-46.7', '-46.6']
+        }
+        
+        with patch.object(geo.geolocator, "geocode", return_value=mock_location):
+            # 2. Mockamos a conversão de coordenadas para que a área resultante
+            # coincida com o nosso quadrante de teste (0 a 1000)
+            with patch.object(gpd.GeoSeries, "to_crs") as mock_to_crs:
+                # Criamos um polígono que sobrepõe o nosso mock_grid_gdf (0,0 a 1000,1000)
+                overlap_box = box(100, 100, 500, 500)
+                mock_to_crs.return_value = gpd.GeoSeries([overlap_box])
+                
+                quadrantes = geo.get_quadrants_by_neighborhood("Vila Olímpia")
+                
+                # Agora deve funcionar, pois as geometrias se interceptam!
+                assert isinstance(quadrantes, list)
+                assert "3316-153" in quadrantes