## Установка

Установите пакет с опцией `[cli]` при помощи удобного для вас пакетного менеджера:
=== "uv (рекомендуется)"
    ``` shell
    $ uv tool install pynspd[cli]
    ```

=== "pipx"

    ``` shell
    $ pipx install pynspd[cli]
    ```

=== "pip"
    ``` shell
    $ python -m pip install pynspd[cli]
    ```

Проверьте корректность установки:
``` shell
$ pynspd -v
1.0.0
```
!!! tip 
    Если команда `pynspd` не найдена - перезапустите консоль

## Использование

При вводе команды без аргументов вам всегда будет доступна подсказка по опциям, аргументам и командам:
``` shell
$ pynspd
                                                                                                                                                                                     
 Usage: pynspd [OPTIONS] COMMAND [ARGS]...        

 Утилита командной строки для поиска на НСПД                                                                                                                                   
                                                                                                                                                                                     
╭─ Options ────────────────────────────────────────────────────────────────────────╮
│ --version             -v        Show current version                       │
│ --install-completion            Install completion for the current shell.  │
│ --show-completion               Show completion for the current shell,     │
│                                 to copy it or customize the installation.  │
│ --help                          Show this message and exit.                │
╰───────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────╮
│ geo    Поиск объектов по геоданным                                         │
│ find   Поиск объектов по списку к/н                                        │
╰───────────────────────────────────────────────────────────────────────────────────╯

```

Как видно по подсказке, доступны два варианта поиска - по текстовому списку к/н или по геоданным.


### `pynspd find`

``` shell
$ pynspd find
                                                                                                                                                                                     
Usage: pynspd find [OPTIONS] INPUT                                                                                                                                                  

Поиск объектов по списку к/н

╭─ Arguments ────────────────────────────────────────────────────────────────────────╮
│ *    input      TEXT  Список искомых к/н. Может быть текстовым файлом        │
╰─────────────────────────────────────────────────────────────────────────────────────╯
```

В качестве аргумента `input` принимается:

- Текстовый список к/н. Номеров может быть несколько (тогда их нужно заключить в кавычки);
``` shell
$ pynspd find "77:07:0006001:9 77:07:0006001:1512"
```

- Текстовый файл `.txt`, в котором хранится перечень к/н.
``` shell
$ pynspd find my_list.txt
```


### `pynspd geo`

``` shell
$ pynspd geo
                                                                                                                                                                                     
 Usage: pynspd geo [OPTIONS] INPUT [LAYER_NAME]                                                                                                                                      

 Поиск объектов по геоданным

╭─ Arguments ────────────────────────────────────────────────────────────────────────╮
│ *    input           TEXT          Путь к файлу с геоданными или WKT         │
│      layer_name      [LAYER_NAME]  Имя слоя с НСПД,                          │
│                                    в котором нужно производить поиск         │
│                                    [default: Земельные участки из ЕГРН]      │
╰─────────────────────────────────────────────────────────────────────────────────────╯
```

В качестве аргумента `input` принимается:

- Файл с геоданными (например `.geojson`). В данном файле может быть несколько объектов, но все они должны быть:
    - одного из поддерживаемого типов (`Point`, `Polygon`, `MultiPolygon`)
    - все объекты - одного типа (например, только точки);
``` shell
$ pynspd geo my_geo.geojson
```

- Строка геоданных формата [WKT](https://ru.wikipedia.org/wiki/WKT). 
Требования к геометрии аналогичны предыдущему варианту
``` shell
$ pynspd geo "Point (37.562 55.605)"
```

!!! tip "Для пользователей QGIS"
    В QGIS WKT-представление геометрии можно быстро получить при помощи, например, [этого плагина](https://github.com/skeenp/QGIS3-getWKT)

В качестве аргумента `layer_name` принимается точное имя слоя с НСПД - именно в нем и будет производиться поиск.
По умолчанию, это слой с земельными участками.


### Опции

Для обоих методов есть одинаковый перечень опциональных параметров, которые указываются в подсказке:

**`-o, --output`**

> Сохранить результат поиска в указанных файл. По умолчанию выводит результат поиска в терминал.

> Можно сохранить в формате табличных данных (файлы `.xlsx`, `.csv`), либо в формате геоданных (форматы `.gpkg`, `.geojson` и др.)


**`-c, --cache`**

> Сохранять кэш запросов для последующего переиспользования. По умолчанию отключено.

> Рекомендуется использовать при больших запросах, когда есть вероятность сброса соединения от НСПД и вынужденной повторной обработке.

> Кэш будет сохраняться в папке `.cache` (при варианте `file`) или в файле `.hishel.sqlite` (при варианте `sqlite`).


**`-l, --localize`**

> Использовать названия колонок, взятые со страницы НСПД, а не оригинальные названия. Например, `cad_num` -> `Кадастровый номер`.

> Из-за того, что не все колонки отображаются на сайте, часть данных будет утеряна.

> Если флаг не указан, то используются оригинальные названия.


**`--tab-objects`**

> При использовании этого флага полученные данные обогащаются данными со вкладки "Объекты"