PyNSPD

https://github.com/yazmolod/pynspd
Admin
PyNSPD - это Python-библиотека, предназначенная для взаимодействия с государственным порталом...
Tokens:7,027
Snippets:67
Trust Score:5.1
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Clone Repository and Install Dependencies

Source: https://github.com/yazmolod/pynspd/blob/main/docs/contributing.md

Clone the pynspd repository and install project dependencies using the 'task install' command. Ensure you have forked the repository first.

```bash
git clone https://github.com/YOUR-USERNAME/pynspd
cd pynspd
task install
```

--------------------------------

### Asynchronous GeoJSON Fetching with AsyncNspd

Source: https://github.com/yazmolod/pynspd/blob/main/docs/advanced/client.md

This example demonstrates how to use the AsyncNspd client to find data based on user input and save the result as a GeoJSON file. It requires the `asyncio` and `aiofiles` libraries. Ensure you are running this in an environment that supports asynchronous operations.

```python
# Стандартная библиотека для работы с `async` функциями 
import asyncio
# Сторонняя библиотека - асинхронной аналог `open` для работы с файлами
import aiofiles
from pynspd import AsyncNspd


async def main():
    async with AsyncNspd() as nspd:
        q = input("Введите к/н: ")
        feat = await nspd.find(q)
        if feat is None:
            print("Ничего не найдено!")
            return
        async with aiofiles.open(f"{q.replace(':', '-')}.geojson", "w") as file:
            await file.write(feat.model_dump_json())


if __name__ == "__main__":
    # Запуск функции в event-loop
    asyncio.run(main())

```

--------------------------------

### Access Feature Properties

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Retrieve and inspect the properties of a feature. The properties are Pydantic models, and `.model_dump()` can be used to convert them to a dictionary. This example shows how to get the keys of the main properties.

```python
feat = nspd.search_in_layer(
    '63:01:0810003:510',
    NspdFeature.by_title("Земельные участки из ЕГРН")
)

print(feat.properties.model_dump().keys())
```

--------------------------------

### Get Specific Tab Data

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Retrieve data from a specific tab of an object by calling the `nspd.get_tab_data` method. This method requires the object itself and the name of the tab from which to fetch data.

```APIDOC
## nspd.get_tab_data(feat, tab_name)

### Description
Retrieves data from a specified tab of an object.

### Parameters
- **feat** (object) - Required - The object from which to retrieve tab data.
- **tab_name** (string) - Required - The name of the tab to retrieve data from. IDEs will provide hints for available tab names.

### Request Example
```python
# Assuming 'obj' is a previously obtained object
# and 'tab_name' is the name of the desired tab

tab_data = nspd.get_tab_data(obj, tab_name)
```

### Response
- **tab_data** (any) - The data retrieved from the specified tab.
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/yazmolod/pynspd/blob/main/docs/contributing.md

Build and serve the project's documentation locally using the 'task docs' command. This allows you to preview documentation changes before committing.

```bash
task docs
```

--------------------------------

### Initialize Nspd Client with Context Manager

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Use the `with` statement for automatic session management. This ensures all connections are properly closed upon exiting the block.

```python
from pynspd import Nspd

with Nspd() as nspd:
    # Ваш код здесь...
```

--------------------------------

### Initialize Nspd Client Manually

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Create an Nspd client instance and manually close the session using a `try...finally` block. This method requires explicit cleanup to prevent resource leaks.

```python
from pynspd import Nspd

nspd = Nspd()

try:
    # Ваш код здесь...
finally:
    nspd.close()
```

--------------------------------

### Run Linter and Formatter

Source: https://github.com/yazmolod/pynspd/blob/main/docs/contributing.md

Apply linting and code formatting to the project using the 'task lint' command. This helps maintain code quality and consistency.

```bash
task lint
```

--------------------------------

### Run Tests

Source: https://github.com/yazmolod/pynspd/blob/main/docs/contributing.md

Execute all project tests using the 'task tests' command. This ensures that code changes do not introduce regressions.

```bash
task tests
```

--------------------------------

### Search Objects by Query

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Use `search` for broader queries, such as by address, when `find` methods are too restrictive. This returns a list of matching features.

```python
feats = nspd.search('Москва Новочерёмушкинская улица 24 корпус 1')
print(feats)
#> [ NspdFeature<Здания: 77:06:0004001:1042>,
#>  NspdFeature<Помещения: 77:06:0002011:1040>,
#>  NspdFeature<Помещения: 77:06:0002013:1204>,, ...]
```

--------------------------------

### Search Objects at a Point

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Find objects located at a specific geographic point using `search_at_point`. You can also use `search_at_coords` with latitude and longitude.

```python
from shapely import Point

