PyDriOSM

https://pydriosm.readthedocs.io/en/latest/
Admin
PyDriOSM is an open-source Python package that simplifies the acquisition, parsing, and management...
Tokens:83,432
Snippets:432
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Setup and Initialization

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.GeofabrikDownloader.download_data.html

Initial imports required for using the GeofabrikDownloader and managing directories.

```python
from pydriosm.downloader import GeofabrikDownloader
from pyhelpers.dirs import delete_dir
import os
```

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

### Initialize PostgresOSM

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.import_osm_pbf.html

Setup the PostgresOSM instance to connect to the target database.

```python
from pydriosm.ios import PostgresOSM
from pyhelpers.dirs import cd, delete_dir
from pyhelpers.store import load_pickle
osmdb = PostgresOSM(database_name='osmdb_test', verbose=True)
```

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

### Initialize PostgresOSM

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.drop_subregion_tables.html

Setup the PostgresOSM instance to connect to a specific database.

```python
from pydriosm.ios import PostgresOSM
from pyhelpers.dirs import delete_dir

osmdb = PostgresOSM(database_name='osmdb_test', verbose=True)
```

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

### Format confirmation prompt examples

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.format_confirmation_prompt.html

Demonstrates generating confirmation messages for default and update scenarios.

```python
>>> from pydriosm.downloader._base import BaseDownloader
>>> BaseDownloader.format_confirmation_prompt()
'Proceed to retrieve/compile data of <data_name>\n?'
>>> BaseDownloader.format_confirmation_prompt(update=True)
'Proceed to update the data of <data_name>\n?'
```

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

### Initialize PostgresOSM and define test variables

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.import_osm_data.html

Setup the database connection and define the subregion and data directory paths.

```python
from pydriosm.ios._base import BaseIOS
from pyhelpers.dirs import delete_dir

osmdb = BaseIOS(database_name='osmdb_test', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "osmdb_test" ... Done.
Connecting postgres:***@localhost:5432/osmdb_test ... Successfully.

subrgn_name = 'Rutland'  # name of a subregion
dat_dir = "tests/osm_data"  # name of a data directory where the subregion data is
```

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

### Initialize BBBikeReader

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.reader.BBBikeReader.merge_shp_layers.html

Setup the BBBikeReader instance and necessary imports before performing operations.

```python
from pydriosm.reader import BBBikeReader
from pyhelpers.dirs import cd, delete_dir
import os

bbr = BBBikeReader()
```

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

### Setup and Data Preparation for null_text_to_empty_string

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.null_text_to_empty_string.html

Initializes a PostgreSQL connection, creates a test table with null values, and verifies the data state.

```python
from pyhelpers.dbms import PostgreSQL
from pyhelpers._cache import example_dataframe
testdb = PostgreSQL(database_name='testdb', verbose=True)
dat = example_dataframe()
dat['Longitude'] = dat['Longitude'].astype(str)
dat.loc['London', 'Longitude'] = None
dat
tbl_name = 'test_table'
testdb.import_data(data=dat, table_name=tbl_name, index=True, verbose=True)
testdb.table_exists(table_name=tbl_name)
testdb.get_column_dtype(table_name=tbl_name)
dat_ = testdb.read_table(tbl_name)
dat_.loc[0, 'Longitude'] is None
```

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

### Initialize PostgresOSM and define test variables

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.import_osm_layer.html

Setup the database connection and define variables for subregion and data directory paths.

```python
from pydriosm.ios._base import BaseIOS
from pyhelpers.dirs import delete_dir

osmdb = BaseIOS(database_name='osmdb_test', verbose=True)

subrgn_name = 'Rutland'  # name of a subregion
dat_dir = "tests/osm_data"  # name of a data directory where the subregion data is
```

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

### Install PyDriosm development version

Source: https://pydriosm.readthedocs.io/en/latest/installation.html

Use this command to install the latest development version directly from the GitHub repository.

```bash
pip install --upgrade git+https://github.com/mikeqfu/pydriosm.git@develop
```

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

### Install PyDriosm via pip

Source: https://pydriosm.readthedocs.io/en/latest/installation.html

Use this command to install the latest stable release of the library.

```bash
pip install --upgrade pydriosm
```

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

### Downloading OSM Data

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.GeofabrikDownloader.download_data.html

Examples demonstrating how to download OSM data for specific regions and formats, including handling default and custom download directories.

```python
gfd = GeofabrikDownloader()
# Download PBF data file of 'Greater London' and 'Rutland'
subregion_names = ['Isle of Wight', 'rutland']  # Case-insensitive
osm_file_format = ".pbf"
gfd.download_data(subregion_names, osm_file_format, verbose=True)
len(gfd.data_paths)
for file_path in gfd.data_paths: print(os.path.basename(file_path))
# Since `download_dir` was not specified when instantiating the class,
#   the data is now in the default download directory
os.path.relpath(gfd.download_dir)  # (on Windows)
download_dir_ = os.path.dirname(gfd.download_dir)

# Download shapefiles of West Midlands (to a given directory "tests/osm_data")
subregion_name = 'west midlands'  # Case-insensitive
osm_file_format = [".shp", ".gpkg", "pbf"]
download_dir = "tests/osm_data"
gfd.download_data(subregion_name, osm_file_format, download_dir, verbose=True)
len(gfd.data_paths)
os.path.relpath(gfd.data_paths[-1])  # (on Windows)
# Now the `.download_dir` variable has changed to the given one `download_dir`
os.path.relpath(gfd.download_dir)  # (on Windows)
# while `.cdd()` remains the default one
os.path.relpath(gfd.cdd())  # (on Windows)
# Delete the above downloaded directories
delete_dir([download_dir_, gfd.download_dir], verbose=True)
```

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

