tessl/pypi-osmapi

Python wrapper for the OSM API

—

Pending

Overview

Eval results

Files

Authentication & Configuration

Name: tessl/pypi-osmapi
Author: tessl

Complete authentication and configuration options for the osmapi library, supporting multiple authentication methods and server configurations for both production and development environments.

Capabilities

Basic Authentication

Simple username/password authentication for OSM API access.

def __init__(self, username=None, password=None, **kwargs):
    """
    Initialize OsmApi with username/password authentication.
    
    Parameters:
    - username (str): OSM username
    - password (str): OSM password
    """

Usage Example:

import osmapi

# Direct credentials
api = osmapi.OsmApi(username="your_username", password="your_password")

# Use with production server (default)
api = osmapi.OsmApi(
    username="your_username", 
    password="your_password",
    api="https://www.openstreetmap.org"
)

# Use with development server
api = osmapi.OsmApi(
    username="dev_username", 
    password="dev_password",
    api="https://api06.dev.openstreetmap.org"
)

Password File Authentication

Load credentials from a file for improved security.

def __init__(self, passwordfile=None, **kwargs):
    """
    Initialize OsmApi with credentials from file.
    
    Parameters:
    - passwordfile (str): Path to password file
    
    File format: username:password (first line)
    Multiple users: one per line with username:password format
    """

Usage Example:

import osmapi

# Single user file format: "username:password"
api = osmapi.OsmApi(passwordfile="/path/to/credentials.txt")

# Multi-user file format:
# user1:pass1
# user2:pass2
api = osmapi.OsmApi(passwordfile="/path/to/multi_user_creds.txt")

OAuth 2.0 Authentication

Advanced authentication using OAuth 2.0 with custom session objects.

def __init__(self, session=None, **kwargs):
    """
    Initialize OsmApi with OAuth 2.0 session.
    
    Parameters:
    - session: requests.Session object with OAuth credentials
    """

Usage Example:

import osmapi
from oauthcli import OpenStreetMapAuth  # External OAuth library

# OAuth 2.0 setup
client_id = "your_client_id"
client_secret = "your_client_secret"
auth = OpenStreetMapAuth(client_id, client_secret, ["write_api"]).auth_code()

# Use OAuth session
api = osmapi.OsmApi(session=auth.session)

# OAuth with development server
api = osmapi.OsmApi(
    session=auth.session,
    api="https://api06.dev.openstreetmap.org"
)

Server Configuration

Configure API endpoint and application identification.

def __init__(
    self,
    api="https://www.openstreetmap.org",
    appid="",
    created_by="osmapi/4.3.0",
    timeout=30,
    **kwargs
):
    """
    Initialize OsmApi with server configuration.
    
    Parameters:
    - api (str): API base URL
    - appid (str): Application identifier
    - created_by (str): User agent string
    - timeout (int): Request timeout in seconds
    """

Usage Example:

import osmapi

# Production server (default)
api = osmapi.OsmApi()

# Development server
api = osmapi.OsmApi(api="https://api06.dev.openstreetmap.org")

# Custom application identification
api = osmapi.OsmApi(
    appid="MyGISApp/1.0",
    created_by="MyGISApp/1.0 (osmapi/4.3.0)"
)

# Custom timeout
api = osmapi.OsmApi(timeout=60)  # 60 seconds

Automatic Changeset Configuration

Configure automatic changeset management for streamlined editing workflows.

def __init__(
    self,
    changesetauto=False,
    changesetautotags={},
    changesetautosize=500,
    changesetautomulti=1,
    **kwargs
):
    """
    Initialize OsmApi with automatic changeset configuration.
    
    Parameters:
    - changesetauto (bool): Enable automatic changeset management
    - changesetautotags (dict): Default tags for auto-created changesets
    - changesetautosize (int): Maximum elements per changeset
    - changesetautomulti (int): Number of uploads before closing changeset
    """

Usage Example:

import osmapi

# Enable automatic changeset management
api = osmapi.OsmApi(
    username="your_username",
    password="your_password",
    changesetauto=True,
    changesetautotags={
        "comment": "Automated data import",
        "source": "Survey GPS data",
        "created_by": "MyApp/1.0"
    },
    changesetautosize=100,  # 100 elements per upload
    changesetautomulti=5    # 5 uploads per changeset
)

# Operations will automatically manage changesets
api.NodeCreate({"lat": 47.6, "lon": -122.3, "tag": {"name": "Test"}})
api.NodeCreate({"lat": 47.61, "lon": -122.31, "tag": {"name": "Test2"}})
# ... more operations handled automatically

Session Management

Advanced session configuration with custom HTTP sessions.

def __init__(self, session=None, **kwargs):
    """
    Initialize OsmApi with custom session configuration.
    
    Parameters:
    - session: Custom requests.Session object
    """

def close(self):
    """Close HTTP session and clean up resources."""

def __enter__(self):
    """Context manager entry."""

def __exit__(self, *args):
    """Context manager exit with cleanup."""

Usage Example:

import osmapi
import requests

# Custom session with specific configuration
session = requests.Session()
session.headers.update({"X-Custom-Header": "MyValue"})
session.proxies = {"https": "https://proxy.example.com:8080"}

api = osmapi.OsmApi(session=session)

# Context manager usage
with osmapi.OsmApi(username="user", password="pass") as api:
    node = api.NodeGet(123)
    # Session automatically closed on exit

Server Capabilities

Query API server capabilities and limitations.

def Capabilities(self):
    """
    Returns the API capabilities as a dict.
    
    Returns:
    dict: Server capabilities including area limits, changeset limits,
          version info, timeout settings, and status information
    """

Usage Example:

import osmapi

api = osmapi.OsmApi()
caps = api.Capabilities()

print(f"API version: {caps['version']['minimum']}-{caps['version']['maximum']}")
print(f"Max area: {caps['area']['maximum']} square degrees")
print(f"Max changeset elements: {caps['changesets']['maximum_elements']}")
print(f"API status: {caps['status']['api']}")
print(f"Database status: {caps['status']['database']}")

Configuration Validation

The library automatically validates configuration and raises appropriate errors:

Production Server Protection: Prevents test changesets on production server
Authentication Validation: Ensures credentials are provided for write operations
Parameter Validation: Validates configuration parameters and combinations
Server Connectivity: Tests connection and API compatibility

Environment-Specific Setup

Development Environment

import osmapi

# Development server setup
api = osmapi.OsmApi(
    username="dev_username",
    password="dev_password", 
    api="https://api06.dev.openstreetmap.org",
    appid="MyApp-Dev/1.0"
)

Production Environment

import osmapi
import os

# Production with environment variables
api = osmapi.OsmApi(
    username=os.getenv("OSM_USERNAME"),
    password=os.getenv("OSM_PASSWORD"),
    api="https://www.openstreetmap.org",
    appid="MyApp/1.0",
    changesetautotags={
        "comment": "Automated maintenance",
        "source": "Official government data"
    }
)

Secure Credential Management

import osmapi
from pathlib import Path

# Secure password file approach
credentials_file = Path.home() / ".osm" / "credentials"
api = osmapi.OsmApi(
    passwordfile=str(credentials_file),
    api="https://www.openstreetmap.org"
)

Install with Tessl CLI