layer_def = NspdFeature.by_title("Земельные участки из ЕГРН")
feats = nspd.search_at_point(Point(37.546440653, 55.787139958), layer_def)

print(feats[0].properties.options.cad_num)
#> "77:09:0005008:11446"
```

--------------------------------

### Direct Tab Data Retrieval Methods

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Convenience methods are available to directly retrieve data from common tabs without needing to specify the tab name explicitly.

```APIDOC
## Direct Tab Data Retrieval Methods

### Description
These methods allow direct access to data from specific, commonly used tabs.

### Available Methods
- **nspd.tab_land_parts(...)**: Retrieves data for Land Parcels (ЗУ).
- **nspd.tab_land_links(...)**: Retrieves data for Linked Land Parcels.
- **nspd.tab_permission_type(...)**: Retrieves data for Permitted Use Types.
- **nspd.tab_composition_land(...)**: Retrieves data for the Composition of Land.
- **nspd.tab_build_parts(...)**: Retrieves data for Building Parts (ОКС).
- **nspd.tab_objects_list(...)**: Retrieves a list of objects.

### Usage Example
```python
# Example for retrieving land parts data
land_parts_data = nspd.tab_land_parts()

# Example for retrieving building parts data
building_parts_data = nspd.tab_build_parts()
```

### Parameters
These methods typically do not require explicit parameters when called directly, as they operate on a contextually available object or default settings. Refer to specific method documentation for details if parameters are needed.
```

--------------------------------

### Search Objects in Layer by Query

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Refine your search by specifying a layer when using the `search` method. This helps narrow down results to a particular object type.

```python
feats = nspd.search_in_layer(
    'Москва Новочерёмушкинская улица 24 корпус 1',
    NspdFeature.by_title("Здания")
)
print(feats)
#> [NspdFeature<Здания: 77:06:0004001:1042>]
```

--------------------------------

### Find Object by Type

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Use `find` to retrieve a single object by its ID and type. This method ensures only one result is returned, performing additional checks to guarantee accuracy.

```python
from pynspd import ThemeId

feat = nspd.find("77:05:0001005:19", ThemeId.REAL_ESTATE_OBJECTS)
print(feat.properties.options.land_record_type)
#> Земельный участок
```

--------------------------------

### Search Objects in Multiple Layers by Query

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Perform a search across multiple specified layers simultaneously. This is useful when an object might belong to different categories.

```python
feats = nspd.search_in_layers(
    'Обнинск',
    NspdFeature.by_title("Муниципальные образования (полигональный)"),
    NspdFeature.by_title("Населённые пункты (полигоны)")
)
print(feats)
#> [NspdFeature<Муниципальные образования (полигональный)>, NspdFeature<Населённые пункты (полигоны)>]
```

--------------------------------

### Generate Synchronous Code

Source: https://github.com/yazmolod/pynspd/blob/main/docs/contributing.md

Use the 'task unasync' command to automatically generate synchronous API code from asynchronous code. This command is part of the project's development workflow.

```bash
task unasync
```

--------------------------------

### Search by address in a specific layer

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Searches for objects matching an address string within a specified layer. This allows for more targeted searches when the object type is known.

```APIDOC
## Search by address in a specific layer

### Description
Searches for objects matching an address string within a specified layer. This allows for more targeted searches when the object type is known.

### Method
`search_in_layer(address: str, layer_definition: NspdFeature.LayerDefinition)`

### Parameters
#### Path Parameters
- **address** (str) - Required - The address string to search for.
- **layer_definition** (NspdFeature.LayerDefinition) - Required - The definition of the layer to search within.

### Request Example
```python
feats = nspd.search_in_layer(
    'Москва Новочерёмушкинская улица 24 корпус 1',
    NspdFeature.by_title("Здания")
)
print(feats)
```

### Response
Returns a list of `NspdFeature` objects from the specified layer matching the address.
```

--------------------------------

### Search by address

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Performs a general search for objects based on an address string. This method returns a list of features that match the address, similar to a direct NSPD search.

```APIDOC
## Search by address

### Description
Performs a general search for objects based on an address string. This method returns a list of features that match the address, similar to a direct NSPD search.

### Method
`search(address: str)`

### Parameters
#### Path Parameters
- **address** (str) - Required - The address string to search for.

### Request Example
```python
feats = nspd.search('Москва Новочерёмушкинская улица 24 корпус 1')
print(feats)
```

### Response
Returns a list of `NspdFeature` objects matching the address.
```

--------------------------------

### Search by address in multiple layers

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Searches for objects matching an address string across multiple specified layers. This is useful for finding related objects in different datasets.

```APIDOC
## Search by address in multiple layers

### Description
Searches for objects matching an address string across multiple specified layers. This is useful for finding related objects in different datasets.