### Parsing OSM PBF data

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.reader._pbf.PBF.read_pbf.html

Demonstrates downloading a PBF file and parsing it with default settings, followed by an example using the expand parameter to structure the output.

```python
>>> from pydriosm.reader._pbf import PBF
>>> from pydriosm.downloader import Downloader
>>> from pyhelpers.dirs import delete_dir
>>> import os

>>> # Download the PBF data file of 'Rutland' as an example
>>> subregion_name = 'rutland'
>>> osm_file_format = ".pbf"
>>> download_dir = "tests/osm_data"

>>> dl = Downloader()

>>> dl.download_data(subregion_name, osm_file_format, download_dir, verbose=True)
To download data in the format '.osm.pbf' for the following geographic (sub)region(s):
    "Rutland"
  to "./tests/osm_data/rutland/"
? [No]|Yes: >? yes
Downloading "rutland-latest.osm.pbf" 100%|██████████| 1.83M/1.83M | 5.74MB/s ...
    Saving "rutland-latest.osm.pbf" to "./tests/osm_data/rutland/" ... Done.

>>> path_to_file = dl.data_paths[0]
>>> os.path.relpath(path_to_file)
'tests\osm_data\rutland\rutland-latest.osm.pbf'

>>> # Read the downloaded PBF data
>>> rutland_pbf = PBF.read_pbf(path_to_file)
>>> type(rutland_pbf)
dict
>>> list(rutland_pbf.keys())
['points', 'lines', 'multilinestrings', 'multipolygons', 'other_relations']

>>> rutland_pbf_points = rutland_pbf['points']
>>> rutland_pbf_points.head()
0    {'type': 'Feature', 'geometry': {'type': 'Poin...
1    {'type': 'Feature', 'geometry': {'type': 'Poin...
2    {'type': 'Feature', 'geometry': {'type': 'Poin...
3    {'type': 'Feature', 'geometry': {'type': 'Poin...
4    {'type': 'Feature', 'geometry': {'type': 'Poin...
Name: points, dtype: object

>>> # Set `expand` to be `True`
>>> pbf_0 = PBF.read_pbf(path_to_file, expand=True)
>>> type(pbf_0)
dict
>>> list(pbf_0.keys())
['points', 'lines', 'multilinestrings', 'multipolygons', 'other_relations']
>>> pbf_0_points = pbf_0['points']
>>> pbf_0_points.head()
         id  ...                                         properties
0    488432  ...  {'osm_id': '488432', 'name': None, 'barrier': ...
1    488658  ...  {'osm_id': '488658', 'name': 'Tickencote Inter...
2  13883868  ...  {'osm_id': '13883868', 'name': None, 'barrier'...
3  14049101  ...  {'osm_id': '14049101', 'name': None, 'barrier'...
4  14558402  ...  {'osm_id': '14558402', 'name': None, 'barrier'...
[5 rows x 3 columns]

>>> pbf_0_points['geometry'].head()
0    {'type': 'Point', 'coordinates': [-0.5134241, ...
1    {'type': 'Point', 'coordinates': [-0.5313354, ...
2    {'type': 'Point', 'coordinates': [-0.7229332, ...
3    {'type': 'Point', 'coordinates': [-0.7249816, ...
4    {'type': 'Point', 'coordinates': [-0.7266581, ...
Name: geometry, dtype: object
```

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

### Get a subregion download URL using BBBikeDownloader

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.get_subregion_download_url.html

Demonstrates how to initialize the downloader and retrieve download URLs for different file formats.

```python
from pydriosm.downloader import BBBikeDownloader
bbd = BBBikeDownloader()
subregion_name, osm_file_format = 'birmingham', "pbf"
# Get a valid subregion name and its download URL
subregion_name_, download_url = bbd.get_subregion_download_url(
    subregion_name, osm_file_format)
subregion_name_
'Birmingham'
download_url
'https://download.bbbike.org/osm/bbbike/Birmingham/Birmingham.osm.pbf'
osm_file_format = "csv.xz"
subregion_name_, download_url = bbd.get_subregion_download_url(
    subregion_name, osm_file_format)
subregion_name_
'Birmingham'
download_url
'https://download.bbbike.org/osm/bbbike/Birmingham/Birmingham.osm.csv.xz'
```

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

### Locating and Processing Shapefiles with GeofabrikReader

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.reader.GeofabrikReader.get_shp_pathname.html

This example demonstrates the workflow of initializing the reader, downloading and unzipping shapefile data, and retrieving specific file paths for layers and features.

