Development¶

import pytest
from wfrmls import WFRMLSClient
from wfrmls.exceptions import ValidationError

class TestPropertyAPI:
    """Test property API functionality."""

    def test_get_properties_success(self, mock_client):
        """Test successful property retrieval."""
        # Arrange
        expected_properties = [{"ListingId": "12345678"}]
        mock_client.property.get_properties.return_value = expected_properties

        # Act
        result = mock_client.property.get_properties(top=1)

        # Assert
        assert result == expected_properties
        mock_client.property.get_properties.assert_called_once_with(top=1)

    def test_get_properties_validation_error(self, mock_client):
        """Test validation error handling."""
        # Act & Assert
        with pytest.raises(ValidationError):
            mock_client.property.get_properties(top=-1)

# conftest.py
import pytest
from unittest.mock import Mock

@pytest.fixture
def mock_client():
    """Create mock WFRMLS client for testing."""
    client = Mock(spec=WFRMLSClient)
    client.property = Mock()
    client.member = Mock()
    client.office = Mock()
    return client

@pytest.fixture
def sample_property():
    """Sample property data for testing."""
    return {
        "ListingId": "12345678",
        "ListPrice": 450000,
        "StandardStatus": "Active",
        "City": "Salt Lake City"
    }

def get_properties(
    self,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    filter_query: Optional[str] = None,
    select: Optional[List[str]] = None,
    orderby: Optional[str] = None,
    count: bool = False
) -> List[Dict[str, Any]]:
    """Retrieve property listings from WFRMLS.

    This method fetches property data with optional filtering, sorting,
    and pagination. All parameters follow OData v4 conventions.

    Args:
        top: Maximum number of results to return. Defaults to API limit.
        skip: Number of results to skip for pagination. Defaults to 0.
        filter_query: OData filter expression for filtering results.
            Example: "StandardStatus eq 'Active' and ListPrice gt 500000"
        select: List of specific fields to include in response.
            Example: ["ListingId", "ListPrice", "City"]
        orderby: Field(s) to sort by with optional direction.
            Example: "ListPrice desc" or "City asc, ListPrice desc"
        count: Whether to include total count in response metadata.

    Returns:
        List of property dictionaries matching the query criteria.
        Each dictionary contains the requested fields or all available
        fields if select parameter is not specified.

    Raises:
        ValidationError: If query parameters are invalid.
        AuthenticationError: If API credentials are invalid.
        RateLimitError: If API rate limits are exceeded.
        NotFoundError: If no results match the query (rare).
        WFRMLSError: For other API-related errors.

    Examples:
        Basic usage:

        >>> client = WFRMLSClient()
        >>> properties = client.property.get_properties(top=10)
        >>> len(properties)
        10

        With filtering:

        >>> active_properties = client.property.get_properties(
        ...     filter_query="StandardStatus eq 'Active'",
        ...     select=["ListingId", "ListPrice"],
        ...     orderby="ListPrice desc"
        ... )

        With pagination:

        >>> page_1 = client.property.get_properties(top=50, skip=0)
        >>> page_2 = client.property.get_properties(top=50, skip=50)

    Note:
        Large result sets are automatically paginated by the API.
        Consider using the skip parameter for manual pagination
        when processing large datasets.
    """

# Good: Clear, descriptive names
def get_active_properties_by_city(city_name: str) -> List[Dict[str, Any]]:
    """Get active properties in a specific city."""
    pass

# Bad: Unclear abbreviations
def get_act_props_by_c(c: str) -> List[Dict]:
    pass

# Good: Type hints and docstrings
from typing import Optional, List, Dict, Any

def search_properties(
    min_price: Optional[int] = None,
    max_price: Optional[int] = None
) -> List[Dict[str, Any]]:
    """Search properties within a price range.

    Args:
        min_price: Minimum listing price filter.
        max_price: Maximum listing price filter.

    Returns:
        List of property dictionaries matching criteria.
    """
    pass

# Good: Error handling
try:
    properties = client.property.get_properties()
except WFRMLSError as e:
    logger.error(f"Failed to fetch properties: {e}")
    raise

# Standard library imports
import os
import logging
from datetime import datetime
from typing import Optional, List, Dict, Any

# Third-party imports
import requests
from requests.adapters import HTTPAdapter

# Local imports
from wfrmls.exceptions import WFRMLSError, ValidationError
from wfrmls.utils import validate_parameters