### Method
`search_in_layers(address: str, *layer_definitions: NspdFeature.LayerDefinition)`

### Parameters
#### Path Parameters
- **address** (str) - Required - The address string to search for.
- **layer_definitions** (NspdFeature.LayerDefinition) - Required - A variable number of layer definitions to search within.

### Request Example
```python
feats = nspd.search_in_layers(
    'Обнинск',
    NspdFeature.by_title("Муниципальные образования (полигональный)"),
    NspdFeature.by_title("Населённые пункты (полигоны)")
)
print(feats)
```

### Response
Returns a list of `NspdFeature` objects from all specified layers matching the address.
```

--------------------------------

### Search at specific coordinates

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Finds objects located at given latitude and longitude coordinates. This is an alternative to `search_at_point` if you prefer not to use Shapely Point objects.

```APIDOC
## Search at specific coordinates

### Description
Finds objects located at given latitude and longitude coordinates. This is an alternative to `search_at_point` if you prefer not to use Shapely Point objects.

### Method
`search_at_coords(lat: float, lng: float, layer_definition: NspdFeature.LayerDefinition)`

### Parameters
#### Path Parameters
- **lat** (float) - Required - The latitude of the location.
- **lng** (float) - Required - The longitude of the location.
- **layer_definition** (NspdFeature.LayerDefinition) - Required - The definition of the layer to search within.

### Request Example
```python
layer_def = NspdFeature.by_title("Земельные участки из ЕГРН")
feats = nspd.search_at_coords(55.787139958, 37.546440653, layer_def)

print(feats[0].properties.options.cad_num)
```

### Response
Returns a list of `NspdFeature` objects found at the specified coordinates.
```

--------------------------------

### Access Human-Readable Feature Options

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Retrieve feature options with human-readable keys, such as 'Кадастровый номер' instead of 'cad_num'. This uses the `.cast()` method followed by `.options.model_dump_human_readable()`.

```python
print(feat.properties.cast().options.model_dump_human_readable().keys())
```

--------------------------------

### Search at a specific point

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Finds objects that are located at a given geographic point. This method is useful for identifying features at a precise location.

```APIDOC
## Search at a specific point

### Description
Finds objects that are located at a given geographic point. This method is useful for identifying features at a precise location.

### Method
`search_at_point(point: Point, layer_definition: NspdFeature.LayerDefinition)`

### Parameters
#### Path Parameters
- **point** (Point) - Required - A `shapely.geometry.Point` object representing the location.
- **layer_definition** (NspdFeature.LayerDefinition) - Required - The definition of the layer to search within.

### Request Example
```python
from shapely import Point

layer_def = NspdFeature.by_title("Земельные участки из ЕГРН")
feats = nspd.search_at_point(Point(37.546440653, 55.787139958), layer_def)

print(feats[0].properties.options.cad_num)
```

### Response
Returns a list of `NspdFeature` objects found at the specified point.
```

--------------------------------

### Find object by ID

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Finds a single feature by its unique identifier and theme. This method ensures that exactly one result matches the query.

```APIDOC
## Find object by ID

### Description
Finds a single feature by its unique identifier and theme. This method ensures that exactly one result matches the query.

### Method
`find(id: str, theme_id: ThemeId)`

### Parameters
#### Path Parameters
- **id** (str) - Required - The unique identifier of the object.
- **theme_id** (ThemeId) - Required - The theme or type of the object to search for.

### Request Example
```python
from pynspd import ThemeId

feat = nspd.find("77:05:0001005:19", ThemeId.REAL_ESTATE_OBJECTS)
print(feat.properties.options.land_record_type)
```

### Response
Returns a single `NspdFeature` object if found, otherwise raises an error.
```

--------------------------------

### Convert Geometry to Shapely Multi-Shape

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Convert a feature's geometry to a Shapely multi-shape object, useful for database storage like PostGIS. This method will fail if the feature lacks boundary coordinates.

```python
feat.geometry.to_multi_shape()
```

--------------------------------

### Access Nested Feature Options

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Access nested options within a feature's properties, which contain specific details about the object. The `.model_dump()` method is used here to view the keys of these options.

```python
print(feat.properties.options.model_dump().keys())
```

--------------------------------

### Search Objects in a Contour

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Retrieve objects within a specified polygonal area using `search_in_contour`. Be aware of potential `TooBigContour` errors for large areas.

```python
from shapely import from_wkt

contour = from_wkt(
    "Polygon ((37.62381 55.75345, 37.62577 55.75390, 37.62448 55.75278, 37.62381 55.75345))"
)