```python
from pydriosm.reader import GeofabrikReader
from pyhelpers.dirs import delete_dir
import os

gfr = GeofabrikReader()

subrgn_name = 'london'
file_format = ".shp"
dat_dir = "tests\osm_data"

# Try to get the shapefiles' pathnames
london_shp_path = gfr.get_shp_pathname(subrgn_name, data_dir=dat_dir)
london_shp_path  # An empty list if no data is available
[]

# Download the shapefiles of London
path_to_london_shp_zip = gfr.downloader.download_data(
    subrgn_name, file_format, dat_dir, verbose=True, ret_download_path=True)

type(path_to_london_shp_zip)
list
len(path_to_london_shp_zip)
1

# Extract the downloaded .zip file
gfr.SHP.unzip_shp_zip(path_to_london_shp_zip[0], verbose=True)

# Try again to get the shapefiles' pathnames
london_shp_path = gfr.get_shp_pathname(subrgn_name, data_dir=dat_dir)
len(london_shp_path) > 1
True

# Get the file path of 'railways' shapefile
lyr_name = 'railways'
railways_shp_path = gfr.get_shp_pathname(subrgn_name, lyr_name, data_dir=dat_dir)
len(railways_shp_path)
1
railways_shp_path = railways_shp_path[0]
os.path.relpath(railways_shp_path)
'tests\osm_data\greater-london\greater-london-latest-free-shp\gis_osm_railways_... 

# Get/save shapefile data of features labelled 'rail' only
feat_name = 'rail'
railways_shp = gfr.SHP.read_layer_shps(
    railways_shp_path, feature_names=feat_name, save_feat_shp=True)
railways_shp.head()

# Get the file path to the data of 'rail'
rail_shp_path = gfr.get_shp_pathname(subrgn_name, lyr_name, feat_name, dat_dir)
len(rail_shp_path)
1
rail_shp_path = rail_shp_path[0]
os.path.relpath(rail_shp_path)
'tests\osm_data\greater-london\greater-london-latest-free-shp\gis_osm_railways_... 

# Retrieve the data of 'rail' feature
railways_rail_shp = gfr.SHP.read_layer_shps(rail_shp_path)
railways_rail_shp.head()

# Delete the example data and the test data directory
delete_dir(dat_dir, verbose=True)
```

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

### Saving shapefile data using SHP.write_to_shapefile

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.reader._shp.SHP.write_to_shapefile.html

This example demonstrates the full workflow of downloading OSM data, extracting a specific layer, reading it into a DataFrame, and saving it to a new location using SHP.write_to_shapefile.

```python
from pydriosm.reader._shp import SHP
from pydriosm.downloader import BBBikeDownloader
from pyhelpers.dirs import cd, delete_dir
import os
import glob

# Download the shapefile data of London as an example
subrgn_name = 'Birmingham'
file_format = ".shp"
dwnld_dir = "tests/osm_data"

bbd = BBBikeDownloader()

bbd.download_data(subrgn_name, file_format, dwnld_dir, verbose=True)

bham_shp_zip = bbd.data_paths[0]
os.path.relpath(bham_shp_zip)

# Extract the 'railways' layer of the downloaded .shp.zip file
lyr_name = 'railways'

railways_shp_dir = SHP.unzip_shp_zip(
    bham_shp_zip, layer_names=lyr_name, verbose=True, ret_extract_dir=True)

# Check out the output directory
os.path.relpath(railways_shp_dir)

# Get the pathname of the .shp data of 'railways'
path_to_railways_shp = glob.glob(
    cd(railways_shp_dir, "Birmingham-shp", "shape", f"*{lyr_name}*.shp"))[0]
os.path.relpath(path_to_railways_shp)  # Check the pathname of the .shp file

# Read the .shp file
bham_railways_shp = SHP.read_shp(path_to_railways_shp)

# Create a new directory for saving the 'railways' data
railways_subdir = cd(os.path.dirname(railways_shp_dir), lyr_name)
os.path.relpath(railways_subdir)

# Save the data of 'railways' to the new directory
path_to_railways_shp_ = SHP.write_to_shapefile(
    bham_railways_shp, railways_subdir, ret_shp_pathname=True, verbose=True)
os.path.basename(path_to_railways_shp_)

# If `shp_filename` is specified
path_to_railways_shp_ = SHP.write_to_shapefile(
    bham_railways_shp, railways_subdir, shp_filename="rail_data",
    ret_shp_pathname=True, verbose=True)
os.path.basename(path_to_railways_shp_)

# Retrieve the saved the .shp file
bham_railways_shp_ = SHP.read_shp(path_to_railways_shp_)
# Check if the retrieved .shp data is equal to the original one
bham_railways_shp_.equals(bham_railways_shp)

# Delete the download/data directory
delete_dir(bbd.download_dir, verbose=True)
```

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

### Verify PyDriosm installation

Source: https://pydriosm.readthedocs.io/en/latest/installation.html

Check the installed version of the library within a Python interpreter.

```python
import pydriosm
pydriosm.__version__  # Check the latest version
```

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

### Initialize and Manage PostgresOSM

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.html

Demonstrates initializing a database connection, switching data sources, and dropping a database.

```python
from pydriosm.ios import PostgresOSM

osmdb = PostgresOSM(database_name='osmdb_test', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "osmdb_test" ... Done.
Connecting postgres:***@localhost:5432/osmdb_test ... Successfully.

osmdb.data_source
'Geofabrik'
type(osmdb.downloader)
pydriosm.downloader._wrapper.Downloader
type(osmdb.reader)
pydriosm.reader._wrapper.Reader

# Change the data source
osmdb.data_source = 'BBBike'
type(osmdb.downloader)
pydriosm.downloader._wrapper.Downloader
type(osmdb.reader)
pydriosm.reader._wrapper.Reader

# Delete the database 'osmdb_test'
osmdb.drop_database(verbose=True)
To drop the database "osmdb_test" from postgres:***@localhost:5432
? [No]|Yes: yes
Dropping "osmdb_test" ... Done.
```

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

