Metadata-Version: 2.4
Name: buscador_propiedad_vertical
Version: 0.1.0
Summary: Detecta edificios en régimen de propiedad vertical a partir de datos abiertos del Catastro español (formato CAT + shapefile).
Author-email: Miguel González <migueljgonz@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://codeberg.org/mig42/BuscadorPropiedadVertical
Project-URL: Repository, https://codeberg.org/mig42/BuscadorPropiedadVertical
Project-URL: Issues, https://codeberg.org/mig42/BuscadorPropiedadVertical/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: matplotlib
Requires-Dist: contextily
Requires-Dist: pytest
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: bandit; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# Buscador de Propiedad Vertical en el Catastro español

Herramienta de línea de comandos que identifica edificios de viviendas en régimen de **propiedad vertical** a partir de los datos abiertos del **Catastro español** (fichero alfanumérico `.CAT` + shapefile de parcelas).

## ¿Qué es la propiedad vertical?

En una finca de propiedad vertical el edificio pertenece a un único titular: los distintos pisos **no tienen referencia catastral individualizada**. En el fichero CAT esto se traduce en que la parcela tiene un **único registro de inmueble (tipo 15)** de uso residencial, a diferencia de una comunidad de propietarios normal, donde existe un registro tipo 15 por cada piso o local.

## Fuentes de datos

Los datos se descargan gratuitamente (con Cl@ve o certificado digital) desde:

- **Fichero alfanumérico `.CAT`** — [Sede Electrónica del Catastro](https://www.sedecatastro.gob.es/Accesos/SECAccDescargaDatos.aspx) → "Descarga de información alfanumérica por provincia (formato CAT)"
- **Cartografía vectorial (shapefile)** — misma página → "Descarga de cartografía vectorial por provincia (formato Shapefile)" → capa `PARCELA.shp`

## Instalación

### Opción recomendada: `pipx`

[`pipx`](https://pipx.pypa.io) instala herramientas de línea de comandos en entornos aislados, sin contaminar el Python del sistema:

```bash
pipx install buscador-propiedad-vertical
```

### Con `pip`

```bash
pip install buscador-propiedad-vertical
```

> **Windows / macOS:** las dependencias geoespaciales (`geopandas`, `shapely`) pueden fallar al instalarse con pip en estas plataformas. Si ocurre, instálalas primero con conda/mamba y luego el paquete con pip:
>
> ```bash
> conda install -c conda-forge geopandas shapely contextily
> pip install buscador-propiedad-vertical
> ```

### Desde el repositorio (sin publicar)

```bash
pip install git+https://codeberg.org/mig42/BuscadorPropiedadVertical.git
```

## Uso

```bash
buscador_propiedad_vertical \
    --cat  datos/47_166_U_20240101.cat \
    --shp  datos/shp/PARCELA.shp \
    --salida resultados/
```

### Opciones

| Opción         | Descripción                                                                     | Valor por defecto |
| -------------- | ------------------------------------------------------------------------------- | ----------------- |
| `--cat`        | Ruta al fichero `.CAT` de Catastro (obligatorio)                                | —                 |
| `--shp`        | Ruta al shapefile `PARCELA.shp` (opcional; sin él no se genera mapa ni GeoJSON) | `None`            |
| `--salida`     | Directorio de salida (se crea si no existe)                                     | `resultados/`     |
| `--sup-minima` | Superficie construida mínima en m² para considerar un edificio                  | `100`             |
| `--zoom-mapa`  | Nivel de zoom del mapa base (1–19). 14 = barrio, 12 = ciudad, 10 = provincia    | automático        |

### Salidas generadas

| Fichero                                 | Descripción                                                              |
| --------------------------------------- | ------------------------------------------------------------------------ |
| `candidatos_propiedad_vertical.csv`     | Tabla con todos los candidatos (RC, dirección, superficies, coordenadas) |
| `candidatos_propiedad_vertical.geojson` | Geometría de parcelas para QGIS / uMap (requiere `--shp`)                |
| `mapa_propiedad_vertical.png`           | Mapa de situación rápido (requiere `--shp`)                              |

## Dependencias

```text
pandas
geopandas
shapely
matplotlib
contextily
```

Instálalas con `pip install -r requirements.txt`.

## Documentación

- [Lógica de procesado](docs/logica-procesado.md) — explica el pipeline completo y los criterios de detección en lenguaje no técnico.

## Testing

```bash
pytest          # ejecuta todos los tests
pytest -s       # muestra la salida estándar
pytest -k _01   # ejecuta solo tests cuyo nombre contiene "_01"
```

## Desarrollo local

Instala el paquete junto con las herramientas de desarrollo (`ruff`, `bandit`, `mypy`, `pytest`, `pytest-cov`):

```bash
make install
```

Los targets disponibles en el `Makefile` son:

| Target       | Qué hace                                                                  |
| ------------ | ------------------------------------------------------------------------- |
| `install`    | `pip install -e ".[dev]"` — instala el paquete en modo editable           |
| `lint`       | Comprueba el estilo del código con **ruff**                               |
| `lint-fix`   | Aplica las correcciones automáticas de ruff                               |
| `security`   | Análisis estático de seguridad con **bandit**                             |
| `mypy`       | Comprueba las anotaciones de tipos con **mypy**                           |
| `test`       | Ejecuta los tests con **pytest**                                          |
| `coverage`   | Ejecuta los tests y muestra el informe de cobertura                       |
| `build`      | Genera los artefactos de distribución (`dist/*.whl` y `.tar.gz`)          |
| `publish`    | Publica en PyPI (requiere `PYPI_TOKEN` en el entorno)                     |
| `check`      | Lanza `security + lint + mypy + test` en orden (igual que el pipeline CI) |

El pipeline de integración continua sigue la misma secuencia:
`security` → `lint + mypy + pyright` (en paralelo) → `test`

## Nota sobre el desarrollo

Este proyecto ha sido implementado con la asistencia de modelos de lenguaje (LLMs), bajo instrucción y supervisión de un ser humano. Todo el código ha sido revisado, validado y dirigido por el autor.