feats = nspd.search_in_contour(
    contour,
    NspdFeature.by_title("Земельные участки из ЕГРН"),
)
cns = [i.properties.options.cad_num for i in feats]
print(cns)
#> ["77:01:0001011:8", "77:01:0001011:14", "77:01:0001011:16"]
```

--------------------------------

### Iterative Search in Contour

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Use `search_in_contour_iter` to efficiently search within large contours by processing results iteratively, avoiding `TooBigContour` errors.

```python
for i in nspd.search_in_contour_iter(
    contour,
    NspdFeature.by_title("Земельные участки из ЕГРН"),
    only_intersects=True, # по умолчанию метод ищет все объекты 
                          # в bounding box контура для экономии ресурсов
):
    print(i.properties.options.cad_num)
```

--------------------------------

### Iterative search within a contour

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

An iterative version of `search_in_contour` that handles large contours by yielding results one by one, avoiding `TooBigContour` errors. It optimizes by default by searching within the bounding box of the contour.

```APIDOC
## Iterative search within a contour

### Description
An iterative version of `search_in_contour` that handles large contours by yielding results one by one, avoiding `TooBigContour` errors. It optimizes by default by searching within the bounding box of the contour.

### Method
`search_in_contour_iter(contour: Polygon, layer_definition: NspdFeature.LayerDefinition, only_intersects: bool = True)`

### Parameters
#### Path Parameters
- **contour** (Polygon) - Required - A `shapely.geometry.Polygon` object representing the search area.
- **layer_definition** (NspdFeature.LayerDefinition) - Required - The definition of the layer to search within.
- **only_intersects** (bool) - Optional - Defaults to `True`. If `True`, searches within the bounding box of the contour for efficiency. If `False`, searches the entire contour.

### Request Example
```python
from shapely import from_wkt

contour = from_wkt(
    "Polygon ((37.62381 55.75345, 37.62577 55.75390, 37.62448 55.75278, 37.62381 55.75345))"
)

for i in nspd.search_in_contour_iter(
    contour,
    NspdFeature.by_title("Земельные участки из ЕГРН"),
    only_intersects=True
):
    print(i.properties.options.cad_num)
```

### Response
Yields `NspdFeature` objects found within the specified contour, one at a time.
```

--------------------------------

### Find object in layer by ID

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Finds a feature within a specific layer using its identifier. This method is useful when you know the object's ID and the layer it belongs to.

```APIDOC
## Find object in layer by ID

### Description
Finds a feature within a specific layer using its identifier. This method is useful when you know the object's ID and the layer it belongs to.

### Method
`find_in_layer(id: str, layer_definition: NspdFeature.LayerDefinition)`

### Parameters
#### Path Parameters
- **id** (str) - Required - The unique identifier of the object.
- **layer_definition** (NspdFeature.LayerDefinition) - Required - The definition of the layer to search within.

### Request Example
```python
feat = nspd.find_in_layer(
    "77:06:0002007:1014", 
    NspdFeature.by_title("Здания")
)
print(feat.properties.options.floors)
```

### Response
Returns a single `NspdFeature` object from the specified layer.
```

--------------------------------

### Convert Geometry to Shapely Shape

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Convert a feature's geometry to a Shapely shape object for geometric operations. Ensure the geometry is in EPSG:4326.

```python
feat.geometry.to_shape()
```

--------------------------------

### Find Object in Layer

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Use `find_in_layer` to search for an object within a specific layer, identified by its title. This method returns a statically typed answer, allowing for easier field access.

```python
feat = nspd.find_in_layer(
    "77:06:0002007:1014", 
    NspdFeature.by_title("Здания")
)
print(feat.properties.options.floors)
#> 5
```

--------------------------------

### Search within a contour

Source: https://github.com/yazmolod/pynspd/blob/main/docs/userguide.md

Finds objects that are located within a specified geographic contour (polygon). This method is suitable for area-based searches.

```APIDOC
## Search within a contour

### Description
Finds objects that are located within a specified geographic contour (polygon). This method is suitable for area-based searches.

### Method
`search_in_contour(contour: Polygon, layer_definition: NspdFeature.LayerDefinition)`

### Parameters
#### Path Parameters
- **contour** (Polygon) - Required - A `shapely.geometry.Polygon` object representing the search area.
- **layer_definition** (NspdFeature.LayerDefinition) - Required - The definition of the layer to search within.

### Request Example
```python
from shapely import from_wkt

contour = from_wkt(
    "Polygon ((37.62381 55.75345, 37.62577 55.75390, 37.62448 55.75278, 37.62381 55.75345))"
)

feats = nspd.search_in_contour(
    contour,
    NspdFeature.by_title("Земельные участки из ЕГРН"),
)
cns = [i.properties.options.cad_num for i in feats]
print(cns)
```

### Response
Returns a list of `NspdFeature` objects found within the specified contour. Note: This method returns results as-is from NSPD and may error on very large contours (`TooBigContour`).
```
Tokens:
Raw