### Initialize and Inspect BBBikeDownloader

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.html

Demonstrates initializing the downloader, accessing metadata attributes, and configuring a custom download directory.

```python
from pydriosm.downloader import BBBikeDownloader
import os
bbd = BBBikeDownloader()
bbd.NAME
'BBBike'
bbd.LONG_NAME
'BBBike exports of OpenStreetMap data'
bbd.URL
'https://download.bbbike.org/osm/bbbike/'
os.path.relpath(bbd.download_dir)
'osm_data\bbbike'
bbd = BBBikeDownloader(download_dir="tests\osm_data")
os.path.relpath(bbd.download_dir)
'tests\osm_data'
```

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

### Initialize BBBikeIOS and Inspect Components

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.BBBikeIOS.html

Demonstrates initializing the BBBikeIOS class with database credentials and verifying the types of its internal downloader and reader components.

```python
from pydriosm.ios import BBBikeIOS
bbi = BBBikeIOS(database_name='osmdb_test', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "osmdb_test" ... Done.
Connecting postgres:***@localhost:5432/osmdb_test ... Successfully.
type(bbi.downloader)
pydriosm.downloader._wrapper.Downloader
type(bbi.reader)
pydriosm.downloader._wrapper.Reader
```

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

### Create and manage a PostgreSQL database

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.create_database.html

Demonstrates initializing a PostgreSQL connection, creating a new database, and subsequently dropping databases.

```python
from pyhelpers.dbms import PostgreSQL
testdb = PostgreSQL(database_name='testdb', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "testdb" ... Done.
Connecting postgres:***@localhost:5432/testdb ... Successfully.
testdb.database_name
'testdb'
testdb.create_database(database_name='testdb1', verbose=True)
Creating a database: "testdb1" ... Done.
testdb.database_name
'testdb1'
# Delete the database "testdb1"
testdb.drop_database(verbose=True)
To drop the database "testdb1" from postgres:***@localhost:5432
? [No]|Yes: yes
Dropping "testdb1" ... Done.
testdb.database_name
'postgres'
# Delete the database "testdb"
testdb.drop_database(database_name='testdb', verbose=True)
To drop the database "testdb" from postgres:***@localhost:5432
? [No]|Yes: yes
Dropping "testdb" ... Done.
testdb.database_name
'postgres'
```

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

### Initialize and Inspect GeofabrikDownloader

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.GeofabrikDownloader.html

Demonstrates initializing the downloader with default and custom directories, and accessing class attributes like the base URL and download index.

```python
from pydriosm.downloader import GeofabrikDownloader
import os
gfd = GeofabrikDownloader()
gfd.NAME
'Geofabrik'
gfd.URL
'https://download.geofabrik.de/'
gfd.DOWNLOAD_INDEX_URL
'https://download.geofabrik.de/index-v1.json'
os.path.relpath(gfd.download_dir)
'osm_data\geofabrik'
gfd = GeofabrikDownloader(download_dir="tests/osm_data")
os.path.relpath(gfd.download_dir)
'tests\osm_data'
```

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

### Creating and managing a table with PostgresOSM

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.create_table.html

Demonstrates the full lifecycle of creating a table, verifying its existence, inspecting column metadata, and cleaning up by dropping the table and database.

```python
from pyhelpers.dbms import PostgreSQL
testdb = PostgreSQL(database_name='testdb', verbose=True)
# Create a new table named 'test_table'
tbl_name = 'test_table'
col_spec = 'col_name_1 INT, col_name_2 TEXT'
testdb.create_table(table_name=tbl_name, column_specs=col_spec, verbose=True)
testdb.table_exists(table_name=tbl_name)
# Get information about all columns of the table "public"."test_table"
test_tbl_col_info = testdb.get_column_info(table_name=tbl_name, as_dict=False)
test_tbl_col_info.head()
# Get column names of the table "public"."test_table"
test_tbl_col_names = testdb.get_column_names(table_name=tbl_name)
test_tbl_col_names
# Get data types of all columns of the table
test_tbl_dtypes = testdb.get_column_dtype(table_name=tbl_name)
test_tbl_dtypes
testdb.validate_column_names(table_name=tbl_name)
# Drop the table "public"."test_table"
testdb.drop_table(table_name=tbl_name, verbose=True)
# Delete the database "testdb"
testdb.drop_database(verbose=True)
```

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

### GeofabrikDownloader.get_default_pathname

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.GeofabrikDownloader.get_default_pathname.html

Get the default pathname of a local directory for storing a downloaded data file.

```APIDOC
## GeofabrikDownloader.get_default_pathname(subregion_name, osm_file_format, mkdir=False, update=False, verbose=False)

### Description
Get the default pathname of a local directory for storing a downloaded data file. The default file path is derived from the download URL of the requested data file.

### Parameters
- **subregion_name** (str) - Required - Name of a (sub)region available on Geofabrik free download server
- **osm_file_format** (str) - Required - File format/extension of the OSM data available on the download server
- **mkdir** (bool) - Optional - Whether to create a directory, defaults to False
- **update** (bool) - Optional - Whether to (check on and) update the prepacked data, defaults to False
- **verbose** (bool | int) - Optional - Whether to print relevant information in console, defaults to False

### Returns
- **Tuple[str, str]** - Default filename of the subregion and default (absolute) path to the file
```

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

