pyregrws

A Python library for interacting with ARIN's Reg-RWS (Registry RESTful Web Service) API. This library provides pydantic-xml models for ARIN payloads and a comprehensive REST client for CRUD operations on ARIN resources like POCs, Customers, Organizations, and Networks.

Features

• Type-safe models: Built with Pydantic v2 and pydantic-xml v2 for robust XML serialization/deserialization
• Complete CRUD operations: Create, read, update, and delete ARIN resources
• Automatic manager integration: Each model type has an associated manager for API operations
• Error handling: Built-in error response handling with proper HTTP status code mapping
• Environment configuration: Configurable via environment variables with sensible defaults (powered by pydantic-settings)

Requirements

• Python 3.11+
• Pydantic v2.0+
• pydantic-xml v2.0+
• pydantic-settings v2.0+

Installation

Install from PyPI using pip:

pip install pyregrws

Or using uv:

uv add pyregrws

Quick Start

from regrws.api.core import Api
from regrws.models import Poc, Org, Net, Customer

# Initialize the API client
api = Api(
    base_url="https://reg.arin.net/",  # Optional, defaults to ARIN production
    api_key="your-api-key-here"           # Or set REGRWS_API_KEY env var
)

# Retrieve a POC by handle
poc = api.poc.from_handle("EXAMPLE-ARIN")
print(f"POC: {poc.first_name} {poc.last_name}")

# Create a new POC
new_poc = api.poc.create(
    contact_type="PERSON",
    first_name="John",
    last_name="Doe",
    company_name="Example Corp",
    iso3166_1={"name": "United States", "code2": "US", "code3": "USA", "e164": "1"},
    street_address=[{"line": "123 Main St"}],
    city="Anytown",
    iso3166_2="VA",
    postal_code="12345",
    phones=[{"type": {"code": "O"}, "number": "555-123-4567"}]
)

# Update and save changes
poc.city = "New City"
updated_poc = poc.save()

# Delete a resource
poc.delete()

Configuration

The library can be configured via environment variables or by passing parameters directly to the Api class:

Environment Variables

• REGRWS_BASE_URL: Base URL for the ARIN Reg-RWS API (default: https://reg.arin.net/)
• REGRWS_API_KEY: Your ARIN API key (required)

Warning: For testing purposes, use ARIN's Operational Test and Evaluation (OTE) environment (https://reg.ote.arin.net/) instead of the production URL. The OTE environment provides a safe sandbox that will not affect real registration data.

Direct Configuration

from regrws.api.core import Api
from regrws.settings import Settings

# Method 1: Pass parameters directly
api = Api(
    base_url="https://reg.arin.net/",
    api_key="your-api-key"
)

# Method 2: Use Settings object
settings = Settings(
    base_url="https://reg.arin.net/",
    api_key="your-api-key"
)
api = Api(settings=settings)

API Reference

Core Classes

Api

The main entry point for the library. Automatically creates manager instances for each supported model type.

api = Api(base_url=None, api_key=None, settings=None)

Attributes:

• poc: Manager for POC operations
• org: Manager for Organization operations
• net: Manager for Network operations
• customer: Manager for Customer operations

BaseManager

All model managers inherit from BaseManager and provide these methods:

• create(**kwargs): Create a new resource
• from_handle(handle): Retrieve a resource by handle
• save(instance): Update an existing resource
• delete(instance): Delete a resource

Models

All models inherit from BaseModel which provides:

• save(): Save changes to the resource
• delete(): Delete the resource
• absolute_url: Get the full API URL for this resource
• manager: Access to the associated API manager

Currently Supported Payloads

Core Resources

• POC - Point of Contact
• Customer - Customer records
• ORG - Organization records
• NET - Network records
• NET Block - Network block records
• POC Link - POC associations

Ticketing

• Ticketed Request Payload
• Ticket Payload

Error Handling

• Error - API error responses

Examples

Working with POCs

# Retrieve an existing POC
poc = api.poc.from_handle("EXAMPLE-ARIN")

# Create a new person POC
person_poc = api.poc.create(
    contact_type="PERSON",
    first_name="Jane",
    last_name="Smith",
    company_name="ACME Corp",
    iso3166_1={"name": "United States", "code2": "US", "code3": "USA", "e164": "1"},
    street_address=[{"line": "456 Oak Ave"}, {"line": "Suite 100"}],
    city="Springfield",
    iso3166_2="IL", 
    postal_code="62701",
    phones=[
        {"type": {"code": "O"}, "number": "217-555-0123"},
        {"type": {"code": "F"}, "number": "217-555-0124"}
    ],
    comment=[{"line": "Technical contact for ACME Corp"}]
)

# Create a role POC
role_poc = api.poc.create(
    contact_type="ROLE",
    last_name="Network Operations Center",  # Role name goes in last_name
    company_name="ACME Corp",
    iso3166_1={"name": "United States", "code2": "US", "code3": "USA", "e164": "1"},
    street_address=[{"line": "789 Tech Dr"}],
    city="Austin",
    iso3166_2="TX",
    postal_code="78701",
    phones=[{"type": {"code": "O"}, "number": "512-555-0100"}]
)

Working with Organizations

# Retrieve an organization
org = api.org.from_handle("EXAMPLE-ARIN")

# Update organization details
org.company_name = "Updated Company Name"
updated_org = org.save()

Working with Networks

# Retrieve a network
net = api.net.from_handle("NET-192-0-2-0-1")

# Update network information
net.net_name = "UPDATED-NET-NAME"
updated_net = net.save()

Error Handling

from regrws.models import Error

try:
    poc = api.poc.from_handle("NONEXISTENT-HANDLE")
except Exception as e:
    # The library automatically handles error responses
    print(f"Error occurred: {e}")

Development

Setup

# Clone the repository
git clone https://github.com/jsenecal/pyregrws.git
cd pyregrws

# Install dependencies
uv sync

Running Tests

# Run all tests with coverage
uv run pytest --cov -n 2 --cov-report xml --cov-report term-missing

# Run a specific test
uv run pytest tests/test_api.py::TestAPI::test_manager_from_handle

Code Quality

# Lint code
uv run ruff check

# Format code  
uv run ruff format

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass and code is formatted
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Links

• ARIN Reg-RWS Documentation
• ARIN Reg-RWS Payloads
• PyPI Package
• GitHub Repository