rrc-field-rules 0.2.0

Python module to parse Texas RRC field rules from Oracle database to JSON

RRC Field Rules Parser

A Python module to parse Texas Railroad Commission (RRC) field rules data from an Oracle database and export to JSON.

Overview

This package connects to an Oracle database containing the RRC Oil & Gas Division's field rules data (originally from Oracle .dmp export files) and provides:

• Python API for programmatic access to field rules data
• CLI tool for quick data extraction and health checks
• JSON export for integration with other systems

Available Tables

Table	Description
og_field	Oil & Gas Field master records
og_field_info	Field information with discovery dates, county codes
og_field_rule	Field-specific spacing and acreage rules
og_std_field_rule	Statewide standard field rules by depth

Installation

# Using pip
pip install rrc-field-rules

# Using uv (recommended)
uv add rrc-field-rules

Development Installation

# Clone the repository
git clone https://github.com/username/rrc-field-rules.git
cd rrc-field-rules

# Install with dev dependencies
uv sync --all-extras

Prerequisites

This module requires access to an Oracle database with the RRC field rules data loaded. The database can be:

1. Docker container (included setup for local development)
2. Remote Oracle instance with the data pre-loaded

Docker Setup (Local Development)

# Start the Oracle container with data import
python main.py

# The container will:
# - Start Oracle Free (slim)
# - Create PROD_OG_OWNR user
# - Import the .dmp file automatically

Default connection details:

• Host: localhost
• Port: 1521
• Service: FREEPDB1
• User: PROD_OG_OWNR
• Password: ParserPassword123

CLI Usage

Check Database Connection

rrc-field-rules check --password ParserPassword123

Export Data to JSON

# Export all tables
rrc-field-rules export output.json --password ParserPassword123

# Export specific table with limit
rrc-field-rules export output.json --table og_field --limit 100 --password ParserPassword123

List Available Tables

rrc-field-rules list-tables

Environment Variables

Instead of passing options, you can set environment variables:

export RRC_HOST=localhost
export RRC_PORT=1521
export RRC_SERVICE=FREEPDB1
export RRC_USER=PROD_OG_OWNR
export RRC_PASSWORD=ParserPassword123

Python API Usage

Basic Usage

from rrc_field_rules import FieldRulesParser, ParserConfig

# Configure connection
config = ParserConfig(password="ParserPassword123")

# Use as context manager (recommended)
with FieldRulesParser(config) as parser:
    # Health check
    if parser.check_health():
        print("Connected!")

    # Get all field records
    fields = parser.get_fields()
    print(f"Found {len(fields)} fields")

    # Get with limit
    first_10 = parser.get_fields(limit=10)

    # Access specific tables
    field_info = parser.get_field_info()
    field_rules = parser.get_field_rules()
    std_rules = parser.get_std_field_rules()

Export to JSON

from pathlib import Path
from rrc_field_rules import FieldRulesParser, ParserConfig

config = ParserConfig(password="ParserPassword123")

with FieldRulesParser(config) as parser:
    # Export all tables
    counts = parser.export_all_to_json(Path("all_data.json"))
    print(f"Exported: {counts}")

    # Export single table
    parser.export_table_to_json("og_field", Path("fields.json"), limit=100)

Working with Models

Data is returned as Pydantic models with full type hints:

from rrc_field_rules import FieldRulesParser, ParserConfig

config = ParserConfig(password="ParserPassword123")

with FieldRulesParser(config) as parser:
    for field in parser.get_fields(limit=5):
        print(f"Field: {field.field_name}")
        print(f"  Number: {field.field_number}")
        print(f"  Class: {field.field_class_code}")
        print(f"  District: {field.district_code}")
        print(f"  H2S Flag: {field.field_h2s_flag}")

Custom Connection Settings

from rrc_field_rules import ParserConfig

# Remote database
config = ParserConfig(
    host="oracle.example.com",
    port=1521,
    service="PRODDB",
    user="rrc_reader",
    password="secure_password"
)

# From .env file (uses pydantic-settings)
# Create .env with RRC_HOST, RRC_PORT, etc.
config = ParserConfig()  # Will load from environment

Schema Reference

og_field

Column	Type	Description
field_number	VARCHAR2(8)	8-digit field number (first 5 unique, last 3 = reservoir)
field_name	VARCHAR2(50)	Field name (operator + formation + depth)
field_id	NUMBER(38)	System-generated unique key
field_class_code	CHAR(1)	G=gas, O=oil, B=both
field_h2s_flag	CHAR(1)	Y=present, N=not present, E=exempt
wildcat_flag	CHAR(1)	Y/N - no known zone of production
district_code	CHAR(2)	RRC district (01-10, 6e, 7b, 7c, 8a, 8b)

og_field_rule

Column	Type	Description
field_id	NUMBER(38)	Foreign key to og_field
rule_type_code	CHAR(1)	B=base, O=optional
minimum_lease_distance	NUMBER(4)	Min distance from lease line (feet)
minimum_well_distance	NUMBER(4)	Min distance between wells (feet)
minimum_acres_per_unit	NUMBER(8,2)	Min acres per well

Development

# Run tests
uv run pytest

# Lint
uv run ruff check src/

# Type check
uv run mypy src/

# Format
uv run ruff format src/

License

MIT License - see LICENSE for details.