### Connecting to a PostgreSQL database

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.connect_database.html

Demonstrates initializing a PostgreSQL instance and switching between databases using the connect_database method.

```python
from pyhelpers.dbms import PostgreSQL
testdb = PostgreSQL(database_name='testdb', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "testdb" ... Done.
Connecting postgres:***@localhost:5432/testdb ... Successfully.
testdb.connect_database(verbose=True)
Being connected with postgres:***@localhost:5432/testdb.
testdb.connect_database(database_name='postgres', verbose=True)
Connecting postgres:***@localhost:5432/postgres ... Successfully.
testdb.database_name
'postgres'
testdb.connect_database(database_name='testdb', verbose=True)
Connecting postgres:***@localhost:5432/testdb ... Successfully.
testdb.database_name
'testdb'
testdb.drop_database(verbose=True)  # Delete the database "testdb"
To drop the database "testdb" from postgres:***@localhost:5432
? [No]|Yes: yes
Dropping "testdb" ... Done.
testdb.database_name
'postgres'
```

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

### Use parameters with pandas.read_sql

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.read_sql_query.html

A brief example showing how to use the params argument with pandas.read_sql for parameterized queries.

```python
import datetime
import pandas as pd
sql_qry = 'SELECT * FROM "table_name" '
          'WHERE "timestamp_column_name" BETWEEN %(ts_start)s AND %(ts_end)s'
params = {'d_start': datetime.datetime.today(), 'd_end': datetime.datetime.today()}
data_frame = pd.read_sql(sql=sql_qry, con=testdb.engine, params=params)
```

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

### Retrieve Download Information

Source: https://pydriosm.readthedocs.io/en/latest/quick-start.html

Get valid download information for a region without requiring the file to exist locally.

```python
download_info = gfd.get_valid_download_info(subrgn_name, file_format, dwnld_dir)
subrgn_name_, london_pbf_filename, london_pbf_url, london_pbf_pathname = download_info

print(f'Current (relative) path: "{os.path.relpath(london_pbf_pathname)}"')
Current (relative) path: "tests\osm_data\greater-london\greater-london-latest.osm.pbf"

print(f'Default filename: "{london_pbf_filename}"')
Default filename: "greater-london-latest.osm.pbf"
```

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

### Get default OSM layer name

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.utils.get_default_layer_name.html

Demonstrates retrieving default layer names for specific schema inputs.

```python
from pydriosm.ios.utils import get_default_layer_name
lyr_name = get_default_layer_name(schema_name='point')
lyr_name
'points'
lyr_name = get_default_layer_name(schema_name='land')
lyr_name
'landuse'
```

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

### Using print_action_prompt

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.print_action_prompt.html

Demonstrates how to use the print_action_prompt method with various verbosity and configuration settings.

```python
from pydriosm.downloader._base import BaseDownloader
BaseDownloader.print_action_prompt(verbose=False) is None  # Nothing is printed.
True
BaseDownloader.print_action_prompt(verbose=True)
... print("Done.")
Retrieving/compiling the data ... Done.
BaseDownloader.print_action_prompt(verbose=True, note="(Some notes)")
... print("Done.")
Retrieving/compiling the data (Some notes) ... Done.
BaseDownloader.print_action_prompt(verbose=True, confirmation_required=False)
... print("Done.")
Retrieving/compiling data of <data_name> ... Done.
```

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

### Create a schema in PostgreSQL

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.create_schema.html

Demonstrates initializing a PostgreSQL connection, creating a schema, verifying its existence, and cleaning up the test database.

```python
from pyhelpers.dbms import PostgreSQL
testdb = PostgreSQL(database_name='testdb', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "testdb" ... Done.
Connecting postgres:***@localhost:5432/testdb ... Successfully.
test_schema_name = 'test_schema'
testdb.create_schema(schema_name=test_schema_name, verbose=True)
Creating a schema: "test_schema" ... Done.
testdb.schema_exists(schema_name=test_schema_name)
True
testdb.drop_database(verbose=True)  # Delete the database "testdb"
To drop the database "testdb" from postgres:***@localhost:5432
? [No]|Yes: yes
Dropping "testdb" ... Done.
```

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

### Get table name for a geographic subregion

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.get_table_name.html

Demonstrates retrieving table names based on subregion and data source configurations.

```python
>>> from pydriosm.ios._base import BaseIOS

>>> osmdb = BaseIOS(database_name='osmdb_test')
Password (postgres@localhost:5432): ***
Creating a database: "osmdb_test" ... Done.
Connecting postgres:***@localhost:5432/osmdb_test ... Successfully.

>>> subrgn_name = 'london'

>>> tbl_name = osmdb.get_table_name(subrgn_name)
>>> tbl_name
'london'

>>> tbl_name = osmdb.get_table_name(subrgn_name, table_named_as_subregion=True)
>>> tbl_name
'Greater London'

>>> # Change the data source
>>> osmdb.data_source = 'BBBike'
>>> tbl_name = osmdb.get_table_name(subrgn_name, table_named_as_subregion=True)
>>> tbl_name
'London'

>>> # Delete the database 'osmdb_test'
>>> osmdb.drop_database(verbose=True)
To drop the database "osmdb_test" from postgres:***@localhost:5432
? [No]|Yes: yes
Dropping "osmdb_test" ... Done.
```

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

### Get default sub path for a region

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.get_default_sub_path.html

Demonstrates how to retrieve the default sub-path for a specific region using the BaseDownloader class.

```python
from pydriosm.downloader._base import BaseDownloader

subrgn_name_ = 'London'
dwnld_url = 'https://download.bbbike.org/osm/bbbike/London/London.osm.pbf'
BaseDownloader.get_default_sub_path(subrgn_name_, dwnld_url)
```

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

### Merge Transport Layers

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.reader.GeofabrikReader.merge_shp_layers.html

A partial example showing the initiation of a merge operation for transport layers across multiple regions.

```python
# To merge 'transport' of Greater London, Kent and Surrey
```

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

### Checking for OSM data file existence

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.GeofabrikDownloader.file_exists.html

Demonstrates initializing the downloader, downloading a file, checking its existence, and retrieving the file path.

```python
from pydriosm.downloader import GeofabrikDownloader
from pyhelpers.dirs import delete_dir
import os
gfd = GeofabrikDownloader(download_dir="tests/osm_data")
# Download the PBF data of London (to the default directory)
subregion_name = 'london'
osm_file_format = ".geopackage"
gfd.download_data(subregion_name, osm_file_format, verbose=True)
# Check whether the PBF data file exists; `ret_file_path` is by default `False`
gpkg_exists = gfd.file_exists(subregion_name, osm_file_format)
gpkg_exists  # If the data file exists at the default directory
True
# Set `ret_file_path=True`
path_to_gpkg = gfd.file_exists(
    subregion_name, osm_file_format, ret_file_path=True)
os.path.relpath(path_to_gpkg)  # If the data file exists at the default directory
'tests\osm_data\europe\united-kingdom\england\greater-london\greater-london-l...'
# Remove the download directory:
delete_dir(gfd.download_dir, verbose=True)
# Check if the data file still exists at the specified download directory
gfd.file_exists(subregion_name, osm_file_format)
False
```

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

### Initialize GeofabrikIOS and inspect components

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.GeofabrikIOS.html

Demonstrates the instantiation of the GeofabrikIOS class and verification of its internal downloader and reader components.

```python
from pydriosm.ios import GeofabrikIOS
gfi = GeofabrikIOS(database_name='osmdb_test', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "osmdb_test" ... Done.
Connecting postgres:***@localhost:5432/osmdb_test ... Successfully.
type(gfi.downloader)
pydriosm.downloader._wrapper.Downloader
type(gfi.reader)
pydriosm.reader._wrapper.Reader
```

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

### Fetch OSM data from PostgreSQL

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.fetch_data.html

Demonstrates initializing the database, importing data, and using fetch_data to retrieve specific layers.

```python
>>> from pydriosm.ios import PostgresOSM
>>> from pyhelpers.dirs import delete_dir

>>> osmdb = PostgresOSM(database_name='osmdb_test', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "osmdb_test" ... Done.
Connecting postgres:***@localhost:5432/osmdb_test ... Successfully.

>>> subrgn_name = 'Rutland'  # name of a subregion
>>> dat_dir = "tests/osm_data"  # name of a data directory where the subregion data is

>>> # Import PBF data of Rutland
>>> osmdb.import_osm_pbf(subrgn_name, data_dir=dat_dir, verbose=True)
Proceed to import .osm.pbf data of the following geographic (sub)region(s):
    "Rutland"
  into postgres:***@localhost:5432/osmdb_test
? [No]|Yes: yes
Downloading "rutland-latest.osm.pbf" 100%|██████████| 1.89M/1.89M | 6.46MB/s ...
  Saving "rutland-latest.osm.pbf" to "./tests/osm_data/rutland/" ... Done.
Reading "tests/osm_data/rutland/rutland-latest.osm.pbf" ... Done.
Importing the data into the table "Rutland" ...
  "points" ... Done. (6473 features)
  "lines" ... Done. (11057 features)
  "multilinestrings" ... Done. (71 features)
  "multipolygons" ... Done. (9423 features)
  "other_relations" ... Done. (33 features)

>>> # Import shapefile data of Rutland
>>> rutland_shp = osmdb.reader.read_shp(
...     subrgn_name, data_dir=dat_dir, rm_extracts=True, verbose=True)
>>> rutland_shp is None
True

>>> # Import geopackage data of Rutland
>>> rutland_gpkg = osmdb.reader.read_gpkg(
...     subrgn_name, data_dir=dat_dir, download=True, verbose=True)
Downloading "rutland-latest-free.gpkg.zip" 100%|██████████| 3.30M/3.30M | 7.5...
  Saving "rutland-latest-free.gpkg.zip" to "./tests/osm_data/rutland/" ... Done.
Parsing the data ... Done.
>>> osmdb.import_osm_data(rutland_gpkg, table_name=subrgn_name, verbose=True)
Proceed to import data into the table "Rutland" at postgres:***@localhost:5432/osmd...
? [No]|Yes: yes
Importing the data ...
  "traffic" ... Done. (557 features)
  "places" ... Done. (301 features)
  "pois" ... Done. (1081 features)
  "transport" ... Done. (65 features)
  "pofw" ... Done. (65 features)
  "natural" ... Done. (665 features)
  "railways" ... Done. (141 features)
  "roads" ... Done. (7315 features)
  "waterways" ... Done. (379 features)
  "protected_areas" ... Done. (20 features)
  "water" ... Done. (233 features)
  "landuse" ... Done. (2461 features)
  "buildings" ... Done. (5706 features)
  "adminareas" ... Done. (58 features)

>>> # Retrieve the data of specific layers
>>> lyr_names = ['points', 'multipolygons']
>>> rutland_data_ = osmdb.fetch_data(subrgn_name, lyr_names, verbose=True)
Fetching the data of "Rutland" ...
  "points" ... Done.
  "multipolygons" ... Done.
>>> type(rutland_data_)
dict
>>> list(rutland_data_.keys())
['points', 'multipolygons']
```

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

### Get layer name from OSM shapefile

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.reader._shp.SHP.get_layer_name.html

Demonstrates extracting layer names from various OSM shapefile filenames using SHP.get_layer_name.

```python
from pydriosm.reader._shp import SHP

SHP.get_layer_name("") is None
True

SHP.get_layer_name("gis_osm_railways_free_1.shp")
'railways'

SHP.get_layer_name("gis_osm_transport_a_free_1.shp")
'transport'
```

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

### BBBikeDownloader.print_action_prompt

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.print_action_prompt.html

Prints a short message showing the action as a function runs.

```APIDOC
## classmethod BBBikeDownloader.print_action_prompt(data_name='<data_name>', verbose=False, confirmation_required=True, note='', end=' ... ')

### Description
Print a short message showing the action as a function runs.

### Parameters
- **data_name** (str) - Optional - Name of the prepacked data, defaults to '<data_name>'
- **verbose** (bool | int) - Optional - Whether to print relevant information in console, defaults to False
- **confirmation_required** (bool) - Optional - Whether asking for confirmation to proceed, defaults to True
- **note** (str) - Optional - Additional message, defaults to ''
- **end** (str) - Optional - End string after printing the status message, defaults to ' ... '

### Returns
- **None** (None) - This method does not return a value.
```

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

### Get default pathname for Geofabrik data

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.GeofabrikDownloader.get_default_pathname.html

Demonstrates how to retrieve the default storage path and filename for a specific subregion and file format.

```python
from pydriosm.downloader import GeofabrikDownloader
import os
gfd = GeofabrikDownloader()

# Default filename and download path of the PBF data of London
subregion_name, osm_file_format = 'london', ".geopackage"
pathname, filename = gfd.get_default_pathname(subregion_name, osm_file_format)
os.path.relpath(os.path.dirname(pathname))
'osm_data\geofabrik\europe\united-kingdom\england\greater-london'
filename
'greater-london-latest-free.gpkg.zip'
```

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

### Retrieve the BBBike download catalogue

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.get_catalogue.html

Demonstrates how to initialize the downloader and fetch the catalogue index, which includes file formats and data types.

```python
from pydriosm.downloader import BBBikeDownloader
bbd = BBBikeDownloader()
# Index for downloading OSM data available on the BBBike free download server
bbbike_catalogue = bbd.get_catalogue()
list(bbbike_catalogue.keys())
['FileFormat', 'DataType', 'Catalogue']
catalogue = bbbike_catalogue['Catalogue']
type(catalogue)
dict
bham_catalogue = catalogue['Birmingham']
type(bham_catalogue)
pandas.core.frame.DataFrame
bham_catalogue.shape
(13, 5)
bham_catalogue.head()
                                   filename  ...                last_update
0                        Birmingham.osm.pbf  ...  2025-09-27 18:51:39+00:00
1                         Birmingham.osm.gz  ...  2025-09-28 05:37:57+00:00
2                    Birmingham.osm.shp.zip  ...  2025-09-28 05:54:16+00:00
3  Birmingham.osm.garmin-ontrail-latin1.zip  ...  2025-09-28 07:05:18+00:00
4   Birmingham.osm.garmin-onroad-latin1.zip  ...  2025-09-28 07:04:54+00:00
[5 rows x 5 columns]
```

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

### Merge and Process Shapefiles

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.reader.BBBikeReader.merge_shp_layers.html

Example demonstrating how to merge railway data for London and Birmingham, read the resulting file, and clean up the generated directories.

```python
# To merge 'railways' of London and Birmingham
subrgn_name = ['London', 'Birmingham']
lyr_name = 'railways'
dat_dir = "tests/osm_data"
path_to_merged_shp_file = bbr.merge_shp_layers(
    subrgn_name, lyr_name, dat_dir, verbose=True, ret_merged_shp_path=True)

path_to_merged_shp_file = path_to_merged_shp_file[0]
os.path.relpath(path_to_merged_shp_file)

# Read the merged data
lon_bir_railways_shp = bbr.SHP.read_shp(path_to_merged_shp_file)
lon_bir_railways_shp.head()

# Delete the merged files
delete_dir(os.path.dirname(path_to_merged_shp_file), verbose=True)

# Delete the downloaded .shp.zip data files
delete_dir(list(map(os.path.dirname, bbr.downloader.data_paths)), verbose=True)

# Delete the example data and the test data directory
delete_dir(dat_dir, verbose=True)
```

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

### Retrieve prepacked data using BaseDownloader

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.GeofabrikDownloader.get_prepacked_data.html

Demonstrates how to use the get_prepacked_data method to retrieve auxiliary data with verbose output enabled.

```python
>>> from pydriosm.downloader._base import BaseDownloader
>>> data = BaseDownloader.get_prepacked_data(print, verbose=True, raise_error=True)
Proceed to retrieve/compile data of <data_name>
? [No]|Yes: yes
Retrieving/compiling the data ...
Done.
>>> data is None
True
```

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

### Checking table existence with PostgresOSM

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.table_exists.html

Demonstrates initializing a PostgreSQL connection, checking for a non-existent table, creating it, verifying its existence, and cleaning up.

```python
from pyhelpers.dbms import PostgreSQL
testdb = PostgreSQL(database_name='testdb', verbose=True)
Password (postgres@localhost:5432): ***
Creating a database: "testdb" ... Done.
Connecting postgres:***@localhost:5432/testdb ... Successfully.
tbl_name = 'points'
testdb.table_exists(table_name=tbl_name)  # (if 'public.points' does not exist)
False
testdb.create_table(table_name=tbl_name, column_specs='column_0 INT', verbose=1)
Creating a table: "public"."points" ... Done.
testdb.table_exists(table_name=tbl_name)
True
testdb.drop_table(table_name=tbl_name, verbose=True)
To drop the table "public"."points" from postgres:***@localhost:5432/testdb
? [No]|Yes: yes
Dropping "public"."points" ... Done.
testdb.drop_database(verbose=True)  # Delete the database "testdb"
To drop the database "testdb" from postgres:***@localhost:5432
? [No]|Yes: yes
Dropping "testdb" ... Done.
```

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

### Retrieve and verify OSM file path

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.reader.GeofabrikReader.get_file_path.html

Demonstrates how to locate a PBF file, download it if missing, and verify its existence on the local filesystem.

```python
from pydriosm.reader import GeofabrikReader
from pyhelpers.dirs import delete_dir
import os

gfr = GeofabrikReader()

subrgn_name = 'rutland'
file_format = ".pbf"
dat_dir = "tests\osm_data"
path_to_rutland_pbf = gfr.get_file_path(subrgn_name, file_format, data_dir=dat_dir)
# When "rutland-latest.osm.pbf" is unavailable at the package data directory
os.path.isfile(path_to_rutland_pbf)
False

# Download the PBF data file of Rutland to "tests\osm_data\"
gfr.downloader.download_data(subrgn_name, file_format, dat_dir, verbose=True)

# Check again
path_to_rutland_pbf = gfr.get_file_path(subrgn_name, file_format, data_dir=dat_dir)
os.path.relpath(path_to_rutland_pbf)
'tests\osm_data\rutland\rutland-latest.osm.pbf'
os.path.isfile(path_to_rutland_pbf)
True

# Delete the test data directory
delete_dir(dat_dir, verbose=True)
```

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

### Check database existence with PostgresOSM

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.database_exists.html

Demonstrates initializing a PostgreSQL connection, checking for a database, and verifying its removal.

```python
from pyhelpers.dbms import PostgreSQL
testdb = PostgreSQL(database_name='testdb', verbose=True)
# Check whether the database "testdb" exists now
testdb.database_exists(database_name='testdb')  # testdb.database_exists()
True
testdb.database_name
'testdb'
# Delete the database "testdb"
testdb.drop_database(verbose=True)
# Check again whether the database "testdb" still exists now
testdb.database_exists(database_name='testdb')
False
testdb.database_name
'postgres'
```

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

### Retrieve available BBBike cities

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.get_bbbike_cities.html

Demonstrates how to initialize the downloader and fetch the list of available cities.

```python
from pydriosm.downloader import BBBikeDownloader
bbd = BBBikeDownloader()
bbbike_cities = bbd.get_bbbike_cities()
bbbike_cities[:5]
```

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

### Cleaning Up Database and Files

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.ios.PostgresOSM.fetch_data.html

Demonstrates how to drop the test database and remove downloaded data directories.

```python
>>> # Delete the database 'osmdb_test'
>>> osmdb.drop_database(verbose=True)
```

```python
>>> # Delete the downloaded data files
>>> delete_dir(dat_dir, verbose=True)
```

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

### BBBikeDownloader.format_confirmation_prompt(data_name='<data_name>', file_path='<file_path>', update=False, note='')

Source: https://pydriosm.readthedocs.io/en/latest/_generated/pydriosm.downloader.BBBikeDownloader.format_confirmation_prompt.html

Composes a short message to be printed for confirmation when handling prepacked data.

```APIDOC
## BBBikeDownloader.format_confirmation_prompt

### Description
Compose a short message to be printed for confirmation.

### Parameters
- **data_name** (str) - Optional - Name of the prepacked data. Defaults to '<data_name>'.
- **file_path** (str | os.PathLike) - Optional - Pathname of the prepacked data file. Defaults to '<file_path>'.
- **update** (bool) - Optional - Whether to (check on and) update the prepacked data. Defaults to False.
- **note** (str) - Optional - Additional message. Defaults to ''.

### Returns
- **str** - A short message to be printed for confirmation.

### Example
```python
from pydriosm.downloader._base import BaseDownloader
BaseDownloader.format_confirmation_prompt()
# 'Proceed to retrieve/compile data of <data_name>\n?'

BaseDownloader.format_confirmation_prompt(update=True)
# 'Proceed to update the data of <data_name>\n?'
```
```
Tokens:
Raw